summaryrefslogtreecommitdiff
path: root/Documentation/revisions.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/revisions.txt')
-rw-r--r--Documentation/revisions.txt24
1 files changed, 18 insertions, 6 deletions
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index d477b3f6bc..07961185fe 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -58,6 +58,9 @@ the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file.
While the ref name encoding is unspecified, UTF-8 is preferred as
some output processing may assume ref names in UTF-8.
+'@'::
+ '@' alone is a shortcut for 'HEAD'.
+
'<refname>@\{<date>\}', e.g. 'master@\{yesterday\}', 'HEAD@\{5 minutes ago\}'::
A ref followed by the suffix '@' with a date specification
enclosed in a brace
@@ -85,13 +88,15 @@ some output processing may assume ref names in UTF-8.
branch 'blabla' then '@\{1\}' means the same as 'blabla@\{1\}'.
'@\{-<n>\}', e.g. '@\{-1\}'::
- The construct '@\{-<n>\}' means the <n>th branch checked out
+ The construct '@\{-<n>\}' means the <n>th branch/commit checked out
before the current one.
'<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}'::
The suffix '@\{upstream\}' to a branchname (short form '<branchname>@\{u\}')
refers to the branch that the branch specified by branchname is set to build on
- top of. A missing branchname defaults to the current one.
+ top of (configured with `branch.<name>.remote` and
+ `branch.<name>.merge`). A missing branchname defaults to the
+ current one.
'<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0'::
A suffix '{caret}' to a revision parameter means the first parent of
@@ -111,16 +116,23 @@ some output processing may assume ref names in UTF-8.
'<rev>{caret}\{<type>\}', e.g. 'v0.99.8{caret}\{commit\}'::
A suffix '{caret}' followed by an object type name enclosed in
- brace pair means the object
- could be a tag, and dereference the tag recursively until an
- object of that type is found or the object cannot be
- dereferenced anymore (in which case, barf). '<rev>{caret}0'
+ brace pair means dereference the object at '<rev>' recursively until
+ an object of type '<type>' is found or the object cannot be
+ dereferenced anymore (in which case, barf).
+ For example, if '<rev>' is a commit-ish, '<rev>{caret}\{commit\}'
+ describes the corresponding commit object.
+ Similarly, if '<rev>' is a tree-ish, '<rev>{caret}\{tree\}'
+ describes the corresponding tree object.
+ '<rev>{caret}0'
is a short-hand for '<rev>{caret}\{commit\}'.
+
'rev{caret}\{object\}' can be used to make sure 'rev' names an
object that exists, without requiring 'rev' to be a tag, and
without dereferencing 'rev'; because a tag is already an object,
it does not have to be dereferenced even once to get to an object.
++
+'rev{caret}\{tag\}' can be used to ensure that 'rev' identifies an
+existing tag object.
'<rev>{caret}\{\}', e.g. 'v0.99.8{caret}\{\}'::
A suffix '{caret}' followed by an empty brace pair