Merge branch 'ho/shared'
[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-------
21d47835
PH
26--parseopt::
27 Use `git-rev-parse` in option parsing mode (see PARSEOPT section below).
28
29--keep-dash-dash::
30 Only meaningful in `--parseopt` mode. Tells the option parser to echo
31 out the first `--` met instead of skipping it.
32
5077fa9c
JH
33--revs-only::
34 Do not output flags and parameters not meant for
35 `git-rev-list` command.
36
37--no-revs::
38 Do not output flags and parameters meant for
39 `git-rev-list` command.
40
41--flags::
42 Do not output non-flag parameters.
43
44--no-flags::
45 Do not output flag parameters.
46
47--default <arg>::
48 If there is no parameter given by the user, use `<arg>`
49 instead.
50
51--verify::
52 The parameter given must be usable as a single, valid
53 object name. Otherwise barf and abort.
54
55--sq::
56 Usually the output is made one line per flag and
57 parameter. This option makes output a single line,
58 properly quoted for consumption by shell. Useful when
59 you expect your parameter to contain whitespaces and
60 newlines (e.g. when using pickaxe `-S` with
61 `git-diff-\*`).
62
63--not::
babfaba2
JF
64 When showing object names, prefix them with '{caret}' and
65 strip '{caret}' prefix from the object names that already have
5077fa9c
JH
66 one.
67
68--symbolic::
69 Usually the object names are output in SHA1 form (with
babfaba2 70 possible '{caret}' prefix); this option makes them output in a
5077fa9c
JH
71 form as close to the original input as possible.
72
a6d97d49
JH
73--symbolic-full-name::
74 This is similar to \--symbolic, but it omits input that
75 are not refs (i.e. branch or tag names; or more
76 explicitly disambiguating "heads/master" form, when you
77 want to name the "master" branch when there is an
78 unfortunately named tag "master"), and show them as full
79 refnames (e.g. "refs/heads/master").
5077fa9c
JH
80
81--all::
82 Show all refs found in `$GIT_DIR/refs`.
83
a62be77f
SE
84--branches::
85 Show branch refs found in `$GIT_DIR/refs/heads`.
86
87--tags::
88 Show tag refs found in `$GIT_DIR/refs/tags`.
89
90--remotes::
91 Show tag refs found in `$GIT_DIR/refs/remotes`.
92
5077fa9c 93--show-prefix::
5f94c730 94 When the command is invoked from a subdirectory, show the
5077fa9c
JH
95 path of the current directory relative to the top-level
96 directory.
7fc9d69f 97
5f94c730
JH
98--show-cdup::
99 When the command is invoked from a subdirectory, show the
100 path of the top-level directory relative to the current
101 directory (typically a sequence of "../", or an empty string).
102
735d80b3
JF
103--git-dir::
104 Show `$GIT_DIR` if defined else show the path to the .git directory.
105
c9bf7be2 106--is-inside-git-dir::
4faac246
ML
107 When the current working directory is below the repository
108 directory print "true", otherwise "false".
109
892c41b9
ML
110--is-inside-work-tree::
111 When the current working directory is inside the work tree of the
112 repository print "true", otherwise "false".
113
493c774e
ML
114--is-bare-repository::
115 When the repository is bare print "true", otherwise "false".
c9bf7be2 116
5102349c 117--short, --short=number::
735d80b3 118 Instead of outputting the full SHA1 values of object names try to
abda1ef5 119 abbreviate them to a shorter unique name. When no length is specified
735d80b3
JF
120 7 is used. The minimum length is 4.
121
a3114b34
JH
122--since=datestring, --after=datestring::
123 Parses the date string, and outputs corresponding
124 --max-age= parameter for git-rev-list command.
125
126--until=datestring, --before=datestring::
127 Parses the date string, and outputs corresponding
128 --min-age= parameter for git-rev-list command.
129
7fc9d69f 130<args>...::
5077fa9c 131 Flags and parameters to be parsed.
7fc9d69f
JH
132
133
3a45f625
JH
134SPECIFYING REVISIONS
135--------------------
136
622ef9df
JH
137A revision parameter typically, but not necessarily, names a
138commit object. They use what is called an 'extended SHA1'
6b09c788
NTND
139syntax. Here are various ways to spell object names. The
140ones listed near the end of this list are to name trees and
141blobs contained in a commit.
3a45f625
JH
142
143* The full SHA1 object name (40-byte hexadecimal string), or
144 a substring of such that is unique within the repository.
145 E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both
146 name the same commit object if there are no other object in
147 your repository whose object name starts with dae86e.
148
6b09c788 149* An output from `git-describe`; i.e. a closest tag, followed by a
0ac30568 150 dash, a `g`, and an abbreviated object name.
6b09c788 151
3a45f625
JH
152* A symbolic ref name. E.g. 'master' typically means the commit
153 object referenced by $GIT_DIR/refs/heads/master. If you
154 happen to have both heads/master and tags/master, you can
72e9340c 155 explicitly say 'heads/master' to tell git which one you mean.
0ac30568
JH
156 When ambiguous, a `<name>` is disambiguated by taking the
157 first match in the following rules:
3a45f625 158
0ac30568
JH
159 . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually
160 useful only for `HEAD`, `FETCH_HEAD` and `MERGE_HEAD`);
161
162 . otherwise, `$GIT_DIR/refs/<name>` if exists;
163
164 . otherwise, `$GIT_DIR/refs/tags/<name>` if exists;
165
166 . otherwise, `$GIT_DIR/refs/heads/<name>` if exists;
167
168 . otherwise, `$GIT_DIR/refs/remotes/<name>` if exists;
169
170 . otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists.
171
172* A ref followed by the suffix '@' with a date specification
173 enclosed in a brace
cce91a2c
SP
174 pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1
175 second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value
176 of the ref at a prior point in time. This suffix may only be
177 used immediately following a ref name and the ref must have an
178 existing log ($GIT_DIR/logs/<ref>).
d556fae2 179
ee53aff4
SP
180* A ref followed by the suffix '@' with an ordinal specification
181 enclosed in a brace pair (e.g. '\{1\}', '\{15\}') to specify
182 the n-th prior value of that ref. For example 'master@\{1\}'
183 is the immediate prior value of 'master' while 'master@\{5\}'
184 is the 5th prior value of 'master'. This suffix may only be used
185 immediately following a ref name and the ref must have an existing
186 log ($GIT_DIR/logs/<ref>).
187
1e5db307
JS
188* You can use the '@' construct with an empty ref part to get at a
189 reflog of the current branch. For example, if you are on the
190 branch 'blabla', then '@\{1\}' means the same as 'blabla@\{1\}'.
191
babfaba2
JF
192* A suffix '{caret}' to a revision parameter means the first parent of
193 that commit object. '{caret}<n>' means the <n>th parent (i.e.
194 'rev{caret}'
195 is equivalent to 'rev{caret}1'). As a special rule,
196 'rev{caret}0' means the commit itself and is used when 'rev' is the
3a45f625
JH
197 object name of a tag object that refers to a commit object.
198
54bd2558 199* A suffix '{tilde}<n>' to a revision parameter means the commit
3a45f625
JH
200 object that is the <n>th generation grand-parent of the named
201 commit object, following only the first parent. I.e. rev~3 is
0ac30568
JH
202 equivalent to rev{caret}{caret}{caret} which is equivalent to
203 rev{caret}1{caret}1{caret}1. See below for a illustration of
204 the usage of this form.
3a45f625 205
622ef9df
JH
206* A suffix '{caret}' followed by an object type name enclosed in
207 brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object
208 could be a tag, and dereference the tag recursively until an
209 object of that type is found or the object cannot be
210 dereferenced anymore (in which case, barf). `rev{caret}0`
211 introduced earlier is a short-hand for `rev{caret}\{commit\}`.
212
213* A suffix '{caret}' followed by an empty brace pair
214 (e.g. `v0.99.8{caret}\{\}`) means the object could be a tag,
215 and dereference the tag recursively until a non-tag object is
216 found.
217
28a4d940
JS
218* A colon, followed by a slash, followed by a text: this names
219 a commit whose commit message starts with the specified text.
220 This name returns the youngest matching commit which is
221 reachable from any ref. If the commit message starts with a
222 '!', you have to repeat that; the special sequence ':/!',
223 followed by something else than '!' is reserved for now.
224
6b09c788
NTND
225* A suffix ':' followed by a path; this names the blob or tree
226 at the given path in the tree-ish object named by the part
227 before the colon.
228
229* A colon, optionally followed by a stage number (0 to 3) and a
230 colon, followed by a path; this names a blob object in the
231 index at the given path. Missing stage number (and the colon
a5d86f74 232 that follows it) names a stage 0 entry. During a merge, stage
257a84d9
SG
233 1 is the common ancestor, stage 2 is the target branch's version
234 (typically the current branch), and stage 3 is the version from
235 the branch being merged.
6b09c788 236
da101b82
MV
237Here is an illustration, by Jon Loeliger. Both commit nodes B
238and C are parents of commit node A. Parent commits are ordered
2be8fd08
JH
239left-to-right.
240
241 G H I J
242 \ / \ /
243 D E F
f1ec6b22 244 \ | / \
be4c7014
JH
245 \ | / |
246 \|/ |
2be8fd08
JH
247 B C
248 \ /
249 \ /
250 A
251
252 A = = A^0
253 B = A^ = A^1 = A~1
254 C = A^2 = A^2
255 D = A^^ = A^1^1 = A~2
256 E = B^2 = A^^2
257 F = B^3 = A^^3
258 G = A^^^ = A^1^1^1 = A~3
259 H = D^2 = B^^2 = A^^^2 = A~2^2
260 I = F^ = B^3^ = A^^3^
261 J = F^2 = B^3^2 = A^^3^2
262
3a45f625 263
be4c7014
JH
264SPECIFYING RANGES
265-----------------
266
267History traversing commands such as `git-log` operate on a set
268of commits, not just a single commit. To these commands,
269specifying a single revision with the notation described in the
270previous section means the set of commits reachable from that
271commit, following the commit ancestry chain.
272
273To exclude commits reachable from a commit, a prefix `{caret}`
274notation is used. E.g. "`{caret}r1 r2`" means commits reachable
275from `r2` but exclude the ones reachable from `r1`.
276
277This set operation appears so often that there is a shorthand
278for it. "`r1..r2`" is equivalent to "`{caret}r1 r2`". It is
279the difference of two sets (subtract the set of commits
280reachable from `r1` from the set of commits reachable from
281`r2`).
282
283A similar notation "`r1\...r2`" is called symmetric difference
284of `r1` and `r2` and is defined as
285"`r1 r2 --not $(git-merge-base --all r1 r2)`".
e18ee576 286It is the set of commits that are reachable from either one of
be4c7014
JH
287`r1` or `r2` but not from both.
288
62476c8e
JH
289Two other shorthands for naming a set that is formed by a commit
290and its parent commits exists. `r1{caret}@` notation means all
291parents of `r1`. `r1{caret}!` includes commit `r1` but excludes
292its all parents.
293
a5d86f74 294Here are a handful of examples:
be4c7014 295
c2c6d930
GP
296 D G H D
297 D F G H I J D F
298 ^G D H D
299 ^D B E I J F B
300 B...C G H D E B C
301 ^D B C E I J F B C
302 C^@ I J F
303 F^! D G H D F
be4c7014 304
21d47835
PH
305PARSEOPT
306--------
307
308In `--parseopt` mode, `git-rev-parse` helps massaging options to bring to shell
309scripts the same facilities C builtins have. It works as an option normalizer
310(e.g. splits single switches aggregate values), a bit like `getopt(1)` does.
311
312It takes on the standard input the specification of the options to parse and
313understand, and echoes on the standard output a line suitable for `sh(1)` `eval`
314to replace the arguments with normalized ones. In case of error, it outputs
315usage on the standard error stream, and exits with code 129.
316
317Input Format
318~~~~~~~~~~~~
319
320`git-rev-parse --parseopt` input format is fully text based. It has two parts,
321separated by a line that contains only `--`. The lines before the separator
322(should be more than one) are used for the usage.
323The lines after the separator describe the options.
324
325Each line of options has this format:
326
327------------
ff962a3f 328<opt_spec><flags>* SP+ help LF
21d47835
PH
329------------
330
331`<opt_spec>`::
332 its format is the short option character, then the long option name
333 separated by a comma. Both parts are not required, though at least one
334 is necessary. `h,help`, `dry-run` and `f` are all three correct
335 `<opt_spec>`.
336
ff962a3f
PH
337`<flags>`::
338 `<flags>` are of `*`, `=`, `?` or `!`.
339 * Use `=` if the option takes an argument.
340
341 * Use `?` to mean that the option is optional (though its use is discouraged).
342
343 * Use `*` to mean that this option should not be listed in the usage
344 generated for the `-h` argument. It's shown for `--help-all` as
345 documented in linkgit:gitcli[5].
346
347 * Use `!` to not make the corresponding negated long option available.
21d47835
PH
348
349The remainder of the line, after stripping the spaces, is used
350as the help associated to the option.
351
352Blank lines are ignored, and lines that don't match this specification are used
353as option group headers (start the line with a space to create such
354lines on purpose).
355
356Example
357~~~~~~~
358
359------------
360OPTS_SPEC="\
361some-command [options] <args>...
362
363some-command does foo and bar!
364--
365h,help show the help
366
367foo some nifty option --foo
368bar= some cool option --bar with an argument
369
370 An option group Header
371C? option C with an optional argument"
372
373eval `echo "$OPTS_SPEC" | git-rev-parse --parseopt -- "$@" || echo exit $?`
374------------
375
376
7fc9d69f
JH
377Author
378------
21d47835
PH
379Written by Linus Torvalds <torvalds@osdl.org> .
380Junio C Hamano <junkio@cox.net> and Pierre Habouzit <madcoder@debian.org>
7fc9d69f
JH
381
382Documentation
383--------------
384Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
385
386GIT
387---
5162e697 388Part of the linkgit:git[7] suite