confused git diff -G

confused git diff -G

[Alexei Podtelezhnikov]

I find this sections of the docs confusing:

git diff -G (https://git.kernel.org/pub/scm/git/git.git/tree/Documentation/diff-options.txt#n656)

 I do not follow why the example talks about `git log -G` and commits.
I see that thai file is included in git-log .txt but I do not
understand how to use git  diff -G.

A.

Re: confused git diff -G

[Taylor Blau]

On Thu, Aug 24, 2023 at 06:08:18PM -0400, Alexei Podtelezhnikov wrote:
> I find this sections of the docs confusing:
>
> git diff -G (https://git.kernel.org/pub/scm/git/git.git/tree/Documentation/diff-options.txt#n656)
>
>  I do not follow why the example talks about `git log -G` and commits.
> I see that thai file is included in git-log .txt but I do not
> understand how to use git  diff -G.

I agree that it can be somewhat confusing :-).

The linked section DIFFCORE-PICKAXE in gitdiffcore(7) may be helpful:

    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.

           [...]

           "-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.

So if I have a setup like:

    $ git init repo
    $ git -C repo commit --allow-empty -m base
    $ for c in a b; do echo $c>repo/$c && git -C $repo add $c; done
    $ git -C repo commit -m changes

Then you can see `-G` has the effect of limiting the output of 'git
diff' to just those file(s) whose diff matches the regular expression
given to `-G`, like so:

    $ git -C repo diff --stat HEAD^
     a | 1 +
     b | 1 +
     2 files changed, 2 insertions(+)
    $ git -C repo diff --stat HEAD^ -G a
     a | 1 +
     1 file changed, 1 insertion(+)
    $ git -C repo diff --stat HEAD^ -G b
     b | 1 +
     1 file changed, 1 insertion(+)

(I'm using --stat here to keep the output brief, since the contents are
only important insomuch as files "a" and "b" match the regular
expressions "a" and "b", respectively).

Thanks,
Taylor

Re: confused git diff -G

[Alexei Podtelezhnikov]

On Thu, Aug 24, 2023 at 6:56 PM Taylor Blau <me@ttaylorr.com> wrote:
>
> On Thu, Aug 24, 2023 at 06:08:18PM -0400, Alexei Podtelezhnikov wrote:
> > I find this sections of the docs confusing:
> >
> > git diff -G (https://git.kernel.org/pub/scm/git/git.git/tree/Documentation/diff-options.txt#n656)
> >
> >  I do not follow why the example talks about `git log -G` and commits.
> > I see that thai file is included in git-log .txt but I do not
> > understand how to use git  diff -G.
>
> I agree that it can be somewhat confusing :-).

[skip to the practical example]

> given to `-G`, like so:
>
>     $ git -C repo diff --stat HEAD^
>      a | 1 +
>      b | 1 +
>      2 files changed, 2 insertions(+)
>     $ git -C repo diff --stat HEAD^ -G a
>      a | 1 +
>      1 file changed, 1 insertion(+)
>     $ git -C repo diff --stat HEAD^ -G b
>      b | 1 +
>      1 file changed, 1 insertion(+)

Do you mean that-G is only useful to filter files and not the content
of changes? That I can do without -G. Canyou give a better example?

Re: confused git diff -G

[Alexei Podtelezhnikov]

> > given to `-G`, like so:
> >
> >     $ git -C repo diff --stat HEAD^
> >      a | 1 +
> >      b | 1 +
> >      2 files changed, 2 insertions(+)
> >     $ git -C repo diff --stat HEAD^ -G a
> >      a | 1 +
> >      1 file changed, 1 insertion(+)
> >     $ git -C repo diff --stat HEAD^ -G b
> >      b | 1 +
> >      1 file changed, 1 insertion(+)

Never mind my last blurp, thank you for the explanation.

This is how I thought it works but the docs *^^$@%&$ for either
git-log or git-diff: the example from diff but the text is from log.
It could not be more confusing than this, not just might. If you want
to share the text, it should be generic.

Re: confused git diff -G

[Junio C Hamano]

Taylor Blau <me@ttaylorr.com> writes:

> Then you can see `-G` has the effect of limiting the output of 'git
> diff' to just those file(s) whose diff matches the regular expression
> given to `-G`, like so:
>
>     $ git -C repo diff --stat HEAD^
>      a | 1 +
>      b | 1 +
>      2 files changed, 2 insertions(+)
>     $ git -C repo diff --stat HEAD^ -G a
>      a | 1 +
>      1 file changed, 1 insertion(+)
>     $ git -C repo diff --stat HEAD^ -G b
>      b | 1 +
>      1 file changed, 1 insertion(+)

All true.

As this feature is primarily designed to help "git log" to choose
which commit to show and which commit to omit in its output, readers
would not appreciate the usefulness of the feature, when shown in
the context of "git diff".

Even more puzzling is how the "--full-diff" option works in
combination with "-G" or "-S" (or --diff-filter=... for that
matter)..

They make perfect sense as ingredients of a mechanism to choose
which commit to show in the context of "git log", but their value is
not immediately apparent in the context of "git diff".  Continuing
with your example [*1*], comparing what these two do would be
illuminating:

    $ git -C repo diff --full-diff --stat -G b HEAD^
    $ git -C repo diff --full-diff --stat -G c HEAD^

The former should show changes to both a and b, and the latter
should show nothing.

While the way how each of these behaves makes perfect sense at the
logical level, it would be very puzzling why anybody may even want
to use such a feature in the first place.  Until you realize that
comparing the previous commit and the current state (which happens
to be identical to the current commit) is more or less a degenerated
form of running "log -n <n> HEAD" with <n> set to 1, that is.


[Footnote]

*1* By the way, as an experienced mentor, avoid giving a command
    line example that has dashed options after revs and paths.  It
    may happen to do what you intended, but is confusing to readers.