Re: Confusion about diffing branches

[Junio C Hamano <gitster@pobox.com>]

Mike Hommey <mh@glandium.org> writes:

> On Mon, Aug 27, 2007 at 03:21:32PM +0200, Francis Moreau <francis.moro@gmail.com> wrote:
>> 
>> This "inconsistency" had already been raised before. Please refer to:
>> http://www.gelato.unsw.edu.au/archives/git/0612/35354.html
>> 
>> I shared and still share your feeling about that but it seems that
>> Junio and Linus don't...
>
> Actually, they may have a good point, cf. the thread you point.
> But it is annoying that it is not documented.

Would something like this reduce the annoyance factor?

---

 Documentation/git-diff.txt |   20 +++++++++++++++++---
 1 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index b36e705..04b62d9 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -42,14 +42,28 @@ tree and the index file, or the index file and the working tree.
 	branch name to compare with the tip of a different
 	branch.
 
-'git-diff' [--options] <commit> <commit> [--] [<path>...]::
+'git-diff' [--options] <commit1> <commit2> [--] [<path>...]::
 
 	This form is to view the changes between two <commit>,
 	for example, tips of two branches.
 
+'git-diff' [--options] <commit1>..<commit2> [--] [<path>...]::
+
+	This is identical to the previous one, just to make the
+	specification of two commits look similar to a commit
+	range notation.
+
+'git-diff' [--options] <commit1>...<commit2> [--] [<path>...]::
+
+	This compares the merge base of two commits and the
+	second commit.  Useful to view what happened in the
+	history that leads to the second commit since that
+	history forked from the history that leads to the first
+	commit.
+
 Just in case if you are doing something exotic, it should be
-noted that all of the <commit> in the above description can be
-any <tree-ish>.
+noted that all of the <commit> in the above description,
+except for the last two variants, can be any <tree-ish>.
 
 For a more complete list of ways to spell <commit>, see
 "SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1].