Re: Confusion about diffing branches

[Mike Hommey <mh@glandium.org>]

[-- Attachment #1: Type: text/plain, Size: 754 bytes --]

On Mon, Aug 27, 2007 at 10:06:21AM -0700, Junio C Hamano <gitster@pobox.com> wrote:
> 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?

I was actually working on the attached diff, though I'm not really
convinced by my wording.

Mike

[-- Attachment #2: diff --]
[-- Type: text/plain, Size: 2192 bytes --]

 Documentation/git-diff.txt |   32 ++++++++++++++++++++++++++++++--
 1 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index b36e705..082ac0b 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -43,9 +43,22 @@ tree and the index file, or the index file and the working tree.
 	branch.
 
 'git-diff' [--options] <commit> <commit> [--] [<path>...]::
+'git-diff' [--options] <commit>..<commit> [--] [<path>...]::
 
-	This form is to view the changes between two <commit>,
-	for example, tips of two branches.
+	These forms are to view the changes between two <commit>,
+	for example, tips of two branches. In the second form,
+	omitting any one of both <commit> will have the same effect
+	as using HEAD.
+
+'git-diff' [--options] <commit>...<commit> [--] [<path>...]::
+
+	This form is to view the changes on the branch containing
+	and up to the second <commit>, starting at a common ancestor
+	of both <commit>.
+	"git-diff A...B" is equivalent to
+	"git-diff `git-merge-base A B` B"
+	You can omit any one of both <commit>, which has the same
+	effect as using HEAD.
 
 Just in case if you are doing something exotic, it should be
 noted that all of the <commit> in the above description can be
@@ -54,6 +67,9 @@ any <tree-ish>.
 For a more complete list of ways to spell <commit>, see
 "SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1].
 
+Be careful that despite looking like so, both "<commit>..<commit>"
+and "<commit>...<commit>" forms are NOT ranges as described in
+the "SPECIFYING RANGES" section in gitlink:git-rev-parse[1].
 
 OPTIONS
 -------
@@ -97,6 +113,18 @@ the tip of the current branch, but limit the comparison to the
 file "test".
 <3> Compare the version before the last commit and the last commit.
 
+Comparing branches::
++
+------------
+$ git diff topic master    <1>
+$ git diff topic..master   <2>
+$ git diff topic...master  <2>
+------------
++
+<1> Changes between the tips of the topic and the master branches.
+<2> Same as <1>
+<3> Changes that occured on the master branch since when the topic
+branch was started off it.
 
 Limiting the diff output::
 +