Update draft release notes to 2.0
[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
17b83d71 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.
117
5077fa9c
JH
118--sq::
119 Usually the output is made one line per flag and
120 parameter. This option makes output a single line,
121 properly quoted for consumption by shell. Useful when
122 you expect your parameter to contain whitespaces and
123 newlines (e.g. when using pickaxe `-S` with
4cacbf67 124 'git diff-{asterisk}'). In contrast to the `--sq-quote` option,
50325377 125 the command input is still interpreted as usual.
5077fa9c
JH
126
127--not::
babfaba2
JF
128 When showing object names, prefix them with '{caret}' and
129 strip '{caret}' prefix from the object names that already have
5077fa9c
JH
130 one.
131
49c63913
JK
132--abbrev-ref[=(strict|loose)]::
133 A non-ambiguous short name of the objects name.
134 The option core.warnAmbiguousRefs is used to select the strict
135 abbreviation mode.
136
137--short::
138--short=number::
139 Instead of outputting the full SHA-1 values of object names try to
140 abbreviate them to a shorter unique name. When no length is specified
141 7 is used. The minimum length is 4.
142
5077fa9c 143--symbolic::
d5fa1f1a 144 Usually the object names are output in SHA-1 form (with
babfaba2 145 possible '{caret}' prefix); this option makes them output in a
5077fa9c
JH
146 form as close to the original input as possible.
147
a6d97d49
JH
148--symbolic-full-name::
149 This is similar to \--symbolic, but it omits input that
150 are not refs (i.e. branch or tag names; or more
151 explicitly disambiguating "heads/master" form, when you
152 want to name the "master" branch when there is an
153 unfortunately named tag "master"), and show them as full
154 refnames (e.g. "refs/heads/master").
5077fa9c 155
49c63913
JK
156Options for Objects
157~~~~~~~~~~~~~~~~~~~
957d7406 158
5077fa9c 159--all::
cc1b8d8b 160 Show all refs found in `refs/`.
5077fa9c 161
b09fe971 162--branches[=pattern]::
b09fe971 163--tags[=pattern]::
b09fe971 164--remotes[=pattern]::
e2b53e58 165 Show all branches, tags, or remote-tracking branches,
cc1b8d8b
JK
166 respectively (i.e., refs found in `refs/heads`,
167 `refs/tags`, or `refs/remotes`, respectively).
e2b53e58
TR
168+
169If a `pattern` is given, only refs matching the given shell glob are
170shown. If the pattern does not contain a globbing character (`?`,
6cf378f0 171`*`, or `[`), it is turned into a prefix match by appending `/*`.
e2b53e58
TR
172
173--glob=pattern::
174 Show all refs matching the shell glob pattern `pattern`. If
175 the pattern does not start with `refs/`, this is automatically
176 prepended. If the pattern does not contain a globbing
6cf378f0
JK
177 character (`?`, `*`, or `[`), it is turned into a prefix
178 match by appending `/*`.
a62be77f 179
9dc01bf0
JH
180--exclude=<glob-pattern>::
181 Do not include refs matching '<glob-pattern>' that the next `--all`,
182 `--branches`, `--tags`, `--remotes`, or `--glob` would otherwise
183 consider. Repetitions of this option accumulate exclusion patterns
184 up to the next `--all`, `--branches`, `--tags`, `--remotes`, or
185 `--glob` option (other options or arguments do not clear
186 accumlated patterns).
187+
188The patterns given should not begin with `refs/heads`, `refs/tags`, or
189`refs/remotes` when applied to `--branches`, `--tags`, or `--remotes`,
190respectively, and they must begin with `refs/` when applied to `--glob`
191or `--all`. If a trailing '/{asterisk}' is intended, it must be given
192explicitly.
193
49c63913
JK
194--disambiguate=<prefix>::
195 Show every object whose name begins with the given prefix.
196 The <prefix> must be at least 4 hexadecimal digits long to
197 avoid listing each and every object in the repository by
198 mistake.
7cceca5c 199
49c63913
JK
200Options for Files
201~~~~~~~~~~~~~~~~~
7fc9d69f 202
49c63913
JK
203--local-env-vars::
204 List the GIT_* environment variables that are local to the
205 repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR).
206 Only the names of the variables are listed, not their value,
207 even if they are set.
5f94c730 208
735d80b3 209--git-dir::
80d868b0 210 Show `$GIT_DIR` if defined. Otherwise show the path to
d0740ce0
JS
211 the .git directory. The path shown, when relative, is
212 relative to the current working directory.
80d868b0
JN
213+
214If `$GIT_DIR` is not defined and the current directory
2de9b711 215is not detected to lie in a Git repository or work tree
80d868b0 216print a message to stderr and exit with nonzero status.
735d80b3 217
c9bf7be2 218--is-inside-git-dir::
4faac246
ML
219 When the current working directory is below the repository
220 directory print "true", otherwise "false".
221
892c41b9
ML
222--is-inside-work-tree::
223 When the current working directory is inside the work tree of the
224 repository print "true", otherwise "false".
225
493c774e
ML
226--is-bare-repository::
227 When the repository is bare print "true", otherwise "false".
c9bf7be2 228
49c63913
JK
229--resolve-git-dir <path>::
230 Check if <path> is a valid repository or a gitfile that
231 points at a valid repository, and print the location of the
232 repository. If <path> is a gitfile then the resolved path
233 to the real repository is printed.
94c8ccaa 234
49c63913
JK
235--show-cdup::
236 When the command is invoked from a subdirectory, show the
237 path of the top-level directory relative to the current
238 directory (typically a sequence of "../", or an empty string).
239
240--show-prefix::
241 When the command is invoked from a subdirectory, show the
242 path of the current directory relative to the top-level
243 directory.
244
245--show-toplevel::
246 Show the absolute path of the top-level directory.
247
248Other Options
249~~~~~~~~~~~~~
735d80b3 250
3240240f
SB
251--since=datestring::
252--after=datestring::
483bc4f0 253 Parse the date string, and output the corresponding
0b444cdb 254 --max-age= parameter for 'git rev-list'.
a3114b34 255
3240240f
SB
256--until=datestring::
257--before=datestring::
483bc4f0 258 Parse the date string, and output the corresponding
0b444cdb 259 --min-age= parameter for 'git rev-list'.
a3114b34 260
7fc9d69f 261<args>...::
5077fa9c 262 Flags and parameters to be parsed.
7fc9d69f
JH
263
264
5a8f3117 265include::revisions.txt[]
be4c7014 266
21d47835
PH
267PARSEOPT
268--------
269
0b444cdb 270In `--parseopt` mode, 'git rev-parse' helps massaging options to bring to shell
21d47835
PH
271scripts the same facilities C builtins have. It works as an option normalizer
272(e.g. splits single switches aggregate values), a bit like `getopt(1)` does.
273
274It takes on the standard input the specification of the options to parse and
ac2e1e63 275understand, and echoes on the standard output a string suitable for `sh(1)` `eval`
21d47835
PH
276to replace the arguments with normalized ones. In case of error, it outputs
277usage on the standard error stream, and exits with code 129.
278
ac2e1e63
TR
279Note: Make sure you quote the result when passing it to `eval`. See
280below for an example.
281
21d47835
PH
282Input Format
283~~~~~~~~~~~~
284
0b444cdb 285'git rev-parse --parseopt' input format is fully text based. It has two parts,
21d47835
PH
286separated by a line that contains only `--`. The lines before the separator
287(should be more than one) are used for the usage.
288The lines after the separator describe the options.
289
290Each line of options has this format:
291
292------------
ff962a3f 293<opt_spec><flags>* SP+ help LF
21d47835
PH
294------------
295
296`<opt_spec>`::
297 its format is the short option character, then the long option name
298 separated by a comma. Both parts are not required, though at least one
299 is necessary. `h,help`, `dry-run` and `f` are all three correct
300 `<opt_spec>`.
301
ff962a3f
PH
302`<flags>`::
303 `<flags>` are of `*`, `=`, `?` or `!`.
304 * Use `=` if the option takes an argument.
305
f8c87212
NV
306 * Use `?` to mean that the option takes an optional argument. You
307 probably want to use the `--stuck-long` mode to be able to
308 unambiguously parse the optional argument.
ff962a3f
PH
309
310 * Use `*` to mean that this option should not be listed in the usage
311 generated for the `-h` argument. It's shown for `--help-all` as
a5af0e2c 312 documented in linkgit:gitcli[7].
ff962a3f
PH
313
314 * Use `!` to not make the corresponding negated long option available.
21d47835
PH
315
316The remainder of the line, after stripping the spaces, is used
317as the help associated to the option.
318
319Blank lines are ignored, and lines that don't match this specification are used
320as option group headers (start the line with a space to create such
321lines on purpose).
322
323Example
324~~~~~~~
325
326------------
327OPTS_SPEC="\
328some-command [options] <args>...
329
330some-command does foo and bar!
331--
332h,help show the help
333
334foo some nifty option --foo
335bar= some cool option --bar with an argument
336
337 An option group Header
338C? option C with an optional argument"
339
ac2e1e63 340eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)"
21d47835
PH
341------------
342
50325377
CC
343SQ-QUOTE
344--------
345
0b444cdb 346In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a
50325377
CC
347single line suitable for `sh(1)` `eval`. This line is made by
348normalizing the arguments following `--sq-quote`. Nothing other than
349quoting the arguments is done.
350
351If you want command input to still be interpreted as usual by
0b444cdb 352'git rev-parse' before the output is shell quoted, see the `--sq`
50325377
CC
353option.
354
355Example
356~~~~~~~
357
358------------
359$ cat >your-git-script.sh <<\EOF
360#!/bin/sh
361args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments
362command="git frotz -n24 $args" # and use it inside a handcrafted
363 # command line
364eval "$command"
365EOF
366
367$ sh your-git-script.sh "a b'c"
368------------
369
824b5dc2
CC
370EXAMPLES
371--------
372
373* Print the object name of the current commit:
374+
375------------
376$ git rev-parse --verify HEAD
377------------
378
379* Print the commit object name from the revision in the $REV shell variable:
380+
381------------
2db60670 382$ git rev-parse --verify $REV^{commit}
824b5dc2
CC
383------------
384+
385This will error out if $REV is empty or not a valid revision.
386
2db60670 387* Similar to above:
824b5dc2
CC
388+
389------------
390$ git rev-parse --default master --verify $REV
391------------
392+
393but if $REV is empty, the commit object name from master will be printed.
394
7fc9d69f
JH
395GIT
396---
9e1f0a85 397Part of the linkgit:git[1] suite