Re: [PATCH] Documentation/git-diff: document git diff with 3+ commits

[Michael J Gruber <git@drmicha.warpmail.net>]

Junio C Hamano venit, vidit, dixit 26.10.2016 20:11:
> Michael J Gruber <git@drmicha.warpmail.net> writes:
> 
>> That one is difficult to discover but super useful, so document it:
>> Specifying 3 or more commits makes git diff switch to combined diff.
>>
>> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
>> ---
>>
>> Notes:
>>     Note that we have the following now:
>> ...
>>     'git diff A..B' equivalent to 'git diff A B'
>>     in contrast to 'git log A..B' listing commits between M and B only
>>     (without the commits between M and A unless they are "in" B).
> 
> The standard answer is: 
> 
>     Do not use two-dot form with 'git diff', if you find it
>     confusing.  Diff is about two endpoints, not about a range
>     between two.
> 
> The reason why we do not reject can be easily guessed by any
> intelligent person when some historical background is given, I
> think.

That is very well true. I'm more concerned with the presence, though,
that is: How easy to use is git now? Users choose git because they care
about the history of their project, not necessarily that of Git ;)

>  - In the beginning A...B did not exist.  A..B was the only "range"
>    notation.
> 
>  - "git log A..B" was in wide use.  Remember, "git log A...B" did
>    not exist.
> 
>  - People started mistyping "git diff A..B", which looked as if the
>    user typed "git diff ^A B" to the internal.
> 
>  - Git _could_ have rejected that as a bogus request to diff two
>    points, ^A (what is that???) and B, but "What else could the user
>    have meant with 'git diff A..B' other than 'git diff A B'?" was
>    an argument to favor doing _something_ useful rather than
>    erroring out.  Remember, "A...B" did not exist when this
>    happened.

It did not exist, but even at that point in time, "git log A..B" listed
only commits between the merge base and B, not those which are only in A
and not in B. Whereas "git diff A B" shows the differences between the
endpoints A and B.

>> @@ -12,6 +12,7 @@ SYNOPSIS
>>  'git diff' [options] [<commit>] [--] [<path>...]
>>  'git diff' [options] --cached [<commit>] [--] [<path>...]
>>  'git diff' [options] <commit> <commit> [--] [<path>...]
>> +'git diff' [options] <commit> <commit> <commit> [<commit>...]
> 
> Made me wonder "is [<A>...] 0-or-more As or 1-or-more As?".

0-or-more, at least that's the way it is used in all lines here.

> Don't we allow pathspecs in this case?

Yes, the combinded diff mode kicks in only with no blobs (not: no
pathspec, which I had misread) and N>=3 commits. Maybe I should update
the code comments in builtin/diff.c to describe this, too.

Michael