aboutsummaryrefslogtreecommitdiff
path: root/Documentation/git-rev-parse.txt
diff options
context:
space:
mode:
authorJunio C Hamano <junkio@cox.net>2006-10-26 01:15:42 -0700
committerJunio C Hamano <junkio@cox.net>2006-10-26 01:15:42 -0700
commit0ac3056850394723c9b407754b44d3d37f1dcc3f (patch)
tree17fb3549e93aea2c4746aee0a09b4a4abc09b842 /Documentation/git-rev-parse.txt
parent0074aba1c0d3b073c635fdc1d5754dc6a6b6b7b9 (diff)
downloadgit-0ac3056850394723c9b407754b44d3d37f1dcc3f.tar.gz
git-0ac3056850394723c9b407754b44d3d37f1dcc3f.tar.xz
Documentation: clarify refname disambiguation rules.
Nobody should create ambiguous refs (i.e. have tag "foobar" and branch "foobar" at the same time) that need to be disambiguated with these rules to keep sanity, but the rules are there so document them. Signed-off-by: Junio C Hamano <junkio@cox.net>
Diffstat (limited to 'Documentation/git-rev-parse.txt')
-rw-r--r--Documentation/git-rev-parse.txt25
1 files changed, 21 insertions, 4 deletions
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 5d4257062..ed938aafb 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -122,14 +122,30 @@ blobs contained in a commit.
your repository whose object name starts with dae86e.
* An output from `git-describe`; i.e. a closest tag, followed by a
- dash, a 'g', and an abbreviated object name.
+ dash, a `g`, and an abbreviated object name.
* A symbolic ref name. E.g. 'master' typically means the commit
object referenced by $GIT_DIR/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
+ first match in the following rules:
-* A suffix '@' followed by a date specification enclosed in a brace
+ . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually
+ useful only for `HEAD`, `FETCH_HEAD` and `MERGE_HEAD`);
+
+ . otherwise, `$GIT_DIR/refs/<name>` if exists;
+
+ . otherwise, `$GIT_DIR/refs/tags/<name>` if exists;
+
+ . otherwise, `$GIT_DIR/refs/heads/<name>` if exists;
+
+ . otherwise, `$GIT_DIR/refs/remotes/<name>` if exists;
+
+ . otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists.
+
+* A ref followed by the suffix '@' with a date specification
+ enclosed in a brace
pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1
second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value
of the ref at a prior point in time. This suffix may only be
@@ -146,8 +162,9 @@ blobs contained in a commit.
* A suffix '{tilde}<n>' to a revision parameter means the commit
object that is the <n>th generation grand-parent of the named
commit object, following only the first parent. I.e. rev~3 is
- equivalent to rev{caret}{caret}{caret} which is equivalent to\
- rev{caret}1{caret}1{caret}1.
+ equivalent to rev{caret}{caret}{caret} which is equivalent to
+ rev{caret}1{caret}1{caret}1. See below for a illustration of
+ the usage of this form.
* A suffix '{caret}' followed by an object type name enclosed in
brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object