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