From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 27 Oct 2016 18:40:50 GMT
Subject: Re: [PATCH] Documentation/git-diff: document git diff with 3+ commits
Message-ID: <xmqqvawd63f1.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <e74d4d84-d848-00be-8ca5-75204cf47262@drmicha.warpmail.net>

Michael J Gruber <git@drmicha.warpmail.net> writes:

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

I think you are speaking with 20/20 hindsight at this point.  

Do you genuinely think you would have thought that way when there
weren't any concept of "merge-base" or "git log A...B" known to you?

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

I don't know about the code comments, but the above SYNOPSIS needs
an update, I would think.  That is why I wondered if [<A>...] were
0-or-more or 1-or-moer.

You can replace

>>>  'git diff' [options] <commit> <commit> [--] [<path>...]

with

>>>  'git diff' [options] <commit> <commit> [<commit>...] [--] [<path>...]

without adding a new line to cover the new(ly discovered) case.