Junio C Hamano venit, vidit, dixit 26.10.2016 20:11: > Michael J Gruber <git@xxxxxxxxxxxxxxxxxxxx> 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@xxxxxxxxxxxxxxxxxxxx> >> --- >> >> 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