git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v4 10/10] diff: docs: Use --patch-{grep,modifies} over -G/-S

From
Illia Bobyr <illia.bobyr@gmail.com>
Date
Feb 11, 2025, 08:50 UTC
Message-ID
<20250211085028.3923875-11-illia.bobyr@gmail.com>
In-Reply-To
<20250206014324.1839232-1-illia.bobyr@gmail.com>

Long argument names are easier to read, compared to short ones. So while short arguments are great when you want to type a command quickly, the documentation readability is improved if we use long argument names.

Note for reviewers: All changes are just a replacement of `-G` with `--patch-grep` and `-S` with `--patch-modifies`. But as the text was reformatted to fit the same width in a few places it might look like there are more changes, if the diff is only line-wise and not word-wise.

The only an exception are changes in `gitdiffcore.adoc`, where I did
rephrase a sentence.  I've moved introduction of the short versions of
the `--patch-{grep,modifies}` into a subsequent paragraph.  The reason
is that I wanted to keep a note on the `-G` mnemonic, and it was awkward
if I would repeat the short definition twice over a span of two
paragraphs.
---
 Documentation/diff-options.adoc | 34 ++++++++++----------
 Documentation/git-blame.adoc    |  2 +-
 Documentation/gitdiffcore.adoc  | 55 +++++++++++++++++----------------
 3 files changed, 46 insertions(+), 45 deletions(-)
diff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc
index 07413d..c9f7c 100644
--- a/Documentation/diff-options.adoc
+++ b/Documentation/diff-options.adoc
@@ -658,8 +658,8 @@ renamed entries cannot appear if detection for those types is disabled.
 It is useful when you're looking for an exact block of code (like a
 struct), and want to know the history of that block since it first
 came into being: use the feature iteratively to feed the interesting
-block in the preimage back into `-S`, and keep going until you get the
-very first version of the block.
+block in the preimage back into `--patch-modifies`, and keep going until
+you get the very first version of the block.
 +
 Binary files are searched as well.
 
@@ -668,9 +668,9 @@ Binary files are searched as well.
 	Look for differences whose patch text contains added/removed
 	lines that match _<regex>_.
 +
-To illustrate the difference between `-S<regex>` `--pickaxe-regex` and
-`-G<regex>`, consider a commit with the following diff in the same
-file:
+To illustrate the difference between `--patch-modifies=<regex>
+--pickaxe-regex` and `--patch-grep=<regex>`, consider a commit with the
+following diff in the same file:
 +
 ----
 +    return frotz(nitfol, two->ptr, 1, 0);
@@ -678,9 +678,9 @@ file:
 -    hit = frotz(nitfol, mf2.ptr, 1, 0);
 ----
 +
-While `git log -G"frotz\(nitfol"` will show this commit, `git log
--S"frotz\(nitfol" --pickaxe-regex` will not (because the number of
-occurrences of that string did not change).
+While `git log --patch-grep="frotz\(nitfol"` will show this commit, `git
+log --patch-modifies="frotz\(nitfol" --pickaxe-regex` will not (because the
+number of occurrences of that string did not change).
 +
 Unless `--text` is supplied patches of binary files without a textconv
 filter will be ignored.
@@ -689,22 +689,22 @@ See the 'pickaxe' entry in linkgit:gitdiffcore[7] for more
 information.
 
 `--find-object=<object-id>`::
-	Look for differences that change the number of occurrences of
-	the specified object. Similar to `-S`, just the argument is different
-	in that it doesn't search for a specific string but for a specific
-	object id.
+	Look for differences that change the number of occurrences of the
+	specified object. Similar to `--patch-modifies`, just the argument
+	is different in that it doesn't search for a specific string but
+	for a specific object id.
 +
 The object can be a blob or a submodule commit. It implies the `-t` option in
 `git-log` to also find trees.
 
 `--pickaxe-all`::
-	When `-S` or `-G` finds a change, show all the changes in that
-	changeset, not just the files that contain the change
-	in _<string>_.
+	When `--patch-modifies` or `--patch-grep` finds a change, show all
+	the changes in that changeset, not just the files that contain the
+	change in _<string>_.
 
 `--pickaxe-regex`::
