Skip to content

Doc fixes #163

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
twaugh merged 2 commits into from
Feb 25, 2026
Merged

Doc fixes #163

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dcf76b0
doc: Remove misleading filterdiff rename example
twaugh Feb 24, 2026
f2c9bf0
Use {braces} for tool-specific help filtering
twaugh Feb 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 50 additions & 8 deletions doc/patchutils.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -962,14 +962,7 @@ patch.file]]></screen></para>

<screen><![CDATA[filterdiff -v --format=unified context.diff]]></screen></para>
<para>Git format diffs are fully supported, including binary files,
file renames, and permission mode changes. For example, to extract
only the renames from a git diff:

<screen><![CDATA[# With --git-prefixes=strip (matches bare filename)
filterdiff --git-prefixes=strip -i '*/newname' git-patch-with-renames.patch

# With --git-prefixes=keep (default, matches with b/ prefix)
filterdiff -i 'b/*/newname' git-patch-with-renames.patch]]></screen></para>
file renames, and permission mode changes.</para>
</refsect1>
<refsect1>
<title>See also</title>
Expand Down Expand Up @@ -1086,6 +1079,8 @@ filterdiff -i 'b/*/newname' git-patch-with-renames.patch]]></screen></para>
<arg choice="opt">--strip=<replaceable>n</replaceable></arg>
<arg choice="opt">--git-prefixes=<replaceable>strip|keep</replaceable></arg>
<arg choice="opt">--addprefix=<replaceable>PREFIX</replaceable></arg>
<arg choice="opt">--addoldprefix=<replaceable>PREFIX</replaceable></arg>
<arg choice="opt">--addnewprefix=<replaceable>PREFIX</replaceable></arg>
<group choice="opt">
<arg>-s</arg>
<arg>--status</arg>
Expand All @@ -1098,10 +1093,18 @@ filterdiff -i 'b/*/newname' git-patch-with-renames.patch]]></screen></para>
<arg>-i <replaceable>PATTERN</replaceable></arg>
<arg>--include=<replaceable>PATTERN</replaceable></arg>
</group>
<group choice="opt">
<arg>-I <replaceable>FILE</replaceable></arg>
<arg>--include-from-file=<replaceable>FILE</replaceable></arg>
</group>
<group choice="opt">
<arg>-x <replaceable>PATTERN</replaceable></arg>
<arg>--exclude=<replaceable>PATTERN</replaceable></arg>
</group>
<group choice="opt">
<arg>-X <replaceable>FILE</replaceable></arg>
<arg>--exclude-from-file=<replaceable>FILE</replaceable></arg>
</group>
<group>
<arg>-z</arg>
<arg>--decompress</arg>
Expand Down Expand Up @@ -1269,6 +1272,22 @@ filterdiff -i 'b/*/newname' git-patch-with-renames.patch]]></screen></para>
it.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--addoldprefix</option>=<replaceable>PREFIX</replaceable></term>
<listitem>
<para>Prefix pathnames for old files with
<replaceable>PREFIX</replaceable> before displaying
them.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--addnewprefix</option>=<replaceable>PREFIX</replaceable></term>
<listitem>
<para>Prefix pathnames for new files with
<replaceable>PREFIX</replaceable> before displaying
them.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-s</option>, <option>--status</option></term>
<listitem>
Expand Down Expand Up @@ -1298,6 +1317,14 @@ filterdiff -i 'b/*/newname' git-patch-with-renames.patch]]></screen></para>
<replaceable>PATTERN</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-I</option><replaceable>FILE</replaceable>,
<option>--include-from-file=<replaceable>FILE</replaceable></option></term>
<listitem>
<para>Include only files matching any pattern listed in
<replaceable>FILE</replaceable>, one pattern per line.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-x</option><replaceable>PATTERN</replaceable>,
<option>--exclude=<replaceable>PATTERN</replaceable></option></term>
Expand All @@ -1306,6 +1333,14 @@ filterdiff -i 'b/*/newname' git-patch-with-renames.patch]]></screen></para>
<replaceable>PATTERN</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-X</option><replaceable>FILE</replaceable>,
<option>--exclude-from-file=<replaceable>FILE</replaceable></option></term>
<listitem>
<para>Exclude files matching any pattern listed in
<replaceable>FILE</replaceable>, one pattern per line.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-z</option>,
<option>--decompress</option></term>
Expand Down Expand Up @@ -2022,6 +2057,7 @@ This is the same as gitdiff but uses git show instead of git diff.
<arg>-s</arg>
<arg>--status</arg>
</group>
<arg choice="opt">--empty-files-as-absent</arg>
<group choice="opt">
<arg>-i <replaceable>PATTERN</replaceable></arg>
<arg>--include=<replaceable>PATTERN</replaceable></arg>
Expand Down Expand Up @@ -2198,6 +2234,12 @@ This is the same as gitdiff but uses git show instead of git diff.
<quote>!</quote>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--empty-files-as-absent</option></term>
<listitem>
<para>Treat empty files as absent when matching patterns.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option><replaceable>PATTERN</replaceable>,
<option>--include=<replaceable>PATTERN</replaceable></option></term>
Expand Down
84 changes: 42 additions & 42 deletions src/filterdiff.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1599,34 +1599,34 @@ const char * syntax_str =
" --lines=L include only hunks with (original) lines in range L, if range begins with x show all excluding range L\n"
" -F F, --files=F\n"
" include only files in range F, if range begins with x show all excluding range F\n"
" --annotate (filterdiff, patchview, grepdiff)\n"
" annotate each hunk with the filename and hunk number (filterdiff, patchview, grepdiff)\n"
" --as-numbered-lines=before|after|original-before|original-after (filterdiff, patchview, grepdiff)\n"
" display lines as they would look before, or after, the patch is applied;\n"
" or with original line numbers from the diff (original-before/original-after)\n"
" --format=context|unified (filterdiff, patchview, grepdiff)\n"
" set output format (filterdiff, patchview, grepdiff)\n"
" --output-matching=hunk|file (grepdiff)\n"
" show matching hunks or file-level diffs (grepdiff)\n"
" --only-match=rem|removals|add|additions|mod|modifications|all (grepdiff)\n"
" regex will only match removals, additions, modifications or (grepdiff)\n"
" the whole hunk (grepdiff)\n"
" --remove-timestamps (filterdiff, patchview, grepdiff)\n"
" don't show timestamps from output (filterdiff, patchview, grepdiff)\n"
" --clean (filterdiff)\n"
" remove all comments (non-diff lines) from output (filterdiff)\n"
" --in-place (filterdiff)\n"
" write output to the original input files (filterdiff)\n"
" --annotate {filterdiff, patchview, grepdiff}\n"
" annotate each hunk with the filename and hunk number {filterdiff, patchview, grepdiff}\n"
" --as-numbered-lines=before|after|original-before|original-after {filterdiff, patchview, grepdiff}\n"
" display lines as they would look before, or after, the patch is applied; {filterdiff, patchview, grepdiff}\n"
" or with original line numbers from the diff (original-before or original-after) {filterdiff, patchview, grepdiff}\n"
" --format=context|unified {filterdiff, patchview, grepdiff}\n"
" set output format {filterdiff, patchview, grepdiff}\n"
" --output-matching=hunk|file {grepdiff}\n"
" show matching hunks or file-level diffs {grepdiff}\n"
" --only-match=rem|removals|add|additions|mod|modifications|all {grepdiff}\n"
" regex will only match removals, additions, modifications or {grepdiff}\n"
" the whole hunk {grepdiff}\n"
" --remove-timestamps {filterdiff, patchview, grepdiff}\n"
" don't show timestamps from output {filterdiff, patchview, grepdiff}\n"
" --clean {filterdiff}\n"
" remove all comments (non-diff lines) from output {filterdiff}\n"
" --in-place {filterdiff}\n"
" write output to the original input files {filterdiff}\n"
" -z, --decompress\n"
" decompress .gz and .bz2 files\n"
" -n, --line-number (lsdiff, grepdiff)\n"
" show line numbers (lsdiff, grepdiff)\n"
" -N, --number-files (lsdiff, grepdiff)\n"
" show file numbers, for use with filterdiff's --files option (lsdiff, grepdiff)\n"
" -H, --with-filename (lsdiff, grepdiff)\n"
" show patch file names (lsdiff, grepdiff)\n"
" -h, --no-filename (lsdiff, grepdiff)\n"
" suppress patch file names (lsdiff, grepdiff)\n"
" -n, --line-number {lsdiff, grepdiff}\n"
" show line numbers {lsdiff, grepdiff}\n"
" -N, --number-files {lsdiff, grepdiff}\n"
" show file numbers, for use with filterdiff's --files option {lsdiff, grepdiff}\n"
" -H, --with-filename {lsdiff, grepdiff}\n"
" show patch file names {lsdiff, grepdiff}\n"
" -h, --no-filename {lsdiff, grepdiff}\n"
" suppress patch file names {lsdiff, grepdiff}\n"
" -p N, --strip-match=N\n"
" initial pathname components to ignore\n"
" --strip=N initial pathname components to strip\n"
Expand All @@ -1639,25 +1639,25 @@ const char * syntax_str =
" prefix pathnames in old files with PREFIX\n"
" --addnewprefix=PREFIX\n"
" prefix pathnames in new files with PREFIX\n"
" -s, --status (lsdiff, grepdiff)\n"
" show file additions (+), removals (-), and modifications (!) (lsdiff, grepdiff)\n"
" -s, --status {lsdiff, grepdiff}\n"
" show file additions (+), removals (-), and modifications (!) {lsdiff, grepdiff}\n"
" -v, --verbose\n"
" verbose output -- use more than once for extra verbosity\n"
" -E, --extended-regexp (grepdiff)\n"
" -E, --extended-regexp {grepdiff}\n"
#ifdef HAVE_PCRE2POSIX_H
" this option has no effect as PCRE regexes are used by default (grepdiff)\n"
" this option has no effect as PCRE regexes are used by default {grepdiff}\n"
#else
" use extended regexps, like egrep (grepdiff)\n"
" use extended regexps, like egrep {grepdiff}\n"
#endif
" -E, --empty-files-as-absent (lsdiff)\n"
" treat empty files as absent (lsdiff)\n"
" --empty-files-as-absent (grepdiff)\n"
" treat empty files as absent (grepdiff)\n"
" -f FILE, --file=FILE (grepdiff)\n"
" read regular expressions from FILE (grepdiff)\n"
" --filter run as 'filterdiff' (grepdiff, patchview, lsdiff)\n"
" --list run as 'lsdiff' (filterdiff, patchview, grepdiff)\n"
" --grep run as 'grepdiff' (filterdiff, patchview, lsdiff)\n"
" -E, --empty-files-as-absent {lsdiff}\n"
" treat empty files as absent {lsdiff}\n"
" --empty-files-as-absent {grepdiff}\n"
" treat empty files as absent {grepdiff}\n"
" -f FILE, --file=FILE {grepdiff}\n"
" read regular expressions from FILE {grepdiff}\n"
" --filter run as 'filterdiff' {grepdiff, patchview, lsdiff}\n"
" --list run as 'lsdiff' {filterdiff, patchview, grepdiff}\n"
" --grep run as 'grepdiff' {filterdiff, patchview, lsdiff}\n"
;

NORETURN
Expand All @@ -1676,8 +1676,8 @@ static void syntax (int err)
break;
endp = next;
*next++ = '\0';
if (*--endp == ')') {
char *begp = strrchr (p, '(');
if (*--endp == '}') {
char *begp = strrchr (p, '{');
char *comma;
if (!begp)
break;
Expand Down