Command Line Tool ftwpatch

Tip

Why we recommend pipx

Unlike standard pip, pipx ensures that the application’s dependencies are kept strictly separate from other tools. This makes it impossible to “break” your system Python or other installed utilities.

General Usage & Path Resolution

Before exploring the individual command-line options, it is important to understand how the ftwpatch command resolves paths and configuration files.

Strict Path Resolution

To ensure maximum predictability and avoid “magic” behavior, ftwpatch follows strict rules:

  • Current Working Directory (CWD): All relative paths (for patches, target files, or config files) are resolved relative to the directory where you execute the command.

  • Project Awareness: The tool looks for a pyproject.toml strictly in the CWD. It does not search parent directories, ensuring that settings from one project do not accidentally leak into another.

Configuration Priority

Settings are merged from the following sources, where the higher level always overrides the lower ones:

  1. Command Line Arguments: Explicit options (e.g., --dry-run) always win.

  2. Project Configuration: Settings in ./pyproject.toml under the [tool.fitzzftw.patch] section.

  3. User Configuration:

    • Either a manual file provided via the --userconfig option.

    • Or the default patch.toml in your OS-specific config directory.

  4. Internal Defaults: Built-in fallback values.

Dynamic Help & Defaults

A key feature of the ftwpatch help system is that it is context-aware. The default values shown in the command-line help below are not hardcoded; they are recalculated every time you run the command.

When you call --help, the tool first evaluates your pyproject.toml and your user configuration. The “(default: …)” strings in the output will reflect the actually effective values for your current environment.

  • If you change a setting in your pyproject.toml, it will immediately show up as the new default in your help output.

  • If you use --userconfig, the help output will adapt to show the values defined in that specific file.

Verbosity Levels

Level

Description

0

Total number of processed files (default).

1

Level 0 + sum of all added and removed lines.

2

Statistics for created, modified, and deleted files (colorized).

3

Level 2 + total count of lines processed.

4

List of filenames for created, modified, and deleted files (colorized).

5

Level 4 + line statistics for each individual file.

6

Real-time progress: shows filenames and line stats during processing.

Command Line Interface

Below is the automatically generated help output for the ftwpatch command:

A Unicode-safe patch application tool with advanced whitespace normalization. Patch utility. Settings are loaded from pyproject.toml [tool.fitzzftw.patch] or a user config file. Keys in TOML match CLI flags (e.g., ‘backupext’).

usage: ftwpatch [-h] [-p STRIP_COUNT] [-d TARGET_DIRECTORY]
                [--normalize-ws [BOOLEAN]] [--ignore-bl [BOOLEAN]]
                [--ignore-all-ws [BOOLEAN]] [--dry-run [BOOLEAN]] [-v]
                [-b [BOOLEAN]] [--backupext BACKUP_EXT]
                [--userconfig USERCONFIG] [--backup-dir BACKUP_PATH]
                patch_file

Positional Arguments

patch_file

The path to the unified diff or patch file.

Named Arguments

-p, --strip

Set the number of leading path components to strip from file names before trying to find the file. (default: 0)

Default: 0

-d, --directory

Change the working directory to <dir> before starting to look for files to patch. (default: .)

Default: .

--normalize-ws

Normalize non-leading whitespace (replace sequences of spaces/tabs with a single space) in context and patch lines before comparison. Useful for patches with minor formatting differences. (default: False)

Default: False

--ignore-bl

Ignore or treat pure blank lines identically during patch matching. This implements a skip-ahead logic that collapses sequences of blank lines in the original file to match the blank lines (or lack thereof) in the patch context. It effectively ignores differences in the number of consecutive blank lines. (default: False)

Default: False

--ignore-all-ws

Ignore all whitespace (leading, non-leading, and blank lines) during comparison. This option overrides –normalize-ws and –ignore-bl. (default: False)

Default: False

--dry-run

Do not write changes to the file system; only simulate the process. (default: False)

Default: False

-v, --verbose

Increase output verbosity. Can be specified multiple times (-vvv) to increase the level of detail. (default: 0)

Default: 0

-b, --backup

Create a backup of each file before applying patches. (default: False)

Default: False

--backupext

The extension for backup files (e.g., ‘.bak’ or ‘old’). A leading dot is added automatically if missing. Special keywords ‘date’, ‘time’, or ‘datetime’ create a timestamped suffix in ISO 8601 format (e.g., ‘.bak_2025-12-30T094200’). (default: ‘.bak’)

Default: '.bak'

--userconfig

Path to a custom user TOML config (default: ‘’)

Note: ‘–userconfig’ cannot be set within a config file itself as it is required to locate

the file.

Default: ''

--backup-dir

Base directory for backups. If set, the relative path structure of patched files is mirrored here. Default is the current directory (default: .).

Default: .

Verbosity Levels:

0: Total number of processed files (default). 1: Level 0 + sum of all added and removed lines. 2: Statistics for created, modified, and deleted files (colorized). 3: Level 2 + total count of lines processed. 4: List of filenames for created, modified, and deleted files (colorized). 5: Level 4 + line statistics for each individual file. 6: Real-time progress: shows filenames and line stats during processing.

Configuration Examples

The keys in your TOML configuration files match the long-form names of the command-line arguments (e.g., use backupext for the --backupext option).

Project-specific (pyproject.toml)

Use this for settings that should be enforced for everyone working on this specific project.

[tool.fitzzftw.patch]
backup = true
backupext = ".original"
normalize-ws = true

User-specific (patch.toml)

Use this for your personal preferences across all your work where no project-specific pyproject.toml is present.

# Always use a specific backup extension and verbosity
verbose = 1
backupext = "datetime"

Note

If you use the --userconfig option, the path is resolved relative to your CWD. Example: ftwpatch --userconfig ./my_rules.toml <patch_file> will look for the config exactly in your current folder.