Metadata-Version: 2.4
Name: ftw-patch
Version: 0.4.0
Summary: A unicode-resistant replacement for the classic `patch` utility
Author-email: Fitzz TeXnik Welt <FitzzTeXnikWelt@t-online.de>
Maintainer-email: Fitzz TeXnik Welt <FitzzTeXnikWelt@t-online.de>
Project-URL: Documentation, https://ftw-patch.readthedocs.io/en/stable/
Project-URL: Homepage, https://github.com/fitzz-ftw/ftw-patch
Project-URL: Issues, https://github.com/fitzz-ftw/ftw-patch/issues
Project-URL: Repository, https://github.com/fitzz-ftw/ftw-patch.git
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Text Processing :: Filters
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: platformdirs
Provides-Extra: doc
Requires-Dist: sphinx; extra == "doc"
Requires-Dist: myst-parser; extra == "doc"
Requires-Dist: sphinx-argparse; extra == "doc"
Requires-Dist: autoclasstoc; extra == "doc"
Requires-Dist: sphinx-nefertiti; extra == "doc"
Requires-Dist: sphinx-copybutton; extra == "doc"
Requires-Dist: sphinx-design; extra == "doc"
Requires-Dist: sphinx-mdinclude; extra == "doc"
Requires-Dist: sphinxcontrib-mermaid; extra == "doc"
Provides-Extra: dev
Requires-Dist: ftw-patch[doc,lint,test]; extra == "dev"
Requires-Dist: esbonio==0.16.5; extra == "dev"
Provides-Extra: lint
Requires-Dist: ruff; extra == "lint"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-mock; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Dynamic: license-file

## FTW Patch

**Author:** Fitzz TeXnik Welt

**Email:** FitzzTeXnikWelt@t-online.de

[![PyPI version](https://img.shields.io/pypi/v/ftw-patch.svg)](https://pypi.org/project/ftw-patch/)
[![Supported Python versions](https://img.shields.io/pypi/pyversions/ftw-patch.svg)](https://pypi.org/project/ftw-patch/)

[![Documentation Status](https://readthedocs.org/projects/ftw-patch/badge/?version=latest)](https://ftw-patch.readthedocs.io/en/latest/?badge=latest)
[![Code Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://codecov.io/gh/fitzz-ftw/ftw-patch)
[![Doc Coverage](https://img.shields.io/badge/doc--coverage-100%25-brightgreen)](https://ftw-patch.readthedocs.io/)
[![Linting: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![License: GPL v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html)



### Abstract
A unicode-resistant replacement for the classic `patch` utility. This tool is designed to handle patches reliably, even when dealing with special characters or different file encodings that often cause issues with traditional tools.

---

## Installation

Install `ftw-patch` easily via pipx:

```bash
pipx install ftw-patch
```

## Features

* **Unicode-Safe:** Reliable processing of files with special characters and various encodings.
* **Modern Python Support:** Fully tested and optimized for Python 3.11 up to the latest version 3.15.
* **Cross-Platform:** Works seamlessly on Linux, macOS, and Windows.
* **Configuration Support:** Settings can be pre-defined in `pyproject.toml` or a custom user TOML file.
* **Robust Path Handling:** Uses `platformdirs` to ensure clean and standard-compliant file paths.
* **High Quality:** Developed with high test coverage and verified via automated `tox` builds.
* **Advanced Whitespace Handling:** Options to normalize non-leading whitespace or ignore blank line differences.
* **Safety First:** Includes a `--dry-run` mode to simulate changes and automatic backup functionality.

## Usage (Command Line Interface)

`ftw-patch` is primarily used as a command-line tool.

### Basic Syntax
```bash
ftwpatch [options] patch_file
```

### Key Arguments & Options

* **`patch_file`**: The path to the unified diff or patch file.
* **`-h, --help`**: Show the help message and exit.
* **`-p, --strip <count>`**: Set the number of leading path components to strip from file names before trying to find the file (default: 0).
* **`-d, --directory <dir>`**: Change the working directory to `<dir>` before starting to look for files to patch.
* **`--normalize-ws`**: Normalize non-leading whitespace (replace spaces/tabs with a single space) in context and patch lines before comparison.
* **`--ignore-bl`**: Ignore differences in the number of consecutive blank lines.
* **`--ignore-all-ws`**: Ignore all whitespace (leading, non-leading, and blank lines). This overrides `--normalize-ws` and `--ignore-bl`.
* **`--dry-run`**: Simulate the process without writing any changes to the file system.
* **`-b, --backup`**: Create a backup of each file before applying patches.
* **`--backupext <ext>`**: Extension for backup files (default: `.bak`). Supports special keywords: `date`, `time`, or `datetime` for ISO 8601 timestamps.
* **`--userconfig <path>`**: Path to a custom user TOML configuration file.

> **Note:** Settings can also be loaded from `pyproject.toml` under `[tool.fitzzftw.patch]`.


### Configuration via pyproject.toml

You can pre-configure `ftwpatch` in your project's `pyproject.toml` file. This is useful for setting permanent defaults for your project.

Add a section `[tool.fitzzftw.patch]` like this:

```toml
[tool.fitzzftw.patch]
backup = true
backupext = ".original"
normalize-ws = true
strip = 1
```

### User Configuration and User Config File

If you want to use `ftw-patch` with the same settings across multiple projects, you can create a central user configuration file. The tool automatically searches for a `patch.toml` file in your standard user configuration directory.

**Standard Locations:**
* **Linux:** `~/.config/ftw-patch/patch.toml`
* **macOS:** `~/Library/Application Support/ftw-patch/patch.toml`
* **Windows:** `%AppData%\ftw-patch\patch.toml`

**Example `patch.toml`:**
```toml
# Your personal defaults
backup = true
backupext = ".original"
normalize-ws = true
```

> **Note:** You can override these defaults at any time by using command-line options or a project-specific `pyproject.toml`. If you want to use a specific configuration file from a different location, use the `--userconfig <path>` option.



## Licensing

This project uses different licenses for software and documentation:

### Software (Code)
The source code of `ftw-patch` is licensed under the **GNU General Public License, Version 2**. 
This allows free use, modification, and integration, provided that the terms of the GPLv2 (such as distributing the source code when you share the software) are met.

### Documentation
The documentation (content in the `docs/` directory and manuals) is licensed under **Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0)**.
* **NC (Non-Commercial):** Commercial use of the documentation (e.g., selling it as a printed book) is prohibited without express permission.
* **BY / SA:** Attribution and sharing under the same conditions are required.
