[v5,05/10] docs: gitdiffcore: -G and -S: Use regex/string placeholders

Commit Message

Illia Bobyr Feb. 12, 2025, 3:26 a.m. UTC

In the rest of the documentation (and in the code) we use `regex` and
`string` as `-G` and `-S` argument placeholders.  While
`regular-expression` and `block-of-text` are a bit easier to read, it is
a bit consistent.

And we could assume that everyone who uses git should be able to
understand that a "string" and a "block-of-text", as well as a "regex"
and "regular-expression" are the same thing.  So, using a shorter
version is also more consistent.
---
 Documentation/gitdiffcore.txt | 23 +++++++++++------------
 1 file changed, 11 insertions(+), 12 deletions(-)

Comments

Junio C Hamano Feb. 13, 2025, 4:36 a.m. UTC | #1

Illia Bobyr <[e-mail]> writes:

> In the rest of the documentation (and in the code) we use `regex` and
> `string` as `-G` and `-S` argument placeholders.  While
> `regular-expression` and `block-of-text` are a bit easier to read, it is
> a bit consistent.
>
> And we could assume that everyone who uses git should be able to
> understand that a "string" and a "block-of-text", as well as a "regex"
> and "regular-expression" are the same thing.  So, using a shorter
> version is also more consistent.
> ---
>  Documentation/gitdiffcore.txt | 23 +++++++++++------------
>  1 file changed, 11 insertions(+), 12 deletions(-)

I am with one reservation.  <block-of-text> was written to stress
the fact that most of the time the string is expected to be a
multi-line block of text (like a function body) [*1*] that is unique
within the codebase.  I do not think replacing a short-and-sweet
<string> with <block-of-text> is a good idea, but if we are to go
this route, we should mention that to compensate for the diminished
stress on that block-ness of the text, as <string> would imply
something quite short and would fit on a single line.

[Footnote]

*1* Go back to Linus's message I cited earlier;
    https://lore.kernel.org/git/[e-mail]/

Patch

diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt
index 642c5..0d7d66 100644
--- a/Documentation/gitdiffcore.txt
+++ b/Documentation/gitdiffcore.txt
@@ -245,26 +245,25 @@  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.  -S<block-of-text> and -G<regular-expression> options are used to
-specify different ways these strings are sought.
+way.  `-S<string>` and `-G<regex>` options are used to specify
+different ways these strings are sought.
 
-"-S<block-of-text>" detects filepairs whose preimage and postimage
-have different number of occurrences of the specified block of text.
+`-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 <block-of-text> as an extended POSIX regular expression to match,
+the _<string>_ as an extended POSIX regular expression to match,
 instead of a literal string.
 
-"-G<regular-expression>" (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.
+`-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