-	Treat the _<string>_ given to `-S` as an extended POSIX regular
-	expression to match.
+	Treat the _<string>_ given to `--patch-modifies` as an extended
+	POSIX regular expression to match.
 
 endif::git-format-patch[]
 
diff --git a/Documentation/git-blame.adoc b/Documentation/git-blame.adoc
index f75ed..10736a 100644
--- a/Documentation/git-blame.adoc
+++ b/Documentation/git-blame.adoc
@@ -41,7 +41,7 @@ a text string in the diff. A small example of the pickaxe interface
 that searches for `blame_usage`:
 
 -----------------------------------------------------------------------------
-$ git log --pretty=oneline -S'blame_usage'
+$ git log --pretty=oneline --patch-modifies='blame_usage'
 5040f17eba15504bad66b14a645bddd9b015ebb7 blame -S <ancestry-file>
 ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output
 -----------------------------------------------------------------------------
diff --git a/Documentation/gitdiffcore.adoc b/Documentation/gitdiffcore.adoc
index e934b9..e7f98 100644
--- a/Documentation/gitdiffcore.adoc
+++ b/Documentation/gitdiffcore.adoc
@@ -245,33 +245,34 @@ diffcore-pickaxe: For Detecting Addition/Deletion of Specified String
 
 This transformation limits the set of filepairs to those that change
 specified strings between the preimage and the postimage in a certain
-way.  `--patch-modifies=<string>` (`-S<string>` for short) and
-`--patch-grep=<regex>` (`-G<regex>` for short) are used to specify
-different ways these strings are sought.
-
-`-S<string>` detects filepairs whose preimage and postimage
-have different number of occurrences of the specified _<string>_.
-By definition, it will not detect in-file moves.  Also, when a
-changeset moves a file wholesale without affecting the interesting
-string, diffcore-rename kicks in as usual, and `-S` omits the filepair
-(since the number of occurrences of that string didn't change in that
-rename-detected filepair).  When used with `--pickaxe-regex`, treat
-the _<string>_ as an extended POSIX regular expression to match,
-instead of a literal string.
-
-`-G<regex>` (mnemonic: grep) detects filepairs whose textual diff has
-an added or a deleted line that matches the given _<regex>_.  This
-means that it will detect in-file (or what rename-detection considers
-the same file) moves, which is noise.  The implementation runs diff
-twice and greps, and this can be quite expensive.  To speed things up,
-binary files without textconv filters will be ignored.
-
-When `-S` or `-G` are used without `--pickaxe-all`, only filepairs
-that match their respective criterion are kept in the output.  When
-`--pickaxe-all` is used, if even one filepair matches their respective
-criterion in a changeset, the entire changeset is kept.  This behavior
-is designed to make reviewing changes in the context of the whole
-changeset easier.
+way.  `--patch-modifies=<string>` and `--patch-grep=<regex>` are used
+to specify different ways these strings are sought.
+
+`--patch-modifies=<string>` (`-S<string>` for short) detects filepairs
+whose preimage and postimage have different number of occurrences of
+the specified _<string>_.  By definition, it will not detect in-file
+moves.  Also, when a changeset moves a file wholesale without
+affecting the interesting string, diffcore-rename kicks in as usual,
+and `--patch-modifies` omits the filepair (since the number of
+occurrences of that string didn't change in that rename-detected
+filepair).  When used with `--pickaxe-regex`, treat the _<string>_ as
+an extended POSIX regular expression to match, instead of a literal
+string.
+
+`--patch-grep=<regex>` (`-G<regex>` for short, mnemonic: grep) detects
+filepairs whose textual diff has an added or a deleted line that
+matches the given regular expression.  This means that it will detect
+in-file (or what rename-detection considers the same file) moves,
+which is noise.  The implementation runs diff twice and greps, and
+this can be quite expensive.  To speed things up, binary files without
+textconv filters will be ignored.
+
+When `--patch-modifies` or `--patch-grep` are used without
+`--pickaxe-all`, only filepairs that match their respective criterion
+are kept in the output.  When `--pickaxe-all` is used, if even one
+filepair matches their respective criterion in a changeset, the entire
+changeset is kept.  This behavior is designed to make reviewing
+changes in the context of the whole changeset easier.
 
 diffcore-order: For Sorting the Output Based on Filenames
 ---------------------------------------------------------

