Re: [PATCH] diff-options.txt: correct command syntax

From: Martin Ågren <martin.agren@gmail.com>
Date: Feb 2, 2020, 19:45 UTC
Message-ID: <CAN0heSoxgsNDbi_tbxEoSSaGOxoJYArqYa-cLu1sPWVvH6wkFg@mail.gmail.com>
In-Reply-To: <20200202192226.29176-1-adam@dinwoodie.org>

Hi Adam,

On Sun, 2 Feb 2020 at 20:24, Adam Dinwoodie <adam@dinwoodie.org> wrote:

Show 33 quoted lines

>
> Change the example arguments in the description of the -G diff argument
> to be consistent throughout the description.
>
> Signed-off-by: Adam Dinwoodie <adam@dinwoodie.org>
> ---
>  Documentation/diff-options.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
> index 09faee3b44..84a74cb2da 100644
> --- a/Documentation/diff-options.txt
> +++ b/Documentation/diff-options.txt
> @@ -561,19 +561,19 @@ Binary files are searched as well.
>  -G<regex>::
>         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:
>  +
>  ----
>  +    return !regexec(regexp, two->ptr, 1, &regmatch, 0);
>  ...
>  -    hit = !regexec(regexp, mf2.ptr, 1, &regmatch, 0);
>  ----
>  +
> -While `git log -G"regexec\(regexp"` will show this commit, `git log
> --S"regexec\(regexp" --pickaxe-regex` will not (because the number of
> +While `git log -G<regex>` will show this commit, `git log
> +-S<regex> --pickaxe-regex` will not (because the number of
>  occurrences of that string did not change).

I don't think this is correct. "<regex>" is a placeholder and this example wants to use a real-world regex instead of the placeholder. Maybe this could be made clearer by having an example that does not try to grep in regex-code using the regex "regexec\(regexp".

Maybe instead of "regexec", "regexp" and "regmatch", this example could use words from some other domain? Would something like this be clearer?

 To illustrate the difference between `-S<regex> --pickaxe-regex` and
 `-G<regex>`, consider a commit with the following diff in the same
 file:
 +
 ----
 +    return !frotz(nitfol, two->ptr, 1, 0);
 ...
 -    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).

BTW, I wonder what "in the same file" tries to say -- my hunch is we could drop those words without any loss of correctness or readability. Would you agree?

Martin