filterdiff

filterdiff [options] [diff_file...]
diff_command | filterdiff [options]

-i
    Include files whose paths match the specified shell-style glob pattern. Can be specified multiple times.

-x
    Exclude files whose paths match the specified shell-style glob pattern. Can be specified multiple times.

-I
    Read include patterns from file, one pattern per line.

-X
    Read exclude patterns from file, one pattern per line.

--files-are-regex
    Treat file patterns provided with -i/-x or -I/-X as regular expressions instead of shell globs.

--lines-matching=
    Include only hunks that contain at least one line matching the specified regex.

--lines-not-matching=
    Exclude hunks that contain any line matching the specified regex.

--grep-hunks
    When using --lines-matching or --lines-not-matching, only output the matching lines/hunks, not the entire diff for the file.

-p
    Strip num leading path components from file names. Useful when applying patches from a different subdirectory.

-z, --uncompress
    Uncompress input files using gzip or bzip2 if they have the appropriate extension.

-s, --no-empty-diff
    Do not output sections that, after filtering, would result in an empty diff for a file.

--add-line-numbers
    Add line numbers to the output, mimicking grep -n behavior.

--strip-match=
    Remove a prefix matching regex from filenames before applying other filters.

--strip-to-bare
    Remove any leading directory components from filenames. Equivalent to -p with a sufficiently large number.

--skip-headers
    Skip any non-diff headers at the beginning of the input.

-v, --verbose
    Increase verbosity, printing more information about the filtering process.

-V, --version
    Display version information and exit.

--help
    Display a help message and exit.

filterdiff is a powerful command-line utility from the patchutils suite designed to selectively filter patches (diffs). It reads a diff from standard input or specified files and outputs only the portions that match (or don't match) certain criteria. This is incredibly useful for developers and system administrators who need to apply or review only specific changes within a larger patch file.

The primary filtering mechanisms involve including or excluding files based on shell-style glob patterns or regular expressions. Additionally, filterdiff can filter individual diff hunks based on their content, allowing for fine-grained control over which changes are processed. It understands various diff formats, making it versatile for use with outputs from commands like diff or git diff. Common use cases include extracting relevant changes for a specific feature, ignoring changes to generated files, or preparing a patch for a specific subsystem.

filterdiff primarily works with unified diff format. While it attempts to handle other formats, its filtering capabilities are most reliable with unified diffs.

Regular expressions used with --lines-matching and --lines-not-matching apply per-line within a hunk, not across hunks or files.

Path stripping (-p) occurs before pattern matching, so patterns should account for the stripped paths.

filterdiff processes include and exclude patterns in a specific order. If both -i and -x (or their file equivalents) are used, filterdiff first checks against include patterns. If a file matches an include pattern, it is then checked against exclude patterns. A file is only output if it matches an include pattern AND does NOT match an exclude pattern. If no include patterns are specified, all files are initially considered for exclusion.

Line-based filtering (--lines-matching, --lines-not-matching) applies to hunks after file-based filtering, further refining the output.

filterdiff is part of the patchutils package, a collection of utilities for manipulating patch files. It was developed by Tim Waugh to provide more fine-grained control over diffs than standard Unix tools typically offer. The patchutils project aimed to create robust, scriptable tools for tasks like splitting, sorting, and filtering patches, enhancing the workflow for patch management in software development. Its development focuses on interoperability with common diff formats and integration into shell scripts.

diff(1), patch(1), grep(1), sed(1), git-diff(1)