From 0ac3056850394723c9b407754b44d3d37f1dcc3f Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Thu, 26 Oct 2006 01:15:42 -0700 Subject: [PATCH] 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 --- Documentation/git-rev-parse.txt | 25 +++++++++++++++++++++---- 1 file 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 `` 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/` exists, that is what you mean (this is usually + useful only for `HEAD`, `FETCH_HEAD` and `MERGE_HEAD`); + + . otherwise, `$GIT_DIR/refs/` if exists; + + . otherwise, `$GIT_DIR/refs/tags/` if exists; + + . otherwise, `$GIT_DIR/refs/heads/` if exists; + + . otherwise, `$GIT_DIR/refs/remotes/` if exists; + + . otherwise, `$GIT_DIR/refs/remotes//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}' to a revision parameter means the commit object that is the 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 -- 2.30.2