6 git-rev-parse - Pick out and massage parameters
11 'git rev-parse' [ --option ] <args>...
16 Many git porcelainish commands take mixture of flags
17 (i.e. parameters that begin with a dash '-') and parameters
18 meant for the underlying 'git rev-list' command they use internally
19 and flags and parameters for the other commands they use
20 downstream of 'git rev-list'. This command is used to
21 distinguish between them.
27 Use 'git rev-parse' in option parsing mode (see PARSEOPT section below).
30 Only meaningful in `--parseopt` mode. Tells the option parser to echo
31 out the first `--` met instead of skipping it.
33 --stop-at-non-option::
34 Only meaningful in `--parseopt` mode. Lets the option parser stop at
35 the first non-option argument. This can be used to parse sub-commands
36 that take options themself.
39 Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE
40 section below). In contrast to the `--sq` option below, this
41 mode does only quoting. Nothing else is done to command input.
44 Do not output flags and parameters not meant for
45 'git rev-list' command.
48 Do not output flags and parameters meant for
49 'git rev-list' command.
52 Do not output non-flag parameters.
55 Do not output flag parameters.
58 If there is no parameter given by the user, use `<arg>`
62 The parameter given must be usable as a single, valid
63 object name. Otherwise barf and abort.
67 Only meaningful in `--verify` mode. Do not output an error
68 message if the first argument is not a valid object name;
69 instead exit with non-zero status silently.
72 Usually the output is made one line per flag and
73 parameter. This option makes output a single line,
74 properly quoted for consumption by shell. Useful when
75 you expect your parameter to contain whitespaces and
76 newlines (e.g. when using pickaxe `-S` with
77 'git diff-\*'). In contrast to the `--sq-quote` option,
78 the command input is still interpreted as usual.
81 When showing object names, prefix them with '{caret}' and
82 strip '{caret}' prefix from the object names that already have
86 Usually the object names are output in SHA1 form (with
87 possible '{caret}' prefix); this option makes them output in a
88 form as close to the original input as possible.
90 --symbolic-full-name::
91 This is similar to \--symbolic, but it omits input that
92 are not refs (i.e. branch or tag names; or more
93 explicitly disambiguating "heads/master" form, when you
94 want to name the "master" branch when there is an
95 unfortunately named tag "master"), and show them as full
96 refnames (e.g. "refs/heads/master").
98 --abbrev-ref[={strict|loose}]::
99 A non-ambiguous short name of the objects name.
100 The option core.warnAmbiguousRefs is used to select the strict
104 Show all refs found in `$GIT_DIR/refs`.
106 --branches[=pattern]::
108 --remotes[=pattern]::
109 Show all branches, tags, or remote-tracking branches,
110 respectively (i.e., refs found in `$GIT_DIR/refs/heads`,
111 `$GIT_DIR/refs/tags`, or `$GIT_DIR/refs/remotes`,
114 If a `pattern` is given, only refs matching the given shell glob are
115 shown. If the pattern does not contain a globbing character (`?`,
116 `\*`, or `[`), it is turned into a prefix match by appending `/\*`.
119 Show all refs matching the shell glob pattern `pattern`. If
120 the pattern does not start with `refs/`, this is automatically
121 prepended. If the pattern does not contain a globbing
122 character (`?`, `\*`, or `[`), it is turned into a prefix
123 match by appending `/\*`.
126 Show the absolute path of the top-level directory.
129 When the command is invoked from a subdirectory, show the
130 path of the current directory relative to the top-level
134 When the command is invoked from a subdirectory, show the
135 path of the top-level directory relative to the current
136 directory (typically a sequence of "../", or an empty string).
139 Show `$GIT_DIR` if defined else show the path to the .git directory.
141 --is-inside-git-dir::
142 When the current working directory is below the repository
143 directory print "true", otherwise "false".
145 --is-inside-work-tree::
146 When the current working directory is inside the work tree of the
147 repository print "true", otherwise "false".
149 --is-bare-repository::
150 When the repository is bare print "true", otherwise "false".
154 Instead of outputting the full SHA1 values of object names try to
155 abbreviate them to a shorter unique name. When no length is specified
156 7 is used. The minimum length is 4.
160 Parse the date string, and output the corresponding
161 --max-age= parameter for 'git rev-list'.
164 --before=datestring::
165 Parse the date string, and output the corresponding
166 --min-age= parameter for 'git rev-list'.
169 Flags and parameters to be parsed.
175 A revision parameter typically, but not necessarily, names a
176 commit object. They use what is called an 'extended SHA1'
177 syntax. Here are various ways to spell object names. The
178 ones listed near the end of this list are to name trees and
179 blobs contained in a commit.
181 * The full SHA1 object name (40-byte hexadecimal string), or
182 a substring of such that is unique within the repository.
183 E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both
184 name the same commit object if there are no other object in
185 your repository whose object name starts with dae86e.
187 * An output from 'git describe'; i.e. a closest tag, optionally
188 followed by a dash and a number of commits, followed by a dash, a
189 `g`, and an abbreviated object name.
191 * A symbolic ref name. E.g. 'master' typically means the commit
192 object referenced by $GIT_DIR/refs/heads/master. If you
193 happen to have both heads/master and tags/master, you can
194 explicitly say 'heads/master' to tell git which one you mean.
195 When ambiguous, a `<name>` is disambiguated by taking the
196 first match in the following rules:
198 . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually
199 useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD` and `MERGE_HEAD`);
201 . otherwise, `$GIT_DIR/refs/<name>` if exists;
203 . otherwise, `$GIT_DIR/refs/tags/<name>` if exists;
205 . otherwise, `$GIT_DIR/refs/heads/<name>` if exists;
207 . otherwise, `$GIT_DIR/refs/remotes/<name>` if exists;
209 . otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists.
211 HEAD names the commit your changes in the working tree is based on.
212 FETCH_HEAD records the branch you fetched from a remote repository
213 with your last 'git fetch' invocation.
214 ORIG_HEAD is created by commands that moves your HEAD in a drastic
215 way, to record the position of the HEAD before their operation, so that
216 you can change the tip of the branch back to the state before you ran
218 MERGE_HEAD records the commit(s) you are merging into your branch
219 when you run 'git merge'.
221 * A ref followed by the suffix '@' with a date specification
223 pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1
224 second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value
225 of the ref at a prior point in time. This suffix may only be
226 used immediately following a ref name and the ref must have an
227 existing log ($GIT_DIR/logs/<ref>). Note that this looks up the state
228 of your *local* ref at a given time; e.g., what was in your local
229 `master` branch last week. If you want to look at commits made during
230 certain times, see `--since` and `--until`.
232 * A ref followed by the suffix '@' with an ordinal specification
233 enclosed in a brace pair (e.g. '\{1\}', '\{15\}') to specify
234 the n-th prior value of that ref. For example 'master@\{1\}'
235 is the immediate prior value of 'master' while 'master@\{5\}'
236 is the 5th prior value of 'master'. This suffix may only be used
237 immediately following a ref name and the ref must have an existing
238 log ($GIT_DIR/logs/<ref>).
240 * You can use the '@' construct with an empty ref part to get at a
241 reflog of the current branch. For example, if you are on the
242 branch 'blabla', then '@\{1\}' means the same as 'blabla@\{1\}'.
244 * The special construct '@\{-<n>\}' means the <n>th branch checked out
245 before the current one.
247 * A suffix '{caret}' to a revision parameter means the first parent of
248 that commit object. '{caret}<n>' means the <n>th parent (i.e.
250 is equivalent to 'rev{caret}1'). As a special rule,
251 'rev{caret}0' means the commit itself and is used when 'rev' is the
252 object name of a tag object that refers to a commit object.
254 * A suffix '{tilde}<n>' to a revision parameter means the commit
255 object that is the <n>th generation grand-parent of the named
256 commit object, following only the first parent. I.e. rev~3 is
257 equivalent to rev{caret}{caret}{caret} which is equivalent to
258 rev{caret}1{caret}1{caret}1. See below for a illustration of
259 the usage of this form.
261 * A suffix '{caret}' followed by an object type name enclosed in
262 brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object
263 could be a tag, and dereference the tag recursively until an
264 object of that type is found or the object cannot be
265 dereferenced anymore (in which case, barf). `rev{caret}0`
266 introduced earlier is a short-hand for `rev{caret}\{commit\}`.
268 * A suffix '{caret}' followed by an empty brace pair
269 (e.g. `v0.99.8{caret}\{\}`) means the object could be a tag,
270 and dereference the tag recursively until a non-tag object is
273 * A colon, followed by a slash, followed by a text: this names
274 a commit whose commit message starts with the specified text.
275 This name returns the youngest matching commit which is
276 reachable from any ref. If the commit message starts with a
277 '!', you have to repeat that; the special sequence ':/!',
278 followed by something else than '!' is reserved for now.
280 * A suffix ':' followed by a path; this names the blob or tree
281 at the given path in the tree-ish object named by the part
284 * A colon, optionally followed by a stage number (0 to 3) and a
285 colon, followed by a path; this names a blob object in the
286 index at the given path. Missing stage number (and the colon
287 that follows it) names a stage 0 entry. During a merge, stage
288 1 is the common ancestor, stage 2 is the target branch's version
289 (typically the current branch), and stage 3 is the version from
290 the branch being merged.
292 Here is an illustration, by Jon Loeliger. Both commit nodes B
293 and C are parents of commit node A. Parent commits are ordered
296 ........................................
307 ........................................
312 D = A^^ = A^1^1 = A~2
315 G = A^^^ = A^1^1^1 = A~3
316 H = D^2 = B^^2 = A^^^2 = A~2^2
317 I = F^ = B^3^ = A^^3^
318 J = F^2 = B^3^2 = A^^3^2
324 History traversing commands such as 'git log' operate on a set
325 of commits, not just a single commit. To these commands,
326 specifying a single revision with the notation described in the
327 previous section means the set of commits reachable from that
328 commit, following the commit ancestry chain.
330 To exclude commits reachable from a commit, a prefix `{caret}`
331 notation is used. E.g. `{caret}r1 r2` means commits reachable
332 from `r2` but exclude the ones reachable from `r1`.
334 This set operation appears so often that there is a shorthand
335 for it. When you have two commits `r1` and `r2` (named according
336 to the syntax explained in SPECIFYING REVISIONS above), you can ask
337 for commits that are reachable from r2 excluding those that are reachable
338 from r1 by `{caret}r1 r2` and it can be written as `r1..r2`.
340 A similar notation `r1\...r2` is called symmetric difference
341 of `r1` and `r2` and is defined as
342 `r1 r2 --not $(git merge-base --all r1 r2)`.
343 It is the set of commits that are reachable from either one of
344 `r1` or `r2` but not from both.
346 Two other shorthands for naming a set that is formed by a commit
347 and its parent commits exist. The `r1{caret}@` notation means all
348 parents of `r1`. `r1{caret}!` includes commit `r1` but excludes
351 Here are a handful of examples:
365 In `--parseopt` mode, 'git rev-parse' helps massaging options to bring to shell
366 scripts the same facilities C builtins have. It works as an option normalizer
367 (e.g. splits single switches aggregate values), a bit like `getopt(1)` does.
369 It takes on the standard input the specification of the options to parse and
370 understand, and echoes on the standard output a line suitable for `sh(1)` `eval`
371 to replace the arguments with normalized ones. In case of error, it outputs
372 usage on the standard error stream, and exits with code 129.
377 'git rev-parse --parseopt' input format is fully text based. It has two parts,
378 separated by a line that contains only `--`. The lines before the separator
379 (should be more than one) are used for the usage.
380 The lines after the separator describe the options.
382 Each line of options has this format:
385 <opt_spec><flags>* SP+ help LF
389 its format is the short option character, then the long option name
390 separated by a comma. Both parts are not required, though at least one
391 is necessary. `h,help`, `dry-run` and `f` are all three correct
395 `<flags>` are of `*`, `=`, `?` or `!`.
396 * Use `=` if the option takes an argument.
398 * Use `?` to mean that the option is optional (though its use is discouraged).
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].
404 * Use `!` to not make the corresponding negated long option available.
406 The remainder of the line, after stripping the spaces, is used
407 as the help associated to the option.
409 Blank lines are ignored, and lines that don't match this specification are used
410 as option group headers (start the line with a space to create such
418 some-command [options] <args>...
420 some-command does foo and bar!
424 foo some nifty option --foo
425 bar= some cool option --bar with an argument
427 An option group Header
428 C? option C with an optional argument"
430 eval `echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?`
436 In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a
437 single line suitable for `sh(1)` `eval`. This line is made by
438 normalizing the arguments following `--sq-quote`. Nothing other than
439 quoting the arguments is done.
441 If you want command input to still be interpreted as usual by
442 'git rev-parse' before the output is shell quoted, see the `--sq`
449 $ cat >your-git-script.sh <<\EOF
451 args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments
452 command="git frotz -n24 $args" # and use it inside a handcrafted
457 $ sh your-git-script.sh "a b'c"
463 * Print the object name of the current commit:
466 $ git rev-parse --verify HEAD
469 * Print the commit object name from the revision in the $REV shell variable:
472 $ git rev-parse --verify $REV
475 This will error out if $REV is empty or not a valid revision.
480 $ git rev-parse --default master --verify $REV
483 but if $REV is empty, the commit object name from master will be printed.
488 Written by Linus Torvalds <torvalds@osdl.org> .
489 Junio C Hamano <gitster@pobox.com> and Pierre Habouzit <madcoder@debian.org>
493 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
497 Part of the linkgit:git[1] suite