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

From

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

Date

Oct 26, 2016, 09:11 UTC

Message-ID

<07712c2c94670ca4d91ef78cd7d3602a8d36b0c1.1477472970.git.git@drmicha.warpmail.net>

In-Reply-To

<CA+P7+xq1i8AtQ7i=1m_n9HTSL10kFUFBn8jvNcB_t_6Rh29u4w@mail.gmail.com>

Signed-off-by: Michael J Gruber <git@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