Currently, the reader has to parse a textual description in order to
find a specific syntax in the list.
Restructure as a labelled list with systematic labels as well as
concrete examples as a visual guide.
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
maint
Michael J Gruber14 years agocommitted byJunio C Hamano
second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value
@ -64,58 +68,68 @@ the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file.
@@ -64,58 +68,68 @@ the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file.
'master' branch last week. If you want to look at commits made during
certain times, see '--since' and '--until'.
* A ref followed by the suffix '@' with an ordinal specification
'<refname>@\{<n>\}', e.g. 'master@\{1\}'::
A ref followed by the suffix '@' with an ordinal specification
enclosed in a brace pair (e.g. '\{1\}', '\{15\}') to specify
the n-th prior value of that ref. For example 'master@\{1\}'
is the immediate prior value of 'master' while 'master@\{5\}'
is the 5th prior value of 'master'. This suffix may only be used
immediately following a ref name and the ref must have an existing
log ('$GIT_DIR/logs/<ref>').
log ('$GIT_DIR/logs/<refname>').
* You can use the '@' construct with an empty ref part to get at a
'@\{<n>\}', e.g. '@\{1\}'::
You can use the '@' construct with an empty ref part to get at a
reflog of the current branch. For example, if you are on the
branch 'blabla', then '@\{1\}' means the same as 'blabla@\{1\}'.
* The special construct '@\{-<n>\}' means the <n>th branch checked out
'@\{-<n>\}', e.g. '@\{-1\}'::
The special construct '@\{-<n>\}' means the <n>th branch checked out
before the current one.
* The suffix '@\{upstream\}' to a ref (short form 'ref@\{u\}') refers to
'<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. Missing ref defaults
to the current branch.
* A suffix '{caret}' to a revision parameter (e.g. 'HEAD{caret}') means the first parent of
'<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0'::
A suffix '{caret}' to a revision parameter means the first parent of
that commit object. '{caret}<n>' means the <n>th parent (i.e.
'rev{caret}'
is equivalent to 'rev{caret}1'). As a special rule,
'rev{caret}0' means the commit itself and is used when 'rev' is the
'<rev>{caret}'
is equivalent to '<rev>{caret}1'). As a special rule,
'<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.
* A suffix '{tilde}<n>' to a revision parameter means the commit
'<rev>{tilde}<n>', e.g. 'master{tilde}3'::
A suffix '{tilde}<n>' to a revision parameter means the commit
object that is the <n>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. See below for a illustration of
commit object, following only the first parent. I.e. '<rev>{tilde}3' is
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
'<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'
introduced earlier is a short-hand for 'rev{caret}\{commit\}'.
dereferenced anymore (in which case, barf). '<rev>{caret}0'
introduced earlier is a short-hand for '<rev>{caret}\{commit\}'.
* A suffix '{caret}' followed by an empty brace pair
(e.g. 'v0.99.8{caret}\{\}') means the object could be a tag,
'<rev>{caret}\{\}', e.g. 'v0.99.8{caret}\{\}'::
A suffix '{caret}' followed by an empty brace pair
means the object could be a tag,
and dereference the tag recursively until a non-tag object is
found.
* A suffix '{caret}' to a revision parameter followed by a brace
pair that contains a text led by a slash (e.g. 'HEAD^{/fix nasty bug}'):
this is the same as ':/fix nasty bug' syntax below except that
'<rev>{caret}\{/<text>\}', e.g. 'HEAD^{/fix nasty bug}'::
A suffix '{caret}' to a revision parameter, followed by a brace
pair that contains a text led by a slash,
is the same as ':/fix nasty bug' syntax below except that
it returns the youngest matching commit which is reachable from
the ref before '{caret}'.
the '<rev>' before '{caret}'.
* A colon, followed by a slash, followed by a text (e.g. ':/fix nasty bug'): this names
':/<text>', e.g. ':/fix nasty bug'::
A colon, followed by a slash, followed by a text, names
a commit whose commit message matches the specified regular expression.
This name returns the youngest matching commit which is
reachable from any ref. If the commit message starts with a
@ -124,10 +138,11 @@ the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file.
@@ -124,10 +138,11 @@ the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file.
The regular expression can match any part of the commit message. To
match messages starting with a string, one can use e.g. ':/^foo'.
* A suffix ':' followed by a path (e.g. 'HEAD:README'); this names the blob or tree
'<rev>:<path>', e.g. 'HEAD:README', ':README', 'master:./README'::
A suffix ':' followed by a path names the blob or tree
at the given path in the tree-ish object named by the part
before the colon.
':path' (with an empty part before the colon, e.g. ':README')
':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 current working directory.
@ -135,10 +150,11 @@ the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file.
@@ -135,10 +150,11 @@ the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file.
This is most useful to address a blob or tree from a commit or tree that has
the same tree structure with the working tree.
* A colon, optionally followed by a stage number (0 to 3) and a
colon, followed by a path (e.g. ':0:README'); this names a blob object in the
':<n>:<path>', e.g. ':0:README', ':README'::
A colon, optionally followed by a stage number (0 to 3) and a
colon, followed by a path, names a blob object in the
index at the given path. Missing stage number (and the colon
that follows it, e.g. ':README') names a stage 0 entry. During a merge, stage
that follows it) names a stage 0 entry. During a merge, stage
1 is the common ancestor, stage 2 is the target branch's version
(typically the current branch), and stage 3 is the version from
Michael J Gruber
14 years ago
committed by