table of contents
other versions
- wheezy 1:1.7.10.4-1+wheezy3
- wheezy-backports 1:1.9.1-1~bpo70+2
- jessie 1:2.1.4-2.1+deb8u2
- jessie-backports 1:2.11.0-3~bpo8+1
- testing 1:2.11.0-3
- unstable 1:2.11.0-4
- experimental 1:2.13.1+next.20170610-1
GITREVISIONS(7) | Git Manual | GITREVISIONS(7) |
NAME¶
gitrevisions - specifying revisions and ranges for gitSYNOPSIS¶
gitrevisionsDESCRIPTION¶
Many Git commands take revision parameters as arguments. Depending on the command, they denote a specific commit or, for commands which walk the revision graph (such as git-log(1)), all commits which can be reached from that commit. In the latter case one can also specify a range of revisions explicitly.SPECIFYING REVISIONS¶
A revision parameter <rev> typically, but not necessarily, names a commit object. It uses what is called an extended SHA1 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, dae86eThe full SHA1 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 your repository whose object name starts
with dae86e.
<describeOutput>, e.g. v1.7.4.2-679-g3bee7fb
Output from git describe; i.e. a closest tag,
optionally followed by a dash and a number of commits, followed by a dash, a
g, and an abbreviated object name.
<refname>, e.g. master, heads/master,
refs/heads/master
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. When
ambiguous, a <name> is disambiguated by taking the first match in
the following rules:
<refname>@{<date>}, e.g. master@{yesterday},
HEAD@{5 minutes ago}
1.If $GIT_DIR/<name> exists,
that is what you mean (this is usually useful only for HEAD,
FETCH_HEAD, ORIG_HEAD, MERGE_HEAD and
CHERRY_PICK_HEAD);
2.otherwise, refs/<name> if it
exists;
3.otherwise, refs/tags/<refname>
if it exists;
4.otherwise, refs/heads/<name>
if it exists;
5.otherwise, refs/remotes/<name>
if it exists;
6.otherwise,
refs/remotes/<name>/HEAD if it exists.
HEAD names the commit on which you based the changes in the working tree.
FETCH_HEAD records the branch which you fetched from a remote
repository with your last git fetch invocation. ORIG_HEAD is created by
commands that move your HEAD in a drastic way, to record the position
of the HEAD before their operation, so that you can easily change the
tip of the branch back to the state before you ran them. MERGE_HEAD
records the commit(s) which you are merging into your branch when you run git
merge. CHERRY_PICK_HEAD records the commit which you are cherry-picking
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.
A ref followed by the suffix @ with a
date specification enclosed in a brace pair (e.g. {yesterday}, {1
month 2 weeks 3 days 1 hour 1 second ago} or {1979-02-26 18:30:00})
specifies the value of the ref at a prior point in time. This suffix may only
be used immediately following a ref name and the ref must have an existing log
( $GIT_DIR/logs/<ref>). Note that this looks up the state of your
local ref at a given time; e.g., what was in your local master
branch last week. If you want to look at commits made during certain times,
see --since and --until.
<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})
specifies 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/<refname>).
@{<n>}, e.g. @{1}
You can use the @ construct with an
empty ref part to get at a reflog entry of the current branch. For example, if
you are on branch blabla then @{1} means the same as
blabla@{1}.
@{-<n>}, e.g. @{-1}
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.
<rev>^, e.g. HEAD^, v1.5.1^0
A suffix ^ to a revision parameter
means the first parent of that commit object. ^<n> means the
<n>th parent (i.e. <rev>^ is equivalent to
<rev>^1). As a special rule, <rev>^0 means the
commit itself and is used when <rev> is the object name of a tag
object that refers to a commit object.
<rev>~<n>, e.g. master~3
A suffix ~<n> to a revision
parameter means the commit object that is the <n>th generation ancestor
of the named commit object, following only the first parents. I.e.
<rev>~3 is equivalent to <rev>^^^ which is
equivalent to <rev>^1^1^1. See below for an illustration of the
usage of this form.
<rev>^{<type>}, e.g. v0.99.8^{commit}
A suffix ^ 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>^0 is a
short-hand for <rev>^{commit}.
<rev>^{}, e.g. v0.99.8^{}
A suffix ^ 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.
<rev>^{/<text>}, e.g. HEAD^{/fix nasty bug}
A suffix ^ to a revision parameter,
followed by a brace pair that contains a text led by a slash, is the same as
the :/fix nasty bug syntax below except that it returns the youngest
matching commit which is reachable from the <rev> before
^.
:/<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 ! you have to repeat
that; the special sequence :/!, followed by something else than
!, is reserved for now. The regular expression can match any part of
the commit message. To match messages starting with a string, one can use e.g.
:/^foo.
<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) 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. 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 the same tree structure as the working
tree.
:<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. A missing stage number (and the colon 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 the branch which is being merged.
G H I J \ / \ / D E F \ | / \ \ | / | \|/ | B C \ / \ / A
A = = A^0 B = A^ = A^1 = A~1 C = A^2 = A^2 D = A^^ = A^1^1 = A~2 E = B^2 = A^^2 F = B^3 = A^^3 G = A^^^ = A^1^1^1 = A~3 H = D^2 = B^^2 = A^^^2 = A~2^2 I = F^ = B^3^ = A^^3^ J = F^2 = B^3^2 = A^^3^2
SPECIFYING RANGES¶
History traversing commands such as git log operate on a set of commits, not just a single commit. To these commands, specifying a single revision with the notation described in the previous section means the set of commits reachable from that commit, following the commit ancestry chain.D G H D D F G H I J D F ^G D H D ^D B E I J F B B...C G H D E B C ^D B C E I J F B C C^@ I J F F^! D G H D F
SEE ALSO¶
git-rev-parse(1)GIT¶
Part of the git(1) suite03/19/2016 | Git 1.7.10.4 |