@matheusbsbs / matheus-bagliano / commits / be4c7014f2
Fork 0

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