Describe two-dot and three-dot notation for diff endpoints.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Mike Hommey committed
Aug 27, 2007 at 22:05 UTC
2b9232cc23a86f650cc1b93a35cce6ad59a8d782
1 file changed
+36
-7
Documentation/git-diff.txt
+36
-7
@@ -22,10 +22,10 @@ tree and the index file, or the index file and the working tree.
22
words, the differences are what you _could_ tell git to
23
further add to the index but you still haven't. You can
24
stage these changes by using gitlink:git-add[1].
25
-
26
- If exactly two paths are given, and at least one is untracked,
27
- compare the two files / directories. This behavior can be
28
- forced by --no-index.
25
++
26
+If exactly two paths are given, and at least one is untracked,
27
+compare the two files / directories. This behavior can be
28
+forced by --no-index.
29
30
'git-diff' [--options] --cached [<commit>] [--] [<path>...]::
31
@@ -44,8 +44,22 @@ tree and the index file, or the index file and the working tree.
44
45
'git-diff' [--options] <commit> <commit> [--] [<path>...]::
46
47
- This form is to view the changes between two <commit>,
48
- for example, tips of two branches.
47
+ This is to view the changes between two arbitrary
48
+ <commit>.
49
+
50
+'git-diff' [--options] <commit>..<commit> [--] [<path>...]::
51
+
52
+ This is synonymous to the previous form. If <commit> on
53
+ one side is omitted, it will have the same effect as
54
+ using HEAD instead.
55
+
56
+'git-diff' [--options] <commit>...<commit> [--] [<path>...]::
57
+
58
+ This form is to view the changes on the branch containing
59
+ and up to the second <commit>, starting at a common ancestor
60
+ of both <commit>. "git-diff A...B" is equivalent to
61
+ "git-diff $(git-merge-base A B) B". You can omit any one
62
+ of <commit>, which has the same effect as using HEAD instead.
63
64
Just in case if you are doing something exotic, it should be
65
noted that all of the <commit> in the above description can be
@@ -53,7 +67,10 @@ any <tree-ish>.
67
68
For a more complete list of ways to spell <commit>, see
69
"SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1].
56
-
70
+However, "diff" is about comparing two _endpoints_, not ranges,
71
+and the range notations ("<commit>..<commit>" and
72
+"<commit>...<commit>") do not mean a range as defined in the
73
+"SPECIFYING RANGES" section in gitlink:git-rev-parse[1].
74
75
OPTIONS
76
-------
@@ -97,6 +114,18 @@ the tip of the current branch, but limit the comparison to the
114
file "test".
115
<3> Compare the version before the last commit and the last commit.
116
117
+Comparing branches::
118
++
119
+------------
120
+$ git diff topic master <1>
121
+$ git diff topic..master <2>
122
+$ git diff topic...master <3>
123
+------------
124
++
125
+<1> Changes between the tips of the topic and the master branches.
126
+<2> Same as above.
127
+<3> Changes that occured on the master branch since when the topic
128
+branch was started off it.
129
130
Limiting the diff output::
131
+