summaryrefslogtreecommitdiff
path: root/Documentation/revisions.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/revisions.txt')
-rw-r--r--Documentation/revisions.txt30
1 files changed, 20 insertions, 10 deletions
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 991fcd8f3f..09896a37b1 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -2,13 +2,13 @@ SPECIFYING REVISIONS
--------------------
A revision parameter '<rev>' typically, but not necessarily, names a
-commit object. It uses what is called an 'extended SHA1'
+commit object. It uses what is called an 'extended SHA-1'
syntax. Here are various ways to spell object names. The
ones listed near the end of this list name trees and
blobs contained in a commit.
'<sha1>', e.g. 'dae86e1950b1277e545cee180551750029cfe735', 'dae86e'::
- The full SHA1 object name (40-byte hexadecimal string), or
+ The full SHA-1 object name (40-byte hexadecimal string), or
a leading substring that is unique within the repository.
E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both
name the same commit object if there is no other object in
@@ -23,7 +23,7 @@ blobs contained in a commit.
A symbolic ref name. E.g. 'master' typically means the 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.
+ explicitly say 'heads/master' to tell Git which one you mean.
When ambiguous, a '<refname>' is disambiguated by taking the
first match in the following rules:
@@ -55,9 +55,12 @@ when you run `git cherry-pick`.
+
Note that any of the 'refs/*' cases above may come either from
the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file.
-While the ref name encoding is unspecified, UTF-8 is prefered as
+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
@@ -88,10 +91,10 @@ some output processing may assume ref names in UTF-8.
The construct '@\{-<n>\}' means the <n>th branch checked out
before the current one.
-'<refname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}'::
- The suffix '@\{upstream\}' to a ref (short form '<refname>@\{u\}') refers to
- the branch the ref is set to build on top of. A missing ref defaults
- to the current branch.
+'<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.
'<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0'::
A suffix '{caret}' to a revision parameter means the first parent of
@@ -116,6 +119,11 @@ some output processing may assume ref names in UTF-8.
object of that type is found or the object cannot be
dereferenced anymore (in which case, barf). '<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}\{\}', e.g. 'v0.99.8{caret}\{\}'::
A suffix '{caret}' followed by an empty brace pair
@@ -239,11 +247,13 @@ To summarize:
'<rev1>..<rev2>'::
Include commits that are reachable from <rev2> but exclude
- those that are reachable from <rev1>.
+ those that are reachable from <rev1>. When either <rev1> or
+ <rev2> is omitted, it defaults to 'HEAD'.
'<rev1>\...<rev2>'::
Include commits that are reachable from either <rev1> or
- <rev2> but exclude those that are reachable from both.
+ <rev2> but exclude those that are reachable from both. When
+ either <rev1> or <rev2> is omitted, it defaults to 'HEAD'.
'<rev>{caret}@', e.g. 'HEAD{caret}@'::
A suffix '{caret}' followed by an at sign is the same as listing