Re: [PATCH 2/2] git-diff.txt: reorder possible usages

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

Chris Torek <chris.torek@gmail.com> writes:

> On Mon, Jul 13, 2020 at 12:10 PM Martin Ågren <martin.agren@gmail.com> wrote:
>> It then goes on to say that "all of the <commit> in the above
>> description, except in the last two forms that use '..' notations, can
>> be any <tree>". The "last two" actually refers to 6 and 8. This got out
>> of sync in commit b7e10b2ca2 ("Documentation: usage for diff combined
>> commits", 2020-06-12) which added item 7 to the mix.
>
> Moving this down (as you do in this patch) is the right thing to do,
> but I'll note that formally, the word "that" in "forms that use ..." is
> part of a restrictive clause, so it means "find the last two examples
> that use dots".  (In American English at least, the unrestrictive version
> would be set off with commas, and use "which" instead of "that".)

Yes, the proposed patch is an improvement, but I agree that "find
the last two that use dots" was indeed what I meant when I wrote
0c783f66 (Documentation/git-diff: A..B and A...B cannot take
tree-ishes, 2007-08-28).

But upon reading it again now, I am not sure it makes sense in the
first place.

    git diff seen^^{tree}..seen^{tree}

uses <tree> (not commit) in the form that uses '..' notation, and it
just works fine.  What does require commit because it depends on
having a history to compute merge base between two objects given
from the command line is the form that uses '...' notation.

    git diff seen^1...seen^2

would be "what did the side branch merged at the tip of seen do
since it forked?" and should look similar to "git diff seen^ seen",
but it cannot use tree objects for obvious reasons

    git diff seen^1^{tree}...seen^2^{tree}

>> An added bonus of this commit is that we're trying to steer users away
>> from `git diff <commit>..<commit>` and moving it further down probably
>> doesn't hurt.
>
> Q: Just how hard should we try?  In particular, would it be good to mark
> the two-dot form as deprecated in the documentation?  I anticipate
> objections because it's not possible to omit `HEAD` without using
> the two-dot form.

I am not sure why it is so important to be able to omit HEAD in the
first place.  I do not think using two-dot form is an offence severe
enough to deserve an extra warning or deprecation notice, but using
the "range" notation when you meant two endpoints is a notation that
confuses uninitiated needlessly and showing it to new people is a
disservice.  "This notation does not make logical sense, but we keep
using it as users, and we keep accepting it as tool makers, purely
for convenience" has been and will be the attitude I'd take towards
the "git diff A..B" syntax---it was a mistake we made when we were
still young ;-)

cf. https://bit.ly/3eBcyZa