@matheusbsbs / matheus-bagliano / commits / 0ac3056850
Fork 0

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>

Junio C Hamano committed Oct 26, 2006 at 01:15 UTC 0ac3056850394723c9b407754b44d3d37f1dcc3f
1 file changed +21 -4
Documentation/git-rev-parse.txt
+21 -4
@@ -122,14 +122,30 @@ blobs contained in a commit.
122 your repository whose object name starts with dae86e.
123
124 * An output from `git-describe`; i.e. a closest tag, followed by a
125 - dash, a 'g', and an abbreviated object name.
125 + dash, a `g`, and an abbreviated object name.
126
127 * A symbolic ref name. E.g. 'master' typically means the commit
128 object referenced by $GIT_DIR/refs/heads/master. If you
129 happen to have both heads/master and tags/master, you can
130 explicitly say 'heads/master' to tell git which one you mean.
131 + When ambiguous, a `<name>` is disambiguated by taking the
132 + first match in the following rules:
133
132 -* A suffix '@' followed by a date specification enclosed in a brace
134 + . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually
135 + useful only for `HEAD`, `FETCH_HEAD` and `MERGE_HEAD`);
136 +
137 + . otherwise, `$GIT_DIR/refs/<name>` if exists;
138 +
139 + . otherwise, `$GIT_DIR/refs/tags/<name>` if exists;
140 +
141 + . otherwise, `$GIT_DIR/refs/heads/<name>` if exists;
142 +
143 + . otherwise, `$GIT_DIR/refs/remotes/<name>` if exists;
144 +
145 + . otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists.
146 +
147 +* A ref followed by the suffix '@' with a date specification
148 + enclosed in a brace
149 pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1
150 second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value
151 of the ref at a prior point in time. This suffix may only be
@@ -146,8 +162,9 @@ blobs contained in a commit.
162 * A suffix '{tilde}<n>' to a revision parameter means the commit
163 object that is the <n>th generation grand-parent of the named
164 commit object, following only the first parent. I.e. rev~3 is
149 - equivalent to rev{caret}{caret}{caret} which is equivalent to\
150 - rev{caret}1{caret}1{caret}1.
165 + equivalent to rev{caret}{caret}{caret} which is equivalent to
166 + rev{caret}1{caret}1{caret}1. See below for a illustration of
167 + the usage of this form.
168
169 * A suffix '{caret}' followed by an object type name enclosed in
170 brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object