summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJunio C Hamano <gitster@pobox.com>2012-08-06 22:30:57 (GMT)
committerJunio C Hamano <gitster@pobox.com>2012-08-06 22:30:57 (GMT)
commiteb536007df3dff31b6f4733c8455e195e0731426 (patch)
treeca351d80be6a9a31ac32d2d3e769a2698e77395a
parentf52a386ef256fbea1618affd85cf62ad8283b2f7 (diff)
parentca5ee2d1fbbb030f499587b58a49eb814f5b5ab0 (diff)
downloadgit-eb536007df3dff31b6f4733c8455e195e0731426.zip
git-eb536007df3dff31b6f4733c8455e195e0731426.tar.gz
git-eb536007df3dff31b6f4733c8455e195e0731426.tar.bz2
Merge branch 'mh/maint-revisions-doc' into maint
* mh/maint-revisions-doc: Enumerate revision range specifiers in the documentation Make <refname> documentation more consistent.
-rw-r--r--Documentation/revisions.txt43
1 files changed, 37 insertions, 6 deletions
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 1725661..dc0070b 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -24,22 +24,22 @@ blobs contained in a commit.
object referenced by 'refs/heads/master'. If you
happen to have both 'heads/master' and 'tags/master', you can
explicitly say 'heads/master' to tell git which one you mean.
- When ambiguous, a '<name>' is disambiguated by taking the
+ When ambiguous, a '<refname>' is disambiguated by taking the
first match in the following rules:
- . If '$GIT_DIR/<name>' exists, that is what you mean (this is usually
+ . If '$GIT_DIR/<refname>' exists, that is what you mean (this is usually
useful only for 'HEAD', 'FETCH_HEAD', 'ORIG_HEAD', 'MERGE_HEAD'
and 'CHERRY_PICK_HEAD');
- . otherwise, 'refs/<name>' if it exists;
+ . otherwise, 'refs/<refname>' if it exists;
. otherwise, 'refs/tags/<refname>' if it exists;
- . otherwise, 'refs/heads/<name>' if it exists;
+ . otherwise, 'refs/heads/<refname>' if it exists;
- . otherwise, 'refs/remotes/<name>' if it exists;
+ . otherwise, 'refs/remotes/<refname>' if it exists;
- . otherwise, 'refs/remotes/<name>/HEAD' if it exists.
+ . otherwise, 'refs/remotes/<refname>/HEAD' if it exists.
+
'HEAD' names the commit on which you based the changes in the working tree.
'FETCH_HEAD' records the branch which you fetched from a remote repository
@@ -218,13 +218,44 @@ 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.
+To summarize:
+
+'<rev>'::
+ Include commits that are reachable from (i.e. ancestors of)
+ <rev>.
+
+'{caret}<rev>'::
+ Exclude commits that are reachable from (i.e. ancestors of)
+ <rev>.
+
+'<rev1>..<rev2>'::
+ Include commits that are reachable from <rev2> but exclude
+ those that are reachable from <rev1>.
+
+'<rev1>\...<rev2>'::
+ Include commits that are reachable from either <rev1> or
+ <rev2> but exclude those that are reachable from both.
+
+'<rev>{caret}@', e.g. 'HEAD{caret}@'::
+ A suffix '{caret}' followed by an at sign is the same as listing
+ all parents of '<rev>' (meaning, include anything reachable from
+ its parents, but not the commit itself).
+
+'<rev>{caret}!', e.g. 'HEAD{caret}!'::
+ A suffix '{caret}' followed by an exclamation mark is the same
+ as giving commit '<rev>' and then all its parents prefixed with
+ '{caret}' to exclude them (and their ancestors).
+
Here are a handful of examples:
D G H D
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