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

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

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.

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

So there.  We may want to deprecate "diff A..B" but I personally do
not think it is worth the effort.  There is no substitute for the
current "diff A...B" to allow us to deprecate both at the same time,
which is the required first step if we want to eventually swap their
meaning in a far future version of Git which would have been better
if we had hindsight.  But remember, "A...B" did not exist back then. 

> diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
> index bbab35fcaf..2047318a27 100644
> --- a/Documentation/git-diff.txt
> +++ b/Documentation/git-diff.txt
> @@ -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?".
Don't we allow pathspecs in this case?

>  'git diff' [options] <blob> <blob>
>  'git diff' [options] [--no-index] [--] <path> <path>
>  
> @@ -75,9 +76,16 @@ two blob objects, or changes between two files on disk.
>  	"git diff $(git-merge-base A B) B".  You can omit any one
>  	of <commit>, which has the same effect as using HEAD instead.
>  
> +'git diff' [options] <commit> <commit> <commit> [<commit>...]::
> +
> +	This is to view a combined diff between the first <commit>
> +	and the remaining ones, just like viewing a combined diff
> +	for a merge commit (see below) where the first <commit>
> +	is the merge commit and the remaining ones are the parents.
> +
>  Just in case if you are doing something exotic, it should be
>  noted that all of the <commit> in the above description, except
> -in the last two forms that use ".." notations, can be any
> +in the two forms that use ".." notations, can be any
>  <tree>.
>  
>  For a more complete list of ways to spell <commit>, see