-- 
2.45.2
Previous: Illia BobyrNext: Illia Bobyr
Message 19 of 36 in “Long names for `git log -S` and `git log -G`”
  1. 0/1 Long names for `git log -S` and `git log -G`Illia Bobyr, Feb 6, 2025
  2. 1/1 diff: --patch-{modifies,grep} arg names for -S and -GIllia Bobyr, Feb 6, 2025
  3. Junio C HamanoFeb 6, 2025
  4. Illia BobyrFeb 12, 2025
  5. Junio C HamanoFeb 12, 2025
  6. Junio C HamanoFeb 6, 2025
  7. 0/10 Long names for `git log -S` and `git log -G`Illia Bobyr, Feb 11, 2025
  8. Junio C HamanoFeb 11, 2025
  9. Illia BobyrFeb 12, 2025
  10. 01/10 t/t4209-log-pickaxe: Naming typo: -G takes a regexIllia Bobyr, Feb 11, 2025
  11. 02/10 diff: -G description: Correct copy/paste errorIllia Bobyr, Feb 11, 2025
  12. 03/10 diff: short help: Correct -S descriptionIllia Bobyr, Feb 11, 2025
  13. 04/10 diff: short help: Add -G and --pickaxe-grepIllia Bobyr, Feb 11, 2025
  14. 05/10 docs: gitdiffcore: -G and -S: Use regex/string placeholdersIllia Bobyr, Feb 11, 2025
  15. 06/10 diff: --patch-{grep,modifies} arg names for -G and -SIllia Bobyr, Feb 11, 2025
  16. 07/10 completion: Support --patch-{grep,modifies}Illia Bobyr, Feb 11, 2025
  17. 08/10 diff: test: Use --patch-{grep,modifies} over -G/-SIllia Bobyr, Feb 11, 2025
  18. 09/10 diff: --pickaxe-{all,regex} help: Add --patch-{grep,modifies}Illia Bobyr, Feb 11, 2025
  19. 10/10 diff: docs: Use --patch-{grep,modifies} over -G/-SIllia Bobyr, Feb 11, 2025
  20. 00/10 Long names for `git log -S` and `git log -G`Illia Bobyr, Feb 12, 2025
  21. 01/10 t/t4209-log-pickaxe: Naming typo: -G takes a regexIllia Bobyr, Feb 12, 2025
  22. Junio C HamanoFeb 13, 2025
  23. 02/10 diff: -G description: Correct copy/paste errorIllia Bobyr, Feb 12, 2025
  24. Junio C HamanoFeb 13, 2025
  25. 04/10 diff: short help: Add -G and --pickaxe-grepIllia Bobyr, Feb 12, 2025
  26. 03/10 diff: short help: Correct -S descriptionIllia Bobyr, Feb 12, 2025
  27. Junio C HamanoFeb 13, 2025
  28. 05/10 docs: gitdiffcore: -G and -S: Use regex/string placeholdersIllia Bobyr, Feb 12, 2025
  29. Junio C HamanoFeb 13, 2025
  30. 06/10 diff: --patch-{grep,modifies} arg names for -G and -SIllia Bobyr, Feb 12, 2025
  31. Junio C HamanoFeb 13, 2025
  32. 07/10 completion: Support --patch-{grep,modifies}Illia Bobyr, Feb 12, 2025
  33. Junio C HamanoFeb 13, 2025
  34. 08/10 diff: test: Use --patch-{grep,modifies} over -G/-SIllia Bobyr, Feb 12, 2025
  35. 09/10 diff: --pickaxe-{all,regex} help: Add --patch-{grep,modifies}Illia Bobyr, Feb 12, 2025
  36. 10/10 diff: docs: Use --patch-{grep,modifies} over -G/-SIllia Bobyr, Feb 12, 2025

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.