path.c: group git_path(), git_pathdup() and strbuf_git_path() together
[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
2de9b711 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-------
49c63913
JK
27
28Operation Modes
29~~~~~~~~~~~~~~~
30
31Each of these options must appear first on the command line.
32
21d47835 33--parseopt::
0b444cdb 34 Use 'git rev-parse' in option parsing mode (see PARSEOPT section below).
21d47835 35
49c63913
JK
36--sq-quote::
37 Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE
38 section below). In contrast to the `--sq` option below, this
39 mode does only quoting. Nothing else is done to command input.
40
41Options for --parseopt
42~~~~~~~~~~~~~~~~~~~~~~
43
2163e3f7 44--keep-dashdash::
21d47835
PH
45 Only meaningful in `--parseopt` mode. Tells the option parser to echo
46 out the first `--` met instead of skipping it.
47
6e0800ef
UKK
48--stop-at-non-option::
49 Only meaningful in `--parseopt` mode. Lets the option parser stop at
50 the first non-option argument. This can be used to parse sub-commands
6a5d0b0a 51 that take options themselves.
6e0800ef 52
f8c87212
NV
53--stuck-long::
54 Only meaningful in `--parseopt` mode. Output the options in their
55 long form if available, and with their arguments stuck.
56
49c63913
JK
57Options for Filtering
58~~~~~~~~~~~~~~~~~~~~~
50325377 59
5077fa9c
JH
60--revs-only::
61 Do not output flags and parameters not meant for
0b444cdb 62 'git rev-list' command.
5077fa9c
JH
63
64--no-revs::
65 Do not output flags and parameters meant for
0b444cdb 66 'git rev-list' command.
5077fa9c
JH
67
68--flags::
69 Do not output non-flag parameters.
70
71--no-flags::
72 Do not output flag parameters.
73
49c63913
JK
74Options for Output
75~~~~~~~~~~~~~~~~~~
76
5077fa9c
JH
77--default <arg>::
78 If there is no parameter given by the user, use `<arg>`
79 instead.
80
12b9d327
JK
81--prefix <arg>::
82 Behave as if 'git rev-parse' was invoked from the `<arg>`
83 subdirectory of the working tree. Any relative filenames are
84 resolved as if they are prefixed by `<arg>` and will be printed
85 in that form.
86+
87This can be used to convert arguments to a command run in a subdirectory
88so that they can still be used after moving to the top-level of the
89repository. For example:
90+
91----
92prefix=$(git rev-parse --show-prefix)
93cd "$(git rev-parse --show-toplevel)"
94eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")"
95----
96
5077fa9c 97--verify::
2db60670
MH
98 Verify that exactly one parameter is provided, and that it
99 can be turned into a raw 20-byte SHA-1 that can be used to
100 access the object database. If so, emit it to the standard
101 output; otherwise, error out.
102+
103If you want to make sure that the output actually names an object in
104your object database and/or can be used as a specific type of object
e6aaa393 105you require, you can add "\^{type}" peeling operator to the parameter.
2db60670
MH
106For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR`
107names an existing object that is a commit-ish (i.e. a commit, or an
108annotated tag that points at a commit). To make sure that `$VAR`
109names an existing object of any type, `git rev-parse "$VAR^{object}"`
110can be used.
5077fa9c 111
3240240f
SB
112-q::
113--quiet::
b1b35969
CC
114 Only meaningful in `--verify` mode. Do not output an error
115 message if the first argument is not a valid object name;
116 instead exit with non-zero status silently.
56625df7 117 SHA-1s for valid object names are printed to stdout on success.
b1b35969 118
5077fa9c
JH
119--sq::
120 Usually the output is made one line per flag and
121 parameter. This option makes output a single line,
122 properly quoted for consumption by shell. Useful when
123 you expect your parameter to contain whitespaces and
124 newlines (e.g. when using pickaxe `-S` with
4cacbf67 125 'git diff-{asterisk}'). In contrast to the `--sq-quote` option,
50325377 126 the command input is still interpreted as usual.
5077fa9c
JH
127
128--not::
babfaba2
JF
129 When showing object names, prefix them with '{caret}' and
130 strip '{caret}' prefix from the object names that already have
5077fa9c
JH
131 one.
132
49c63913
JK
133--abbrev-ref[=(strict|loose)]::
134 A non-ambiguous short name of the objects name.
135 The option core.warnAmbiguousRefs is used to select the strict
136 abbreviation mode.
137
138--short::
139--short=number::
140 Instead of outputting the full SHA-1 values of object names try to
141 abbreviate them to a shorter unique name. When no length is specified
142 7 is used. The minimum length is 4.
143
5077fa9c 144--symbolic::
d5fa1f1a 145 Usually the object names are output in SHA-1 form (with
babfaba2 146 possible '{caret}' prefix); this option makes them output in a
5077fa9c
JH
147 form as close to the original input as possible.
148
a6d97d49
JH
149--symbolic-full-name::
150 This is similar to \--symbolic, but it omits input that
151 are not refs (i.e. branch or tag names; or more
152 explicitly disambiguating "heads/master" form, when you
153 want to name the "master" branch when there is an
154 unfortunately named tag "master"), and show them as full
155 refnames (e.g. "refs/heads/master").
5077fa9c 156
49c63913
JK
157Options for Objects
158~~~~~~~~~~~~~~~~~~~
957d7406 159
5077fa9c 160--all::
cc1b8d8b 161 Show all refs found in `refs/`.
5077fa9c 162
b09fe971 163--branches[=pattern]::
b09fe971 164--tags[=pattern]::
b09fe971 165--remotes[=pattern]::
e2b53e58 166 Show all branches, tags, or remote-tracking branches,
cc1b8d8b
JK
167 respectively (i.e., refs found in `refs/heads`,
168 `refs/tags`, or `refs/remotes`, respectively).
e2b53e58
TR
169+
170If a `pattern` is given, only refs matching the given shell glob are
171shown. If the pattern does not contain a globbing character (`?`,
6cf378f0 172`*`, or `[`), it is turned into a prefix match by appending `/*`.
e2b53e58
TR
173
174--glob=pattern::
175 Show all refs matching the shell glob pattern `pattern`. If
176 the pattern does not start with `refs/`, this is automatically
177 prepended. If the pattern does not contain a globbing
6cf378f0
JK
178 character (`?`, `*`, or `[`), it is turned into a prefix
179 match by appending `/*`.
a62be77f 180
9dc01bf0
JH
181--exclude=<glob-pattern>::
182 Do not include refs matching '<glob-pattern>' that the next `--all`,
183 `--branches`, `--tags`, `--remotes`, or `--glob` would otherwise
184 consider. Repetitions of this option accumulate exclusion patterns
185 up to the next `--all`, `--branches`, `--tags`, `--remotes`, or
186 `--glob` option (other options or arguments do not clear
f745acb0 187 accumulated patterns).
9dc01bf0
JH
188+
189The patterns given should not begin with `refs/heads`, `refs/tags`, or
190`refs/remotes` when applied to `--branches`, `--tags`, or `--remotes`,
191respectively, and they must begin with `refs/` when applied to `--glob`
192or `--all`. If a trailing '/{asterisk}' is intended, it must be given
193explicitly.
194
49c63913
JK
195--disambiguate=<prefix>::
196 Show every object whose name begins with the given prefix.
197 The <prefix> must be at least 4 hexadecimal digits long to
198 avoid listing each and every object in the repository by
199 mistake.
7cceca5c 200
49c63913
JK
201Options for Files
202~~~~~~~~~~~~~~~~~
7fc9d69f 203
49c63913
JK
204--local-env-vars::
205 List the GIT_* environment variables that are local to the
206 repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR).
207 Only the names of the variables are listed, not their value,
208 even if they are set.
5f94c730 209
735d80b3 210--git-dir::
80d868b0 211 Show `$GIT_DIR` if defined. Otherwise show the path to
d0740ce0
JS
212 the .git directory. The path shown, when relative, is
213 relative to the current working directory.
80d868b0
JN
214+
215If `$GIT_DIR` is not defined and the current directory
2de9b711 216is not detected to lie in a Git repository or work tree
80d868b0 217print a message to stderr and exit with nonzero status.
735d80b3 218
c9bf7be2 219--is-inside-git-dir::
4faac246
ML
220 When the current working directory is below the repository
221 directory print "true", otherwise "false".
222
892c41b9
ML
223--is-inside-work-tree::
224 When the current working directory is inside the work tree of the
225 repository print "true", otherwise "false".
226
493c774e
ML
227--is-bare-repository::
228 When the repository is bare print "true", otherwise "false".
c9bf7be2 229
49c63913
JK
230--resolve-git-dir <path>::
231 Check if <path> is a valid repository or a gitfile that
232 points at a valid repository, and print the location of the
233 repository. If <path> is a gitfile then the resolved path
234 to the real repository is printed.
94c8ccaa 235
49c63913
JK
236--show-cdup::
237 When the command is invoked from a subdirectory, show the
238 path of the top-level directory relative to the current
239 directory (typically a sequence of "../", or an empty string).
240
241--show-prefix::
242 When the command is invoked from a subdirectory, show the
243 path of the current directory relative to the top-level
244 directory.
245
246--show-toplevel::
247 Show the absolute path of the top-level directory.
248
a76295da
NTND
249--shared-index-path::
250 Show the path to the shared index file in split index mode, or
251 empty if not in split-index mode.
252
49c63913
JK
253Other Options
254~~~~~~~~~~~~~
735d80b3 255
3240240f
SB
256--since=datestring::
257--after=datestring::
483bc4f0 258 Parse the date string, and output the corresponding
0b444cdb 259 --max-age= parameter for 'git rev-list'.
a3114b34 260
3240240f
SB
261--until=datestring::
262--before=datestring::
483bc4f0 263 Parse the date string, and output the corresponding
0b444cdb 264 --min-age= parameter for 'git rev-list'.
a3114b34 265
7fc9d69f 266<args>...::
5077fa9c 267 Flags and parameters to be parsed.
7fc9d69f
JH
268
269
5a8f3117 270include::revisions.txt[]
be4c7014 271
21d47835
PH
272PARSEOPT
273--------
274
0b444cdb 275In `--parseopt` mode, 'git rev-parse' helps massaging options to bring to shell
21d47835
PH
276scripts the same facilities C builtins have. It works as an option normalizer
277(e.g. splits single switches aggregate values), a bit like `getopt(1)` does.
278
279It takes on the standard input the specification of the options to parse and
ac2e1e63 280understand, and echoes on the standard output a string suitable for `sh(1)` `eval`
21d47835
PH
281to replace the arguments with normalized ones. In case of error, it outputs
282usage on the standard error stream, and exits with code 129.
283
ac2e1e63
TR
284Note: Make sure you quote the result when passing it to `eval`. See
285below for an example.
286
21d47835
PH
287Input Format
288~~~~~~~~~~~~
289
0b444cdb 290'git rev-parse --parseopt' input format is fully text based. It has two parts,
21d47835 291separated by a line that contains only `--`. The lines before the separator
9bab5b60 292(should be one or more) are used for the usage.
21d47835
PH
293The lines after the separator describe the options.
294
295Each line of options has this format:
296
297------------
e703d711 298<opt-spec><flags>*<arg-hint>? SP+ help LF
21d47835
PH
299------------
300
e703d711 301`<opt-spec>`::
21d47835
PH
302 its format is the short option character, then the long option name
303 separated by a comma. Both parts are not required, though at least one
304 is necessary. `h,help`, `dry-run` and `f` are all three correct
e703d711 305 `<opt-spec>`.
21d47835 306
ff962a3f
PH
307`<flags>`::
308 `<flags>` are of `*`, `=`, `?` or `!`.
309 * Use `=` if the option takes an argument.
310
f8c87212
NV
311 * Use `?` to mean that the option takes an optional argument. You
312 probably want to use the `--stuck-long` mode to be able to
313 unambiguously parse the optional argument.
ff962a3f
PH
314
315 * Use `*` to mean that this option should not be listed in the usage
316 generated for the `-h` argument. It's shown for `--help-all` as
a5af0e2c 317 documented in linkgit:gitcli[7].
ff962a3f
PH
318
319 * Use `!` to not make the corresponding negated long option available.
21d47835 320
e703d711
JH
321`<arg-hint>`::
322 `<arg-hint>`, if specified, is used as a name of the argument in the
323 help output, for options that take arguments. `<arg-hint>` is
324 terminated by the first whitespace. It is customary to use a
325 dash to separate words in a multi-word argument hint.
9bab5b60 326
21d47835
PH
327The remainder of the line, after stripping the spaces, is used
328as the help associated to the option.
329
330Blank lines are ignored, and lines that don't match this specification are used
331as option group headers (start the line with a space to create such
332lines on purpose).
333
334Example
335~~~~~~~
336
337------------
338OPTS_SPEC="\
339some-command [options] <args>...
340
341some-command does foo and bar!
342--
343h,help show the help
344
345foo some nifty option --foo
346bar= some cool option --bar with an argument
9bab5b60
IB
347baz=arg another cool option --baz with a named argument
348qux?path qux may take a path argument but has meaning by itself
21d47835
PH
349
350 An option group Header
351C? option C with an optional argument"
352
ac2e1e63 353eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)"
21d47835
PH
354------------
355
9bab5b60
IB
356
357Usage text
358~~~~~~~~~~
359
360When `"$@"` is `-h` or `--help` in the above example, the following
361usage text would be shown:
362
363------------
364usage: some-command [options] <args>...
365
366 some-command does foo and bar!
367
368 -h, --help show the help
369 --foo some nifty option --foo
370 --bar ... some cool option --bar with an argument
a2df5211 371 --baz <arg> another cool option --baz with a named argument
9bab5b60
IB
372 --qux[=<path>] qux may take a path argument but has meaning by itself
373
374An option group Header
375 -C[...] option C with an optional argument
376------------
377
50325377
CC
378SQ-QUOTE
379--------
380
0b444cdb 381In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a
50325377
CC
382single line suitable for `sh(1)` `eval`. This line is made by
383normalizing the arguments following `--sq-quote`. Nothing other than
384quoting the arguments is done.
385
386If you want command input to still be interpreted as usual by
0b444cdb 387'git rev-parse' before the output is shell quoted, see the `--sq`
50325377
CC
388option.
389
390Example
391~~~~~~~
392
393------------
394$ cat >your-git-script.sh <<\EOF
395#!/bin/sh
396args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments
397command="git frotz -n24 $args" # and use it inside a handcrafted
398 # command line
399eval "$command"
400EOF
401
402$ sh your-git-script.sh "a b'c"
403------------
404
824b5dc2
CC
405EXAMPLES
406--------
407
408* Print the object name of the current commit:
409+
410------------
411$ git rev-parse --verify HEAD
412------------
413
414* Print the commit object name from the revision in the $REV shell variable:
415+
416------------
2db60670 417$ git rev-parse --verify $REV^{commit}
824b5dc2
CC
418------------
419+
420This will error out if $REV is empty or not a valid revision.
421
2db60670 422* Similar to above:
824b5dc2
CC
423+
424------------
425$ git rev-parse --default master --verify $REV
426------------
427+
428but if $REV is empty, the commit object name from master will be printed.
429
7fc9d69f
JH
430GIT
431---
9e1f0a85 432Part of the linkgit:git[1] suite