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 <g...@drmicha.warpmail.net>
---
Notes:
Note that we have the following now:
'git diff A B' displays 'B minus A'
'git diff A B C' displays 'A minus B' and 'A minus C'
While I know why, that (the implicit '-R' seems unfortunate).
(NB: One has to use '-c' if A is an actual merge commiti, it seems.)
If M is a merge base for A and B, we have:
'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).
I would expect 'git diff M B' here.
'git diff A...B' is equivalent to 'git diff M B'
in contrast to 'git log A...B' listing commits between M and A (marked left)
as well as commits between M and B (marked right).
I would expect 'git diff -c -R M A B' here.
Somehow the positive and negative ends of these ranges don't correspond well
with thinking about diffs as differences between these ends.
[I'm not exact with my use of "between" regarding boundary commits.]
Documentation/git-diff.txt | 10 +++++++++-
1 file changed, 9 insertions(+), 1 deletion(-)
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>...]
'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
--
2.10.1.723.g0f00470
