Skip to content

Creating patches#

When packaging software, you often need to make small source code changes – fixing a typo, applying a bug fix, or adapting build scripts. Instead of maintaining a fork of the upstream project, you can create patch files that are applied during the build process.

rattler-build provides a streamlined workflow for creating patches using the debug and create-patch commands.

How it works#

The debug command sets up a build environment and downloads sources without running the actual build script. This gives you a clean workspace to make changes. The create-patch command then compares your modified files against the original sources and generates a unified diff patch.

Basic workflow#

# Set up debug environment and enter the debug shell
rattler-build debug setup --recipe recipe.yaml
rattler-build debug shell

# You're now in the work directory with the build environment sourced.
# Edit files directly:
vim some_file.c

# Generate patch (from inside the debug shell, the directories are auto-detected)
rattler-build create-patch --name fix-typo

# Add to recipe
recipe.yaml
source:
  - url: https://example.com/package.tar.gz
    sha256: abc123...
    patches:
      - fix-typo.patch

Command options#

The create-patch command supports the following options:

  • --directory <DIR> - Work directory containing the modified sources (required)
  • --name <NAME> - Patch filename without .patch extension (default: "changes")
  • --patch-dir <DIR> - Directory to write the patch file (default: recipe directory)
  • --exclude <PATTERNS> - Files to exclude from the patch (comma-separated glob patterns)
  • --dry-run - Preview changes without creating a file

Examples#

Generate a patch with a custom name:

rattler-build create-patch --directory work/ --name fix-build-system

Preview changes before creating the patch:

rattler-build create-patch --directory work/ --dry-run

Create a patch in a dedicated patches folder:

rattler-build create-patch --directory work/ \
                           --name fix-compilation \
                           --patch-dir patches/

Supported source types#

Currently, the create-patch command supports:

  • URL sources - Creates patches for extracted archives (tar.gz, zip, etc.)
  • Git sources - ⚠️ Not yet implemented
  • Path sources - ⚠️ Not yet implemented