peel_onion(): teach $foo^{object} peeler
[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--------
7791a1d9 11[verse]
b1889c36 12'git rev-parse' [ --option ] <args>...
7fc9d69f
JH
13
14DESCRIPTION
15-----------
5077fa9c 16
abda1ef5 17Many git porcelainish commands take mixture of flags
5077fa9c 18(i.e. parameters that begin with a dash '-') and parameters
0b444cdb 19meant for the underlying 'git rev-list' command they use internally
483bc4f0 20and flags and parameters for the other commands they use
0b444cdb 21downstream of 'git rev-list'. This command is used to
5077fa9c 22distinguish between them.
7fc9d69f
JH
23
24
25OPTIONS
26-------
21d47835 27--parseopt::
0b444cdb 28 Use 'git rev-parse' in option parsing mode (see PARSEOPT section below).
21d47835 29
2163e3f7 30--keep-dashdash::
21d47835
PH
31 Only meaningful in `--parseopt` mode. Tells the option parser to echo
32 out the first `--` met instead of skipping it.
33
6e0800ef
UKK
34--stop-at-non-option::
35 Only meaningful in `--parseopt` mode. Lets the option parser stop at
36 the first non-option argument. This can be used to parse sub-commands
6a5d0b0a 37 that take options themselves.
6e0800ef 38
50325377 39--sq-quote::
0b444cdb 40 Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE
50325377
CC
41 section below). In contrast to the `--sq` option below, this
42 mode does only quoting. Nothing else is done to command input.
43
5077fa9c
JH
44--revs-only::
45 Do not output flags and parameters not meant for
0b444cdb 46 'git rev-list' command.
5077fa9c
JH
47
48--no-revs::
49 Do not output flags and parameters meant for
0b444cdb 50 'git rev-list' command.
5077fa9c
JH
51
52--flags::
53 Do not output non-flag parameters.
54
55--no-flags::
56 Do not output flag parameters.
57
58--default <arg>::
59 If there is no parameter given by the user, use `<arg>`
60 instead.
61
62--verify::
63 The parameter given must be usable as a single, valid
64 object name. Otherwise barf and abort.
65
3240240f
SB
66-q::
67--quiet::
b1b35969
CC
68 Only meaningful in `--verify` mode. Do not output an error
69 message if the first argument is not a valid object name;
70 instead exit with non-zero status silently.
71
5077fa9c
JH
72--sq::
73 Usually the output is made one line per flag and
74 parameter. This option makes output a single line,
75 properly quoted for consumption by shell. Useful when
76 you expect your parameter to contain whitespaces and
77 newlines (e.g. when using pickaxe `-S` with
4cacbf67 78 'git diff-{asterisk}'). In contrast to the `--sq-quote` option,
50325377 79 the command input is still interpreted as usual.
5077fa9c
JH
80
81--not::
babfaba2
JF
82 When showing object names, prefix them with '{caret}' and
83 strip '{caret}' prefix from the object names that already have
5077fa9c
JH
84 one.
85
86--symbolic::
87 Usually the object names are output in SHA1 form (with
babfaba2 88 possible '{caret}' prefix); this option makes them output in a
5077fa9c
JH
89 form as close to the original input as possible.
90
a6d97d49
JH
91--symbolic-full-name::
92 This is similar to \--symbolic, but it omits input that
93 are not refs (i.e. branch or tag names; or more
94 explicitly disambiguating "heads/master" form, when you
95 want to name the "master" branch when there is an
96 unfortunately named tag "master"), and show them as full
97 refnames (e.g. "refs/heads/master").
5077fa9c 98
0adda936 99--abbrev-ref[=(strict|loose)]::
a45d3469
BW
100 A non-ambiguous short name of the objects name.
101 The option core.warnAmbiguousRefs is used to select the strict
102 abbreviation mode.
103
957d7406
JH
104--disambiguate=<prefix>::
105 Show every object whose name begins with the given prefix.
106 The <prefix> must be at least 4 hexadecimal digits long to
107 avoid listing each and every object in the repository by
108 mistake.
109
5077fa9c 110--all::
cc1b8d8b 111 Show all refs found in `refs/`.
5077fa9c 112
b09fe971 113--branches[=pattern]::
b09fe971 114--tags[=pattern]::
b09fe971 115--remotes[=pattern]::
e2b53e58 116 Show all branches, tags, or remote-tracking branches,
cc1b8d8b
JK
117 respectively (i.e., refs found in `refs/heads`,
118 `refs/tags`, or `refs/remotes`, respectively).
e2b53e58
TR
119+
120If a `pattern` is given, only refs matching the given shell glob are
121shown. If the pattern does not contain a globbing character (`?`,
6cf378f0 122`*`, or `[`), it is turned into a prefix match by appending `/*`.
e2b53e58
TR
123
124--glob=pattern::
125 Show all refs matching the shell glob pattern `pattern`. If
126 the pattern does not start with `refs/`, this is automatically
127 prepended. If the pattern does not contain a globbing
6cf378f0
JK
128 character (`?`, `*`, or `[`), it is turned into a prefix
129 match by appending `/*`.
a62be77f 130
7cceca5c
SD
131--show-toplevel::
132 Show the absolute path of the top-level directory.
133
5077fa9c 134--show-prefix::
5f94c730 135 When the command is invoked from a subdirectory, show the
5077fa9c
JH
136 path of the current directory relative to the top-level
137 directory.
7fc9d69f 138
5f94c730
JH
139--show-cdup::
140 When the command is invoked from a subdirectory, show the
141 path of the top-level directory relative to the current
142 directory (typically a sequence of "../", or an empty string).
143
735d80b3 144--git-dir::
80d868b0 145 Show `$GIT_DIR` if defined. Otherwise show the path to
d0740ce0
JS
146 the .git directory. The path shown, when relative, is
147 relative to the current working directory.
80d868b0
JN
148+
149If `$GIT_DIR` is not defined and the current directory
150is not detected to lie in a git repository or work tree
151print a message to stderr and exit with nonzero status.
735d80b3 152
c9bf7be2 153--is-inside-git-dir::
4faac246
ML
154 When the current working directory is below the repository
155 directory print "true", otherwise "false".
156
892c41b9
ML
157--is-inside-work-tree::
158 When the current working directory is inside the work tree of the
159 repository print "true", otherwise "false".
160
493c774e
ML
161--is-bare-repository::
162 When the repository is bare print "true", otherwise "false".
c9bf7be2 163
94c8ccaa
GB
164--local-env-vars::
165 List the GIT_* environment variables that are local to the
166 repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR).
167 Only the names of the variables are listed, not their value,
168 even if they are set.
169
3240240f
SB
170--short::
171--short=number::
735d80b3 172 Instead of outputting the full SHA1 values of object names try to
abda1ef5 173 abbreviate them to a shorter unique name. When no length is specified
735d80b3
JF
174 7 is used. The minimum length is 4.
175
3240240f
SB
176--since=datestring::
177--after=datestring::
483bc4f0 178 Parse the date string, and output the corresponding
0b444cdb 179 --max-age= parameter for 'git rev-list'.
a3114b34 180
3240240f
SB
181--until=datestring::
182--before=datestring::
483bc4f0 183 Parse the date string, and output the corresponding
0b444cdb 184 --min-age= parameter for 'git rev-list'.
a3114b34 185
7fc9d69f 186<args>...::
5077fa9c 187 Flags and parameters to be parsed.
7fc9d69f 188
abc06822
FG
189--resolve-git-dir <path>::
190 Check if <path> is a valid git-dir or a git-file pointing to a valid
191 git-dir. If <path> is a valid git-dir the resolved path to git-dir will
192 be printed.
7fc9d69f 193
5a8f3117 194include::revisions.txt[]
be4c7014 195
21d47835
PH
196PARSEOPT
197--------
198
0b444cdb 199In `--parseopt` mode, 'git rev-parse' helps massaging options to bring to shell
21d47835
PH
200scripts the same facilities C builtins have. It works as an option normalizer
201(e.g. splits single switches aggregate values), a bit like `getopt(1)` does.
202
203It takes on the standard input the specification of the options to parse and
ac2e1e63 204understand, and echoes on the standard output a string suitable for `sh(1)` `eval`
21d47835
PH
205to replace the arguments with normalized ones. In case of error, it outputs
206usage on the standard error stream, and exits with code 129.
207
ac2e1e63
TR
208Note: Make sure you quote the result when passing it to `eval`. See
209below for an example.
210
21d47835
PH
211Input Format
212~~~~~~~~~~~~
213
0b444cdb 214'git rev-parse --parseopt' input format is fully text based. It has two parts,
21d47835
PH
215separated by a line that contains only `--`. The lines before the separator
216(should be more than one) are used for the usage.
217The lines after the separator describe the options.
218
219Each line of options has this format:
220
221------------
ff962a3f 222<opt_spec><flags>* SP+ help LF
21d47835
PH
223------------
224
225`<opt_spec>`::
226 its format is the short option character, then the long option name
227 separated by a comma. Both parts are not required, though at least one
228 is necessary. `h,help`, `dry-run` and `f` are all three correct
229 `<opt_spec>`.
230
ff962a3f
PH
231`<flags>`::
232 `<flags>` are of `*`, `=`, `?` or `!`.
233 * Use `=` if the option takes an argument.
234
235 * Use `?` to mean that the option is optional (though its use is discouraged).
236
237 * Use `*` to mean that this option should not be listed in the usage
238 generated for the `-h` argument. It's shown for `--help-all` as
a5af0e2c 239 documented in linkgit:gitcli[7].
ff962a3f
PH
240
241 * Use `!` to not make the corresponding negated long option available.
21d47835
PH
242
243The remainder of the line, after stripping the spaces, is used
244as the help associated to the option.
245
246Blank lines are ignored, and lines that don't match this specification are used
247as option group headers (start the line with a space to create such
248lines on purpose).
249
250Example
251~~~~~~~
252
253------------
254OPTS_SPEC="\
255some-command [options] <args>...
256
257some-command does foo and bar!
258--
259h,help show the help
260
261foo some nifty option --foo
262bar= some cool option --bar with an argument
263
264 An option group Header
265C? option C with an optional argument"
266
ac2e1e63 267eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)"
21d47835
PH
268------------
269
50325377
CC
270SQ-QUOTE
271--------
272
0b444cdb 273In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a
50325377
CC
274single line suitable for `sh(1)` `eval`. This line is made by
275normalizing the arguments following `--sq-quote`. Nothing other than
276quoting the arguments is done.
277
278If you want command input to still be interpreted as usual by
0b444cdb 279'git rev-parse' before the output is shell quoted, see the `--sq`
50325377
CC
280option.
281
282Example
283~~~~~~~
284
285------------
286$ cat >your-git-script.sh <<\EOF
287#!/bin/sh
288args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments
289command="git frotz -n24 $args" # and use it inside a handcrafted
290 # command line
291eval "$command"
292EOF
293
294$ sh your-git-script.sh "a b'c"
295------------
296
824b5dc2
CC
297EXAMPLES
298--------
299
300* Print the object name of the current commit:
301+
302------------
303$ git rev-parse --verify HEAD
304------------
305
306* Print the commit object name from the revision in the $REV shell variable:
307+
308------------
309$ git rev-parse --verify $REV
310------------
311+
312This will error out if $REV is empty or not a valid revision.
313
314* Same as above:
315+
316------------
317$ git rev-parse --default master --verify $REV
318------------
319+
320but if $REV is empty, the commit object name from master will be printed.
321
7fc9d69f
JH
322GIT
323---
9e1f0a85 324Part of the linkgit:git[1] suite