kernel
/
git
mirror of https://git.kernel.org/pub/scm/git/git.git
1
0
Fork 0
Code Releases Activity

Merge branch 'dl/rev-tilde-doc-clarify' 

Docfix.

* dl/rev-tilde-doc-clarify:
  revisions.txt: remove ambibuity between <rev>:<path> and :<path>
  revisions.txt: mention <rev>~ form
  revisions.txt: mark optional rev arguments with []
  revisions.txt: change "rev" to "<rev>"
maint
Junio C Hamano 2019-05-13 23:50:33 +09:00
parent a505f62f6f 4ad1b2c7a6
commit 7a188da354
1 changed files with 14 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
Documentation/revisions.txt
View File

@ -65,7 +65,7 @@ some output processing may assume ref names in UTF-8.
'@':: '@'::
'@' alone is a shortcut for `HEAD`. '@' alone is a shortcut for `HEAD`.


'<refname>@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}':: '[<refname>]@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}'::
A ref followed by the suffix '@' with a date specification A ref followed by the suffix '@' with a date specification
enclosed in a brace enclosed in a brace
pair (e.g. '\{yesterday\}', '{1 month 2 weeks 3 days 1 hour 1 pair (e.g. '\{yesterday\}', '{1 month 2 weeks 3 days 1 hour 1
@ -95,7 +95,7 @@ some output processing may assume ref names in UTF-8.
The construct '@{-<n>}' means the <n>th branch/commit checked out The construct '@{-<n>}' means the <n>th branch/commit checked out
before the current one. before the current one.


'<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: '[<branchname>]@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}'::
The suffix '@\{upstream\}' to a branchname (short form '<branchname>@\{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 refers to the branch that the branch specified by branchname is set to build on
top of (configured with `branch.<name>.remote` and top of (configured with `branch.<name>.remote` and
@ -103,7 +103,7 @@ some output processing may assume ref names in UTF-8.
current one. These suffixes are also accepted when spelled in uppercase, and current one. These suffixes are also accepted when spelled in uppercase, and
they mean the same thing no matter the case. they mean the same thing no matter the case.


'<branchname>@\{push\}', e.g. 'master@\{push\}', '@\{push\}':: '[<branchname>]@\{push\}', e.g. 'master@\{push\}', '@\{push\}'::
The suffix '@\{push}' reports the branch "where we would push to" if The suffix '@\{push}' reports the branch "where we would push to" if
`git push` were run while `branchname` was checked out (or the current `git push` were run while `branchname` was checked out (or the current
`HEAD` if no branchname is specified). Since our push destination is `HEAD` if no branchname is specified). Since our push destination is
@ -131,7 +131,7 @@ from one location and push to another. In a non-triangular workflow,
This suffix is also accepted when spelled in uppercase, and means the same This suffix is also accepted when spelled in uppercase, and means the same
thing no matter the case. thing no matter the case.


'<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0':: '<rev>{caret}[<n>]', e.g. 'HEAD{caret}, v1.5.1{caret}0'::
A suffix '{caret}' to a revision parameter means the first parent of A suffix '{caret}' to a revision parameter means the first parent of
that commit object. '{caret}<n>' means the <n>th parent (i.e. that commit object. '{caret}<n>' means the <n>th parent (i.e.
'<rev>{caret}' '<rev>{caret}'
@ -139,7 +139,9 @@ thing no matter the case.
'<rev>{caret}0' means the commit itself and is used when '<rev>' is the '<rev>{caret}0' means the commit itself and is used when '<rev>' is the
object name of a tag object that refers to a commit object. object name of a tag object that refers to a commit object.


'<rev>{tilde}<n>', e.g. 'master{tilde}3':: '<rev>{tilde}[<n>]', e.g. 'HEAD{tilde}, master{tilde}3'::
A suffix '{tilde}' to a revision parameter means the first parent of
that commit object.
A suffix '{tilde}<n>' to a revision parameter means the commit A suffix '{tilde}<n>' to a revision parameter means the commit
object that is the <n>th generation ancestor of the named object that is the <n>th generation ancestor of the named
commit object, following only the first parents. I.e. '<rev>{tilde}3' is commit object, following only the first parents. I.e. '<rev>{tilde}3' is
@ -159,12 +161,12 @@ thing no matter the case.
'<rev>{caret}0' '<rev>{caret}0'
is a short-hand for '<rev>{caret}\{commit\}'. is a short-hand for '<rev>{caret}\{commit\}'.
+ +
'rev{caret}\{object\}' can be used to make sure 'rev' names an '<rev>{caret}\{object\}' can be used to make sure '<rev>' names an
object that exists, without requiring 'rev' to be a tag, and object that exists, without requiring '<rev>' to be a tag, and
without dereferencing 'rev'; because a tag is already an object, without dereferencing '<rev>'; because a tag is already an object,
it does not have to be dereferenced even once to get to 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 '<rev>{caret}\{tag\}' can be used to ensure that '<rev>' identifies an
existing tag object. existing tag object.


'<rev>{caret}{}', e.g. 'v0.99.8{caret}{}':: '<rev>{caret}{}', e.g. 'v0.99.8{caret}{}'::
@ -194,19 +196,16 @@ existing tag object.
Depending on the given text, the shell's word splitting rules might Depending on the given text, the shell's word splitting rules might
require additional quoting. require additional quoting.


'<rev>:<path>', e.g. 'HEAD:README', ':README', 'master:./README':: '<rev>:<path>', e.g. 'HEAD:README', 'master:./README'::
A suffix ':' followed by a path names the blob or tree A suffix ':' followed by a path names the blob or tree
at the given path in the tree-ish object named by the part at the given path in the tree-ish object named by the part
before the colon. before the colon.
':path' (with an empty part before the colon)
is a special case of the syntax described next: content
recorded in the index at the given path.
A path starting with './' or '../' is relative to the current working directory. A path starting with './' or '../' is relative to the current working directory.
The given path will be converted to be relative to the working tree's root directory. The given path will be converted to be relative to the working tree's root directory.
This is most useful to address a blob or tree from a commit or tree that has This is most useful to address a blob or tree from a commit or tree that has
the same tree structure as the working tree. the same tree structure as the working tree.


':<n>:<path>', e.g. ':0:README', ':README':: ':[<n>:]<path>', e.g. ':0:README', ':README'::
A colon, optionally followed by a stage number (0 to 3) and a A colon, optionally followed by a stage number (0 to 3) and a
colon, followed by a path, names a blob object in the colon, followed by a path, names a blob object in the
index at the given path. A missing stage number (and the colon index at the given path. A missing stage number (and the colon
@ -302,7 +301,7 @@ The 'r1{caret}@' notation means all parents of 'r1'.
The 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents. The 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents.
By itself, this notation denotes the single commit 'r1'. By itself, this notation denotes the single commit 'r1'.


The '<rev>{caret}-<n>' notation includes '<rev>' but excludes the <n>th The '<rev>{caret}-[<n>]' notation includes '<rev>' but excludes the <n>th
parent (i.e. a shorthand for '<rev>{caret}<n>..<rev>'), with '<n>' = 1 if parent (i.e. a shorthand for '<rev>{caret}<n>..<rev>'), with '<n>' = 1 if
not given. This is typically useful for merge commits where you not given. This is typically useful for merge commits where you
can just pass '<commit>{caret}-' to get all the commits in the branch can just pass '<commit>{caret}-' to get all the commits in the branch