1 <?xml version="1.0" encoding="UTF-8"?>
\r
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
\r
4 <article lang="en" id="git-rev-parse(1)">
\r
6 <title>git-rev-parse(1)</title>
\r
8 <primary>git-rev-parse(1)</primary>
\r
11 <simplesect id="_name">
\r
13 <simpara>git-rev-parse - Pick out and massage parameters</simpara>
\r
15 <simplesect id="_synopsis">
\r
16 <title>SYNOPSIS</title>
\r
17 <simpara><emphasis>git rev-parse</emphasis> [ --option ] <args>…</simpara>
\r
19 <simplesect id="_description">
\r
20 <title>DESCRIPTION</title>
\r
21 <simpara>Many git porcelainish commands take mixture of flags
\r
22 (i.e. parameters that begin with a dash <emphasis>-</emphasis>) and parameters
\r
23 meant for the underlying <emphasis>git-rev-list</emphasis> command they use internally
\r
24 and flags and parameters for the other commands they use
\r
25 downstream of <emphasis>git-rev-list</emphasis>. This command is used to
\r
26 distinguish between them.</simpara>
\r
28 <simplesect id="_options">
\r
29 <title>OPTIONS</title>
\r
37 Use <emphasis>git-rev-parse</emphasis> in option parsing mode (see PARSEOPT section below).
\r
47 Only meaningful in <literal>--parseopt</literal> mode. Tells the option parser to echo
\r
48 out the first <literal>--</literal> met instead of skipping it.
\r
58 Do not output flags and parameters not meant for
\r
59 <emphasis>git-rev-list</emphasis> command.
\r
69 Do not output flags and parameters meant for
\r
70 <emphasis>git-rev-list</emphasis> command.
\r
80 Do not output non-flag parameters.
\r
90 Do not output flag parameters.
\r
96 --default <arg>
\r
100 If there is no parameter given by the user, use <literal><arg></literal>
\r
111 The parameter given must be usable as a single, valid
\r
112 object name. Otherwise barf and abort.
\r
125 Only meaningful in <literal>--verify</literal> mode. Do not output an error
\r
126 message if the first argument is not a valid object name;
\r
127 instead exit with non-zero status silently.
\r
137 Usually the output is made one line per flag and
\r
138 parameter. This option makes output a single line,
\r
139 properly quoted for consumption by shell. Useful when
\r
140 you expect your parameter to contain whitespaces and
\r
141 newlines (e.g. when using pickaxe <literal>-S</literal> with
\r
142 <emphasis>git-diff-\*</emphasis>).
\r
152 When showing object names, prefix them with <emphasis>^</emphasis> and
\r
153 strip <emphasis>^</emphasis> prefix from the object names that already have
\r
164 Usually the object names are output in SHA1 form (with
\r
165 possible <emphasis>^</emphasis> prefix); this option makes them output in a
\r
166 form as close to the original input as possible.
\r
172 --symbolic-full-name
\r
176 This is similar to --symbolic, but it omits input that
\r
177 are not refs (i.e. branch or tag names; or more
\r
178 explicitly disambiguating "heads/master" form, when you
\r
179 want to name the "master" branch when there is an
\r
180 unfortunately named tag "master"), and show them as full
\r
181 refnames (e.g. "refs/heads/master").
\r
191 Show all refs found in <literal>$GIT_DIR/refs</literal>.
\r
201 Show branch refs found in <literal>$GIT_DIR/refs/heads</literal>.
\r
211 Show tag refs found in <literal>$GIT_DIR/refs/tags</literal>.
\r
221 Show tag refs found in <literal>$GIT_DIR/refs/remotes</literal>.
\r
231 When the command is invoked from a subdirectory, show the
\r
232 path of the current directory relative to the top-level
\r
243 When the command is invoked from a subdirectory, show the
\r
244 path of the top-level directory relative to the current
\r
245 directory (typically a sequence of "../", or an empty string).
\r
255 Show <literal>$GIT_DIR</literal> if defined else show the path to the .git directory.
\r
261 --is-inside-git-dir
\r
265 When the current working directory is below the repository
\r
266 directory print "true", otherwise "false".
\r
272 --is-inside-work-tree
\r
276 When the current working directory is inside the work tree of the
\r
277 repository print "true", otherwise "false".
\r
283 --is-bare-repository
\r
287 When the repository is bare print "true", otherwise "false".
\r
300 Instead of outputting the full SHA1 values of object names try to
\r
301 abbreviate them to a shorter unique name. When no length is specified
\r
302 7 is used. The minimum length is 4.
\r
315 Parse the date string, and output the corresponding
\r
316 --max-age= parameter for <emphasis>git-rev-list</emphasis>.
\r
325 --before=datestring
\r
329 Parse the date string, and output the corresponding
\r
330 --min-age= parameter for <emphasis>git-rev-list</emphasis>.
\r
336 <args>…
\r
340 Flags and parameters to be parsed.
\r
346 <simplesect id="_specifying_revisions">
\r
347 <title>SPECIFYING REVISIONS</title>
\r
348 <simpara>A revision parameter typically, but not necessarily, names a
\r
349 commit object. They use what is called an <emphasis>extended SHA1</emphasis>
\r
350 syntax. Here are various ways to spell object names. The
\r
351 ones listed near the end of this list are to name trees and
\r
352 blobs contained in a commit.</simpara>
\r
356 The full SHA1 object name (40-byte hexadecimal string), or
\r
357 a substring of such that is unique within the repository.
\r
358 E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both
\r
359 name the same commit object if there are no other object in
\r
360 your repository whose object name starts with dae86e.
\r
365 An output from <emphasis>git-describe</emphasis>; i.e. a closest tag, optionally
\r
366 followed by a dash and a number of commits, followed by a dash, a
\r
367 <literal>g</literal>, and an abbreviated object name.
\r
372 A symbolic ref name. E.g. <emphasis>master</emphasis> typically means the commit
\r
373 object referenced by $GIT_DIR/refs/heads/master. If you
\r
374 happen to have both heads/master and tags/master, you can
\r
375 explicitly say <emphasis>heads/master</emphasis> to tell git which one you mean.
\r
376 When ambiguous, a <literal><name></literal> is disambiguated by taking the
\r
377 first match in the following rules:
\r
379 <orderedlist numeration="arabic">
\r
382 if <literal>$GIT_DIR/<name></literal> exists, that is what you mean (this is usually
\r
383 useful only for <literal>HEAD</literal>, <literal>FETCH_HEAD</literal>, <literal>ORIG_HEAD</literal> and <literal>MERGE_HEAD</literal>);
\r
388 otherwise, <literal>$GIT_DIR/refs/<name></literal> if exists;
\r
393 otherwise, <literal>$GIT_DIR/refs/tags/<name></literal> if exists;
\r
398 otherwise, <literal>$GIT_DIR/refs/heads/<name></literal> if exists;
\r
403 otherwise, <literal>$GIT_DIR/refs/remotes/<name></literal> if exists;
\r
408 otherwise, <literal>$GIT_DIR/refs/remotes/<name>/HEAD</literal> if exists.
\r
410 <simpara>HEAD names the commit your changes in the working tree is based on.
\r
411 FETCH_HEAD records the branch you fetched from a remote repository
\r
412 with your last <emphasis>git-fetch</emphasis> invocation.
\r
413 ORIG_HEAD is created by commands that moves your HEAD in a drastic
\r
414 way, to record the position of the HEAD before their operation, so that
\r
415 you can change the tip of the branch back to the state before you ran
\r
417 MERGE_HEAD records the commit(s) you are merging into your branch
\r
418 when you run <emphasis>git-merge</emphasis>.</simpara>
\r
424 A ref followed by the suffix <emphasis>@</emphasis> with a date specification
\r
425 enclosed in a brace
\r
426 pair (e.g. <emphasis>{yesterday}</emphasis>, <emphasis>{1 month 2 weeks 3 days 1 hour 1
\r
427 second ago}</emphasis> or <emphasis>{1979-02-26 18:30:00}</emphasis>) to specify the value
\r
428 of the ref at a prior point in time. This suffix may only be
\r
429 used immediately following a ref name and the ref must have an
\r
430 existing log ($GIT_DIR/logs/<ref>). Note that this looks up the state
\r
431 of your <emphasis role="strong">local</emphasis> ref at a given time; e.g., what was in your local
\r
432 <literal>master</literal> branch last week. If you want to look at commits made during
\r
433 certain times, see <literal>--since</literal> and <literal>--until</literal>.
\r
438 A ref followed by the suffix <emphasis>@</emphasis> with an ordinal specification
\r
439 enclosed in a brace pair (e.g. <emphasis>{1}</emphasis>, <emphasis>{15}</emphasis>) to specify
\r
440 the n-th prior value of that ref. For example <emphasis>master@{1}</emphasis>
\r
441 is the immediate prior value of <emphasis>master</emphasis> while <emphasis>master@{5}</emphasis>
\r
442 is the 5th prior value of <emphasis>master</emphasis>. This suffix may only be used
\r
443 immediately following a ref name and the ref must have an existing
\r
444 log ($GIT_DIR/logs/<ref>).
\r
449 You can use the <emphasis>@</emphasis> construct with an empty ref part to get at a
\r
450 reflog of the current branch. For example, if you are on the
\r
451 branch <emphasis>blabla</emphasis>, then <emphasis>@{1}</emphasis> means the same as <emphasis>blabla@{1}</emphasis>.
\r
456 The special construct <emphasis>@{-<n>}</emphasis> means the <n>th branch checked out
\r
457 before the current one.
\r
462 A suffix <emphasis>^</emphasis> to a revision parameter means the first parent of
\r
463 that commit object. <emphasis>^<n></emphasis> means the <n>th parent (i.e.
\r
464 <emphasis>rev^</emphasis>
\r
465 is equivalent to <emphasis>rev^1</emphasis>). As a special rule,
\r
466 <emphasis>rev^0</emphasis> means the commit itself and is used when <emphasis>rev</emphasis> is the
\r
467 object name of a tag object that refers to a commit object.
\r
472 A suffix <emphasis>~<n></emphasis> to a revision parameter means the commit
\r
473 object that is the <n>th generation grand-parent of the named
\r
474 commit object, following only the first parent. I.e. rev~3 is
\r
475 equivalent to rev^^^ which is equivalent to
\r
476 rev^1^1^1. See below for a illustration of
\r
477 the usage of this form.
\r
482 A suffix <emphasis>^</emphasis> followed by an object type name enclosed in
\r
483 brace pair (e.g. <literal>v0.99.8^{commit}</literal>) means the object
\r
484 could be a tag, and dereference the tag recursively until an
\r
485 object of that type is found or the object cannot be
\r
486 dereferenced anymore (in which case, barf). <literal>rev^0</literal>
\r
487 introduced earlier is a short-hand for <literal>rev^{commit}</literal>.
\r
492 A suffix <emphasis>^</emphasis> followed by an empty brace pair
\r
493 (e.g. <literal>v0.99.8^{}</literal>) means the object could be a tag,
\r
494 and dereference the tag recursively until a non-tag object is
\r
500 A colon, followed by a slash, followed by a text: this names
\r
501 a commit whose commit message starts with the specified text.
\r
502 This name returns the youngest matching commit which is
\r
503 reachable from any ref. If the commit message starts with a
\r
504 <emphasis>!</emphasis>, you have to repeat that; the special sequence <emphasis>:/!</emphasis>,
\r
505 followed by something else than <emphasis>!</emphasis> is reserved for now.
\r
510 A suffix <emphasis>:</emphasis> followed by a path; this names the blob or tree
\r
511 at the given path in the tree-ish object named by the part
\r
517 A colon, optionally followed by a stage number (0 to 3) and a
\r
518 colon, followed by a path; this names a blob object in the
\r
519 index at the given path. Missing stage number (and the colon
\r
520 that follows it) names a stage 0 entry. During a merge, stage
\r
521 1 is the common ancestor, stage 2 is the target branch’s version
\r
522 (typically the current branch), and stage 3 is the version from
\r
523 the branch being merged.
\r
527 <simpara>Here is an illustration, by Jon Loeliger. Both commit nodes B
\r
528 and C are parents of commit node A. Parent commits are ordered
\r
529 left-to-right.</simpara>
\r
530 <literallayout class="monospaced">G H I J
\r
540 <literallayout class="monospaced">A = = A^0
\r
543 D = A^^ = A^1^1 = A~2
\r
546 G = A^^^ = A^1^1^1 = A~3
\r
547 H = D^2 = B^^2 = A^^^2 = A~2^2
\r
548 I = F^ = B^3^ = A^^3^
\r
549 J = F^2 = B^3^2 = A^^3^2</literallayout>
\r
551 <simplesect id="_specifying_ranges">
\r
552 <title>SPECIFYING RANGES</title>
\r
553 <simpara>History traversing commands such as <emphasis>git-log</emphasis> operate on a set
\r
554 of commits, not just a single commit. To these commands,
\r
555 specifying a single revision with the notation described in the
\r
556 previous section means the set of commits reachable from that
\r
557 commit, following the commit ancestry chain.</simpara>
\r
558 <simpara>To exclude commits reachable from a commit, a prefix <literal>^</literal>
\r
559 notation is used. E.g. "<literal>^r1 r2</literal>" means commits reachable
\r
560 from <literal>r2</literal> but exclude the ones reachable from <literal>r1</literal>.</simpara>
\r
561 <simpara>This set operation appears so often that there is a shorthand
\r
562 for it. When you have two commits <literal>r1</literal> and <literal>r2</literal> (named according
\r
563 to the syntax explained in SPECIFYING REVISIONS above), you can ask
\r
564 for commits that are reachable from r2 excluding those that are reachable
\r
565 from r1 by "<literal>^r1 r2</literal>" and it can be written as "<literal>r1..r2</literal>".</simpara>
\r
566 <simpara>A similar notation "<literal>r1...r2</literal>" is called symmetric difference
\r
567 of <literal>r1</literal> and <literal>r2</literal> and is defined as
\r
568 "<literal>r1 r2 --not $(git merge-base --all r1 r2)</literal>".
\r
569 It is the set of commits that are reachable from either one of
\r
570 <literal>r1</literal> or <literal>r2</literal> but not from both.</simpara>
\r
571 <simpara>Two other shorthands for naming a set that is formed by a commit
\r
572 and its parent commits exist. The <literal>r1^@</literal> notation means all
\r
573 parents of <literal>r1</literal>. <literal>r1^!</literal> includes commit <literal>r1</literal> but excludes
\r
574 all of its parents.</simpara>
\r
575 <simpara>Here are a handful of examples:</simpara>
\r
576 <literallayout class="monospaced">D G H D
\r
583 F^! D G H D F</literallayout>
\r
585 <simplesect id="_parseopt">
\r
586 <title>PARSEOPT</title>
\r
587 <simpara>In <literal>--parseopt</literal> mode, <emphasis>git-rev-parse</emphasis> helps massaging options to bring to shell
\r
588 scripts the same facilities C builtins have. It works as an option normalizer
\r
589 (e.g. splits single switches aggregate values), a bit like <literal>getopt(1)</literal> does.</simpara>
\r
590 <simpara>It takes on the standard input the specification of the options to parse and
\r
591 understand, and echoes on the standard output a line suitable for <literal>sh(1)</literal> <literal>eval</literal>
\r
592 to replace the arguments with normalized ones. In case of error, it outputs
\r
593 usage on the standard error stream, and exits with code 129.</simpara>
\r
594 <simplesect id="_input_format">
\r
595 <title>Input Format</title>
\r
596 <simpara><emphasis>git-rev-parse --parseopt</emphasis> input format is fully text based. It has two parts,
\r
597 separated by a line that contains only <literal>--</literal>. The lines before the separator
\r
598 (should be more than one) are used for the usage.
\r
599 The lines after the separator describe the options.</simpara>
\r
600 <simpara>Each line of options has this format:</simpara>
\r
601 <literallayout><opt_spec><flags>* SP+ help LF</literallayout>
\r
605 <literal><opt_spec></literal>
\r
609 its format is the short option character, then the long option name
\r
610 separated by a comma. Both parts are not required, though at least one
\r
611 is necessary. <literal>h,help</literal>, <literal>dry-run</literal> and <literal>f</literal> are all three correct
\r
612 <literal><opt_spec></literal>.
\r
618 <literal><flags></literal>
\r
622 <literal><flags></literal> are of <literal>*</literal>, <literal>=</literal>, <literal>?</literal> or <literal>!</literal>.
\r
627 Use <literal>=</literal> if the option takes an argument.
\r
632 Use <literal>?</literal> to mean that the option is optional (though its use is discouraged).
\r
637 Use <literal>*</literal> to mean that this option should not be listed in the usage
\r
638 generated for the <literal>-h</literal> argument. It’s shown for <literal>--help-all</literal> as
\r
639 documented in <xref linkend="gitcli(7)"/>.
\r
644 Use <literal>!</literal> to not make the corresponding negated long option available.
\r
651 <simpara>The remainder of the line, after stripping the spaces, is used
\r
652 as the help associated to the option.</simpara>
\r
653 <simpara>Blank lines are ignored, and lines that don’t match this specification are used
\r
654 as option group headers (start the line with a space to create such
\r
655 lines on purpose).</simpara>
\r
657 <simplesect id="_example">
\r
658 <title>Example</title>
\r
659 <literallayout>OPTS_SPEC="\
\r
660 some-command [options] <args>...
\r
662 some-command does foo and bar!
\r
664 h,help show the help
\r
666 foo some nifty option --foo
\r
667 bar= some cool option --bar with an argument
\r
669 An option group Header
\r
670 C? option C with an optional argument"
\r
672 eval `echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?`</literallayout>
\r
675 <simplesect id="_examples">
\r
676 <title>EXAMPLES</title>
\r
680 Print the object name of the current commit:
\r
682 <literallayout>$ git rev-parse --verify HEAD</literallayout>
\r
686 Print the commit object name from the revision in the $REV shell variable:
\r
688 <literallayout>$ git rev-parse --verify $REV</literallayout>
\r
689 <simpara>This will error out if $REV is empty or not a valid revision.</simpara>
\r
695 <literallayout>$ git rev-parse --default master --verify $REV</literallayout>
\r
696 <simpara>but if $REV is empty, the commit object name from master will be printed.</simpara>
\r
700 <simplesect id="_author">
\r
701 <title>Author</title>
\r
702 <simpara>Written by Linus Torvalds <<ulink url="mailto:torvalds@osdl.org">torvalds@osdl.org</ulink>> .
\r
703 Junio C Hamano <<ulink url="mailto:gitster@pobox.com">gitster@pobox.com</ulink>> and Pierre Habouzit <<ulink url="mailto:madcoder@debian.org">madcoder@debian.org</ulink>></simpara>
\r
705 <simplesect id="_documentation">
\r
706 <title>Documentation</title>
\r
707 <simpara>Documentation by Junio C Hamano and the git-list <<ulink url="mailto:git@vger.kernel.org">git@vger.kernel.org</ulink>>.</simpara>
\r
709 <simplesect id="_git">
\r
711 <simpara>Part of the <xref linkend="git(1)"/> suite</simpara>
\r
OSDN Git Service
