git-rev-parse.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   2     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   6 <meta name="generator" content="AsciiDoc 8.2.5" />
   7 <style type="text/css">
   8 /* Debug borders */
   9 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
  10 /*
  11   border: 1px solid red;
  12 */
  13 }
  14
  15 body {
  16   margin: 1em 5% 1em 5%;
  17 }
  18
  19 a {
  20   color: blue;
  21   text-decoration: underline;
  22 }
  23 a:visited {
  24   color: fuchsia;
  25 }
  26
  27 em {
  28   font-style: italic;
  29 }
  30
  31 strong {
  32   font-weight: bold;
  33 }
  34
  35 tt {
  36   color: navy;
  37 }
  38
  39 h1, h2, h3, h4, h5, h6 {
  40   color: #527bbd;
  41   font-family: sans-serif;
  42   margin-top: 1.2em;
  43   margin-bottom: 0.5em;
  44   line-height: 1.3;
  45 }
  46
  47 h1, h2, h3 {
  48   border-bottom: 2px solid silver;
  49 }
  50 h2 {
  51   padding-top: 0.5em;
  52 }
  53 h3 {
  54   float: left;
  55 }
  56 h3 + * {
  57   clear: left;
  58 }
  59
  60 div.sectionbody {
  61   font-family: serif;
  62   margin-left: 0;
  63 }
  64
  65 hr {
  66   border: 1px solid silver;
  67 }
  68
  69 p {
  70   margin-top: 0.5em;
  71   margin-bottom: 0.5em;
  72 }
  73
  74 pre {
  75   padding: 0;
  76   margin: 0;
  77 }
  78
  79 span#author {
  80   color: #527bbd;
  81   font-family: sans-serif;
  82   font-weight: bold;
  83   font-size: 1.1em;
  84 }
  85 span#email {
  86 }
  87 span#revision {
  88   font-family: sans-serif;
  89 }
  90
  91 div#footer {
  92   font-family: sans-serif;
  93   font-size: small;
  94   border-top: 2px solid silver;
  95   padding-top: 0.5em;
  96   margin-top: 4.0em;
  97 }
  98 div#footer-text {
  99   float: left;
 100   padding-bottom: 0.5em;
 101 }
 102 div#footer-badges {
 103   float: right;
 104   padding-bottom: 0.5em;
 105 }
 106
 107 div#preamble,
 108 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
 109 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 110 div.admonitionblock {
 111   margin-right: 10%;
 112   margin-top: 1.5em;
 113   margin-bottom: 1.5em;
 114 }
 115 div.admonitionblock {
 116   margin-top: 2.5em;
 117   margin-bottom: 2.5em;
 118 }
 119
 120 div.content { /* Block element content. */
 121   padding: 0;
 122 }
 123
 124 /* Block element titles. */
 125 div.title, caption.title {
 126   font-family: sans-serif;
 127   font-weight: bold;
 128   text-align: left;
 129   margin-top: 1.0em;
 130   margin-bottom: 0.5em;
 131 }
 132 div.title + * {
 133   margin-top: 0;
 134 }
 135
 136 td div.title:first-child {
 137   margin-top: 0.0em;
 138 }
 139 div.content div.title:first-child {
 140   margin-top: 0.0em;
 141 }
 142 div.content + div.title {
 143   margin-top: 0.0em;
 144 }
 145
 146 div.sidebarblock > div.content {
 147   background: #ffffee;
 148   border: 1px solid silver;
 149   padding: 0.5em;
 150 }
 151
 152 div.listingblock {
 153   margin-right: 0%;
 154 }
 155 div.listingblock > div.content {
 156   border: 1px solid silver;
 157   background: #f4f4f4;
 158   padding: 0.5em;
 159 }
 160
 161 div.quoteblock > div.content {
 162   padding-left: 2.0em;
 163 }
 164
 165 div.attribution {
 166   text-align: right;
 167 }
 168 div.verseblock + div.attribution {
 169   text-align: left;
 170 }
 171
 172 div.admonitionblock .icon {
 173   vertical-align: top;
 174   font-size: 1.1em;
 175   font-weight: bold;
 176   text-decoration: underline;
 177   color: #527bbd;
 178   padding-right: 0.5em;
 179 }
 180 div.admonitionblock td.content {
 181   padding-left: 0.5em;
 182   border-left: 2px solid silver;
 183 }
 184
 185 div.exampleblock > div.content {
 186   border-left: 2px solid silver;
 187   padding: 0.5em;
 188 }
 189
 190 div.verseblock div.content {
 191   white-space: pre;
 192 }
 193
 194 div.imageblock div.content { padding-left: 0; }
 195 div.imageblock img { border: 1px solid silver; }
 196 span.image img { border-style: none; }
 197
 198 dl {
 199   margin-top: 0.8em;
 200   margin-bottom: 0.8em;
 201 }
 202 dt {
 203   margin-top: 0.5em;
 204   margin-bottom: 0;
 205   font-style: italic;
 206 }
 207 dd > *:first-child {
 208   margin-top: 0;
 209 }
 210
 211 ul, ol {
 212     list-style-position: outside;
 213 }
 214 div.olist2 ol {
 215   list-style-type: lower-alpha;
 216 }
 217
 218 div.tableblock > table {
 219   border: 3px solid #527bbd;
 220 }
 221 thead {
 222   font-family: sans-serif;
 223   font-weight: bold;
 224 }
 225 tfoot {
 226   font-weight: bold;
 227 }
 228
 229 div.hlist {
 230   margin-top: 0.8em;
 231   margin-bottom: 0.8em;
 232 }
 233 div.hlist td {
 234   padding-bottom: 5px;
 235 }
 236 td.hlist1 {
 237   vertical-align: top;
 238   font-style: italic;
 239   padding-right: 0.8em;
 240 }
 241 td.hlist2 {
 242   vertical-align: top;
 243 }
 244
 245 @media print {
 246   div#footer-badges { display: none; }
 247 }
 248
 249 div#toctitle {
 250   color: #527bbd;
 251   font-family: sans-serif;
 252   font-size: 1.1em;
 253   font-weight: bold;
 254   margin-top: 1.0em;
 255   margin-bottom: 0.1em;
 256 }
 257
 258 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
 259   margin-top: 0;
 260   margin-bottom: 0;
 261 }
 262 div.toclevel2 {
 263   margin-left: 2em;
 264   font-size: 0.9em;
 265 }
 266 div.toclevel3 {
 267   margin-left: 4em;
 268   font-size: 0.9em;
 269 }
 270 div.toclevel4 {
 271   margin-left: 6em;
 272   font-size: 0.9em;
 273 }
 274 include1::./stylesheets/xhtml11-manpage.css[]
 275 /* Workarounds for IE6's broken and incomplete CSS2. */
 276
 277 div.sidebar-content {
 278   background: #ffffee;
 279   border: 1px solid silver;
 280   padding: 0.5em;
 281 }
 282 div.sidebar-title, div.image-title {
 283   font-family: sans-serif;
 284   font-weight: bold;
 285   margin-top: 0.0em;
 286   margin-bottom: 0.5em;
 287 }
 288
 289 div.listingblock div.content {
 290   border: 1px solid silver;
 291   background: #f4f4f4;
 292   padding: 0.5em;
 293 }
 294
 295 div.quoteblock-content {
 296   padding-left: 2.0em;
 297 }
 298
 299 div.exampleblock-content {
 300   border-left: 2px solid silver;
 301   padding-left: 0.5em;
 302 }
 303
 304 /* IE6 sets dynamically generated links as visited. */
 305 div#toc a:visited { color: blue; }
 306 </style>
 307 <title>git-rev-parse(1)</title>
 308 </head>
 309 <body>
 310 <div id="header">
 311 <h1>
 312 git-rev-parse(1) Manual Page
 313 </h1>
 314 <h2>NAME</h2>
 315 <div class="sectionbody">
 316 <p>git-rev-parse -
 317    Pick out and massage parameters
 318 </p>
 319 </div>
 320 </div>
 321 <h2>SYNOPSIS</h2>
 322 <div class="sectionbody">
 323 <div class="para"><p><em>git rev-parse</em> [ --option ] &lt;args&gt;&#8230;</p></div>
 324 </div>
 325 <h2 id="_description">DESCRIPTION</h2>
 326 <div class="sectionbody">
 327 <div class="para"><p>Many git porcelainish commands take mixture of flags
 328 (i.e. parameters that begin with a dash <em>-</em>) and parameters
 329 meant for the underlying <em>git-rev-list</em> command they use internally
 330 and flags and parameters for the other commands they use
 331 downstream of <em>git-rev-list</em>.  This command is used to
 332 distinguish between them.</p></div>
 333 </div>
 334 <h2 id="_options">OPTIONS</h2>
 335 <div class="sectionbody">
 336 <div class="vlist"><dl>
 337 <dt>
 338 --parseopt
 339 </dt>
 340 <dd>
 341 <p>
 342         Use <em>git-rev-parse</em> in option parsing mode (see PARSEOPT section below).
 343 </p>
 344 </dd>
 345 <dt>
 346 --keep-dashdash
 347 </dt>
 348 <dd>
 349 <p>
 350         Only meaningful in <tt>--parseopt</tt> mode. Tells the option parser to echo
 351         out the first <tt>--</tt> met instead of skipping it.
 352 </p>
 353 </dd>
 354 <dt>
 355 --stop-at-non-option
 356 </dt>
 357 <dd>
 358 <p>
 359         Only meaningful in <tt>--parseopt</tt> mode.  Lets the option parser stop at
 360         the first non-option argument.  This can be used to parse sub-commands
 361         that take options themself.
 362 </p>
 363 </dd>
 364 <dt>
 365 --sq-quote
 366 </dt>
 367 <dd>
 368 <p>
 369         Use <em>git-rev-parse</em> in shell quoting mode (see SQ-QUOTE
 370         section below). In contrast to the <tt>--sq</tt> option below, this
 371         mode does only quoting. Nothing else is done to command input.
 372 </p>
 373 </dd>
 374 <dt>
 375 --revs-only
 376 </dt>
 377 <dd>
 378 <p>
 379         Do not output flags and parameters not meant for
 380         <em>git-rev-list</em> command.
 381 </p>
 382 </dd>
 383 <dt>
 384 --no-revs
 385 </dt>
 386 <dd>
 387 <p>
 388         Do not output flags and parameters meant for
 389         <em>git-rev-list</em> command.
 390 </p>
 391 </dd>
 392 <dt>
 393 --flags
 394 </dt>
 395 <dd>
 396 <p>
 397         Do not output non-flag parameters.
 398 </p>
 399 </dd>
 400 <dt>
 401 --no-flags
 402 </dt>
 403 <dd>
 404 <p>
 405         Do not output flag parameters.
 406 </p>
 407 </dd>
 408 <dt>
 409 --default &lt;arg&gt;
 410 </dt>
 411 <dd>
 412 <p>
 413         If there is no parameter given by the user, use <tt>&lt;arg&gt;</tt>
 414         instead.
 415 </p>
 416 </dd>
 417 <dt>
 418 --verify
 419 </dt>
 420 <dd>
 421 <p>
 422         The parameter given must be usable as a single, valid
 423         object name.  Otherwise barf and abort.
 424 </p>
 425 </dd>
 426 <dt>
 427 -q
 428 </dt>
 429 <dt>
 430 --quiet
 431 </dt>
 432 <dd>
 433 <p>
 434         Only meaningful in <tt>--verify</tt> mode. Do not output an error
 435         message if the first argument is not a valid object name;
 436         instead exit with non-zero status silently.
 437 </p>
 438 </dd>
 439 <dt>
 440 --sq
 441 </dt>
 442 <dd>
 443 <p>
 444         Usually the output is made one line per flag and
 445         parameter.  This option makes output a single line,
 446         properly quoted for consumption by shell.  Useful when
 447         you expect your parameter to contain whitespaces and
 448         newlines (e.g. when using pickaxe <tt>-S</tt> with
 449         <em>git-diff-*</em>). In contrast to the <tt>--sq-quote</tt> option,
 450         the command input is still interpreted as usual.
 451 </p>
 452 </dd>
 453 <dt>
 454 --not
 455 </dt>
 456 <dd>
 457 <p>
 458         When showing object names, prefix them with <em>&#94;</em> and
 459         strip <em>&#94;</em> prefix from the object names that already have
 460         one.
 461 </p>
 462 </dd>
 463 <dt>
 464 --symbolic
 465 </dt>
 466 <dd>
 467 <p>
 468         Usually the object names are output in SHA1 form (with
 469         possible <em>&#94;</em> prefix); this option makes them output in a
 470         form as close to the original input as possible.
 471 </p>
 472 </dd>
 473 <dt>
 474 --symbolic-full-name
 475 </dt>
 476 <dd>
 477 <p>
 478         This is similar to --symbolic, but it omits input that
 479         are not refs (i.e. branch or tag names; or more
 480         explicitly disambiguating "heads/master" form, when you
 481         want to name the "master" branch when there is an
 482         unfortunately named tag "master"), and show them as full
 483         refnames (e.g. "refs/heads/master").
 484 </p>
 485 </dd>
 486 <dt>
 487 --abbrev-ref[={strict|loose}]
 488 </dt>
 489 <dd>
 490 <p>
 491         A non-ambiguous short name of the objects name.
 492         The option core.warnAmbiguousRefs is used to select the strict
 493         abbreviation mode.
 494 </p>
 495 </dd>
 496 <dt>
 497 --all
 498 </dt>
 499 <dd>
 500 <p>
 501         Show all refs found in <tt>$GIT_DIR/refs</tt>.
 502 </p>
 503 </dd>
 504 <dt>
 505 --branches
 506 </dt>
 507 <dd>
 508 <p>
 509         Show branch refs found in <tt>$GIT_DIR/refs/heads</tt>.
 510 </p>
 511 </dd>
 512 <dt>
 513 --tags
 514 </dt>
 515 <dd>
 516 <p>
 517         Show tag refs found in <tt>$GIT_DIR/refs/tags</tt>.
 518 </p>
 519 </dd>
 520 <dt>
 521 --remotes
 522 </dt>
 523 <dd>
 524 <p>
 525         Show tag refs found in <tt>$GIT_DIR/refs/remotes</tt>.
 526 </p>
 527 </dd>
 528 <dt>
 529 --show-prefix
 530 </dt>
 531 <dd>
 532 <p>
 533         When the command is invoked from a subdirectory, show the
 534         path of the current directory relative to the top-level
 535         directory.
 536 </p>
 537 </dd>
 538 <dt>
 539 --show-cdup
 540 </dt>
 541 <dd>
 542 <p>
 543         When the command is invoked from a subdirectory, show the
 544         path of the top-level directory relative to the current
 545         directory (typically a sequence of "../", or an empty string).
 546 </p>
 547 </dd>
 548 <dt>
 549 --git-dir
 550 </dt>
 551 <dd>
 552 <p>
 553         Show <tt>$GIT_DIR</tt> if defined else show the path to the .git directory.
 554 </p>
 555 </dd>
 556 <dt>
 557 --is-inside-git-dir
 558 </dt>
 559 <dd>
 560 <p>
 561         When the current working directory is below the repository
 562         directory print "true", otherwise "false".
 563 </p>
 564 </dd>
 565 <dt>
 566 --is-inside-work-tree
 567 </dt>
 568 <dd>
 569 <p>
 570         When the current working directory is inside the work tree of the
 571         repository print "true", otherwise "false".
 572 </p>
 573 </dd>
 574 <dt>
 575 --is-bare-repository
 576 </dt>
 577 <dd>
 578 <p>
 579         When the repository is bare print "true", otherwise "false".
 580 </p>
 581 </dd>
 582 <dt>
 583 --short
 584 </dt>
 585 <dt>
 586 --short=number
 587 </dt>
 588 <dd>
 589 <p>
 590         Instead of outputting the full SHA1 values of object names try to
 591         abbreviate them to a shorter unique name. When no length is specified
 592         7 is used. The minimum length is 4.
 593 </p>
 594 </dd>
 595 <dt>
 596 --since=datestring
 597 </dt>
 598 <dt>
 599 --after=datestring
 600 </dt>
 601 <dd>
 602 <p>
 603         Parse the date string, and output the corresponding
 604         --max-age= parameter for <em>git-rev-list</em>.
 605 </p>
 606 </dd>
 607 <dt>
 608 --until=datestring
 609 </dt>
 610 <dt>
 611 --before=datestring
 612 </dt>
 613 <dd>
 614 <p>
 615         Parse the date string, and output the corresponding
 616         --min-age= parameter for <em>git-rev-list</em>.
 617 </p>
 618 </dd>
 619 <dt>
 620 &lt;args&gt;&#8230;
 621 </dt>
 622 <dd>
 623 <p>
 624         Flags and parameters to be parsed.
 625 </p>
 626 </dd>
 627 </dl></div>
 628 </div>
 629 <h2 id="_specifying_revisions">SPECIFYING REVISIONS</h2>
 630 <div class="sectionbody">
 631 <div class="para"><p>A revision parameter typically, but not necessarily, names a
 632 commit object.  They use what is called an <em>extended SHA1</em>
 633 syntax.  Here are various ways to spell object names.  The
 634 ones listed near the end of this list are to name trees and
 635 blobs contained in a commit.</p></div>
 636 <div class="ilist"><ul>
 637 <li>
 638 <p>
 639 The full SHA1 object name (40-byte hexadecimal string), or
 640   a substring of such that is unique within the repository.
 641   E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both
 642   name the same commit object if there are no other object in
 643   your repository whose object name starts with dae86e.
 644 </p>
 645 </li>
 646 <li>
 647 <p>
 648 An output from <em>git-describe</em>; i.e. a closest tag, optionally
 649   followed by a dash and a number of commits, followed by a dash, a
 650   <tt>g</tt>, and an abbreviated object name.
 651 </p>
 652 </li>
 653 <li>
 654 <p>
 655 A symbolic ref name.  E.g. <em>master</em> typically means the commit
 656   object referenced by $GIT_DIR/refs/heads/master.  If you
 657   happen to have both heads/master and tags/master, you can
 658   explicitly say <em>heads/master</em> to tell git which one you mean.
 659   When ambiguous, a <tt>&lt;name&gt;</tt> is disambiguated by taking the
 660   first match in the following rules:
 661 </p>
 662 <div class="olist"><ol>
 663 <li>
 664 <p>
 665 if <tt>$GIT_DIR/&lt;name&gt;</tt> exists, that is what you mean (this is usually
 666     useful only for <tt>HEAD</tt>, <tt>FETCH_HEAD</tt>, <tt>ORIG_HEAD</tt> and <tt>MERGE_HEAD</tt>);
 667 </p>
 668 </li>
 669 <li>
 670 <p>
 671 otherwise, <tt>$GIT_DIR/refs/&lt;name&gt;</tt> if exists;
 672 </p>
 673 </li>
 674 <li>
 675 <p>
 676 otherwise, <tt>$GIT_DIR/refs/tags/&lt;name&gt;</tt> if exists;
 677 </p>
 678 </li>
 679 <li>
 680 <p>
 681 otherwise, <tt>$GIT_DIR/refs/heads/&lt;name&gt;</tt> if exists;
 682 </p>
 683 </li>
 684 <li>
 685 <p>
 686 otherwise, <tt>$GIT_DIR/refs/remotes/&lt;name&gt;</tt> if exists;
 687 </p>
 688 </li>
 689 <li>
 690 <p>
 691 otherwise, <tt>$GIT_DIR/refs/remotes/&lt;name&gt;/HEAD</tt> if exists.
 692 </p>
 693 <div class="para"><p>HEAD names the commit your changes in the working tree is based on.
 694 FETCH_HEAD records the branch you fetched from a remote repository
 695 with your last <em>git-fetch</em> invocation.
 696 ORIG_HEAD is created by commands that moves your HEAD in a drastic
 697 way, to record the position of the HEAD before their operation, so that
 698 you can change the tip of the branch back to the state before you ran
 699 them easily.
 700 MERGE_HEAD records the commit(s) you are merging into your branch
 701 when you run <em>git-merge</em>.</p></div>
 702 </li>
 703 </ol></div>
 704 </li>
 705 <li>
 706 <p>
 707 A ref followed by the suffix <em>@</em> with a date specification
 708   enclosed in a brace
 709   pair (e.g. <em>{yesterday}</em>, <em>{1 month 2 weeks 3 days 1 hour 1
 710   second ago}</em> or <em>{1979-02-26 18:30:00}</em>) to specify the value
 711   of the ref at a prior point in time.  This suffix may only be
 712   used immediately following a ref name and the ref must have an
 713   existing log ($GIT_DIR/logs/&lt;ref&gt;). Note that this looks up the state
 714   of your <strong>local</strong> ref at a given time; e.g., what was in your local
 715   <tt>master</tt> branch last week. If you want to look at commits made during
 716   certain times, see <tt>--since</tt> and <tt>--until</tt>.
 717 </p>
 718 </li>
 719 <li>
 720 <p>
 721 A ref followed by the suffix <em>@</em> with an ordinal specification
 722   enclosed in a brace pair (e.g. <em>{1}</em>, <em>{15}</em>) to specify
 723   the n-th prior value of that ref.  For example <em>master@{1}</em>
 724   is the immediate prior value of <em>master</em> while <em>master@{5}</em>
 725   is the 5th prior value of <em>master</em>. This suffix may only be used
 726   immediately following a ref name and the ref must have an existing
 727   log ($GIT_DIR/logs/&lt;ref&gt;).
 728 </p>
 729 </li>
 730 <li>
 731 <p>
 732 You can use the <em>@</em> construct with an empty ref part to get at a
 733   reflog of the current branch. For example, if you are on the
 734   branch <em>blabla</em>, then <em>@{1}</em> means the same as <em>blabla@{1}</em>.
 735 </p>
 736 </li>
 737 <li>
 738 <p>
 739 The special construct <em>@{-&lt;n&gt;}</em> means the &lt;n&gt;th branch checked out
 740   before the current one.
 741 </p>
 742 </li>
 743 <li>
 744 <p>
 745 A suffix <em>&#94;</em> to a revision parameter means the first parent of
 746   that commit object.  <em>&#94;&lt;n&gt;</em> means the &lt;n&gt;th parent (i.e.
 747   <em>rev&#94;</em>
 748   is equivalent to <em>rev&#94;1</em>).  As a special rule,
 749   <em>rev&#94;0</em> means the commit itself and is used when <em>rev</em> is the
 750   object name of a tag object that refers to a commit object.
 751 </p>
 752 </li>
 753 <li>
 754 <p>
 755 A suffix <em>&#126;&lt;n&gt;</em> to a revision parameter means the commit
 756   object that is the &lt;n&gt;th generation grand-parent of the named
 757   commit object, following only the first parent.  I.e. rev~3 is
 758   equivalent to rev&#94;&#94;&#94; which is equivalent to
 759   rev&#94;1&#94;1&#94;1.  See below for a illustration of
 760   the usage of this form.
 761 </p>
 762 </li>
 763 <li>
 764 <p>
 765 A suffix <em>&#94;</em> followed by an object type name enclosed in
 766   brace pair (e.g. <tt>v0.99.8&#94;{commit}</tt>) means the object
 767   could be a tag, and dereference the tag recursively until an
 768   object of that type is found or the object cannot be
 769   dereferenced anymore (in which case, barf).  <tt>rev&#94;0</tt>
 770   introduced earlier is a short-hand for <tt>rev&#94;{commit}</tt>.
 771 </p>
 772 </li>
 773 <li>
 774 <p>
 775 A suffix <em>&#94;</em> followed by an empty brace pair
 776   (e.g. <tt>v0.99.8&#94;{}</tt>) means the object could be a tag,
 777   and dereference the tag recursively until a non-tag object is
 778   found.
 779 </p>
 780 </li>
 781 <li>
 782 <p>
 783 A colon, followed by a slash, followed by a text: this names
 784   a commit whose commit message starts with the specified text.
 785   This name returns the youngest matching commit which is
 786   reachable from any ref.  If the commit message starts with a
 787   <em>!</em>, you have to repeat that;  the special sequence <em>:/!</em>,
 788   followed by something else than <em>!</em> is reserved for now.
 789 </p>
 790 </li>
 791 <li>
 792 <p>
 793 A suffix <em>:</em> followed by a path; this names the blob or tree
 794   at the given path in the tree-ish object named by the part
 795   before the colon.
 796 </p>
 797 </li>
 798 <li>
 799 <p>
 800 A colon, optionally followed by a stage number (0 to 3) and a
 801   colon, followed by a path; this names a blob object in the
 802   index at the given path.  Missing stage number (and the colon
 803   that follows it) names a stage 0 entry. During a merge, stage
 804   1 is the common ancestor, stage 2 is the target branch's version
 805   (typically the current branch), and stage 3 is the version from
 806   the branch being merged.
 807 </p>
 808 </li>
 809 </ul></div>
 810 <div class="para"><p>Here is an illustration, by Jon Loeliger.  Both commit nodes B
 811 and C are parents of commit node A.  Parent commits are ordered
 812 left-to-right.</p></div>
 813 <div class="literalblock">
 814 <div class="content">
 815 <pre><tt>G   H   I   J
 816  \ /     \ /
 817   D   E   F
 818    \  |  / \
 819     \ | /   |
 820      \|/    |
 821       B     C
 822        \   /
 823         \ /
 824          A</tt></pre>
 825 </div></div>
 826 <div class="literalblock">
 827 <div class="content">
 828 <pre><tt>A =      = A^0
 829 B = A^   = A^1     = A~1
 830 C = A^2  = A^2
 831 D = A^^  = A^1^1   = A~2
 832 E = B^2  = A^^2
 833 F = B^3  = A^^3
 834 G = A^^^ = A^1^1^1 = A~3
 835 H = D^2  = B^^2    = A^^^2  = A~2^2
 836 I = F^   = B^3^    = A^^3^
 837 J = F^2  = B^3^2   = A^^3^2</tt></pre>
 838 </div></div>
 839 </div>
 840 <h2 id="_specifying_ranges">SPECIFYING RANGES</h2>
 841 <div class="sectionbody">
 842 <div class="para"><p>History traversing commands such as <em>git-log</em> operate on a set
 843 of commits, not just a single commit.  To these commands,
 844 specifying a single revision with the notation described in the
 845 previous section means the set of commits reachable from that
 846 commit, following the commit ancestry chain.</p></div>
 847 <div class="para"><p>To exclude commits reachable from a commit, a prefix <tt>&#94;</tt>
 848 notation is used.  E.g. <tt>&#94;r1 r2</tt> means commits reachable
 849 from <tt>r2</tt> but exclude the ones reachable from <tt>r1</tt>.</p></div>
 850 <div class="para"><p>This set operation appears so often that there is a shorthand
 851 for it.  When you have two commits <tt>r1</tt> and <tt>r2</tt> (named according
 852 to the syntax explained in SPECIFYING REVISIONS above), you can ask
 853 for commits that are reachable from r2 excluding those that are reachable
 854 from r1 by <tt>&#94;r1 r2</tt> and it can be written as <tt>r1..r2</tt>.</p></div>
 855 <div class="para"><p>A similar notation <tt>r1...r2</tt> is called symmetric difference
 856 of <tt>r1</tt> and <tt>r2</tt> and is defined as
 857 <tt>r1 r2 --not $(git merge-base --all r1 r2)</tt>.
 858 It is the set of commits that are reachable from either one of
 859 <tt>r1</tt> or <tt>r2</tt> but not from both.</p></div>
 860 <div class="para"><p>Two other shorthands for naming a set that is formed by a commit
 861 and its parent commits exist.  The <tt>r1&#94;@</tt> notation means all
 862 parents of <tt>r1</tt>.  <tt>r1&#94;!</tt> includes commit <tt>r1</tt> but excludes
 863 all of its parents.</p></div>
 864 <div class="para"><p>Here are a handful of examples:</p></div>
 865 <div class="literalblock">
 866 <div class="content">
 867 <pre><tt>D                G H D
 868 D F              G H I J D F
 869 ^G D             H D
 870 ^D B             E I J F B
 871 B...C            G H D E B C
 872 ^D B C           E I J F B C
 873 C^@              I J F
 874 F^! D            G H D F</tt></pre>
 875 </div></div>
 876 </div>
 877 <h2 id="_parseopt">PARSEOPT</h2>
 878 <div class="sectionbody">
 879 <div class="para"><p>In <tt>--parseopt</tt> mode, <em>git-rev-parse</em> helps massaging options to bring to shell
 880 scripts the same facilities C builtins have. It works as an option normalizer
 881 (e.g. splits single switches aggregate values), a bit like <tt>getopt(1)</tt> does.</p></div>
 882 <div class="para"><p>It takes on the standard input the specification of the options to parse and
 883 understand, and echoes on the standard output a line suitable for <tt>sh(1)</tt> <tt>eval</tt>
 884 to replace the arguments with normalized ones.  In case of error, it outputs
 885 usage on the standard error stream, and exits with code 129.</p></div>
 886 <h3 id="_input_format">Input Format</h3><div style="clear:left"></div>
 887 <div class="para"><p><em>git-rev-parse --parseopt</em> input format is fully text based. It has two parts,
 888 separated by a line that contains only <tt>--</tt>. The lines before the separator
 889 (should be more than one) are used for the usage.
 890 The lines after the separator describe the options.</p></div>
 891 <div class="para"><p>Each line of options has this format:</p></div>
 892 <div class="listingblock">
 893 <div class="content">
 894 <pre><tt>&lt;opt_spec&gt;&lt;flags&gt;* SP+ help LF</tt></pre>
 895 </div></div>
 896 <div class="vlist"><dl>
 897 <dt>
 898 <tt>&lt;opt_spec&gt;</tt>
 899 </dt>
 900 <dd>
 901 <p>
 902         its format is the short option character, then the long option name
 903         separated by a comma. Both parts are not required, though at least one
 904         is necessary. <tt>h,help</tt>, <tt>dry-run</tt> and <tt>f</tt> are all three correct
 905         <tt>&lt;opt_spec&gt;</tt>.
 906 </p>
 907 </dd>
 908 <dt>
 909 <tt>&lt;flags&gt;</tt>
 910 </dt>
 911 <dd>
 912 <p>
 913         <tt>&lt;flags&gt;</tt> are of <tt>*</tt>, <tt>=</tt>, <tt>?</tt> or <tt>!</tt>.
 914 </p>
 915 <div class="ilist"><ul>
 916 <li>
 917 <p>
 918 Use <tt>=</tt> if the option takes an argument.
 919 </p>
 920 </li>
 921 <li>
 922 <p>
 923 Use <tt>?</tt> to mean that the option is optional (though its use is discouraged).
 924 </p>
 925 </li>
 926 <li>
 927 <p>
 928 Use <tt>*</tt> to mean that this option should not be listed in the usage
 929           generated for the <tt>-h</tt> argument. It's shown for <tt>--help-all</tt> as
 930           documented in <a href="gitcli.html">gitcli(7)</a>.
 931 </p>
 932 </li>
 933 <li>
 934 <p>
 935 Use <tt>!</tt> to not make the corresponding negated long option available.
 936 </p>
 937 </li>
 938 </ul></div>
 939 </dd>
 940 </dl></div>
 941 <div class="para"><p>The remainder of the line, after stripping the spaces, is used
 942 as the help associated to the option.</p></div>
 943 <div class="para"><p>Blank lines are ignored, and lines that don't match this specification are used
 944 as option group headers (start the line with a space to create such
 945 lines on purpose).</p></div>
 946 <h3 id="_example">Example</h3><div style="clear:left"></div>
 947 <div class="listingblock">
 948 <div class="content">
 949 <pre><tt>OPTS_SPEC="\
 950 some-command [options] &lt;args&gt;...
 951
 952 some-command does foo and bar!
 953 --
 954 h,help    show the help
 955
 956 foo       some nifty option --foo
 957 bar=      some cool option --bar with an argument
 958
 959   An option group Header
 960 C?        option C with an optional argument"
 961
 962 eval `echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?`</tt></pre>
 963 </div></div>
 964 </div>
 965 <h2 id="_sq_quote">SQ-QUOTE</h2>
 966 <div class="sectionbody">
 967 <div class="para"><p>In <tt>--sq-quote</tt> mode, <em>git-rev-parse</em> echoes on the standard output a
 968 single line suitable for <tt>sh(1)</tt> <tt>eval</tt>. This line is made by
 969 normalizing the arguments following <tt>--sq-quote</tt>. Nothing other than
 970 quoting the arguments is done.</p></div>
 971 <div class="para"><p>If you want command input to still be interpreted as usual by
 972 <em>git-rev-parse</em> before the output is shell quoted, see the <tt>--sq</tt>
 973 option.</p></div>
 974 <h3 id="_example_2">Example</h3><div style="clear:left"></div>
 975 <div class="listingblock">
 976 <div class="content">
 977 <pre><tt>$ cat &gt;your-git-script.sh &lt;&lt;\EOF
 978 #!/bin/sh
 979 args=$(git rev-parse --sq-quote "$@")   # quote user-supplied arguments
 980 command="git frotz -n24 $args"          # and use it inside a handcrafted
 981                                         # command line
 982 eval "$command"
 983 EOF
 984
 985 $ sh your-git-script.sh "a b'c"</tt></pre>
 986 </div></div>
 987 </div>
 988 <h2 id="_examples">EXAMPLES</h2>
 989 <div class="sectionbody">
 990 <div class="ilist"><ul>
 991 <li>
 992 <p>
 993 Print the object name of the current commit:
 994 </p>
 995 <div class="listingblock">
 996 <div class="content">
 997 <pre><tt>$ git rev-parse --verify HEAD</tt></pre>
 998 </div></div>
 999 </li>
1000 <li>
1001 <p>
1002 Print the commit object name from the revision in the $REV shell variable:
1003 </p>
1004 <div class="listingblock">
1005 <div class="content">
1006 <pre><tt>$ git rev-parse --verify $REV</tt></pre>
1007 </div></div>
1008 <div class="para"><p>This will error out if $REV is empty or not a valid revision.</p></div>
1009 </li>
1010 <li>
1011 <p>
1012 Same as above:
1013 </p>
1014 <div class="listingblock">
1015 <div class="content">
1016 <pre><tt>$ git rev-parse --default master --verify $REV</tt></pre>
1017 </div></div>
1018 <div class="para"><p>but if $REV is empty, the commit object name from master will be printed.</p></div>
1019 </li>
1020 </ul></div>
1021 </div>
1022 <h2 id="_author">Author</h2>
1023 <div class="sectionbody">
1024 <div class="para"><p>Written by Linus Torvalds &lt;torvalds@osdl.org&gt; .
1025 Junio C Hamano &lt;gitster@pobox.com&gt; and Pierre Habouzit &lt;madcoder@debian.org&gt;</p></div>
1026 </div>
1027 <h2 id="_documentation">Documentation</h2>
1028 <div class="sectionbody">
1029 <div class="para"><p>Documentation by Junio C Hamano and the git-list &lt;git@vger.kernel.org&gt;.</p></div>
1030 </div>
1031 <h2 id="_git">GIT</h2>
1032 <div class="sectionbody">
1033 <div class="para"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
1034 </div>
1035 <div id="footer">
1036 <div id="footer-text">
1037 Last updated 2009-07-06 18:05:24 UTC
1038 </div>
1039 </div>
1040 </body>
1041 </html>