From 67bb6482078b691c7b667b31eb8338077e438968 Mon Sep 17 00:00:00 2001 From: Tim Waugh Date: Fri, 17 Oct 2025 15:37:14 +0100 Subject: [PATCH] doc: improve grepdiff documentation with better examples and organization Fix several issues with grepdiff documentation in patchutils.xml: * Move misplaced grepdiff example from filterdiff Examples section to grepdiff Examples section. The advanced example showing --output-matching=hunk with --as-numbered-lines was incorrectly placed in filterdiff documentation. * Clean up grepdiff Description section by removing embedded example that used a complex, inefficient pipeline (grepdiff | xargs filterdiff). Keep the section focused on conceptual explanation. * Completely rewrite grepdiff Examples section with comprehensive, progressive examples: - Start with filename-only output showing why it's useful for quick patch scanning - Show --output-matching=hunk for seeing actual matching hunks - Show --output-matching=file for complete file diffs - Include advanced usage with line numbering options - Preserve Git format example with explanatory notes * Add explanatory text for each example showing when and why to use each mode, making grepdiff's capabilities clearer These changes better showcase grepdiff as a powerful standalone tool rather than just a helper for filterdiff, with clear examples of its different output modes and proper organization of documentation. Assisted-by: Cursor --- doc/patchutils.xml | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/doc/patchutils.xml b/doc/patchutils.xml index 7d46c788..b561852c 100644 --- a/doc/patchutils.xml +++ b/doc/patchutils.xml @@ -956,8 +956,7 @@ patch.file]]> For CI/CD systems that need line numbers matching the original diff context (useful for error reporting), use the original-* variants: - + Filterdiff can also be used to convert between unified and context format diffs: @@ -2100,12 +2099,6 @@ This is the same as gitdiff but uses git show instead of git diff. are used instead of POSIX regular expressions, and the option has no effect since PCRE already supports extended regular expression features by default. - For example, to see the patches in - my.patch which contain the regular - expression pf_gfp_mask, use: - - You can use unified, context, and Git format diffs with this program. Git format includes support for binary files, file renames, permission mode changes, and other Git-specific @@ -2409,6 +2402,23 @@ This is the same as gitdiff but uses git show instead of git diff. Examples + To quickly identify which files in a large patch contain + memory allocation changes (useful for code review): + + + This shows only the filenames, giving you a quick overview + without being overwhelmed by diff content. + To see the actual hunks containing the pattern: + + + To see complete file diffs for files containing the pattern: + + + For CI/CD systems that need line numbers matching the original + diff context (useful for error reporting): + + Git format diffs are fully supported. For example, to find files in a git patch that contain changes to malloc calls: