[PATCH 2/2] Document rev^! and rev^@ as revision specifiers

From: Max Horn <max@quendi.de>
Date: Jul 6, 2012, 00:01 UTC
Message-ID: <1341532890-13829-2-git-send-email-max@quendi.de>
In-Reply-To: <1341532890-13829-1-git-send-email-max@quendi.de>

Previously, the rev^! and rev^@ syntax were only described in the SPECIFYING RANGES section of revisions.txt, making it a bit harder to find information about it. Moreover, that description was slightly confusing as it described the technical definition of rev^! and rev^@ without making it completely clear what the end effect was. This patch attempts to address this by adding dedicate entries for rev^! and rev^@ in the SPECIFYING REVISIONS section, rewording the existing explanation, and adding two select additional examples.

Finally, it also adds an example for the B..C range syntax, to help illustrate how it differs from B...C.

Signed-off-by: Max Horn <max@quendi.de>
---
 Documentation/revisions.txt | 24 +++++++++++++++++++++---
 1 Datei geändert, 21 Zeilen hinzugefügt(+), 3 Zeilen entfernt(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index f4f6f28..2784298 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -128,6 +128,20 @@ the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file.
   it returns the youngest matching commit which is reachable from
   the '<rev>' before '{caret}'.
 
+'<rev>{caret}@', e.g. 'HEAD{caret}@'::
+  A suffix '{caret}' followed by an at sign
+  means all parents of '<rev>'.
+  This is somewhat different from the other specifiers in this
+  section in that it may refer to multiple commits at once.
+  See also the next section on SPECIFYING RANGES.
+
+'<rev>{caret}!', e.g. 'HEAD{caret}!'::
+  A suffix '{caret}' followed by an exclamation mark
+  means commit '<rev>' but forces all of its parents to be excluded. For
+  commands that deal with a single revision, this is the same as '<rev>".
+  Hence it is primarily used with commands expecting commit ranges.
+  See also the next section on SPECIFYING RANGES.
+
 ':/<text>', e.g. ':/fix nasty bug'::
   A colon, followed by a slash, followed by a text, names
   a commit whose commit message matches the specified regular expression.
@@ -214,9 +228,10 @@ It is the set of commits that are reachable from either one of
 'r1' or 'r2' but not from both.
 
 Two other shorthands for naming a set that is formed by a commit
-and its parent commits exist.  The 'r1{caret}@' notation means all
-parents of 'r1'.  'r1{caret}!' includes commit 'r1' but excludes
-all of its parents.
+and its parent commits exist.  Recall that 'r1{caret}@' means all
+parents of 'r1'. When specifying ranges, this effectively includes
+all ancestors of 'r1' but excludes 'r1' itself. In contrast to this,
+'r1{caret}!' includes commit 'r1' but excludes all of its ancestors.
 
 Here are a handful of examples:
 
@@ -224,7 +239,10 @@ Here are a handful of examples:
    D F              G H I J D F
    ^G D             H D
    ^D B             E I J F B
+   B..C             C
    B...C            G H D E B C
    ^D B C           E I J F B C
+   C                I J F C
    C^@              I J F
+   C^!              C
    F^! D            G H D F

-- 
1.7.11.1.145.g4722b29.dirty