freshlybakedca.ke
Git fork
1git-rev-parse(1)
2================
3
4NAME
5----
6git-rev-parse - Pick out and massage parameters
7
8
9SYNOPSIS
10--------
11[verse]
12'git rev-parse' [<options>] <arg>...
13
14DESCRIPTION
15-----------
16
17Many Git porcelainish commands take a mixture of flags
18(i.e. parameters that begin with a dash '-') and parameters
19meant for the underlying 'git rev-list' command they use internally
20and flags and parameters for the other commands they use
21downstream of 'git rev-list'. The primary purpose of this command
22is to allow calling programs to distinguish between them. There are
23a few other operation modes that have nothing to do with the above
24"help parse command line options".
25
26Unless otherwise specified, most of the options and operation modes
27require you to run this command inside a git repository or a working
28tree that is under the control of a git repository, and will give you
29a fatal error otherwise.
30
31
32OPTIONS
33-------
34
35Operation Modes
36~~~~~~~~~~~~~~~
37
38Each of these options must appear first on the command line.
39
40--parseopt::
41 Use 'git rev-parse' in option parsing mode (see PARSEOPT section below).
42 The command in this mode can be used outside a repository or
43 a working tree controlled by a repository.
44
45--sq-quote::
46 Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE
47 section below). In contrast to the `--sq` option below, this
48 mode only does quoting. Nothing else is done to command input.
49 The command in this mode can be used outside a repository or
50 a working tree controlled by a repository.
51
52Options for --parseopt
53~~~~~~~~~~~~~~~~~~~~~~
54
55--keep-dashdash::
56 Only meaningful in `--parseopt` mode. Tells the option parser to echo
57 out the first `--` met instead of skipping it.
58
59--stop-at-non-option::
60 Only meaningful in `--parseopt` mode. Lets the option parser stop at
61 the first non-option argument. This can be used to parse sub-commands
62 that take options themselves.
63
64--stuck-long::
65 Only meaningful in `--parseopt` mode. Output the options in their
66 long form if available, and with their arguments stuck.
67
68Options for Filtering
69~~~~~~~~~~~~~~~~~~~~~
70
71--revs-only::
72 Do not output flags and parameters not meant for
73 'git rev-list' command.
74
75--no-revs::
76 Do not output flags and parameters meant for
77 'git rev-list' command.
78
79--flags::
80 Do not output non-flag parameters.
81
82--no-flags::
83 Do not output flag parameters.
84
85Options for Output
86~~~~~~~~~~~~~~~~~~
87
88--default <arg>::
89 If there is no parameter given by the user, use `<arg>`
90 instead.
91
92--prefix <arg>::
93 Behave as if 'git rev-parse' was invoked from the `<arg>`
94 subdirectory of the working tree. Any relative filenames are
95 resolved as if they are prefixed by `<arg>` and will be printed
96 in that form.
97+
98This can be used to convert arguments to a command run in a subdirectory
99so that they can still be used after moving to the top-level of the
100repository. For example:
101+
102----
103prefix=$(git rev-parse --show-prefix)
104cd "$(git rev-parse --show-toplevel)"
105# rev-parse provides the -- needed for 'set'
106eval "set $(git rev-parse --sq --prefix "$prefix" -- "$@")"
107----
108
109--verify::
110 Verify that exactly one parameter is provided, and that it
111 can be turned into a raw 20-byte SHA-1 that can be used to
112 access the object database. If so, emit it to the standard
113 output; otherwise, error out.
114+
115If you want to make sure that the output actually names an object in
116your object database and/or can be used as a specific type of object
117you require, you can add the `^{type}` peeling operator to the parameter.
118For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR`
119names an existing object that is a commit-ish (i.e. a commit, or an
120annotated tag that points at a commit). To make sure that `$VAR`
121names an existing object of any type, `git rev-parse "$VAR^{object}"`
122can be used.
123+
124Note that if you are verifying a name from an untrusted source, it is
125wise to use `--end-of-options` so that the name argument is not mistaken
126for another option.
127
128-q::
129--quiet::
130 Only meaningful in `--verify` mode. Do not output an error
131 message if the first argument is not a valid object name;
132 instead exit with non-zero status silently.
133 SHA-1s for valid object names are printed to stdout on success.
134
135--sq::
136 Usually the output is made one line per flag and
137 parameter. This option makes output a single line,
138 properly quoted for consumption by shell. Useful when
139 you expect your parameter to contain whitespaces and
140 newlines (e.g. when using pickaxe `-S` with
141 'git diff-{asterisk}'). In contrast to the `--sq-quote` option,
142 the command input is still interpreted as usual.
143
144--short[=<length>]::
145 Same as `--verify` but shortens the object name to a unique
146 prefix with at least `length` characters. The minimum length
147 is 4, the default is the effective value of the `core.abbrev`
148 configuration variable (see linkgit:git-config[1]).
149
150--not::
151 When showing object names, prefix them with '{caret}' and
152 strip '{caret}' prefix from the object names that already have
153 one.
154
155--abbrev-ref[=(strict|loose)]::
156 A non-ambiguous short name of the objects name.
157 The option core.warnAmbiguousRefs is used to select the strict
158 abbreviation mode.
159
160--symbolic::
161 Usually the object names are output in SHA-1 form (with
162 possible '{caret}' prefix); this option makes them output in a
163 form as close to the original input as possible.
164
165--symbolic-full-name::
166 This is similar to --symbolic, but it omits input that
167 are not refs (i.e. branch or tag names; or more
168 explicitly disambiguating "heads/master" form, when you
169 want to name the "master" branch when there is an
170 unfortunately named tag "master"), and shows them as full
171 refnames (e.g. "refs/heads/master").
172
173--output-object-format=(sha1|sha256|storage)::
174
175 Allow oids to be input from any object format that the current
176 repository supports.
177+
178Specifying "sha1" translates if necessary and returns a sha1 oid.
179+
180Specifying "sha256" translates if necessary and returns a sha256 oid.
181+
182Specifying "storage" translates if necessary and returns an oid in
183encoded in the storage hash algorithm.
184
185Options for Objects
186~~~~~~~~~~~~~~~~~~~
187
188--all::
189 Show all refs found in `refs/`.
190
191--branches[=<pattern>]::
192--tags[=<pattern>]::
193--remotes[=<pattern>]::
194 Show all branches, tags, or remote-tracking branches,
195 respectively (i.e., refs found in `refs/heads`,
196 `refs/tags`, or `refs/remotes`, respectively).
197+
198If a `pattern` is given, only refs matching the given shell glob are
199shown. If the pattern does not contain a globbing character (`?`,
200`*`, or `[`), it is turned into a prefix match by appending `/*`.
201
202--glob=<pattern>::
203 Show all refs matching the shell glob pattern `pattern`. If
204 the pattern does not start with `refs/`, this is automatically
205 prepended. If the pattern does not contain a globbing
206 character (`?`, `*`, or `[`), it is turned into a prefix
207 match by appending `/*`.
208
209--exclude=<glob-pattern>::
210 Do not include refs matching '<glob-pattern>' that the next `--all`,
211 `--branches`, `--tags`, `--remotes`, or `--glob` would otherwise
212 consider. Repetitions of this option accumulate exclusion patterns
213 up to the next `--all`, `--branches`, `--tags`, `--remotes`, or
214 `--glob` option (other options or arguments do not clear
215 accumulated patterns).
216+
217The patterns given should not begin with `refs/heads`, `refs/tags`, or
218`refs/remotes` when applied to `--branches`, `--tags`, or `--remotes`,
219respectively, and they must begin with `refs/` when applied to `--glob`
220or `--all`. If a trailing '/{asterisk}' is intended, it must be given
221explicitly.
222
223--exclude-hidden=(fetch|receive|uploadpack)::
224 Do not include refs that would be hidden by `git-fetch`,
225 `git-receive-pack` or `git-upload-pack` by consulting the appropriate
226 `fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs`
227 configuration along with `transfer.hideRefs` (see
228 linkgit:git-config[1]). This option affects the next pseudo-ref option
229 `--all` or `--glob` and is cleared after processing them.
230
231--disambiguate=<prefix>::
232 Show every object whose name begins with the given prefix.
233 The <prefix> must be at least 4 hexadecimal digits long to
234 avoid listing each and every object in the repository by
235 mistake.
236
237Options for Files
238~~~~~~~~~~~~~~~~~
239
240--local-env-vars::
241 List the GIT_* environment variables that are local to the
242 repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR).
243 Only the names of the variables are listed, not their value,
244 even if they are set.
245
246--path-format=(absolute|relative)::
247 Controls the behavior of certain other options. If specified as absolute, the
248 paths printed by those options will be absolute and canonical. If specified as
249 relative, the paths will be relative to the current working directory if that
250 is possible. The default is option specific.
251+
252This option may be specified multiple times and affects only the arguments that
253follow it on the command line, either to the end of the command line or the next
254instance of this option.
255
256The following options are modified by `--path-format`:
257
258--git-dir::
259 Show `$GIT_DIR` if defined. Otherwise show the path to
260 the .git directory. The path shown, when relative, is
261 relative to the current working directory.
262+
263If `$GIT_DIR` is not defined and the current directory
264is not detected to lie in a Git repository or work tree
265print a message to stderr and exit with nonzero status.
266
267--git-common-dir::
268 Show `$GIT_COMMON_DIR` if defined, else `$GIT_DIR`.
269
270--resolve-git-dir <path>::
271 Check if <path> is a valid repository or a gitfile that
272 points at a valid repository, and print the location of the
273 repository. If <path> is a gitfile then the resolved path
274 to the real repository is printed.
275
276--git-path <path>::
277 Resolve "$GIT_DIR/<path>" and takes other path relocation
278 variables such as $GIT_OBJECT_DIRECTORY,
279 $GIT_INDEX_FILE... into account. For example, if
280 $GIT_OBJECT_DIRECTORY is set to /foo/bar then "git rev-parse
281 --git-path objects/abc" returns /foo/bar/abc.
282
283--show-toplevel::
284 Show the (by default, absolute) path of the top-level directory
285 of the working tree. If there is no working tree, report an error.
286
287--show-superproject-working-tree::
288 Show the absolute path of the root of the superproject's
289 working tree (if exists) that uses the current repository as
290 its submodule. Outputs nothing if the current repository is
291 not used as a submodule by any project.
292
293--shared-index-path::
294 Show the path to the shared index file in split index mode, or
295 empty if not in split-index mode.
296
297The following options are unaffected by `--path-format`:
298
299--absolute-git-dir::
300 Like `--git-dir`, but its output is always the canonicalized
301 absolute path.
302
303--is-inside-git-dir::
304 When the current working directory is below the repository
305 directory print "true", otherwise "false".
306
307--is-inside-work-tree::
308 When the current working directory is inside the work tree of the
309 repository print "true", otherwise "false".
310
311--is-bare-repository::
312 When the repository is bare print "true", otherwise "false".
313
314--is-shallow-repository::
315 When the repository is shallow print "true", otherwise "false".
316
317--show-cdup::
318 When the command is invoked from a subdirectory, show the
319 path of the top-level directory relative to the current
320 directory (typically a sequence of "../", or an empty string).
321
322--show-prefix::
323 When the command is invoked from a subdirectory, show the
324 path of the current directory relative to the top-level
325 directory.
326
327--show-object-format[=(storage|input|output|compat)]::
328 Show the object format (hash algorithm) used for the repository for storage
329 inside the `.git` directory, input, output, or compatibility. For input,
330 multiple algorithms may be printed, space-separated. If `compat` is
331 requested and no compatibility algorithm is enabled, prints an empty line. If
332 not specified, the default is "storage".
333
334--show-ref-format::
335 Show the reference storage format used for the repository.
336
337
338Other Options
339~~~~~~~~~~~~~
340
341--since=<datestring>::
342--after=<datestring>::
343 Parse the date string, and output the corresponding
344 --max-age= parameter for 'git rev-list'.
345
346--until=<datestring>::
347--before=<datestring>::
348 Parse the date string, and output the corresponding
349 --min-age= parameter for 'git rev-list'.
350
351<arg>...::
352 Flags and parameters to be parsed.
353
354
355include::revisions.adoc[]
356
357PARSEOPT
358--------
359
360In `--parseopt` mode, 'git rev-parse' helps massaging options to bring to shell
361scripts the same facilities C builtins have. It works as an option normalizer
362(e.g. splits single switches aggregate values), a bit like `getopt(1)` does.
363
364It takes on the standard input the specification of the options to parse and
365understand, and echoes on the standard output a string suitable for `sh(1)` `eval`
366to replace the arguments with normalized ones. In case of error, it outputs
367usage on the standard error stream, and exits with code 129.
368
369Note: Make sure you quote the result when passing it to `eval`. See
370below for an example.
371
372Input Format
373~~~~~~~~~~~~
374
375'git rev-parse --parseopt' input format is fully text based. It has two parts,
376separated by a line that contains only `--`. The lines before the separator
377(should be one or more) are used for the usage.
378The lines after the separator describe the options.
379
380Each line of options has this format:
381
382------------
383<opt-spec><flags>*<arg-hint>? SP+ help LF
384------------
385
386`<opt-spec>`::
387 its format is the short option character, then the long option name
388 separated by a comma. Both parts are not required, though at least one
389 is necessary. May not contain any of the `<flags>` characters.
390 `h,help`, `dry-run` and `f` are examples of correct `<opt-spec>`.
391
392`<flags>`::
393 `<flags>` are of `*`, `=`, `?` or `!`.
394 * Use `=` if the option takes an argument.
395
396 * Use `?` to mean that the option takes an optional argument. You
397 probably want to use the `--stuck-long` mode to be able to
398 unambiguously parse the optional argument.
399
400 * Use `*` to mean that this option should not be listed in the usage
401 generated for the `-h` argument. It's shown for `--help-all` as
402 documented in linkgit:gitcli[7].
403
404 * Use `!` to not make the corresponding negated long option available.
405
406`<arg-hint>`::
407 `<arg-hint>`, if specified, is used as a name of the argument in the
408 help output, for options that take arguments. `<arg-hint>` is
409 terminated by the first whitespace. It is customary to use a
410 dash to separate words in a multi-word argument hint.
411
412The remainder of the line, after stripping the spaces, is used
413as the help associated with the option.
414
415Blank lines are ignored, and lines that don't match this specification are used
416as option group headers (start the line with a space to create such
417lines on purpose).
418
419Example
420~~~~~~~
421
422------------
423OPTS_SPEC="\
424some-command [<options>] <args>...
425
426some-command does foo and bar!
427--
428h,help! show the help
429
430foo some nifty option --foo
431bar= some cool option --bar with an argument
432baz=arg another cool option --baz with a named argument
433qux?path qux may take a path argument but has meaning by itself
434
435 An option group Header
436C? option C with an optional argument"
437
438eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)"
439------------
440
441
442Usage text
443~~~~~~~~~~
444
445When `"$@"` is `-h` or `--help` in the above example, the following
446usage text would be shown:
447
448------------
449usage: some-command [<options>] <args>...
450
451 some-command does foo and bar!
452
453 -h, --help show the help
454 --[no-]foo some nifty option --foo
455 --[no-]bar ... some cool option --bar with an argument
456 --[no-]baz <arg> another cool option --baz with a named argument
457 --[no-]qux[=<path>] qux may take a path argument but has meaning by itself
458
459An option group Header
460 -C[...] option C with an optional argument
461------------
462
463SQ-QUOTE
464--------
465
466In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a
467single line suitable for `sh(1)` `eval`. This line is made by
468normalizing the arguments following `--sq-quote`. Nothing other than
469quoting the arguments is done.
470
471If you want command input to still be interpreted as usual by
472'git rev-parse' before the output is shell quoted, see the `--sq`
473option.
474
475Example
476~~~~~~~
477
478------------
479$ cat >your-git-script.sh <<\EOF
480#!/bin/sh
481args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments
482command="git frotz -n24 $args" # and use it inside a handcrafted
483 # command line
484eval "$command"
485EOF
486
487$ sh your-git-script.sh "a b'c"
488------------
489
490EXAMPLES
491--------
492
493* Print the object name of the current commit:
494+
495------------
496$ git rev-parse --verify HEAD
497------------
498
499* Print the commit object name from the revision in the $REV shell variable:
500+
501------------
502$ git rev-parse --verify --end-of-options $REV^{commit}
503------------
504+
505This will error out if $REV is empty or not a valid revision.
506
507* Similar to above:
508+
509------------
510$ git rev-parse --default master --verify --end-of-options $REV
511------------
512+
513but if $REV is empty, the commit object name from master will be printed.
514
515GIT
516---
517Part of the linkgit:git[1] suite