1GIT-REV-PARSE(1) Git Manual GIT-REV-PARSE(1)
2
3
4
6 git-rev-parse - Pick out and massage parameters
7
9 git rev-parse [<options>] <args>...
10
11
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 Operation Modes
21 Each of these options must appear first on the command line.
22
23 --parseopt
24 Use git rev-parse in option parsing mode (see PARSEOPT section
25 below).
26
27 --sq-quote
28 Use git rev-parse in shell quoting mode (see SQ-QUOTE section
29 below). In contrast to the --sq option below, this mode does only
30 quoting. Nothing else is done to command input.
31
32 Options for --parseopt
33 --keep-dashdash
34 Only meaningful in --parseopt mode. Tells the option parser to echo
35 out the first -- met instead of skipping it.
36
37 --stop-at-non-option
38 Only meaningful in --parseopt mode. Lets the option parser stop at
39 the first non-option argument. This can be used to parse
40 sub-commands that take options themselves.
41
42 --stuck-long
43 Only meaningful in --parseopt mode. Output the options in their
44 long form if available, and with their arguments stuck.
45
46 Options for Filtering
47 --revs-only
48 Do not output flags and parameters not meant for git rev-list
49 command.
50
51 --no-revs
52 Do not output flags and parameters meant for git rev-list command.
53
54 --flags
55 Do not output non-flag parameters.
56
57 --no-flags
58 Do not output flag parameters.
59
60 Options for Output
61 --default <arg>
62 If there is no parameter given by the user, use <arg> instead.
63
64 --prefix <arg>
65 Behave as if git rev-parse was invoked from the <arg> subdirectory
66 of the working tree. Any relative filenames are resolved as if they
67 are prefixed by <arg> and will be printed in that form.
68
69 This can be used to convert arguments to a command run in a
70 subdirectory so that they can still be used after moving to the
71 top-level of the repository. For example:
72
73 prefix=$(git rev-parse --show-prefix)
74 cd "$(git rev-parse --show-toplevel)"
75 # rev-parse provides the -- needed for 'set'
76 eval "set $(git rev-parse --sq --prefix "$prefix" -- "$@")"
77
78
79 --verify
80 Verify that exactly one parameter is provided, and that it can be
81 turned into a raw 20-byte SHA-1 that can be used to access the
82 object database. If so, emit it to the standard output; otherwise,
83 error out.
84
85 If you want to make sure that the output actually names an object
86 in your object database and/or can be used as a specific type of
87 object you require, you can add the ^{type} peeling operator to the
88 parameter. For example, git rev-parse "$VAR^{commit}" will make
89 sure $VAR names an existing object that is a commit-ish (i.e. a
90 commit, or an annotated tag that points at a commit). To make sure
91 that $VAR names an existing object of any type, git rev-parse
92 "$VAR^{object}" can be used.
93
94 -q, --quiet
95 Only meaningful in --verify mode. Do not output an error message if
96 the first argument is not a valid object name; instead exit with
97 non-zero status silently. SHA-1s for valid object names are printed
98 to stdout on success.
99
100 --sq
101 Usually the output is made one line per flag and parameter. This
102 option makes output a single line, properly quoted for consumption
103 by shell. Useful when you expect your parameter to contain
104 whitespaces and newlines (e.g. when using pickaxe -S with git
105 diff-*). In contrast to the --sq-quote option, the command input is
106 still interpreted as usual.
107
108 --short[=length]
109 Same as --verify but shortens the object name to a unique prefix
110 with at least length characters. The minimum length is 4, the
111 default is the effective value of the core.abbrev configuration
112 variable (see git-config(1)).
113
114 --not
115 When showing object names, prefix them with ^ and strip ^ prefix
116 from the object names that already have one.
117
118 --abbrev-ref[=(strict|loose)]
119 A non-ambiguous short name of the objects name. The option
120 core.warnAmbiguousRefs is used to select the strict abbreviation
121 mode.
122
123 --symbolic
124 Usually the object names are output in SHA-1 form (with possible ^
125 prefix); this option makes them output in a form as close to the
126 original input as possible.
127
128 --symbolic-full-name
129 This is similar to --symbolic, but it omits input that are not refs
130 (i.e. branch or tag names; or more explicitly disambiguating
131 "heads/master" form, when you want to name the "master" branch when
132 there is an unfortunately named tag "master"), and show them as
133 full refnames (e.g. "refs/heads/master").
134
135 Options for Objects
136 --all
137 Show all refs found in refs/.
138
139 --branches[=pattern], --tags[=pattern], --remotes[=pattern]
140 Show all branches, tags, or remote-tracking branches, respectively
141 (i.e., refs found in refs/heads, refs/tags, or refs/remotes,
142 respectively).
143
144 If a pattern is given, only refs matching the given shell glob are
145 shown. If the pattern does not contain a globbing character (?, *,
146 or [), it is turned into a prefix match by appending /*.
147
148 --glob=pattern
149 Show all refs matching the shell glob pattern pattern. If the
150 pattern does not start with refs/, this is automatically prepended.
151 If the pattern does not contain a globbing character (?, *, or [),
152 it is turned into a prefix match by appending /*.
153
154 --exclude=<glob-pattern>
155 Do not include refs matching <glob-pattern> that the next --all,
156 --branches, --tags, --remotes, or --glob would otherwise consider.
157 Repetitions of this option accumulate exclusion patterns up to the
158 next --all, --branches, --tags, --remotes, or --glob option (other
159 options or arguments do not clear accumulated patterns).
160
161 The patterns given should not begin with refs/heads, refs/tags, or
162 refs/remotes when applied to --branches, --tags, or --remotes,
163 respectively, and they must begin with refs/ when applied to --glob
164 or --all. If a trailing /* is intended, it must be given
165 explicitly.
166
167 --disambiguate=<prefix>
168 Show every object whose name begins with the given prefix. The
169 <prefix> must be at least 4 hexadecimal digits long to avoid
170 listing each and every object in the repository by mistake.
171
172 Options for Files
173 --local-env-vars
174 List the GIT_* environment variables that are local to the
175 repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR).
176 Only the names of the variables are listed, not their value, even
177 if they are set.
178
179 --git-dir
180 Show $GIT_DIR if defined. Otherwise show the path to the .git
181 directory. The path shown, when relative, is relative to the
182 current working directory.
183
184 If $GIT_DIR is not defined and the current directory is not
185 detected to lie in a Git repository or work tree print a message to
186 stderr and exit with nonzero status.
187
188 --absolute-git-dir
189 Like --git-dir, but its output is always the canonicalized absolute
190 path.
191
192 --git-common-dir
193 Show $GIT_COMMON_DIR if defined, else $GIT_DIR.
194
195 --is-inside-git-dir
196 When the current working directory is below the repository
197 directory print "true", otherwise "false".
198
199 --is-inside-work-tree
200 When the current working directory is inside the work tree of the
201 repository print "true", otherwise "false".
202
203 --is-bare-repository
204 When the repository is bare print "true", otherwise "false".
205
206 --is-shallow-repository
207 When the repository is shallow print "true", otherwise "false".
208
209 --resolve-git-dir <path>
210 Check if <path> is a valid repository or a gitfile that points at a
211 valid repository, and print the location of the repository. If
212 <path> is a gitfile then the resolved path to the real repository
213 is printed.
214
215 --git-path <path>
216 Resolve "$GIT_DIR/<path>" and takes other path relocation variables
217 such as $GIT_OBJECT_DIRECTORY, $GIT_INDEX_FILE... into account. For
218 example, if $GIT_OBJECT_DIRECTORY is set to /foo/bar then "git
219 rev-parse --git-path objects/abc" returns /foo/bar/abc.
220
221 --show-cdup
222 When the command is invoked from a subdirectory, show the path of
223 the top-level directory relative to the current directory
224 (typically a sequence of "../", or an empty string).
225
226 --show-prefix
227 When the command is invoked from a subdirectory, show the path of
228 the current directory relative to the top-level directory.
229
230 --show-toplevel
231 Show the absolute path of the top-level directory.
232
233 --show-superproject-working-tree
234 Show the absolute path of the root of the superproject’s working
235 tree (if exists) that uses the current repository as its submodule.
236 Outputs nothing if the current repository is not used as a
237 submodule by any project.
238
239 --shared-index-path
240 Show the path to the shared index file in split index mode, or
241 empty if not in split-index mode.
242
243 Other Options
244 --since=datestring, --after=datestring
245 Parse the date string, and output the corresponding --max-age=
246 parameter for git rev-list.
247
248 --until=datestring, --before=datestring
249 Parse the date string, and output the corresponding --min-age=
250 parameter for git rev-list.
251
252 <args>...
253 Flags and parameters to be parsed.
254
256 A revision parameter <rev> typically, but not necessarily, names a
257 commit object. It uses what is called an extended SHA-1 syntax. Here
258 are various ways to spell object names. The ones listed near the end of
259 this list name trees and blobs contained in a commit.
260
261 Note
262 This document shows the "raw" syntax as seen by git. The shell and
263 other UIs might require additional quoting to protect special
264 characters and to avoid word splitting.
265
266 <sha1>, e.g. dae86e1950b1277e545cee180551750029cfe735, dae86e
267 The full SHA-1 object name (40-byte hexadecimal string), or a
268 leading substring that is unique within the repository. E.g.
269 dae86e1950b1277e545cee180551750029cfe735 and dae86e both name the
270 same commit object if there is no other object in your repository
271 whose object name starts with dae86e.
272
273 <describeOutput>, e.g. v1.7.4.2-679-g3bee7fb
274 Output from git describe; i.e. a closest tag, optionally followed
275 by a dash and a number of commits, followed by a dash, a g, and an
276 abbreviated object name.
277
278 <refname>, e.g. master, heads/master, refs/heads/master
279 A symbolic ref name. E.g. master typically means the commit object
280 referenced by refs/heads/master. If you happen to have both
281 heads/master and tags/master, you can explicitly say heads/master
282 to tell Git which one you mean. When ambiguous, a <refname> is
283 disambiguated by taking the first match in the following rules:
284
285 1. If $GIT_DIR/<refname> exists, that is what you mean (this is
286 usually useful only for HEAD, FETCH_HEAD, ORIG_HEAD, MERGE_HEAD
287 and CHERRY_PICK_HEAD);
288
289 2. otherwise, refs/<refname> if it exists;
290
291 3. otherwise, refs/tags/<refname> if it exists;
292
293 4. otherwise, refs/heads/<refname> if it exists;
294
295 5. otherwise, refs/remotes/<refname> if it exists;
296
297 6. otherwise, refs/remotes/<refname>/HEAD if it exists.
298
299 HEAD names the commit on which you based the changes in the
300 working tree. FETCH_HEAD records the branch which you fetched
301 from a remote repository with your last git fetch invocation.
302 ORIG_HEAD is created by commands that move your HEAD in a
303 drastic way, to record the position of the HEAD before their
304 operation, so that you can easily change the tip of the branch
305 back to the state before you ran them. MERGE_HEAD records the
306 commit(s) which you are merging into your branch when you run
307 git merge. CHERRY_PICK_HEAD records the commit which you are
308 cherry-picking when you run git cherry-pick.
309
310 Note that any of the refs/* cases above may come either from
311 the $GIT_DIR/refs directory or from the $GIT_DIR/packed-refs
312 file. While the ref name encoding is unspecified, UTF-8 is
313 preferred as some output processing may assume ref names in
314 UTF-8.
315
316 @
317 @ alone is a shortcut for HEAD.
318
319 [<refname>]@{<date>}, e.g. master@{yesterday}, HEAD@{5 minutes ago}
320 A ref followed by the suffix @ with a date specification enclosed
321 in a brace pair (e.g. {yesterday}, {1 month 2 weeks 3 days 1 hour
322 1 second ago} or {1979-02-26 18:30:00}) specifies the value of the
323 ref at a prior point in time. This suffix may only be used
324 immediately following a ref name and the ref must have an existing
325 log ($GIT_DIR/logs/<ref>). Note that this looks up the state of
326 your local ref at a given time; e.g., what was in your local master
327 branch last week. If you want to look at commits made during
328 certain times, see --since and --until.
329
330 <refname>@{<n>}, e.g. master@{1}
331 A ref followed by the suffix @ with an ordinal specification
332 enclosed in a brace pair (e.g. {1}, {15}) specifies the n-th prior
333 value of that ref. For example master@{1} is the immediate prior
334 value of master while master@{5} is the 5th prior value of master.
335 This suffix may only be used immediately following a ref name and
336 the ref must have an existing log ($GIT_DIR/logs/<refname>).
337
338 @{<n>}, e.g. @{1}
339 You can use the @ construct with an empty ref part to get at a
340 reflog entry of the current branch. For example, if you are on
341 branch blabla then @{1} means the same as blabla@{1}.
342
343 @{-<n>}, e.g. @{-1}
344 The construct @{-<n>} means the <n>th branch/commit checked out
345 before the current one.
346
347 [<branchname>]@{upstream}, e.g. master@{upstream}, @{u}
348 The suffix @{upstream} to a branchname (short form
349 <branchname>@{u}) refers to the branch that the branch specified by
350 branchname is set to build on top of (configured with
351 branch.<name>.remote and branch.<name>.merge). A missing branchname
352 defaults to the current one. These suffixes are also accepted when
353 spelled in uppercase, and they mean the same thing no matter the
354 case.
355
356 [<branchname>]@{push}, e.g. master@{push}, @{push}
357 The suffix @{push} reports the branch "where we would push to" if
358 git push were run while branchname was checked out (or the current
359 HEAD if no branchname is specified). Since our push destination is
360 in a remote repository, of course, we report the local tracking
361 branch that corresponds to that branch (i.e., something in
362 refs/remotes/).
363
364 Here’s an example to make it more clear:
365
366 $ git config push.default current
367 $ git config remote.pushdefault myfork
368 $ git switch -c mybranch origin/master
369
370 $ git rev-parse --symbolic-full-name @{upstream}
371 refs/remotes/origin/master
372
373 $ git rev-parse --symbolic-full-name @{push}
374 refs/remotes/myfork/mybranch
375
376 Note in the example that we set up a triangular workflow, where we
377 pull from one location and push to another. In a non-triangular
378 workflow, @{push} is the same as @{upstream}, and there is no need
379 for it.
380
381 This suffix is also accepted when spelled in uppercase, and means
382 the same thing no matter the case.
383
384 <rev>^[<n>], e.g. HEAD^, v1.5.1^0
385 A suffix ^ to a revision parameter means the first parent of that
386 commit object. ^<n> means the <n>th parent (i.e. <rev>^ is
387 equivalent to <rev>^1). As a special rule, <rev>^0 means the commit
388 itself and is used when <rev> is the object name of a tag object
389 that refers to a commit object.
390
391 <rev>~[<n>], e.g. HEAD~, master~3
392 A suffix ~ to a revision parameter means the first parent of that
393 commit object. A suffix ~<n> to a revision parameter means the
394 commit object that is the <n>th generation ancestor of the named
395 commit object, following only the first parents. I.e. <rev>~3 is
396 equivalent to <rev>^^^ which is equivalent to <rev>^1^1^1. See
397 below for an illustration of the usage of this form.
398
399 <rev>^{<type>}, e.g. v0.99.8^{commit}
400 A suffix ^ followed by an object type name enclosed in brace pair
401 means dereference the object at <rev> recursively until an object
402 of type <type> is found or the object cannot be dereferenced
403 anymore (in which case, barf). For example, if <rev> is a
404 commit-ish, <rev>^{commit} describes the corresponding commit
405 object. Similarly, if <rev> is a tree-ish, <rev>^{tree} describes
406 the corresponding tree object. <rev>^0 is a short-hand for
407 <rev>^{commit}.
408
409 <rev>^{object} can be used to make sure <rev> names an object that
410 exists, without requiring <rev> to be a tag, and without
411 dereferencing <rev>; because a tag is already an object, it does
412 not have to be dereferenced even once to get to an object.
413
414 <rev>^{tag} can be used to ensure that <rev> identifies an existing
415 tag object.
416
417 <rev>^{}, e.g. v0.99.8^{}
418 A suffix ^ followed by an empty brace pair means the object could
419 be a tag, and dereference the tag recursively until a non-tag
420 object is found.
421
422 <rev>^{/<text>}, e.g. HEAD^{/fix nasty bug}
423 A suffix ^ to a revision parameter, followed by a brace pair that
424 contains a text led by a slash, is the same as the :/fix nasty bug
425 syntax below except that it returns the youngest matching commit
426 which is reachable from the <rev> before ^.
427
428 :/<text>, e.g. :/fix nasty bug
429 A colon, followed by a slash, followed by a text, names a commit
430 whose commit message matches the specified regular expression. This
431 name returns the youngest matching commit which is reachable from
432 any ref, including HEAD. The regular expression can match any part
433 of the commit message. To match messages starting with a string,
434 one can use e.g. :/^foo. The special sequence :/! is reserved for
435 modifiers to what is matched. :/!-foo performs a negative match,
436 while :/!!foo matches a literal ! character, followed by foo. Any
437 other sequence beginning with :/! is reserved for now. Depending
438 on the given text, the shell’s word splitting rules might require
439 additional quoting.
440
441 <rev>:<path>, e.g. HEAD:README, master:./README
442 A suffix : followed by a path names the blob or tree at the given
443 path in the tree-ish object named by the part before the colon. A
444 path starting with ./ or ../ is relative to the current working
445 directory. The given path will be converted to be relative to the
446 working tree’s root directory. This is most useful to address a
447 blob or tree from a commit or tree that has the same tree structure
448 as the working tree.
449
450 :[<n>:]<path>, e.g. :0:README, :README
451 A colon, optionally followed by a stage number (0 to 3) and a
452 colon, followed by a path, names a blob object in the index at the
453 given path. A missing stage number (and the colon that follows it)
454 names a stage 0 entry. During a merge, stage 1 is the common
455 ancestor, stage 2 is the target branch’s version (typically the
456 current branch), and stage 3 is the version from the branch which
457 is being merged.
458
459 Here is an illustration, by Jon Loeliger. Both commit nodes B and C are
460 parents of commit node A. Parent commits are ordered left-to-right.
461
462 G H I J
463 \ / \ /
464 D E F
465 \ | / \
466 \ | / |
467 \|/ |
468 B C
469 \ /
470 \ /
471 A
472
473 A = = A^0
474 B = A^ = A^1 = A~1
475 C = A^2 = A^2
476 D = A^^ = A^1^1 = A~2
477 E = B^2 = A^^2
478 F = B^3 = A^^3
479 G = A^^^ = A^1^1^1 = A~3
480 H = D^2 = B^^2 = A^^^2 = A~2^2
481 I = F^ = B^3^ = A^^3^
482 J = F^2 = B^3^2 = A^^3^2
483
485 History traversing commands such as git log operate on a set of
486 commits, not just a single commit.
487
488 For these commands, specifying a single revision, using the notation
489 described in the previous section, means the set of commits reachable
490 from the given commit.
491
492 A commit’s reachable set is the commit itself and the commits in its
493 ancestry chain.
494
495 Commit Exclusions
496 ^<rev> (caret) Notation
497 To exclude commits reachable from a commit, a prefix ^ notation is
498 used. E.g. ^r1 r2 means commits reachable from r2 but exclude the
499 ones reachable from r1 (i.e. r1 and its ancestors).
500
501 Dotted Range Notations
502 The .. (two-dot) Range Notation
503 The ^r1 r2 set operation appears so often that there is a shorthand
504 for it. When you have two commits r1 and r2 (named according to the
505 syntax explained in SPECIFYING REVISIONS above), you can ask for
506 commits that are reachable from r2 excluding those that are
507 reachable from r1 by ^r1 r2 and it can be written as r1..r2.
508
509 The ... (three-dot) Symmetric Difference Notation
510 A similar notation r1...r2 is called symmetric difference of r1 and
511 r2 and is defined as r1 r2 --not $(git merge-base --all r1 r2). It
512 is the set of commits that are reachable from either one of r1
513 (left side) or r2 (right side) but not from both.
514
515 In these two shorthand notations, you can omit one end and let it
516 default to HEAD. For example, origin.. is a shorthand for origin..HEAD
517 and asks "What did I do since I forked from the origin branch?"
518 Similarly, ..origin is a shorthand for HEAD..origin and asks "What did
519 the origin do since I forked from them?" Note that .. would mean
520 HEAD..HEAD which is an empty range that is both reachable and
521 unreachable from HEAD.
522
523 Other <rev>^ Parent Shorthand Notations
524 Three other shorthands exist, particularly useful for merge commits,
525 for naming a set that is formed by a commit and its parent commits.
526
527 The r1^@ notation means all parents of r1.
528
529 The r1^! notation includes commit r1 but excludes all of its parents.
530 By itself, this notation denotes the single commit r1.
531
532 The <rev>^-[<n>] notation includes <rev> but excludes the <n>th parent
533 (i.e. a shorthand for <rev>^<n>..<rev>), with <n> = 1 if not given.
534 This is typically useful for merge commits where you can just pass
535 <commit>^- to get all the commits in the branch that was merged in
536 merge commit <commit> (including <commit> itself).
537
538 While <rev>^<n> was about specifying a single commit parent, these
539 three notations also consider its parents. For example you can say
540 HEAD^2^@, however you cannot say HEAD^@^2.
541
543 <rev>
544 Include commits that are reachable from <rev> (i.e. <rev> and its
545 ancestors).
546
547 ^<rev>
548 Exclude commits that are reachable from <rev> (i.e. <rev> and its
549 ancestors).
550
551 <rev1>..<rev2>
552 Include commits that are reachable from <rev2> but exclude those
553 that are reachable from <rev1>. When either <rev1> or <rev2> is
554 omitted, it defaults to HEAD.
555
556 <rev1>...<rev2>
557 Include commits that are reachable from either <rev1> or <rev2> but
558 exclude those that are reachable from both. When either <rev1> or
559 <rev2> is omitted, it defaults to HEAD.
560
561 <rev>^@, e.g. HEAD^@
562 A suffix ^ followed by an at sign is the same as listing all
563 parents of <rev> (meaning, include anything reachable from its
564 parents, but not the commit itself).
565
566 <rev>^!, e.g. HEAD^!
567 A suffix ^ followed by an exclamation mark is the same as giving
568 commit <rev> and then all its parents prefixed with ^ to exclude
569 them (and their ancestors).
570
571 <rev>^-<n>, e.g. HEAD^-, HEAD^-2
572 Equivalent to <rev>^<n>..<rev>, with <n> = 1 if not given.
573
574 Here are a handful of examples using the Loeliger illustration above,
575 with each step in the notation’s expansion and selection carefully
576 spelt out:
577
578 Args Expanded arguments Selected commits
579 D G H D
580 D F G H I J D F
581 ^G D H D
582 ^D B E I J F B
583 ^D B C E I J F B C
584 C I J F C
585 B..C = ^B C C
586 B...C = B ^F C G H D E B C
587 B^- = B^..B
588 = ^B^1 B E I J F B
589 C^@ = C^1
590 = F I J F
591 B^@ = B^1 B^2 B^3
592 = D E F D G H E F I J
593 C^! = C ^C^@
594 = C ^C^1
595 = C ^F C
596 B^! = B ^B^@
597 = B ^B^1 ^B^2 ^B^3
598 = B ^D ^E ^F B
599 F^! D = F ^I ^J D G H D F
600
602 In --parseopt mode, git rev-parse helps massaging options to bring to
603 shell scripts the same facilities C builtins have. It works as an
604 option normalizer (e.g. splits single switches aggregate values), a bit
605 like getopt(1) does.
606
607 It takes on the standard input the specification of the options to
608 parse and understand, and echoes on the standard output a string
609 suitable for sh(1) eval to replace the arguments with normalized ones.
610 In case of error, it outputs usage on the standard error stream, and
611 exits with code 129.
612
613 Note: Make sure you quote the result when passing it to eval. See below
614 for an example.
615
616 Input Format
617 git rev-parse --parseopt input format is fully text based. It has two
618 parts, separated by a line that contains only --. The lines before the
619 separator (should be one or more) are used for the usage. The lines
620 after the separator describe the options.
621
622 Each line of options has this format:
623
624 <opt-spec><flags>*<arg-hint>? SP+ help LF
625
626
627
628 <opt-spec>
629 its format is the short option character, then the long option name
630 separated by a comma. Both parts are not required, though at least
631 one is necessary. May not contain any of the <flags> characters.
632 h,help, dry-run and f are examples of correct <opt-spec>.
633
634 <flags>
635 <flags> are of *, =, ? or !.
636
637 · Use = if the option takes an argument.
638
639 · Use ? to mean that the option takes an optional argument. You
640 probably want to use the --stuck-long mode to be able to
641 unambiguously parse the optional argument.
642
643 · Use * to mean that this option should not be listed in the
644 usage generated for the -h argument. It’s shown for --help-all
645 as documented in gitcli(7).
646
647 · Use ! to not make the corresponding negated long option
648 available.
649
650 <arg-hint>
651 <arg-hint>, if specified, is used as a name of the argument in the
652 help output, for options that take arguments. <arg-hint> is
653 terminated by the first whitespace. It is customary to use a dash
654 to separate words in a multi-word argument hint.
655
656 The remainder of the line, after stripping the spaces, is used as the
657 help associated to the option.
658
659 Blank lines are ignored, and lines that don’t match this specification
660 are used as option group headers (start the line with a space to create
661 such lines on purpose).
662
663 Example
664 OPTS_SPEC="\
665 some-command [<options>] <args>...
666
667 some-command does foo and bar!
668 --
669 h,help show the help
670
671 foo some nifty option --foo
672 bar= some cool option --bar with an argument
673 baz=arg another cool option --baz with a named argument
674 qux?path qux may take a path argument but has meaning by itself
675
676 An option group Header
677 C? option C with an optional argument"
678
679 eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)"
680
681
682 Usage text
683 When "$@" is -h or --help in the above example, the following usage
684 text would be shown:
685
686 usage: some-command [<options>] <args>...
687
688 some-command does foo and bar!
689
690 -h, --help show the help
691 --foo some nifty option --foo
692 --bar ... some cool option --bar with an argument
693 --baz <arg> another cool option --baz with a named argument
694 --qux[=<path>] qux may take a path argument but has meaning by itself
695
696 An option group Header
697 -C[...] option C with an optional argument
698
699
701 In --sq-quote mode, git rev-parse echoes on the standard output a
702 single line suitable for sh(1) eval. This line is made by normalizing
703 the arguments following --sq-quote. Nothing other than quoting the
704 arguments is done.
705
706 If you want command input to still be interpreted as usual by git
707 rev-parse before the output is shell quoted, see the --sq option.
708
709 Example
710 $ cat >your-git-script.sh <<\EOF
711 #!/bin/sh
712 args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments
713 command="git frotz -n24 $args" # and use it inside a handcrafted
714 # command line
715 eval "$command"
716 EOF
717
718 $ sh your-git-script.sh "a b'c"
719
720
722 · Print the object name of the current commit:
723
724 $ git rev-parse --verify HEAD
725
726
727 · Print the commit object name from the revision in the $REV shell
728 variable:
729
730 $ git rev-parse --verify $REV^{commit}
731
732 This will error out if $REV is empty or not a valid revision.
733
734 · Similar to above:
735
736 $ git rev-parse --default master --verify $REV
737
738 but if $REV is empty, the commit object name from master will be
739 printed.
740
742 Part of the git(1) suite
743
744
745
746Git 2.24.1 12/10/2019 GIT-REV-PARSE(1)