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
commit
7a188da354
|
@ -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
|
||||||
|
|
Loading…
Reference in New Issue