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">
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">
10 p
, li
, dt
, dd
, div
, pre
, h1
, h2
, h3
, h4
, h5
, h6
{
12 border: 1px solid red;
17 margin: 1em 5% 1em 5%;
22 text-decoration: underline
;
42 h1
, h2
, h3
, h4
, h5
, h6
{
44 font-family: sans-serif
;
51 border-bottom: 2px solid silver
;
69 border: 1px solid silver
;
88 font-family: sans-serif
;
94 span#revnumber
, span#revdate
, span#revremark
{
95 font-family: sans-serif
;
99 font-family: sans-serif
;
101 border-top: 2px solid silver
;
107 padding-bottom: 0.5em;
111 padding-bottom: 0.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
{
122 margin-bottom: 1.5em;
124 div
.admonitionblock
{
126 margin-bottom: 2.5em;
129 div
.content
{ /* Block element content. */
133 /* Block element titles. */
134 div
.title
, caption
.title
{
136 font-family: sans-serif
;
140 margin-bottom: 0.5em;
146 td div
.title:first-child
{
149 div
.content div
.title:first-child
{
152 div
.content
+ div
.title
{
156 div
.sidebarblock
> div
.content
{
158 border: 1px solid silver
;
162 div
.listingblock
> div
.content
{
163 border: 1px solid silver
;
172 div
.quoteblock
> div
.attribution
{
181 div
.verseblock
> div
.content
{
184 div
.verseblock
> div
.attribution
{
188 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
189 div
.verseblock
+ div
.attribution
{
193 div
.admonitionblock
.icon
{
197 text-decoration: underline
;
199 padding-right: 0.5em;
201 div
.admonitionblock td
.content
{
203 border-left: 2px solid silver
;
206 div
.exampleblock
> div
.content
{
207 border-left: 2px solid silver
;
211 div
.imageblock div
.content
{ padding-left: 0; }
212 span
.image img
{ border-style: none
; }
213 a
.image:visited
{ color: white
; }
217 margin-bottom: 0.8em;
230 list-style-position: outside
;
233 list-style-type: decimal
;
236 list-style-type: lower-alpha
;
239 list-style-type: upper-alpha
;
242 list-style-type: lower-roman
;
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
{
252 margin-bottom: 0.1em;
255 div
.tableblock
> table
{
256 border: 3px solid
#527bbd;
259 font-family: sans-serif
;
271 /* Because the table frame attribute is overriden by CSS in most browsers. */
272 div
.tableblock
> table
[frame
="void"] {
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
;
287 margin-bottom: 0.8em;
290 padding-bottom: 15px;
292 dt
.hdlist1
.strong
, td
.hdlist1
.strong
{
298 padding-right: 0.8em;
304 div
.hdlist
.compact tr
{
314 div#footer-badges
{ display: none
; }
319 font-family: sans-serif
;
323 margin-bottom: 0.1em;
326 div
.toclevel1
, div
.toclevel2
, div
.toclevel3
, div
.toclevel4
{
342 /* Overrides for manpage documents */
345 padding-bottom: 0.5em;
346 border-top: 2px solid silver
;
347 border-bottom: 2px solid silver
;
357 div#toc
{ display: none
; }
360 /* Workarounds for IE6's broken and incomplete CSS2. */
362 div
.sidebar-content
{
364 border: 1px solid silver
;
367 div
.sidebar-title
, div
.image-title
{
369 font-family: sans-serif
;
372 margin-bottom: 0.5em;
375 div
.listingblock div
.content
{
376 border: 1px solid silver
;
381 div
.quoteblock-attribution
{
386 div
.verseblock-content
{
389 div
.verseblock-attribution
{
394 div
.exampleblock-content
{
395 border-left: 2px solid silver
;
399 /* IE6 sets dynamically generated links as visited. */
400 div#toc
a:visited
{ color: blue
; }
406 gitrevisions(
7) Manual Page
409 <div class=
"sectionbody">
411 specifying revisions and ranges for git
415 <h2 id=
"_synopsis">SYNOPSIS
</h2>
416 <div class=
"sectionbody">
417 <div class=
"paragraph"><p>gitrevisions
</p></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>
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>
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.
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.
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><name
></tt> is disambiguated by taking the
461 first match in the following rules:
463 <div class=
"olist arabic"><ol class=
"arabic">
466 if
<tt>$GIT_DIR/
<name
></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>);
472 otherwise,
<tt>refs/
<name
></tt> if exists;
477 otherwise,
<tt>refs/tags/
<name
></tt> if exists;
482 otherwise,
<tt>refs/heads/
<name
></tt> if exists;
487 otherwise,
<tt>refs/remotes/
<name
></tt> if exists;
492 otherwise,
<tt>refs/remotes/
<name
>/HEAD
</tt> if exists.
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
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>
510 A ref followed by the suffix
<em>@
</em> with a date specification
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/
<ref
>). 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>.
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/
<ref
>).
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>.
542 The special construct
<em>@{-
<n
>}
</em> means the
<n
>th branch checked out
543 before the current one.
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.
555 A suffix
<em>^</em> to a revision parameter (e.g.
<em>HEAD
^</em>) means the first parent of
556 that commit object.
<em>^<n
></em> means the
<n
>th parent (i.e.
558 is equivalent to
<em>rev
^1</em>). As a special rule,
559 <em>rev
^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.
565 A suffix
<em>~<n
></em> to a revision parameter means the commit
566 object that is the
<n
>th generation grand-parent of the named
567 commit object, following only the first parent. I.e. rev~
3 is
568 equivalent to rev
^^^ which is equivalent to
569 rev
^1^1^1. See below for a illustration of
570 the usage of this form.
575 A suffix
<em>^</em> followed by an object type name enclosed in
576 brace pair (e.g.
<tt>v0.99
.8^{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
^0</tt>
580 introduced earlier is a short-hand for
<tt>rev
^{commit}
</tt>.
585 A suffix
<em>^</em> followed by an empty brace pair
586 (e.g.
<tt>v0.99
.8^{}
</tt>) means the object could be a tag,
587 and dereference the tag recursively until a non-tag object is
593 A suffix
<em>^</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>^</em>.
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>.
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
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
’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.
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
’s version
633 (typically the current branch), and stage
3 is the version from
634 the branch being merged.
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">
654 <div class=
"literalblock">
655 <div class=
"content">
659 D = A^^ = A^
1^
1 = A~
2
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>
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>^</tt>
676 notation is used. E.g.
<tt>^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>^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
^@
</tt> notation means all
690 parents of
<tt>r1
</tt>.
<tt>r1
^!
</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">
702 F^! D G H D F
</tt></pre>
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>
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>
714 <div id=
"footer-text">
715 Last updated
2010-
07-
15 22:
23:
57 UTC