1GITREVISIONS(7) Git Manual GITREVISIONS(7)
2
6 gitrevisions - specifying revisions and ranges for git
7
9 gitrevisions
10
12 Many Git commands take revision parameters as arguments. Depending on
13 the command, they denote a specific commit or, for commands which walk
14 the revision graph (such as git-log(1)), all commits which can be
15 reached from that commit. In the latter case one can also specify a
16 range of revisions explicitly.
17 In addition, some Git commands (such as git-show(1)) also take revision
19 parameters which denote other objects than commits, e.g. blobs
20 ("files") or trees ("directories of files").
21
23 A revision parameter typically, but not necessarily, names a commit
24 object. They use what is called an extended SHA1 syntax. Here are
25 various ways to spell object names. The ones listed near the end of
26 this list are to name trees and blobs contained in a commit.
27 · The full SHA1 object name (40-byte hexadecimal string), or a
29 substring of such that is unique within the repository. E.g.
30 dae86e1950b1277e545cee180551750029cfe735 and dae86e both name the
31 same commit object if there are no other object in your repository
32 whose object name starts with dae86e.
33 · An output from git describe; i.e. a closest tag, optionally
35 followed by a dash and a number of commits, followed by a dash, a
36 g, and an abbreviated object name.
37 · A symbolic ref name. E.g. master typically means the commit object
39 referenced by refs/heads/master. If you happen to have both
40 heads/master and tags/master, you can explicitly say heads/master
41 to tell git which one you mean. When ambiguous, a <name> is
42 disambiguated by taking the first match in the following rules:
43 1. if $GIT_DIR/<name> exists, that is what you mean (this is
45 usually useful only for HEAD, FETCH_HEAD, ORIG_HEAD and
46 MERGE_HEAD);
47 2. otherwise, refs/<name> if exists;
49 3. otherwise, refs/tags/<name> if exists;
51 4. otherwise, refs/heads/<name> if exists;
53 5. otherwise, refs/remotes/<name> if exists;
55 6. otherwise, refs/remotes/<name>/HEAD if exists.
57 HEAD names the commit your changes in the working tree is based
59 on. FETCH_HEAD records the branch you fetched from a remote
60 repository with your last git fetch invocation. ORIG_HEAD is
61 created by commands that moves your HEAD in a drastic way, to
62 record the position of the HEAD before their operation, so that
63 you can change the tip of the branch back to the state before
64 you ran them easily. MERGE_HEAD records the commit(s) you are
65 merging into your branch when you run git merge.
66 Note that any of the refs/* cases above may come either from
68 the $GIT_DIR/refs directory or from the $GIT_DIR/packed-refs
69 file.
70 · A ref followed by the suffix @ with a date specification enclosed
72 in a brace pair (e.g. {yesterday}, {1 month 2 weeks 3 days 1 hour
73 1 second ago} or {1979-02-26 18:30:00}) to specify the value of the
74 ref at a prior point in time. This suffix may only be used
75 immediately following a ref name and the ref must have an existing
76 log ($GIT_DIR/logs/<ref>). Note that this looks up the state of
77 your local ref at a given time; e.g., what was in your local master
78 branch last week. If you want to look at commits made during
79 certain times, see --since and --until.
80 · A ref followed by the suffix @ with an ordinal specification
82 enclosed in a brace pair (e.g. {1}, {15}) to specify the n-th
83 prior value of that ref. For example master@{1} is the immediate
84 prior value of master while master@{5} is the 5th prior value of
85 master. This suffix may only be used immediately following a ref
86 name and the ref must have an existing log ($GIT_DIR/logs/<ref>).
87 · You can use the @ construct with an empty ref part to get at a
89 reflog of the current branch. For example, if you are on the branch
90 blabla, then @{1} means the same as blabla@{1}.
91 · The special construct @{-<n>} means the <n>th branch checked out
93 before the current one.
94 · The suffix @{upstream} to a ref (short form ref@{u}) refers to the
96 branch the ref is set to build on top of. Missing ref defaults to
97 the current branch.
98 · A suffix ^ to a revision parameter (e.g. HEAD^) means the first
100 parent of that commit object. ^<n> means the <n>th parent (i.e.
101 rev^ is equivalent to rev^1). As a special rule, rev^0 means the
102 commit itself and is used when rev is the object name of a tag
103 object that refers to a commit object.
104 · A suffix ~<n> to a revision parameter means the commit object that
106 is the <n>th generation grand-parent of the named commit object,
107 following only the first parent. I.e. rev~3 is equivalent to rev^^^
108 which is equivalent to rev^1^1^1. See below for a illustration of
109 the usage of this form.
110 · A suffix ^ followed by an object type name enclosed in brace pair
112 (e.g. v0.99.8^{commit}) means the object could be a tag, and
113 dereference the tag recursively until an object of that type is
114 found or the object cannot be dereferenced anymore (in which case,
115 barf). rev^0 introduced earlier is a short-hand for rev^{commit}.
116 · A suffix ^ followed by an empty brace pair (e.g. v0.99.8^{}) means
118 the object could be a tag, and dereference the tag recursively
119 until a non-tag object is found.
120 · A suffix ^ to a revision parameter followed by a brace pair that
122 contains a text led by a slash (e.g. HEAD^{/fix nasty bug}): this
123 is the same as :/fix nasty bug syntax below except that it returns
124 the youngest matching commit which is reachable from the ref before
125 ^.
126 · A colon, followed by a slash, followed by a text (e.g. :/fix nasty
128 bug): this names a commit whose commit message matches the
129 specified regular expression. This name returns the youngest
130 matching commit which is reachable from any ref. If the commit
131 message starts with a !, you have to repeat that; the special
132 sequence :/!, followed by something else than ! is reserved for
133 now. The regular expression can match any part of the commit
134 message. To match messages starting with a string, one can use e.g.
135 :/^foo.
136 · A suffix : followed by a path (e.g. HEAD:README); this names the
138 blob or tree at the given path in the tree-ish object named by the
139 part before the colon. :path (with an empty part before the colon,
140 e.g. :README) is a special case of the syntax described next:
141 content recorded in the index at the given path. A path starting
142 with ./ or ../ is relative to current working directory. The given
143 path will be converted to be relative to working tree’s root
144 directory. This is most useful to address a blob or tree from a
145 commit or tree that has the same tree structure with the working
146 tree.
147 · A colon, optionally followed by a stage number (0 to 3) and a
149 colon, followed by a path (e.g. :0:README); this names a blob
150 object in the index at the given path. Missing stage number (and
151 the colon that follows it, e.g. :README) names a stage 0 entry.
152 During a merge, stage 1 is the common ancestor, stage 2 is the
153 target branch’s version (typically the current branch), and stage 3
154 is the version from the branch being merged.
155 Here is an illustration, by Jon Loeliger. Both commit nodes B and C are
157 parents of commit node A. Parent commits are ordered left-to-right.
158 G H I J
160 \ / \ /
161 D E F
162 \ | / \
163 \ | / |
164 \|/ |
165 B C
166 \ /
167 \ /
168 A
169 A = = A^0
171 B = A^ = A^1 = A~1
172 C = A^2 = A^2
173 D = A^^ = A^1^1 = A~2
174 E = B^2 = A^^2
175 F = B^3 = A^^3
176 G = A^^^ = A^1^1^1 = A~3
177 H = D^2 = B^^2 = A^^^2 = A~2^2
178 I = F^ = B^3^ = A^^3^
179 J = F^2 = B^3^2 = A^^3^2
180
182 History traversing commands such as git log operate on a set of
183 commits, not just a single commit. To these commands, specifying a
184 single revision with the notation described in the previous section
185 means the set of commits reachable from that commit, following the
186 commit ancestry chain.
187 To exclude commits reachable from a commit, a prefix ^ notation is
189 used. E.g. ^r1 r2 means commits reachable from r2 but exclude the ones
190 reachable from r1.
191 This set operation appears so often that there is a shorthand for it.
193 When you have two commits r1 and r2 (named according to the syntax
194 explained in SPECIFYING REVISIONS above), you can ask for commits that
195 are reachable from r2 excluding those that are reachable from r1 by ^r1
196 r2 and it can be written as r1..r2.
197 A similar notation r1...r2 is called symmetric difference of r1 and r2
199 and is defined as r1 r2 --not $(git merge-base --all r1 r2). It is the
200 set of commits that are reachable from either one of r1 or r2 but not
201 from both.
202 Two other shorthands for naming a set that is formed by a commit and
204 its parent commits exist. The r1^@ notation means all parents of r1.
205 r1^! includes commit r1 but excludes all of its parents.
206 Here are a handful of examples:
208 D G H D
210 D F G H I J D F
211 ^G D H D
212 ^D B E I J F B
213 B...C G H D E B C
214 ^D B C E I J F B C
215 C^@ I J F
216 F^! D G H D F
217
219 git-rev-parse(1)
220
222 Part of the git(1) suite
223Git 1.7.4.4 04/11/2011 GITREVISIONS(7)