Merge branch 'maint'
[git/git.git] / Documentation / git-rev-parse.txt
CommitLineData
7fc9d69f
JH
1git-rev-parse(1)
2================
3
4NAME
5----
7bd7f280 6git-rev-parse - Pick out and massage parameters
7fc9d69f
JH
7
8
9SYNOPSIS
10--------
11'git-rev-parse' [ --option ] <args>...
12
13DESCRIPTION
14-----------
5077fa9c 15
abda1ef5 16Many git porcelainish commands take mixture of flags
5077fa9c
JH
17(i.e. parameters that begin with a dash '-') and parameters
18meant for underlying `git-rev-list` command they use internally
19and flags and parameters for other commands they use as the
20downstream of `git-rev-list`. This command is used to
21distinguish between them.
7fc9d69f
JH
22
23
24OPTIONS
25-------
5077fa9c
JH
26--revs-only::
27 Do not output flags and parameters not meant for
28 `git-rev-list` command.
29
30--no-revs::
31 Do not output flags and parameters meant for
32 `git-rev-list` command.
33
34--flags::
35 Do not output non-flag parameters.
36
37--no-flags::
38 Do not output flag parameters.
39
40--default <arg>::
41 If there is no parameter given by the user, use `<arg>`
42 instead.
43
44--verify::
45 The parameter given must be usable as a single, valid
46 object name. Otherwise barf and abort.
47
48--sq::
49 Usually the output is made one line per flag and
50 parameter. This option makes output a single line,
51 properly quoted for consumption by shell. Useful when
52 you expect your parameter to contain whitespaces and
53 newlines (e.g. when using pickaxe `-S` with
54 `git-diff-\*`).
55
56--not::
babfaba2
JF
57 When showing object names, prefix them with '{caret}' and
58 strip '{caret}' prefix from the object names that already have
5077fa9c
JH
59 one.
60
61--symbolic::
62 Usually the object names are output in SHA1 form (with
babfaba2 63 possible '{caret}' prefix); this option makes them output in a
5077fa9c
JH
64 form as close to the original input as possible.
65
66
67--all::
68 Show all refs found in `$GIT_DIR/refs`.
69
a62be77f
SE
70--branches::
71 Show branch refs found in `$GIT_DIR/refs/heads`.
72
73--tags::
74 Show tag refs found in `$GIT_DIR/refs/tags`.
75
76--remotes::
77 Show tag refs found in `$GIT_DIR/refs/remotes`.
78
5077fa9c 79--show-prefix::
5f94c730 80 When the command is invoked from a subdirectory, show the
5077fa9c
JH
81 path of the current directory relative to the top-level
82 directory.
7fc9d69f 83
5f94c730
JH
84--show-cdup::
85 When the command is invoked from a subdirectory, show the
86 path of the top-level directory relative to the current
87 directory (typically a sequence of "../", or an empty string).
88
735d80b3
JF
89--git-dir::
90 Show `$GIT_DIR` if defined else show the path to the .git directory.
91
c9bf7be2 92--is-inside-git-dir::
4faac246
ML
93 When the current working directory is below the repository
94 directory print "true", otherwise "false".
95
892c41b9
ML
96--is-inside-work-tree::
97 When the current working directory is inside the work tree of the
98 repository print "true", otherwise "false".
99
493c774e
ML
100--is-bare-repository::
101 When the repository is bare print "true", otherwise "false".
c9bf7be2 102
5102349c 103--short, --short=number::
735d80b3 104 Instead of outputting the full SHA1 values of object names try to
abda1ef5 105 abbreviate them to a shorter unique name. When no length is specified
735d80b3
JF
106 7 is used. The minimum length is 4.
107
a3114b34
JH
108--since=datestring, --after=datestring::
109 Parses the date string, and outputs corresponding
110 --max-age= parameter for git-rev-list command.
111
112--until=datestring, --before=datestring::
113 Parses the date string, and outputs corresponding
114 --min-age= parameter for git-rev-list command.
115
7fc9d69f 116<args>...::
5077fa9c 117 Flags and parameters to be parsed.
7fc9d69f
JH
118
119
3a45f625
JH
120SPECIFYING REVISIONS
121--------------------
122
622ef9df
JH
123A revision parameter typically, but not necessarily, names a
124commit object. They use what is called an 'extended SHA1'
6b09c788
NTND
125syntax. Here are various ways to spell object names. The
126ones listed near the end of this list are to name trees and
127blobs contained in a commit.
3a45f625
JH
128
129* The full SHA1 object name (40-byte hexadecimal string), or
130 a substring of such that is unique within the repository.
131 E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both
132 name the same commit object if there are no other object in
133 your repository whose object name starts with dae86e.
134
6b09c788 135* An output from `git-describe`; i.e. a closest tag, followed by a
0ac30568 136 dash, a `g`, and an abbreviated object name.
6b09c788 137
3a45f625
JH
138* A symbolic ref name. E.g. 'master' typically means the commit
139 object referenced by $GIT_DIR/refs/heads/master. If you
140 happen to have both heads/master and tags/master, you can
72e9340c 141 explicitly say 'heads/master' to tell git which one you mean.
0ac30568
JH
142 When ambiguous, a `<name>` is disambiguated by taking the
143 first match in the following rules:
3a45f625 144
0ac30568
JH
145 . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually
146 useful only for `HEAD`, `FETCH_HEAD` and `MERGE_HEAD`);
147
148 . otherwise, `$GIT_DIR/refs/<name>` if exists;
149
150 . otherwise, `$GIT_DIR/refs/tags/<name>` if exists;
151
152 . otherwise, `$GIT_DIR/refs/heads/<name>` if exists;
153
154 . otherwise, `$GIT_DIR/refs/remotes/<name>` if exists;
155
156 . otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists.
157
158* A ref followed by the suffix '@' with a date specification
159 enclosed in a brace
cce91a2c
SP
160 pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1
161 second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value
162 of the ref at a prior point in time. This suffix may only be
163 used immediately following a ref name and the ref must have an
164 existing log ($GIT_DIR/logs/<ref>).
d556fae2 165
ee53aff4
SP
166* A ref followed by the suffix '@' with an ordinal specification
167 enclosed in a brace pair (e.g. '\{1\}', '\{15\}') to specify
168 the n-th prior value of that ref. For example 'master@\{1\}'
169 is the immediate prior value of 'master' while 'master@\{5\}'
170 is the 5th prior value of 'master'. This suffix may only be used
171 immediately following a ref name and the ref must have an existing
172 log ($GIT_DIR/logs/<ref>).
173
1e5db307
JS
174* You can use the '@' construct with an empty ref part to get at a
175 reflog of the current branch. For example, if you are on the
176 branch 'blabla', then '@\{1\}' means the same as 'blabla@\{1\}'.
177
babfaba2
JF
178* A suffix '{caret}' to a revision parameter means the first parent of
179 that commit object. '{caret}<n>' means the <n>th parent (i.e.
180 'rev{caret}'
181 is equivalent to 'rev{caret}1'). As a special rule,
182 'rev{caret}0' means the commit itself and is used when 'rev' is the
3a45f625
JH
183 object name of a tag object that refers to a commit object.
184
54bd2558 185* A suffix '{tilde}<n>' to a revision parameter means the commit
3a45f625
JH
186 object that is the <n>th generation grand-parent of the named
187 commit object, following only the first parent. I.e. rev~3 is
0ac30568
JH
188 equivalent to rev{caret}{caret}{caret} which is equivalent to
189 rev{caret}1{caret}1{caret}1. See below for a illustration of
190 the usage of this form.
3a45f625 191
622ef9df
JH
192* A suffix '{caret}' followed by an object type name enclosed in
193 brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object
194 could be a tag, and dereference the tag recursively until an
195 object of that type is found or the object cannot be
196 dereferenced anymore (in which case, barf). `rev{caret}0`
197 introduced earlier is a short-hand for `rev{caret}\{commit\}`.
198
199* A suffix '{caret}' followed by an empty brace pair
200 (e.g. `v0.99.8{caret}\{\}`) means the object could be a tag,
201 and dereference the tag recursively until a non-tag object is
202 found.
203
28a4d940
JS
204* A colon, followed by a slash, followed by a text: this names
205 a commit whose commit message starts with the specified text.
206 This name returns the youngest matching commit which is
207 reachable from any ref. If the commit message starts with a
208 '!', you have to repeat that; the special sequence ':/!',
209 followed by something else than '!' is reserved for now.
210
6b09c788
NTND
211* A suffix ':' followed by a path; this names the blob or tree
212 at the given path in the tree-ish object named by the part
213 before the colon.
214
215* A colon, optionally followed by a stage number (0 to 3) and a
216 colon, followed by a path; this names a blob object in the
217 index at the given path. Missing stage number (and the colon
257a84d9
SG
218 that follows it) names an stage 0 entry. During a merge, stage
219 1 is the common ancestor, stage 2 is the target branch's version
220 (typically the current branch), and stage 3 is the version from
221 the branch being merged.
6b09c788 222
2be8fd08
JH
223Here is an illustration, by Jon Loeliger. Both node B and C are
224a commit parents of commit node A. Parent commits are ordered
225left-to-right.
226
227 G H I J
228 \ / \ /
229 D E F
f1ec6b22 230 \ | / \
be4c7014
JH
231 \ | / |
232 \|/ |
2be8fd08
JH
233 B C
234 \ /
235 \ /
236 A
237
238 A = = A^0
239 B = A^ = A^1 = A~1
240 C = A^2 = A^2
241 D = A^^ = A^1^1 = A~2
242 E = B^2 = A^^2
243 F = B^3 = A^^3
244 G = A^^^ = A^1^1^1 = A~3
245 H = D^2 = B^^2 = A^^^2 = A~2^2
246 I = F^ = B^3^ = A^^3^
247 J = F^2 = B^3^2 = A^^3^2
248
3a45f625 249
be4c7014
JH
250SPECIFYING RANGES
251-----------------
252
253History traversing commands such as `git-log` operate on a set
254of commits, not just a single commit. To these commands,
255specifying a single revision with the notation described in the
256previous section means the set of commits reachable from that
257commit, following the commit ancestry chain.
258
259To exclude commits reachable from a commit, a prefix `{caret}`
260notation is used. E.g. "`{caret}r1 r2`" means commits reachable
261from `r2` but exclude the ones reachable from `r1`.
262
263This set operation appears so often that there is a shorthand
264for it. "`r1..r2`" is equivalent to "`{caret}r1 r2`". It is
265the difference of two sets (subtract the set of commits
266reachable from `r1` from the set of commits reachable from
267`r2`).
268
269A similar notation "`r1\...r2`" is called symmetric difference
270of `r1` and `r2` and is defined as
271"`r1 r2 --not $(git-merge-base --all r1 r2)`".
e18ee576 272It is the set of commits that are reachable from either one of
be4c7014
JH
273`r1` or `r2` but not from both.
274
62476c8e
JH
275Two other shorthands for naming a set that is formed by a commit
276and its parent commits exists. `r1{caret}@` notation means all
277parents of `r1`. `r1{caret}!` includes commit `r1` but excludes
278its all parents.
279
280Here are a handful examples:
be4c7014 281
c2c6d930
GP
282 D G H D
283 D F G H I J D F
284 ^G D H D
285 ^D B E I J F B
286 B...C G H D E B C
287 ^D B C E I J F B C
288 C^@ I J F
289 F^! D G H D F
be4c7014 290
7fc9d69f
JH
291Author
292------
5077fa9c
JH
293Written by Linus Torvalds <torvalds@osdl.org> and
294Junio C Hamano <junkio@cox.net>
7fc9d69f
JH
295
296Documentation
297--------------
298Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
299
300GIT
301---
a7154e91 302Part of the gitlink:git[7] suite