doc: revisions: give headings for the two and three dot notations
While there, also break out the other shorthand notations and add a title for the revision range summary (which also appears in git-rev-parse, so keep it mixed case). We do not quote the notation within the headings as the asciidoc -> docbook -> groff man viewer toolchain, particularly the docbook-groff step, does not cope with two font changes, failing to return the heading font to bold after the quotation of the notation. Signed-off-by: Philip Oakley <philipoakley@iee.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Philip Oakley committed
Aug 12, 2016 at 08:07 UTC
391a3c70c3a9597d30b59e32489774f299555bb6
1 file changed
+36
-22
Documentation/revisions.txt
+36
-22
@@ -241,35 +241,49 @@ specifying a single revision with the notation described in the
241
previous section means the set of commits reachable from that
242
commit, following the commit ancestry chain.
243
244
-To exclude commits reachable from a commit, a prefix '{caret}'
245
-notation is used. E.g. '{caret}r1 r2' means commits reachable
246
-from 'r2' but exclude the ones reachable from 'r1'.
247
-
248
-This set operation appears so often that there is a shorthand
249
-for it. When you have two commits 'r1' and 'r2' (named according
250
-to the syntax explained in SPECIFYING REVISIONS above), you can ask
251
-for commits that are reachable from r2 excluding those that are reachable
252
-from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.
253
-
254
-A similar notation 'r1\...r2' is called symmetric difference
255
-of 'r1' and 'r2' and is defined as
256
-'r1 r2 --not $(git merge-base --all r1 r2)'.
257
-It is the set of commits that are reachable from either one of
258
-'r1' (left side) or 'r2' (right side) but not from both.
259
-
260
-In these two shorthands, you can omit one end and let it default to HEAD.
244
+Commit Exclusions
245
+~~~~~~~~~~~~~~~~~
246
+
247
+'{caret}<rev>' (caret) Notation::
248
+ To exclude commits reachable from a commit, a prefix '{caret}'
249
+ notation is used. E.g. '{caret}r1 r2' means commits reachable
250
+ from 'r2' but exclude the ones reachable from 'r1'.
251
+
252
+Dotted Range Notations
253
+~~~~~~~~~~~~~~~~~~~~~~
254
+
255
+The '..' (two-dot) Range Notation::
256
+ The '{caret}r1 r2' set operation appears so often that there is a shorthand
257
+ for it. When you have two commits 'r1' and 'r2' (named according
258
+ to the syntax explained in SPECIFYING REVISIONS above), you can ask
259
+ for commits that are reachable from r2 excluding those that are reachable
260
+ from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.
261
+
262
+The '...' (three dot) Symmetric Difference Notation::
263
+ A similar notation 'r1\...r2' is called symmetric difference
264
+ of 'r1' and 'r2' and is defined as
265
+ 'r1 r2 --not $(git merge-base --all r1 r2)'.
266
+ It is the set of commits that are reachable from either one of
267
+ 'r1' (left side) or 'r2' (right side) but not from both.
268
+
269
+In these two shorthand notations, you can omit one end and let it default to HEAD.
270
For example, 'origin..' is a shorthand for 'origin..HEAD' and asks "What
271
did I do since I forked from the origin branch?" Similarly, '..origin'
272
is a shorthand for 'HEAD..origin' and asks "What did the origin do since
273
I forked from them?" Note that '..' would mean 'HEAD..HEAD' which is an
274
empty range that is both reachable and unreachable from HEAD.
275
267
-Two other shorthands for naming a set that is formed by a commit
268
-and its parent commits exist. The 'r1{caret}@' notation means all
269
-parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes
270
-all of its parents.
276
+Other <rev>{caret} Parent Shorthand Notations
277
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
278
+Two other shorthands exist, particularly useful for merge commits,
279
+for naming a set that is formed by a commit and its parent commits.
280
272
-To summarize:
281
+The 'r1{caret}@' notation means all parents of 'r1'.
282
+
283
+'r1{caret}!' includes commit 'r1' but excludes all of its parents.
284
+
285
+Revision Range Summary
286
+----------------------
287
288
'<rev>'::
289
Include commits that are reachable from (i.e. ancestors of)