Autogenerated HTML docs for v1.7.4.1-225-g83c3c
[git/jnareb-git.git] / gitrevisions.html
blobe5e9edcd760179999247f4ab6d4b2cd125289612
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.4.5" />
7 <title>gitrevisions(7)</title>
8 <style type="text/css">
9 /* Debug borders */
10 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
12 border: 1px solid red;
16 body {
17 margin: 1em 5% 1em 5%;
20 a {
21 color: blue;
22 text-decoration: underline;
24 a:visited {
25 color: fuchsia;
28 em {
29 font-style: italic;
30 color: navy;
33 strong {
34 font-weight: bold;
35 color: #083194;
38 tt {
39 color: navy;
42 h1, h2, h3, h4, h5, h6 {
43 color: #527bbd;
44 font-family: sans-serif;
45 margin-top: 1.2em;
46 margin-bottom: 0.5em;
47 line-height: 1.3;
50 h1, h2, h3 {
51 border-bottom: 2px solid silver;
53 h2 {
54 padding-top: 0.5em;
56 h3 {
57 float: left;
59 h3 + * {
60 clear: left;
63 div.sectionbody {
64 font-family: serif;
65 margin-left: 0;
68 hr {
69 border: 1px solid silver;
72 p {
73 margin-top: 0.5em;
74 margin-bottom: 0.5em;
77 ul, ol, li > p {
78 margin-top: 0;
81 pre {
82 padding: 0;
83 margin: 0;
86 span#author {
87 color: #527bbd;
88 font-family: sans-serif;
89 font-weight: bold;
90 font-size: 1.1em;
92 span#email {
94 span#revnumber, span#revdate, span#revremark {
95 font-family: sans-serif;
98 div#footer {
99 font-family: sans-serif;
100 font-size: small;
101 border-top: 2px solid silver;
102 padding-top: 0.5em;
103 margin-top: 4.0em;
105 div#footer-text {
106 float: left;
107 padding-bottom: 0.5em;
109 div#footer-badges {
110 float: right;
111 padding-bottom: 0.5em;
114 div#preamble {
115 margin-top: 1.5em;
116 margin-bottom: 1.5em;
118 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
119 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
120 div.admonitionblock {
121 margin-top: 1.5em;
122 margin-bottom: 1.5em;
124 div.admonitionblock {
125 margin-top: 2.5em;
126 margin-bottom: 2.5em;
129 div.content { /* Block element content. */
130 padding: 0;
133 /* Block element titles. */
134 div.title, caption.title {
135 color: #527bbd;
136 font-family: sans-serif;
137 font-weight: bold;
138 text-align: left;
139 margin-top: 1.0em;
140 margin-bottom: 0.5em;
142 div.title + * {
143 margin-top: 0;
146 td div.title:first-child {
147 margin-top: 0.0em;
149 div.content div.title:first-child {
150 margin-top: 0.0em;
152 div.content + div.title {
153 margin-top: 0.0em;
156 div.sidebarblock > div.content {
157 background: #ffffee;
158 border: 1px solid silver;
159 padding: 0.5em;
162 div.listingblock > div.content {
163 border: 1px solid silver;
164 background: #f4f4f4;
165 padding: 0.5em;
168 div.quoteblock {
169 padding-left: 2.0em;
170 margin-right: 10%;
172 div.quoteblock > div.attribution {
173 padding-top: 0.5em;
174 text-align: right;
177 div.verseblock {
178 padding-left: 2.0em;
179 margin-right: 10%;
181 div.verseblock > div.content {
182 white-space: pre;
184 div.verseblock > div.attribution {
185 padding-top: 0.75em;
186 text-align: left;
188 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
189 div.verseblock + div.attribution {
190 text-align: left;
193 div.admonitionblock .icon {
194 vertical-align: top;
195 font-size: 1.1em;
196 font-weight: bold;
197 text-decoration: underline;
198 color: #527bbd;
199 padding-right: 0.5em;
201 div.admonitionblock td.content {
202 padding-left: 0.5em;
203 border-left: 2px solid silver;
206 div.exampleblock > div.content {
207 border-left: 2px solid silver;
208 padding: 0.5em;
211 div.imageblock div.content { padding-left: 0; }
212 span.image img { border-style: none; }
213 a.image:visited { color: white; }
215 dl {
216 margin-top: 0.8em;
217 margin-bottom: 0.8em;
219 dt {
220 margin-top: 0.5em;
221 margin-bottom: 0;
222 font-style: normal;
223 color: navy;
225 dd > *:first-child {
226 margin-top: 0.1em;
229 ul, ol {
230 list-style-position: outside;
232 ol.arabic {
233 list-style-type: decimal;
235 ol.loweralpha {
236 list-style-type: lower-alpha;
238 ol.upperalpha {
239 list-style-type: upper-alpha;
241 ol.lowerroman {
242 list-style-type: lower-roman;
244 ol.upperroman {
245 list-style-type: upper-roman;
248 div.compact ul, div.compact ol,
249 div.compact p, div.compact p,
250 div.compact div, div.compact div {
251 margin-top: 0.1em;
252 margin-bottom: 0.1em;
255 div.tableblock > table {
256 border: 3px solid #527bbd;
258 thead {
259 font-family: sans-serif;
260 font-weight: bold;
262 tfoot {
263 font-weight: bold;
265 td > div.verse {
266 white-space: pre;
268 p.table {
269 margin-top: 0;
271 /* Because the table frame attribute is overriden by CSS in most browsers. */
272 div.tableblock > table[frame="void"] {
273 border-style: none;
275 div.tableblock > table[frame="hsides"] {
276 border-left-style: none;
277 border-right-style: none;
279 div.tableblock > table[frame="vsides"] {
280 border-top-style: none;
281 border-bottom-style: none;
285 div.hdlist {
286 margin-top: 0.8em;
287 margin-bottom: 0.8em;
289 div.hdlist tr {
290 padding-bottom: 15px;
292 dt.hdlist1.strong, td.hdlist1.strong {
293 font-weight: bold;
295 td.hdlist1 {
296 vertical-align: top;
297 font-style: normal;
298 padding-right: 0.8em;
299 color: navy;
301 td.hdlist2 {
302 vertical-align: top;
304 div.hdlist.compact tr {
305 margin: 0;
306 padding-bottom: 0;
309 .comment {
310 background: yellow;
313 @media print {
314 div#footer-badges { display: none; }
317 div#toctitle {
318 color: #527bbd;
319 font-family: sans-serif;
320 font-size: 1.1em;
321 font-weight: bold;
322 margin-top: 1.0em;
323 margin-bottom: 0.1em;
326 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
327 margin-top: 0;
328 margin-bottom: 0;
330 div.toclevel2 {
331 margin-left: 2em;
332 font-size: 0.9em;
334 div.toclevel3 {
335 margin-left: 4em;
336 font-size: 0.9em;
338 div.toclevel4 {
339 margin-left: 6em;
340 font-size: 0.9em;
342 /* Overrides for manpage documents */
343 h1 {
344 padding-top: 0.5em;
345 padding-bottom: 0.5em;
346 border-top: 2px solid silver;
347 border-bottom: 2px solid silver;
349 h2 {
350 border-style: none;
352 div.sectionbody {
353 margin-left: 5%;
356 @media print {
357 div#toc { display: none; }
360 /* Workarounds for IE6's broken and incomplete CSS2. */
362 div.sidebar-content {
363 background: #ffffee;
364 border: 1px solid silver;
365 padding: 0.5em;
367 div.sidebar-title, div.image-title {
368 color: #527bbd;
369 font-family: sans-serif;
370 font-weight: bold;
371 margin-top: 0.0em;
372 margin-bottom: 0.5em;
375 div.listingblock div.content {
376 border: 1px solid silver;
377 background: #f4f4f4;
378 padding: 0.5em;
381 div.quoteblock-attribution {
382 padding-top: 0.5em;
383 text-align: right;
386 div.verseblock-content {
387 white-space: pre;
389 div.verseblock-attribution {
390 padding-top: 0.75em;
391 text-align: left;
394 div.exampleblock-content {
395 border-left: 2px solid silver;
396 padding-left: 0.5em;
399 /* IE6 sets dynamically generated links as visited. */
400 div#toc a:visited { color: blue; }
401 </style>
402 </head>
403 <body>
404 <div id="header">
405 <h1>
406 gitrevisions(7) Manual Page
407 </h1>
408 <h2>NAME</h2>
409 <div class="sectionbody">
410 <p>gitrevisions -
411 specifying revisions and ranges for git
412 </p>
413 </div>
414 </div>
415 <h2 id="_synopsis">SYNOPSIS</h2>
416 <div class="sectionbody">
417 <div class="paragraph"><p>gitrevisions</p></div>
418 </div>
419 <h2 id="_description">DESCRIPTION</h2>
420 <div class="sectionbody">
421 <div class="paragraph"><p>Many Git commands take revision parameters as arguments. Depending on
422 the command, they denote a specific commit or, for commands which
423 walk the revision graph (such as <a href="git-log.html">git-log(1)</a>), all commits which can
424 be reached from that commit. In the latter case one can also specify a
425 range of revisions explicitly.</p></div>
426 <div class="paragraph"><p>In addition, some Git commands (such as <a href="git-show.html">git-show(1)</a>) also take
427 revision parameters which denote other objects than commits, e.g. blobs
428 ("files") or trees ("directories of files").</p></div>
429 </div>
430 <h2 id="_specifying_revisions">SPECIFYING REVISIONS</h2>
431 <div class="sectionbody">
432 <div class="paragraph"><p>A revision parameter typically, but not necessarily, names a
433 commit object. They use what is called an <em>extended SHA1</em>
434 syntax. Here are various ways to spell object names. The
435 ones listed near the end of this list are to name trees and
436 blobs contained in a commit.</p></div>
437 <div class="ulist"><ul>
438 <li>
440 The full SHA1 object name (40-byte hexadecimal string), or
441 a substring of such that is unique within the repository.
442 E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both
443 name the same commit object if there are no other object in
444 your repository whose object name starts with dae86e.
445 </p>
446 </li>
447 <li>
449 An output from <em>git describe</em>; i.e. a closest tag, optionally
450 followed by a dash and a number of commits, followed by a dash, a
451 <tt>g</tt>, and an abbreviated object name.
452 </p>
453 </li>
454 <li>
456 A symbolic ref name. E.g. <em>master</em> typically means the commit
457 object referenced by refs/heads/master. If you
458 happen to have both heads/master and tags/master, you can
459 explicitly say <em>heads/master</em> to tell git which one you mean.
460 When ambiguous, a <tt>&lt;name&gt;</tt> is disambiguated by taking the
461 first match in the following rules:
462 </p>
463 <div class="olist arabic"><ol class="arabic">
464 <li>
466 if <tt>$GIT_DIR/&lt;name&gt;</tt> exists, that is what you mean (this is usually
467 useful only for <tt>HEAD</tt>, <tt>FETCH_HEAD</tt>, <tt>ORIG_HEAD</tt>, <tt>MERGE_HEAD</tt>
468 and <tt>CHERRY_PICK_HEAD</tt>);
469 </p>
470 </li>
471 <li>
473 otherwise, <tt>refs/&lt;name&gt;</tt> if exists;
474 </p>
475 </li>
476 <li>
478 otherwise, <tt>refs/tags/&lt;name&gt;</tt> if exists;
479 </p>
480 </li>
481 <li>
483 otherwise, <tt>refs/heads/&lt;name&gt;</tt> if exists;
484 </p>
485 </li>
486 <li>
488 otherwise, <tt>refs/remotes/&lt;name&gt;</tt> if exists;
489 </p>
490 </li>
491 <li>
493 otherwise, <tt>refs/remotes/&lt;name&gt;/HEAD</tt> if exists.
494 </p>
495 <div class="paragraph"><p>HEAD names the commit your changes in the working tree is based on.
496 FETCH_HEAD records the branch you fetched from a remote repository
497 with your last <em>git fetch</em> invocation.
498 ORIG_HEAD is created by commands that moves your HEAD in a drastic
499 way, to record the position of the HEAD before their operation, so that
500 you can change the tip of the branch back to the state before you ran
501 them easily.
502 MERGE_HEAD records the commit(s) you are merging into your branch
503 when you run <em>git merge</em>.
504 CHERRY_PICK_HEAD records the commit you are cherry-picking
505 when you run <em>git cherry-pick</em>.</p></div>
506 <div class="paragraph"><p>Note that any of the <tt>refs/*</tt> cases above may come either from
507 the <tt>$GIT_DIR/refs</tt> directory or from the <tt>$GIT_DIR/packed-refs</tt> file.</p></div>
508 </li>
509 </ol></div>
510 </li>
511 <li>
513 A ref followed by the suffix <em>@</em> with a date specification
514 enclosed in a brace
515 pair (e.g. <em>{yesterday}</em>, <em>{1 month 2 weeks 3 days 1 hour 1
516 second ago}</em> or <em>{1979-02-26 18:30:00}</em>) to specify the value
517 of the ref at a prior point in time. This suffix may only be
518 used immediately following a ref name and the ref must have an
519 existing log ($GIT_DIR/logs/&lt;ref&gt;). Note that this looks up the state
520 of your <strong>local</strong> ref at a given time; e.g., what was in your local
521 <tt>master</tt> branch last week. If you want to look at commits made during
522 certain times, see <tt>--since</tt> and <tt>--until</tt>.
523 </p>
524 </li>
525 <li>
527 A ref followed by the suffix <em>@</em> with an ordinal specification
528 enclosed in a brace pair (e.g. <em>{1}</em>, <em>{15}</em>) to specify
529 the n-th prior value of that ref. For example <em>master@{1}</em>
530 is the immediate prior value of <em>master</em> while <em>master@{5}</em>
531 is the 5th prior value of <em>master</em>. This suffix may only be used
532 immediately following a ref name and the ref must have an existing
533 log ($GIT_DIR/logs/&lt;ref&gt;).
534 </p>
535 </li>
536 <li>
538 You can use the <em>@</em> construct with an empty ref part to get at a
539 reflog of the current branch. For example, if you are on the
540 branch <em>blabla</em>, then <em>@{1}</em> means the same as <em>blabla@{1}</em>.
541 </p>
542 </li>
543 <li>
545 The special construct <em>@{-&lt;n&gt;}</em> means the &lt;n&gt;th branch checked out
546 before the current one.
547 </p>
548 </li>
549 <li>
551 The suffix <em>@{upstream}</em> to a ref (short form <em>ref@{u}</em>) refers to
552 the branch the ref is set to build on top of. Missing ref defaults
553 to the current branch.
554 </p>
555 </li>
556 <li>
558 A suffix <em>&#94;</em> to a revision parameter (e.g. <em>HEAD&#94;</em>) means the first parent of
559 that commit object. <em>&#94;&lt;n&gt;</em> means the &lt;n&gt;th parent (i.e.
560 <em>rev&#94;</em>
561 is equivalent to <em>rev&#94;1</em>). As a special rule,
562 <em>rev&#94;0</em> means the commit itself and is used when <em>rev</em> is the
563 object name of a tag object that refers to a commit object.
564 </p>
565 </li>
566 <li>
568 A suffix <em>&#126;&lt;n&gt;</em> to a revision parameter means the commit
569 object that is the &lt;n&gt;th generation grand-parent of the named
570 commit object, following only the first parent. I.e. rev~3 is
571 equivalent to rev&#94;&#94;&#94; which is equivalent to
572 rev&#94;1&#94;1&#94;1. See below for a illustration of
573 the usage of this form.
574 </p>
575 </li>
576 <li>
578 A suffix <em>&#94;</em> followed by an object type name enclosed in
579 brace pair (e.g. <tt>v0.99.8&#94;{commit}</tt>) means the object
580 could be a tag, and dereference the tag recursively until an
581 object of that type is found or the object cannot be
582 dereferenced anymore (in which case, barf). <tt>rev&#94;0</tt>
583 introduced earlier is a short-hand for <tt>rev&#94;{commit}</tt>.
584 </p>
585 </li>
586 <li>
588 A suffix <em>&#94;</em> followed by an empty brace pair
589 (e.g. <tt>v0.99.8&#94;{}</tt>) means the object could be a tag,
590 and dereference the tag recursively until a non-tag object is
591 found.
592 </p>
593 </li>
594 <li>
596 A suffix <em>&#94;</em> to a revision parameter followed by a brace
597 pair that contains a text led by a slash (e.g. <tt>HEAD^{/fix nasty bug}</tt>):
598 this is the same as <tt>:/fix nasty bug</tt> syntax below except that
599 it returns the youngest matching commit which is reachable from
600 the ref before <em>&#94;</em>.
601 </p>
602 </li>
603 <li>
605 A colon, followed by a slash, followed by a text (e.g. <tt>:/fix nasty bug</tt>): this names
606 a commit whose commit message matches the specified regular expression.
607 This name returns the youngest matching commit which is
608 reachable from any ref. If the commit message starts with a
609 <em>!</em>, you have to repeat that; the special sequence <em>:/!</em>,
610 followed by something else than <em>!</em> is reserved for now.
611 The regular expression can match any part of the commit message. To
612 match messages starting with a string, one can use e.g. <tt>:/^foo</tt>.
613 </p>
614 </li>
615 <li>
617 A suffix <em>:</em> followed by a path (e.g. <tt>HEAD:README</tt>); this names the blob or tree
618 at the given path in the tree-ish object named by the part
619 before the colon.
620 <em>:path</em> (with an empty part before the colon, e.g. <tt>:README</tt>)
621 is a special case of the syntax described next: content
622 recorded in the index at the given path.
623 A path starting with <em>./</em> or <em>../</em> is relative to current working directory.
624 The given path will be converted to be relative to working tree&#8217;s root directory.
625 This is most useful to address a blob or tree from a commit or tree that has
626 the same tree structure with the working tree.
627 </p>
628 </li>
629 <li>
631 A colon, optionally followed by a stage number (0 to 3) and a
632 colon, followed by a path (e.g. <tt>:0:README</tt>); this names a blob object in the
633 index at the given path. Missing stage number (and the colon
634 that follows it, e.g. <tt>:README</tt>) names a stage 0 entry. During a merge, stage
635 1 is the common ancestor, stage 2 is the target branch&#8217;s version
636 (typically the current branch), and stage 3 is the version from
637 the branch being merged.
638 </p>
639 </li>
640 </ul></div>
641 <div class="paragraph"><p>Here is an illustration, by Jon Loeliger. Both commit nodes B
642 and C are parents of commit node A. Parent commits are ordered
643 left-to-right.</p></div>
644 <div class="literalblock">
645 <div class="content">
646 <pre><tt>G H I J
647 \ / \ /
648 D E F
649 \ | / \
650 \ | / |
651 \|/ |
655 A</tt></pre>
656 </div></div>
657 <div class="literalblock">
658 <div class="content">
659 <pre><tt>A = = A^0
660 B = A^ = A^1 = A~1
661 C = A^2 = A^2
662 D = A^^ = A^1^1 = A~2
663 E = B^2 = A^^2
664 F = B^3 = A^^3
665 G = A^^^ = A^1^1^1 = A~3
666 H = D^2 = B^^2 = A^^^2 = A~2^2
667 I = F^ = B^3^ = A^^3^
668 J = F^2 = B^3^2 = A^^3^2</tt></pre>
669 </div></div>
670 </div>
671 <h2 id="_specifying_ranges">SPECIFYING RANGES</h2>
672 <div class="sectionbody">
673 <div class="paragraph"><p>History traversing commands such as <em>git log</em> operate on a set
674 of commits, not just a single commit. To these commands,
675 specifying a single revision with the notation described in the
676 previous section means the set of commits reachable from that
677 commit, following the commit ancestry chain.</p></div>
678 <div class="paragraph"><p>To exclude commits reachable from a commit, a prefix <tt>&#94;</tt>
679 notation is used. E.g. <tt>&#94;r1 r2</tt> means commits reachable
680 from <tt>r2</tt> but exclude the ones reachable from <tt>r1</tt>.</p></div>
681 <div class="paragraph"><p>This set operation appears so often that there is a shorthand
682 for it. When you have two commits <tt>r1</tt> and <tt>r2</tt> (named according
683 to the syntax explained in SPECIFYING REVISIONS above), you can ask
684 for commits that are reachable from r2 excluding those that are reachable
685 from r1 by <tt>&#94;r1 r2</tt> and it can be written as <tt>r1..r2</tt>.</p></div>
686 <div class="paragraph"><p>A similar notation <tt>r1...r2</tt> is called symmetric difference
687 of <tt>r1</tt> and <tt>r2</tt> and is defined as
688 <tt>r1 r2 --not $(git merge-base --all r1 r2)</tt>.
689 It is the set of commits that are reachable from either one of
690 <tt>r1</tt> or <tt>r2</tt> but not from both.</p></div>
691 <div class="paragraph"><p>Two other shorthands for naming a set that is formed by a commit
692 and its parent commits exist. The <tt>r1&#94;@</tt> notation means all
693 parents of <tt>r1</tt>. <tt>r1&#94;!</tt> includes commit <tt>r1</tt> but excludes
694 all of its parents.</p></div>
695 <div class="paragraph"><p>Here are a handful of examples:</p></div>
696 <div class="literalblock">
697 <div class="content">
698 <pre><tt>D G H D
699 D F G H I J D F
700 ^G D H D
701 ^D B E I J F B
702 B...C G H D E B C
703 ^D B C E I J F B C
704 C^@ I J F
705 F^! D G H D F</tt></pre>
706 </div></div>
707 </div>
708 <h2 id="_see_also">SEE ALSO</h2>
709 <div class="sectionbody">
710 <div class="paragraph"><p><a href="git-rev-parse.html">git-rev-parse(1)</a></p></div>
711 </div>
712 <h2 id="_git">GIT</h2>
713 <div class="sectionbody">
714 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
715 </div>
716 <div id="footer">
717 <div id="footer-text">
718 Last updated 2010-07-15 22:23:57 UTC
719 </div>
720 </div>
721 </body>
722 </html>