Enumerate revision range specifiers in the documentation
It was a bit hard to learn how <rev>^@, <rev>^! and various other forms of range specifiers are used, because they were discussed mostly in the prose part of the documentation, unlike various forms of extended SHA-1 expressions that are listed in an enumerated list. Also add a few more examples showing use of <rev>, <rev>..<rev> and <rev>^! forms, stolen from a patch by Max Horn. Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Jul 24, 2012 at 15:03 UTC
ca5ee2d1fbbb030f499587b58a49eb814f5b5ab0
1 file changed
+31
Documentation/revisions.txt
+31
@@ -218,13 +218,44 @@ and its parent commits exist. The 'r1{caret}@' notation means all
218
parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes
219
all of its parents.
220
221
+To summarize:
222
+
223
+'<rev>'::
224
+ Include commits that are reachable from (i.e. ancestors of)
225
+ <rev>.
226
+
227
+'{caret}<rev>'::
228
+ Exclude commits that are reachable from (i.e. ancestors of)
229
+ <rev>.
230
+
231
+'<rev1>..<rev2>'::
232
+ Include commits that are reachable from <rev2> but exclude
233
+ those that are reachable from <rev1>.
234
+
235
+'<rev1>\...<rev2>'::
236
+ Include commits that are reachable from either <rev1> or
237
+ <rev2> but exclude those that are reachable from both.
238
+
239
+'<rev>{caret}@', e.g. 'HEAD{caret}@'::
240
+ A suffix '{caret}' followed by an at sign is the same as listing
241
+ all parents of '<rev>' (meaning, include anything reachable from
242
+ its parents, but not the commit itself).
243
+
244
+'<rev>{caret}!', e.g. 'HEAD{caret}!'::
245
+ A suffix '{caret}' followed by an exclamation mark is the same
246
+ as giving commit '<rev>' and then all its parents prefixed with
247
+ '{caret}' to exclude them (and their ancestors).
248
+
249
Here are a handful of examples:
250
251
D G H D
252
D F G H I J D F
253
^G D H D
254
^D B E I J F B
255
+ B..C C
256
B...C G H D E B C
257
^D B C E I J F B C
258
+ C I J F C
259
C^@ I J F
260
+ C^! C
261
F^! D G H D F