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

[Junio C Hamano <gitster@pobox.com>]

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

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