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

Michael J Gruber [off-list ref] 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?

quoted

quoted

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

quoted

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

quoted

quoted

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

with

quoted

quoted

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

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