Autogenerated HTML docs for v1.7.4-15-g7811
[git/jnareb-git.git] / gitrevisions.html
blobe791ccc40e1f40a7d7fa29aa3085ecb2af34d584
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> and <tt>MERGE_HEAD</tt>);
468 </p>
469 </li>
470 <li>
472 otherwise, <tt>refs/&lt;name&gt;</tt> if exists;
473 </p>
474 </li>
475 <li>
477 otherwise, <tt>refs/tags/&lt;name&gt;</tt> if exists;
478 </p>
479 </li>
480 <li>
482 otherwise, <tt>refs/heads/&lt;name&gt;</tt> if exists;
483 </p>
484 </li>
485 <li>
487 otherwise, <tt>refs/remotes/&lt;name&gt;</tt> if exists;
488 </p>
489 </li>
490 <li>
492 otherwise, <tt>refs/remotes/&lt;name&gt;/HEAD</tt> if exists.
493 </p>
494 <div class="paragraph"><p>HEAD names the commit your changes in the working tree is based on.
495 FETCH_HEAD records the branch you fetched from a remote repository
496 with your last <em>git fetch</em> invocation.
497 ORIG_HEAD is created by commands that moves your HEAD in a drastic
498 way, to record the position of the HEAD before their operation, so that
499 you can change the tip of the branch back to the state before you ran
500 them easily.
501 MERGE_HEAD records the commit(s) you are merging into your branch
502 when you run <em>git merge</em>.</p></div>
503 <div class="paragraph"><p>Note that any of the <tt>refs/*</tt> cases above may come either from
504 the <tt>$GIT_DIR/refs</tt> directory or from the <tt>$GIT_DIR/packed-refs</tt> file.</p></div>
505 </li>
506 </ol></div>
507 </li>
508 <li>
510 A ref followed by the suffix <em>@</em> with a date specification
511 enclosed in a brace
512 pair (e.g. <em>{yesterday}</em>, <em>{1 month 2 weeks 3 days 1 hour 1
513 second ago}</em> or <em>{1979-02-26 18:30:00}</em>) to specify the value
514 of the ref at a prior point in time. This suffix may only be
515 used immediately following a ref name and the ref must have an
516 existing log ($GIT_DIR/logs/&lt;ref&gt;). Note that this looks up the state
517 of your <strong>local</strong> ref at a given time; e.g., what was in your local
518 <tt>master</tt> branch last week. If you want to look at commits made during
519 certain times, see <tt>--since</tt> and <tt>--until</tt>.
520 </p>
521 </li>
522 <li>
524 A ref followed by the suffix <em>@</em> with an ordinal specification
525 enclosed in a brace pair (e.g. <em>{1}</em>, <em>{15}</em>) to specify
526 the n-th prior value of that ref. For example <em>master@{1}</em>
527 is the immediate prior value of <em>master</em> while <em>master@{5}</em>
528 is the 5th prior value of <em>master</em>. This suffix may only be used
529 immediately following a ref name and the ref must have an existing
530 log ($GIT_DIR/logs/&lt;ref&gt;).
531 </p>
532 </li>
533 <li>
535 You can use the <em>@</em> construct with an empty ref part to get at a
536 reflog of the current branch. For example, if you are on the
537 branch <em>blabla</em>, then <em>@{1}</em> means the same as <em>blabla@{1}</em>.
538 </p>
539 </li>
540 <li>
542 The special construct <em>@{-&lt;n&gt;}</em> means the &lt;n&gt;th branch checked out
543 before the current one.
544 </p>
545 </li>
546 <li>
548 The suffix <em>@{upstream}</em> to a ref (short form <em>ref@{u}</em>) refers to
549 the branch the ref is set to build on top of. Missing ref defaults
550 to the current branch.
551 </p>
552 </li>
553 <li>
555 A suffix <em>&#94;</em> to a revision parameter (e.g. <em>HEAD&#94;</em>) means the first parent of
556 that commit object. <em>&#94;&lt;n&gt;</em> means the &lt;n&gt;th parent (i.e.
557 <em>rev&#94;</em>
558 is equivalent to <em>rev&#94;1</em>). As a special rule,
559 <em>rev&#94;0</em> means the commit itself and is used when <em>rev</em> is the
560 object name of a tag object that refers to a commit object.
561 </p>
562 </li>
563 <li>
565 A suffix <em>&#126;&lt;n&gt;</em> to a revision parameter means the commit
566 object that is the &lt;n&gt;th generation grand-parent of the named
567 commit object, following only the first parent. I.e. rev~3 is
568 equivalent to rev&#94;&#94;&#94; which is equivalent to
569 rev&#94;1&#94;1&#94;1. See below for a illustration of
570 the usage of this form.
571 </p>
572 </li>
573 <li>
575 A suffix <em>&#94;</em> followed by an object type name enclosed in
576 brace pair (e.g. <tt>v0.99.8&#94;{commit}</tt>) means the object
577 could be a tag, and dereference the tag recursively until an
578 object of that type is found or the object cannot be
579 dereferenced anymore (in which case, barf). <tt>rev&#94;0</tt>
580 introduced earlier is a short-hand for <tt>rev&#94;{commit}</tt>.
581 </p>
582 </li>
583 <li>
585 A suffix <em>&#94;</em> followed by an empty brace pair
586 (e.g. <tt>v0.99.8&#94;{}</tt>) means the object could be a tag,
587 and dereference the tag recursively until a non-tag object is
588 found.
589 </p>
590 </li>
591 <li>
593 A suffix <em>&#94;</em> to a revision parameter followed by a brace
594 pair that contains a text led by a slash (e.g. <tt>HEAD^{/fix nasty bug}</tt>):
595 this is the same as <tt>:/fix nasty bug</tt> syntax below except that
596 it returns the youngest matching commit which is reachable from
597 the ref before <em>&#94;</em>.
598 </p>
599 </li>
600 <li>
602 A colon, followed by a slash, followed by a text (e.g. <tt>:/fix nasty bug</tt>): this names
603 a commit whose commit message matches the specified regular expression.
604 This name returns the youngest matching commit which is
605 reachable from any ref. If the commit message starts with a
606 <em>!</em>, you have to repeat that; the special sequence <em>:/!</em>,
607 followed by something else than <em>!</em> is reserved for now.
608 The regular expression can match any part of the commit message. To
609 match messages starting with a string, one can use e.g. <tt>:/^foo</tt>.
610 </p>
611 </li>
612 <li>
614 A suffix <em>:</em> followed by a path (e.g. <tt>HEAD:README</tt>); this names the blob or tree
615 at the given path in the tree-ish object named by the part
616 before the colon.
617 <em>:path</em> (with an empty part before the colon, e.g. <tt>:README</tt>)
618 is a special case of the syntax described next: content
619 recorded in the index at the given path.
620 A path starting with <em>./</em> or <em>../</em> is relative to current working directory.
621 The given path will be converted to be relative to working tree&#8217;s root directory.
622 This is most useful to address a blob or tree from a commit or tree that has
623 the same tree structure with the working tree.
624 </p>
625 </li>
626 <li>
628 A colon, optionally followed by a stage number (0 to 3) and a
629 colon, followed by a path (e.g. <tt>:0:README</tt>); this names a blob object in the
630 index at the given path. Missing stage number (and the colon
631 that follows it, e.g. <tt>:README</tt>) names a stage 0 entry. During a merge, stage
632 1 is the common ancestor, stage 2 is the target branch&#8217;s version
633 (typically the current branch), and stage 3 is the version from
634 the branch being merged.
635 </p>
636 </li>
637 </ul></div>
638 <div class="paragraph"><p>Here is an illustration, by Jon Loeliger. Both commit nodes B
639 and C are parents of commit node A. Parent commits are ordered
640 left-to-right.</p></div>
641 <div class="literalblock">
642 <div class="content">
643 <pre><tt>G H I J
644 \ / \ /
645 D E F
646 \ | / \
647 \ | / |
648 \|/ |
652 A</tt></pre>
653 </div></div>
654 <div class="literalblock">
655 <div class="content">
656 <pre><tt>A = = A^0
657 B = A^ = A^1 = A~1
658 C = A^2 = A^2
659 D = A^^ = A^1^1 = A~2
660 E = B^2 = A^^2
661 F = B^3 = A^^3
662 G = A^^^ = A^1^1^1 = A~3
663 H = D^2 = B^^2 = A^^^2 = A~2^2
664 I = F^ = B^3^ = A^^3^
665 J = F^2 = B^3^2 = A^^3^2</tt></pre>
666 </div></div>
667 </div>
668 <h2 id="_specifying_ranges">SPECIFYING RANGES</h2>
669 <div class="sectionbody">
670 <div class="paragraph"><p>History traversing commands such as <em>git log</em> operate on a set
671 of commits, not just a single commit. To these commands,
672 specifying a single revision with the notation described in the
673 previous section means the set of commits reachable from that
674 commit, following the commit ancestry chain.</p></div>
675 <div class="paragraph"><p>To exclude commits reachable from a commit, a prefix <tt>&#94;</tt>
676 notation is used. E.g. <tt>&#94;r1 r2</tt> means commits reachable
677 from <tt>r2</tt> but exclude the ones reachable from <tt>r1</tt>.</p></div>
678 <div class="paragraph"><p>This set operation appears so often that there is a shorthand
679 for it. When you have two commits <tt>r1</tt> and <tt>r2</tt> (named according
680 to the syntax explained in SPECIFYING REVISIONS above), you can ask
681 for commits that are reachable from r2 excluding those that are reachable
682 from r1 by <tt>&#94;r1 r2</tt> and it can be written as <tt>r1..r2</tt>.</p></div>
683 <div class="paragraph"><p>A similar notation <tt>r1...r2</tt> is called symmetric difference
684 of <tt>r1</tt> and <tt>r2</tt> and is defined as
685 <tt>r1 r2 --not $(git merge-base --all r1 r2)</tt>.
686 It is the set of commits that are reachable from either one of
687 <tt>r1</tt> or <tt>r2</tt> but not from both.</p></div>
688 <div class="paragraph"><p>Two other shorthands for naming a set that is formed by a commit
689 and its parent commits exist. The <tt>r1&#94;@</tt> notation means all
690 parents of <tt>r1</tt>. <tt>r1&#94;!</tt> includes commit <tt>r1</tt> but excludes
691 all of its parents.</p></div>
692 <div class="paragraph"><p>Here are a handful of examples:</p></div>
693 <div class="literalblock">
694 <div class="content">
695 <pre><tt>D G H D
696 D F G H I J D F
697 ^G D H D
698 ^D B E I J F B
699 B...C G H D E B C
700 ^D B C E I J F B C
701 C^@ I J F
702 F^! D G H D F</tt></pre>
703 </div></div>
704 </div>
705 <h2 id="_see_also">SEE ALSO</h2>
706 <div class="sectionbody">
707 <div class="paragraph"><p><a href="git-rev-parse.html">git-rev-parse(1)</a></p></div>
708 </div>
709 <h2 id="_git">GIT</h2>
710 <div class="sectionbody">
711 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
712 </div>
713 <div id="footer">
714 <div id="footer-text">
715 Last updated 2010-07-15 22:23:57 UTC
716 </div>
717 </div>
718 </body>
719 </html>