1GIT-REV-PARSE(1) Git Manual GIT-REV-PARSE(1)
2
6 git-rev-parse - Pick out and massage parameters
7
9 git rev-parse [ --option ] <args>...
10
13 Many Git porcelainish commands take mixture of flags (i.e. parameters
14 that begin with a dash -) and parameters meant for the underlying git
15 rev-list command they use internally and flags and parameters for the
16 other commands they use downstream of git rev-list. This command is
17 used to distinguish between them.
18
20 --parseopt
21 Use git rev-parse in option parsing mode (see PARSEOPT section
22 below).
23 --keep-dashdash
25 Only meaningful in --parseopt mode. Tells the option parser to echo
26 out the first -- met instead of skipping it.
27 --stop-at-non-option
29 Only meaningful in --parseopt mode. Lets the option parser stop at
30 the first non-option argument. This can be used to parse
31 sub-commands that take options themselves.
32 --sq-quote
34 Use git rev-parse in shell quoting mode (see SQ-QUOTE section
35 below). In contrast to the --sq option below, this mode does only
36 quoting. Nothing else is done to command input.
37 --revs-only
39 Do not output flags and parameters not meant for git rev-list
40 command.
41 --no-revs
43 Do not output flags and parameters meant for git rev-list command.
44 --flags
46 Do not output non-flag parameters.
47 --no-flags
49 Do not output flag parameters.
50 --default <arg>
52 If there is no parameter given by the user, use <arg> instead.
53 --verify
55 Verify that exactly one parameter is provided, and that it can be
56 turned into a raw 20-byte SHA-1 that can be used to access the
57 object database. If so, emit it to the standard output; otherwise,
58 error out.
59 If you want to make sure that the output actually names an object
61 in your object database and/or can be used as a specific type of
62 object For example, git rev-parse "$VAR^{commit}" will make sure
63 $VAR names an existing object that is a commit-ish (i.e. a commit,
64 or an annotated tag that points at a commit). To make sure that
65 $VAR names an existing object of any type, git rev-parse
66 "$VAR^{object}" can be used.
67 -q, --quiet
69 Only meaningful in --verify mode. Do not output an error message if
70 the first argument is not a valid object name; instead exit with
71 non-zero status silently.
72 --sq
74 Usually the output is made one line per flag and parameter. This
75 option makes output a single line, properly quoted for consumption
76 by shell. Useful when you expect your parameter to contain
77 whitespaces and newlines (e.g. when using pickaxe -S with git
78 diff-*). In contrast to the --sq-quote option, the command input is
79 still interpreted as usual.
80 --not
82 When showing object names, prefix them with ^ and strip ^ prefix
83 from the object names that already have one.
84 --symbolic
86 Usually the object names are output in SHA-1 form (with possible ^
87 prefix); this option makes them output in a form as close to the
88 original input as possible.
89 --symbolic-full-name
91 This is similar to --symbolic, but it omits input that are not refs
92 (i.e. branch or tag names; or more explicitly disambiguating
93 "heads/master" form, when you want to name the "master" branch when
94 there is an unfortunately named tag "master"), and show them as
95 full refnames (e.g. "refs/heads/master").
96 --abbrev-ref[=(strict|loose)]
98 A non-ambiguous short name of the objects name. The option
99 core.warnAmbiguousRefs is used to select the strict abbreviation
100 mode.
101 --disambiguate=<prefix>
103 Show every object whose name begins with the given prefix. The
104 <prefix> must be at least 4 hexadecimal digits long to avoid
105 listing each and every object in the repository by mistake.
106 --all
108 Show all refs found in refs/.
109 --branches[=pattern], --tags[=pattern], --remotes[=pattern]
111 Show all branches, tags, or remote-tracking branches, respectively
112 (i.e., refs found in refs/heads, refs/tags, or refs/remotes,
113 respectively).
114 If a pattern is given, only refs matching the given shell glob are
116 shown. If the pattern does not contain a globbing character (?, *,
117 or [), it is turned into a prefix match by appending /*.
118 --glob=pattern
120 Show all refs matching the shell glob pattern pattern. If the
121 pattern does not start with refs/, this is automatically prepended.
122 If the pattern does not contain a globbing character (?, *, or [),
123 it is turned into a prefix match by appending /*.
124 --show-toplevel
126 Show the absolute path of the top-level directory.
127 --show-prefix
129 When the command is invoked from a subdirectory, show the path of
130 the current directory relative to the top-level directory.
131 --show-cdup
133 When the command is invoked from a subdirectory, show the path of
134 the top-level directory relative to the current directory
135 (typically a sequence of "../", or an empty string).
136 --git-dir
138 Show $GIT_DIR if defined. Otherwise show the path to the .git
139 directory. The path shown, when relative, is relative to the
140 current working directory.
141 If $GIT_DIR is not defined and the current directory is not
143 detected to lie in a Git repository or work tree print a message to
144 stderr and exit with nonzero status.
145 --is-inside-git-dir
147 When the current working directory is below the repository
148 directory print "true", otherwise "false".
149 --is-inside-work-tree
151 When the current working directory is inside the work tree of the
152 repository print "true", otherwise "false".
153 --is-bare-repository
155 When the repository is bare print "true", otherwise "false".
156 --local-env-vars
158 List the GIT_* environment variables that are local to the
159 repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR).
160 Only the names of the variables are listed, not their value, even
161 if they are set.
162 --short, --short=number
164 Instead of outputting the full SHA-1 values of object names try to
165 abbreviate them to a shorter unique name. When no length is
166 specified 7 is used. The minimum length is 4.
167 --since=datestring, --after=datestring
169 Parse the date string, and output the corresponding --max-age=
170 parameter for git rev-list.
171 --until=datestring, --before=datestring
173 Parse the date string, and output the corresponding --min-age=
174 parameter for git rev-list.
175 <args>...
177 Flags and parameters to be parsed.
178 --resolve-git-dir <path>
180 Check if <path> is a valid repository or a gitfile that points at a
181 valid repository, and print the location of the repository. If
182 <path> is a gitfile then the resolved path to the real repository
183 is printed.
184
186 A revision parameter <rev> typically, but not necessarily, names a
187 commit object. It uses what is called an extended SHA-1 syntax. Here
188 are various ways to spell object names. The ones listed near the end of
189 this list name trees and blobs contained in a commit.
190 <sha1>, e.g. dae86e1950b1277e545cee180551750029cfe735, dae86e
192 The full SHA-1 object name (40-byte hexadecimal string), or a
193 leading substring that is unique within the repository. E.g.
194 dae86e1950b1277e545cee180551750029cfe735 and dae86e both name the
195 same commit object if there is no other object in your repository
196 whose object name starts with dae86e.
197 <describeOutput>, e.g. v1.7.4.2-679-g3bee7fb
199 Output from git describe; i.e. a closest tag, optionally followed
200 by a dash and a number of commits, followed by a dash, a g, and an
201 abbreviated object name.
202 <refname>, e.g. master, heads/master, refs/heads/master
204 A symbolic ref name. E.g. master typically means the commit object
205 referenced by refs/heads/master. If you happen to have both
206 heads/master and tags/master, you can explicitly say heads/master
207 to tell Git which one you mean. When ambiguous, a <refname> is
208 disambiguated by taking the first match in the following rules:
209 1. If $GIT_DIR/<refname> exists, that is what you mean (this is
211 usually useful only for HEAD, FETCH_HEAD, ORIG_HEAD, MERGE_HEAD
212 and CHERRY_PICK_HEAD);
213 2. otherwise, refs/<refname> if it exists;
215 3. otherwise, refs/tags/<refname> if it exists;
217 4. otherwise, refs/heads/<refname> if it exists;
219 5. otherwise, refs/remotes/<refname> if it exists;
221 6. otherwise, refs/remotes/<refname>/HEAD if it exists.
223 HEAD names the commit on which you based the changes in the
225 working tree. FETCH_HEAD records the branch which you fetched
226 from a remote repository with your last git fetch invocation.
227 ORIG_HEAD is created by commands that move your HEAD in a
228 drastic way, to record the position of the HEAD before their
229 operation, so that you can easily change the tip of the branch
230 back to the state before you ran them. MERGE_HEAD records the
231 commit(s) which you are merging into your branch when you run
232 git merge. CHERRY_PICK_HEAD records the commit which you are
233 cherry-picking when you run git cherry-pick.
234 Note that any of the refs/* cases above may come either from
236 the $GIT_DIR/refs directory or from the $GIT_DIR/packed-refs
237 file. While the ref name encoding is unspecified, UTF-8 is
238 preferred as some output processing may assume ref names in
239 UTF-8.
240 <refname>@{<date>}, e.g. master@{yesterday}, HEAD@{5 minutes ago}
242 A ref followed by the suffix @ with a date specification enclosed
243 in a brace pair (e.g. {yesterday}, {1 month 2 weeks 3 days 1 hour
244 1 second ago} or {1979-02-26 18:30:00}) specifies the value of the
245 ref at a prior point in time. This suffix may only be used
246 immediately following a ref name and the ref must have an existing
247 log ($GIT_DIR/logs/<ref>). Note that this looks up the state of
248 your local ref at a given time; e.g., what was in your local master
249 branch last week. If you want to look at commits made during
250 certain times, see --since and --until.
251 <refname>@{<n>}, e.g. master@{1}
253 A ref followed by the suffix @ with an ordinal specification
254 enclosed in a brace pair (e.g. {1}, {15}) specifies the n-th prior
255 value of that ref. For example master@{1} is the immediate prior
256 value of master while master@{5} is the 5th prior value of master.
257 This suffix may only be used immediately following a ref name and
258 the ref must have an existing log ($GIT_DIR/logs/<refname>).
259 @{<n>}, e.g. @{1}
261 You can use the @ construct with an empty ref part to get at a
262 reflog entry of the current branch. For example, if you are on
263 branch blabla then @{1} means the same as blabla@{1}.
264 @{-<n>}, e.g. @{-1}
266 The construct @{-<n>} means the <n>th branch checked out before the
267 current one.
268 <branchname>@{upstream}, e.g. master@{upstream}, @{u}
270 The suffix @{upstream} to a branchname (short form
271 <branchname>@{u}) refers to the branch that the branch specified by
272 branchname is set to build on top of. A missing branchname defaults
273 to the current one.
274 <rev>^, e.g. HEAD^, v1.5.1^0
276 A suffix ^ to a revision parameter means the first parent of that
277 commit object. ^<n> means the <n>th parent (i.e. <rev>^ is
278 equivalent to <rev>^1). As a special rule, <rev>^0 means the commit
279 itself and is used when <rev> is the object name of a tag object
280 that refers to a commit object.
281 <rev>~<n>, e.g. master~3
283 A suffix ~<n> to a revision parameter means the commit object that
284 is the <n>th generation ancestor of the named commit object,
285 following only the first parents. I.e. <rev>~3 is equivalent to
286 <rev>^^^ which is equivalent to <rev>^1^1^1. See below for an
287 illustration of the usage of this form.
288 <rev>^{<type>}, e.g. v0.99.8^{commit}
290 A suffix ^ followed by an object type name enclosed in brace pair
291 means the object could be a tag, and dereference the tag
292 recursively until an object of that type is found or the object
293 cannot be dereferenced anymore (in which case, barf). <rev>^0 is a
294 short-hand for <rev>^{commit}.
295 rev^{object} can be used to make sure rev names an object that
297 exists, without requiring rev to be a tag, and without
298 dereferencing rev; because a tag is already an object, it does not
299 have to be dereferenced even once to get to an object.
300 <rev>^{}, e.g. v0.99.8^{}
302 A suffix ^ followed by an empty brace pair means the object could
303 be a tag, and dereference the tag recursively until a non-tag
304 object is found.
305 <rev>^{/<text>}, e.g. HEAD^{/fix nasty bug}
307 A suffix ^ to a revision parameter, followed by a brace pair that
308 contains a text led by a slash, is the same as the :/fix nasty bug
309 syntax below except that it returns the youngest matching commit
310 which is reachable from the <rev> before ^.
311 :/<text>, e.g. :/fix nasty bug
313 A colon, followed by a slash, followed by a text, names a commit
314 whose commit message matches the specified regular expression. This
315 name returns the youngest matching commit which is reachable from
316 any ref. If the commit message starts with a ! you have to repeat
317 that; the special sequence :/!, followed by something else than !,
318 is reserved for now. The regular expression can match any part of
319 the commit message. To match messages starting with a string, one
320 can use e.g. :/^foo.
321 <rev>:<path>, e.g. HEAD:README, :README, master:./README
323 A suffix : followed by a path names the blob or tree at the given
324 path in the tree-ish object named by the part before the colon.
325 :path (with an empty part before the colon) is a special case of
326 the syntax described next: content recorded in the index at the
327 given path. A path starting with ./ or ../ is relative to the
328 current working directory. The given path will be converted to be
329 relative to the working tree’s root directory. This is most useful
330 to address a blob or tree from a commit or tree that has the same
331 tree structure as the working tree.
332 :<n>:<path>, e.g. :0:README, :README
334 A colon, optionally followed by a stage number (0 to 3) and a
335 colon, followed by a path, names a blob object in the index at the
336 given path. A missing stage number (and the colon that follows it)
337 names a stage 0 entry. During a merge, stage 1 is the common
338 ancestor, stage 2 is the target branch’s version (typically the
339 current branch), and stage 3 is the version from the branch which
340 is being merged.
341 Here is an illustration, by Jon Loeliger. Both commit nodes B and C are
343 parents of commit node A. Parent commits are ordered left-to-right.
344 G H I J
346 \ / \ /
347 D E F
348 \ | / \
349 \ | / |
350 \|/ |
351 B C
352 \ /
353 \ /
354 A
355 A = = A^0
357 B = A^ = A^1 = A~1
358 C = A^2 = A^2
359 D = A^^ = A^1^1 = A~2
360 E = B^2 = A^^2
361 F = B^3 = A^^3
362 G = A^^^ = A^1^1^1 = A~3
363 H = D^2 = B^^2 = A^^^2 = A~2^2
364 I = F^ = B^3^ = A^^3^
365 J = F^2 = B^3^2 = A^^3^2
366
368 History traversing commands such as git log operate on a set of
369 commits, not just a single commit. To these commands, specifying a
370 single revision with the notation described in the previous section
371 means the set of commits reachable from that commit, following the
372 commit ancestry chain.
373 To exclude commits reachable from a commit, a prefix ^ notation is
375 used. E.g. ^r1 r2 means commits reachable from r2 but exclude the ones
376 reachable from r1.
377 This set operation appears so often that there is a shorthand for it.
379 When you have two commits r1 and r2 (named according to the syntax
380 explained in SPECIFYING REVISIONS above), you can ask for commits that
381 are reachable from r2 excluding those that are reachable from r1 by ^r1
382 r2 and it can be written as r1..r2.
383 A similar notation r1...r2 is called symmetric difference of r1 and r2
385 and is defined as r1 r2 --not $(git merge-base --all r1 r2). It is the
386 set of commits that are reachable from either one of r1 or r2 but not
387 from both.
388 In these two shorthands, you can omit one end and let it default to
390 HEAD. For example, origin.. is a shorthand for origin..HEAD and asks
391 "What did I do since I forked from the origin branch?" Similarly,
392 ..origin is a shorthand for HEAD..origin and asks "What did the origin
393 do since I forked from them?" Note that .. would mean HEAD..HEAD which
394 is an empty range that is both reachable and unreachable from HEAD.
395 Two other shorthands for naming a set that is formed by a commit and
397 its parent commits exist. The r1^@ notation means all parents of r1.
398 r1^! includes commit r1 but excludes all of its parents.
399 To summarize:
401 <rev>
403 Include commits that are reachable from (i.e. ancestors of) <rev>.
404 ^<rev>
406 Exclude commits that are reachable from (i.e. ancestors of) <rev>.
407 <rev1>..<rev2>
409 Include commits that are reachable from <rev2> but exclude those
410 that are reachable from <rev1>. When either <rev1> or <rev2> is
411 omitted, it defaults to HEAD.
412 <rev1>...<rev2>
414 Include commits that are reachable from either <rev1> or <rev2> but
415 exclude those that are reachable from both. When either <rev1> or
416 <rev2> is omitted, it defaults to HEAD.
417 <rev>^@, e.g. HEAD^@
419 A suffix ^ followed by an at sign is the same as listing all
420 parents of <rev> (meaning, include anything reachable from its
421 parents, but not the commit itself).
422 <rev>^!, e.g. HEAD^!
424 A suffix ^ followed by an exclamation mark is the same as giving
425 commit <rev> and then all its parents prefixed with ^ to exclude
426 them (and their ancestors).
427 Here are a handful of examples:
429 D G H D
431 D F G H I J D F
432 ^G D H D
433 ^D B E I J F B
434 B..C C
435 B...C G H D E B C
436 ^D B C E I J F B C
437 C I J F C
438 C^@ I J F
439 C^! C
440 F^! D G H D F
441
443 In --parseopt mode, git rev-parse helps massaging options to bring to
444 shell scripts the same facilities C builtins have. It works as an
445 option normalizer (e.g. splits single switches aggregate values), a bit
446 like getopt(1) does.
447 It takes on the standard input the specification of the options to
449 parse and understand, and echoes on the standard output a string
450 suitable for sh(1) eval to replace the arguments with normalized ones.
451 In case of error, it outputs usage on the standard error stream, and
452 exits with code 129.
453 Note: Make sure you quote the result when passing it to eval. See below
455 for an example.
456 Input Format
458 git rev-parse --parseopt input format is fully text based. It has two
459 parts, separated by a line that contains only --. The lines before the
460 separator (should be more than one) are used for the usage. The lines
461 after the separator describe the options.
462 Each line of options has this format:
464 <opt_spec><flags>* SP+ help LF
466 <opt_spec>
470 its format is the short option character, then the long option name
471 separated by a comma. Both parts are not required, though at least
472 one is necessary. h,help, dry-run and f are all three correct
473 <opt_spec>.
474 <flags>
476 <flags> are of *, =, ? or !.
477 · Use = if the option takes an argument.
479 · Use ? to mean that the option is optional (though its use is
481 discouraged).
482 · Use * to mean that this option should not be listed in the
484 usage generated for the -h argument. It’s shown for --help-all
485 as documented in gitcli(7).
486 · Use ! to not make the corresponding negated long option
488 available.
489 The remainder of the line, after stripping the spaces, is used as the
491 help associated to the option.
492 Blank lines are ignored, and lines that don’t match this specification
494 are used as option group headers (start the line with a space to create
495 such lines on purpose).
496 Example
498 OPTS_SPEC="\
499 some-command [options] <args>...
500 some-command does foo and bar!
502 --
503 h,help show the help
504 foo some nifty option --foo
506 bar= some cool option --bar with an argument
507 An option group Header
509 C? option C with an optional argument"
510 eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)"
512
515 In --sq-quote mode, git rev-parse echoes on the standard output a
516 single line suitable for sh(1) eval. This line is made by normalizing
517 the arguments following --sq-quote. Nothing other than quoting the
518 arguments is done.
519 If you want command input to still be interpreted as usual by git
521 rev-parse before the output is shell quoted, see the --sq option.
522 Example
524 $ cat >your-git-script.sh <<\EOF
525 #!/bin/sh
526 args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments
527 command="git frotz -n24 $args" # and use it inside a handcrafted
528 # command line
529 eval "$command"
530 EOF
531 $ sh your-git-script.sh "a b'c"
533
536 · Print the object name of the current commit:
537 $ git rev-parse --verify HEAD
539 · Print the commit object name from the revision in the $REV shell
542 variable:
543 $ git rev-parse --verify $REV^{commit}
545 This will error out if $REV is empty or not a valid revision.
547 · Similar to above:
549 $ git rev-parse --default master --verify $REV
551 but if $REV is empty, the commit object name from master will be
553 printed.
554
556 Part of the git(1) suite
557Git 1.8.3.1 11/19/2018 GIT-REV-PARSE(1)