rev-parse documentation: talk about range notation.
Signed-off-by: Junio C Hamano <junkio@cox.net>
Junio C Hamano committed
Jul 6, 2006 at 22:37 UTC
be4c7014f2f5945c59001297d2b0f282056f6d34
1 file changed
+37
-8
Documentation/git-rev-parse.txt
+37
-8
@@ -156,11 +156,6 @@ syntax.
156
and dereference the tag recursively until a non-tag object is
157
found.
158
159
-'git-rev-parse' also accepts a prefix '{caret}' to revision parameter,
160
-which is passed to 'git-rev-list'. Two revision parameters
161
-concatenated with '..' is a short-hand for writing a range
162
-between them. I.e. 'r1..r2' is equivalent to saying '{caret}r1 r2'
163
-
159
Here is an illustration, by Jon Loeliger. Both node B and C are
160
a commit parents of commit node A. Parent commits are ordered
161
left-to-right.
@@ -168,9 +163,9 @@ left-to-right.
163
G H I J
164
\ / \ /
165
D E F
171
- \ | /
172
- \ | /
173
- \|/
166
+ \ | / \
167
+ \ | / |
168
+ \|/ |
169
B C
170
\ /
171
\ /
@@ -188,6 +183,40 @@ left-to-right.
183
J = F^2 = B^3^2 = A^^3^2
184
185
186
+SPECIFYING RANGES
187
+-----------------
188
+
189
+History traversing commands such as `git-log` operate on a set
190
+of commits, not just a single commit. To these commands,
191
+specifying a single revision with the notation described in the
192
+previous section means the set of commits reachable from that
193
+commit, following the commit ancestry chain.
194
+
195
+To exclude commits reachable from a commit, a prefix `{caret}`
196
+notation is used. E.g. "`{caret}r1 r2`" means commits reachable
197
+from `r2` but exclude the ones reachable from `r1`.
198
+
199
+This set operation appears so often that there is a shorthand
200
+for it. "`r1..r2`" is equivalent to "`{caret}r1 r2`". It is
201
+the difference of two sets (subtract the set of commits
202
+reachable from `r1` from the set of commits reachable from
203
+`r2`).
204
+
205
+A similar notation "`r1\...r2`" is called symmetric difference
206
+of `r1` and `r2` and is defined as
207
+"`r1 r2 --not $(git-merge-base --all r1 r2)`".
208
+It it the set of commits that are reachable from either one of
209
+`r1` or `r2` but not from both.
210
+
211
+Here are a few examples:
212
+
213
+ D A B D
214
+ D F A B C D F
215
+ ^A G B D
216
+ ^A F B C F
217
+ G...I C D F G I
218
+ ^B G I C D F G I
219
+
220
Author
221
------
222
Written by Linus Torvalds <torvalds@osdl.org> and