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@xxxxxxxxx>
---
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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html