6 git-rev-parse - Pick out and massage parameters
12 'git rev-parse' [<options>] <arg>...
17 Many Git porcelainish commands take a mixture of flags
18 (i.e. parameters that begin with a dash '-') and parameters
19 meant for the underlying 'git rev-list' command they use internally
20 and flags and parameters for the other commands they use
21 downstream of 'git rev-list'. This command is used to
22 distinguish between them.
31 Each of these options must appear first on the command line.
34 Use 'git rev-parse' in option parsing mode (see PARSEOPT section below).
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 only does quoting. Nothing else is done to command input.
41 Options for --parseopt
42 ~~~~~~~~~~~~~~~~~~~~~~
45 Only meaningful in `--parseopt` mode. Tells the option parser to echo
46 out the first `--` met instead of skipping it.
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
51 that take options themselves.
54 Only meaningful in `--parseopt` mode. Output the options in their
55 long form if available, and with their arguments stuck.
61 Do not output flags and parameters not meant for
62 'git rev-list' command.
65 Do not output flags and parameters meant for
66 'git rev-list' command.
69 Do not output non-flag parameters.
72 Do not output flag parameters.
78 If there is no parameter given by the user, use `<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
87 This can be used to convert arguments to a command run in a subdirectory
88 so that they can still be used after moving to the top-level of the
89 repository. For example:
92 prefix=$(git rev-parse --show-prefix)
93 cd "$(git rev-parse --show-toplevel)"
94 # rev-parse provides the -- needed for 'set'
95 eval "set $(git rev-parse --sq --prefix "$prefix" -- "$@")"
99 Verify that exactly one parameter is provided, and that it
100 can be turned into a raw 20-byte SHA-1 that can be used to
101 access the object database. If so, emit it to the standard
102 output; otherwise, error out.
104 If you want to make sure that the output actually names an object in
105 your object database and/or can be used as a specific type of object
106 you require, you can add the `^{type}` peeling operator to the parameter.
107 For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR`
108 names an existing object that is a commit-ish (i.e. a commit, or an
109 annotated tag that points at a commit). To make sure that `$VAR`
110 names an existing object of any type, `git rev-parse "$VAR^{object}"`
113 Note that if you are verifying a name from an untrusted source, it is
114 wise to use `--end-of-options` so that the name argument is not mistaken
119 Only meaningful in `--verify` mode. Do not output an error
120 message if the first argument is not a valid object name;
121 instead exit with non-zero status silently.
122 SHA-1s for valid object names are printed to stdout on success.
125 Usually the output is made one line per flag and
126 parameter. This option makes output a single line,
127 properly quoted for consumption by shell. Useful when
128 you expect your parameter to contain whitespaces and
129 newlines (e.g. when using pickaxe `-S` with
130 'git diff-{asterisk}'). In contrast to the `--sq-quote` option,
131 the command input is still interpreted as usual.
134 Same as `--verify` but shortens the object name to a unique
135 prefix with at least `length` characters. The minimum length
136 is 4, the default is the effective value of the `core.abbrev`
137 configuration variable (see linkgit:git-config[1]).
140 When showing object names, prefix them with '{caret}' and
141 strip '{caret}' prefix from the object names that already have
144 --abbrev-ref[=(strict|loose)]::
145 A non-ambiguous short name of the objects name.
146 The option core.warnAmbiguousRefs is used to select the strict
150 Usually the object names are output in SHA-1 form (with
151 possible '{caret}' prefix); this option makes them output in a
152 form as close to the original input as possible.
154 --symbolic-full-name::
155 This is similar to --symbolic, but it omits input that
156 are not refs (i.e. branch or tag names; or more
157 explicitly disambiguating "heads/master" form, when you
158 want to name the "master" branch when there is an
159 unfortunately named tag "master"), and shows them as full
160 refnames (e.g. "refs/heads/master").
162 --output-object-format=(sha1|sha256|storage)::
164 Allow oids to be input from any object format that the current
167 Specifying "sha1" translates if necessary and returns a sha1 oid.
169 Specifying "sha256" translates if necessary and returns a sha256 oid.
171 Specifying "storage" translates if necessary and returns an oid in
172 encoded in the storage hash algorithm.
178 Show all refs found in `refs/`.
180 --branches[=<pattern>]::
182 --remotes[=<pattern>]::
183 Show all branches, tags, or remote-tracking branches,
184 respectively (i.e., refs found in `refs/heads`,
185 `refs/tags`, or `refs/remotes`, respectively).
187 If a `pattern` is given, only refs matching the given shell glob are
188 shown. If the pattern does not contain a globbing character (`?`,
189 `*`, or `[`), it is turned into a prefix match by appending `/*`.
192 Show all refs matching the shell glob pattern `pattern`. If
193 the pattern does not start with `refs/`, this is automatically
194 prepended. If the pattern does not contain a globbing
195 character (`?`, `*`, or `[`), it is turned into a prefix
196 match by appending `/*`.
198 --exclude=<glob-pattern>::
199 Do not include refs matching '<glob-pattern>' that the next `--all`,
200 `--branches`, `--tags`, `--remotes`, or `--glob` would otherwise
201 consider. Repetitions of this option accumulate exclusion patterns
202 up to the next `--all`, `--branches`, `--tags`, `--remotes`, or
203 `--glob` option (other options or arguments do not clear
204 accumulated patterns).
206 The patterns given should not begin with `refs/heads`, `refs/tags`, or
207 `refs/remotes` when applied to `--branches`, `--tags`, or `--remotes`,
208 respectively, and they must begin with `refs/` when applied to `--glob`
209 or `--all`. If a trailing '/{asterisk}' is intended, it must be given
212 --exclude-hidden=(fetch|receive|uploadpack)::
213 Do not include refs that would be hidden by `git-fetch`,
214 `git-receive-pack` or `git-upload-pack` by consulting the appropriate
215 `fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs`
216 configuration along with `transfer.hideRefs` (see
217 linkgit:git-config[1]). This option affects the next pseudo-ref option
218 `--all` or `--glob` and is cleared after processing them.
220 --disambiguate=<prefix>::
221 Show every object whose name begins with the given prefix.
222 The <prefix> must be at least 4 hexadecimal digits long to
223 avoid listing each and every object in the repository by
230 List the GIT_* environment variables that are local to the
231 repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR).
232 Only the names of the variables are listed, not their value,
233 even if they are set.
235 --path-format=(absolute|relative)::
236 Controls the behavior of certain other options. If specified as absolute, the
237 paths printed by those options will be absolute and canonical. If specified as
238 relative, the paths will be relative to the current working directory if that
239 is possible. The default is option specific.
241 This option may be specified multiple times and affects only the arguments that
242 follow it on the command line, either to the end of the command line or the next
243 instance of this option.
245 The following options are modified by `--path-format`:
248 Show `$GIT_DIR` if defined. Otherwise show the path to
249 the .git directory. The path shown, when relative, is
250 relative to the current working directory.
252 If `$GIT_DIR` is not defined and the current directory
253 is not detected to lie in a Git repository or work tree
254 print a message to stderr and exit with nonzero status.
257 Show `$GIT_COMMON_DIR` if defined, else `$GIT_DIR`.
259 --resolve-git-dir <path>::
260 Check if <path> is a valid repository or a gitfile that
261 points at a valid repository, and print the location of the
262 repository. If <path> is a gitfile then the resolved path
263 to the real repository is printed.
266 Resolve "$GIT_DIR/<path>" and takes other path relocation
267 variables such as $GIT_OBJECT_DIRECTORY,
268 $GIT_INDEX_FILE... into account. For example, if
269 $GIT_OBJECT_DIRECTORY is set to /foo/bar then "git rev-parse
270 --git-path objects/abc" returns /foo/bar/abc.
273 Show the (by default, absolute) path of the top-level directory
274 of the working tree. If there is no working tree, report an error.
276 --show-superproject-working-tree::
277 Show the absolute path of the root of the superproject's
278 working tree (if exists) that uses the current repository as
279 its submodule. Outputs nothing if the current repository is
280 not used as a submodule by any project.
282 --shared-index-path::
283 Show the path to the shared index file in split index mode, or
284 empty if not in split-index mode.
286 The following options are unaffected by `--path-format`:
289 Like `--git-dir`, but its output is always the canonicalized
292 --is-inside-git-dir::
293 When the current working directory is below the repository
294 directory print "true", otherwise "false".
296 --is-inside-work-tree::
297 When the current working directory is inside the work tree of the
298 repository print "true", otherwise "false".
300 --is-bare-repository::
301 When the repository is bare print "true", otherwise "false".
303 --is-shallow-repository::
304 When the repository is shallow print "true", otherwise "false".
307 When the command is invoked from a subdirectory, show the
308 path of the top-level directory relative to the current
309 directory (typically a sequence of "../", or an empty string).
312 When the command is invoked from a subdirectory, show the
313 path of the current directory relative to the top-level
316 --show-object-format[=(storage|input|output)]::
317 Show the object format (hash algorithm) used for the repository
318 for storage inside the `.git` directory, input, or output. For
319 input, multiple algorithms may be printed, space-separated.
320 If not specified, the default is "storage".
323 Show the reference storage format used for the repository.
329 --since=<datestring>::
330 --after=<datestring>::
331 Parse the date string, and output the corresponding
332 --max-age= parameter for 'git rev-list'.
334 --until=<datestring>::
335 --before=<datestring>::
336 Parse the date string, and output the corresponding
337 --min-age= parameter for 'git rev-list'.
340 Flags and parameters to be parsed.
343 include::revisions.txt[]
348 In `--parseopt` mode, 'git rev-parse' helps massaging options to bring to shell
349 scripts the same facilities C builtins have. It works as an option normalizer
350 (e.g. splits single switches aggregate values), a bit like `getopt(1)` does.
352 It takes on the standard input the specification of the options to parse and
353 understand, and echoes on the standard output a string suitable for `sh(1)` `eval`
354 to replace the arguments with normalized ones. In case of error, it outputs
355 usage on the standard error stream, and exits with code 129.
357 Note: Make sure you quote the result when passing it to `eval`. See
358 below for an example.
363 'git rev-parse --parseopt' input format is fully text based. It has two parts,
364 separated by a line that contains only `--`. The lines before the separator
365 (should be one or more) are used for the usage.
366 The lines after the separator describe the options.
368 Each line of options has this format:
371 <opt-spec><flags>*<arg-hint>? SP+ help LF
375 its format is the short option character, then the long option name
376 separated by a comma. Both parts are not required, though at least one
377 is necessary. May not contain any of the `<flags>` characters.
378 `h,help`, `dry-run` and `f` are examples of correct `<opt-spec>`.
381 `<flags>` are of `*`, `=`, `?` or `!`.
382 * Use `=` if the option takes an argument.
384 * Use `?` to mean that the option takes an optional argument. You
385 probably want to use the `--stuck-long` mode to be able to
386 unambiguously parse the optional argument.
388 * Use `*` to mean that this option should not be listed in the usage
389 generated for the `-h` argument. It's shown for `--help-all` as
390 documented in linkgit:gitcli[7].
392 * Use `!` to not make the corresponding negated long option available.
395 `<arg-hint>`, if specified, is used as a name of the argument in the
396 help output, for options that take arguments. `<arg-hint>` is
397 terminated by the first whitespace. It is customary to use a
398 dash to separate words in a multi-word argument hint.
400 The remainder of the line, after stripping the spaces, is used
401 as the help associated with the option.
403 Blank lines are ignored, and lines that don't match this specification are used
404 as option group headers (start the line with a space to create such
412 some-command [<options>] <args>...
414 some-command does foo and bar!
416 h,help! show the help
418 foo some nifty option --foo
419 bar= some cool option --bar with an argument
420 baz=arg another cool option --baz with a named argument
421 qux?path qux may take a path argument but has meaning by itself
423 An option group Header
424 C? option C with an optional argument"
426 eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)"
433 When `"$@"` is `-h` or `--help` in the above example, the following
434 usage text would be shown:
437 usage: some-command [<options>] <args>...
439 some-command does foo and bar!
441 -h, --help show the help
442 --[no-]foo some nifty option --foo
443 --[no-]bar ... some cool option --bar with an argument
444 --[no-]baz <arg> another cool option --baz with a named argument
445 --[no-]qux[=<path>] qux may take a path argument but has meaning by itself
447 An option group Header
448 -C[...] option C with an optional argument
454 In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a
455 single line suitable for `sh(1)` `eval`. This line is made by
456 normalizing the arguments following `--sq-quote`. Nothing other than
457 quoting the arguments is done.
459 If you want command input to still be interpreted as usual by
460 'git rev-parse' before the output is shell quoted, see the `--sq`
467 $ cat >your-git-script.sh <<\EOF
469 args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments
470 command="git frotz -n24 $args" # and use it inside a handcrafted
475 $ sh your-git-script.sh "a b'c"
481 * Print the object name of the current commit:
484 $ git rev-parse --verify HEAD
487 * Print the commit object name from the revision in the $REV shell variable:
490 $ git rev-parse --verify --end-of-options $REV^{commit}
493 This will error out if $REV is empty or not a valid revision.
498 $ git rev-parse --default master --verify --end-of-options $REV
501 but if $REV is empty, the commit object name from master will be printed.
505 Part of the linkgit:git[1] suite