Re: how does one interpret "git diff <commit> ^<commit>"

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 22, 2019, 15:30 UTC
Message-ID: <xmqq1s3zsuvi.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <alpine.LFD.2.21.1902220816010.6353@localhost.localdomain>

"Robert P. J. Day" <rpjday@crashcourse.ca> writes:

Show 11 quoted lines

>   was perusing the git FAQ and ran across this:
>
>   How do I obtain a list of files which have changed in a given commit?
>
>      $ git diff --name-only <commit>^!
>
>
> after playing with "git rev-parse", i figured out that the above was
> equivalent to (using kernel "v4.19" tag as an example):
>
> $ git diff v4.19 ^v4.19^

A "rev" argument on the command line can have two (and a half but that one does not come into picture in this discussion) polarity. Normal and negative. Negative revs are written with "^" prefix (not to be confused with "^" suffix which means "the first parent of), and normal revs are written without "^" prefix.

There are some short-hands like <rev>^!, but they expand to combination of the normal and negative rev arguments at the bottom. The one you used, "rev^!", on the command line expands to "rev --not rev^1 rev^2... --not" for all its parents. Here "--not" means "treat all revs that follow have opposite polarity than they are written until you see the next "--not". For a non-merge commit, that's equivalent to "rev --not rev^", which in turn is "rev ^rev^.

Now these normal and negative revs are often used for specifying ranges to revision walking operations (think: "git log" etc.) When used to specify revision range, the set of commits a range specifies is anything reachable from any one or more of normal revs, excluding the ones reachable from any one or more of negative revs. So "git log v4.18..v4.19", which is a short-hand for "git log ^v4.18 v4.19" (because A..B is a short-hand that expands to "^A B"), i.e. list all commits that are reachable from v4.19, but I am not interested in the ones that are reachable from v4.18.

"git diff" is about comparing two endpoints, so these normal and negative revs are used differently. With one negative and one normal rev, you can tell "compare negative with normal to produce a patch that takes the tree of the negative one to the tree of the normal one".

So with "git diff v4.19^!", aka "git diff ^v4.19^ v4.19" (as v4.19 is not a merge), you are asking

	git diff v4.19^..v4.19

which is equivalent to asking

	git diff v4.19^ v4.19

which is "give me difference to bring the tree of the first parent of v4.19 to that of v4.19".

For interactive use to see "What happend at v4.19?", it is much easier to type "git show v4.19" than "git diff v4.19^!", though.