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>,
<tt>MERGE_HEAD
</tt>
468 and
<tt>CHERRY_PICK_HEAD
</tt>);
473 otherwise,
<tt>refs/
<name
></tt> if exists;
478 otherwise,
<tt>refs/tags/
<name
></tt> if exists;
483 otherwise,
<tt>refs/heads/
<name
></tt> if exists;
488 otherwise,
<tt>refs/remotes/
<name
></tt> if exists;
493 otherwise,
<tt>refs/remotes/
<name
>/HEAD
</tt> if exists.
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
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>
513 A ref followed by the suffix
<em>@
</em> with a date specification
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/
<ref
>). 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>.
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/
<ref
>).
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>.
545 The special construct
<em>@{-
<n
>}
</em> means the
<n
>th branch checked out
546 before the current one.
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.
558 A suffix
<em>^</em> to a revision parameter (e.g.
<em>HEAD
^</em>) means the first parent of
559 that commit object.
<em>^<n
></em> means the
<n
>th parent (i.e.
561 is equivalent to
<em>rev
^1</em>). As a special rule,
562 <em>rev
^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.
568 A suffix
<em>~<n
></em> to a revision parameter means the commit
569 object that is the
<n
>th generation grand-parent of the named
570 commit object, following only the first parent. I.e. rev~
3 is
571 equivalent to rev
^^^ which is equivalent to
572 rev
^1^1^1. See below for a illustration of
573 the usage of this form.
578 A suffix
<em>^</em> followed by an object type name enclosed in
579 brace pair (e.g.
<tt>v0.99
.8^{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
^0</tt>
583 introduced earlier is a short-hand for
<tt>rev
^{commit}
</tt>.
588 A suffix
<em>^</em> followed by an empty brace pair
589 (e.g.
<tt>v0.99
.8^{}
</tt>) means the object could be a tag,
590 and dereference the tag recursively until a non-tag object is
596 A suffix
<em>^</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>^</em>.
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>.
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
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
’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.
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
’s version
636 (typically the current branch), and stage
3 is the version from
637 the branch being merged.
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">
657 <div class=
"literalblock">
658 <div class=
"content">
662 D = A^^ = A^
1^
1 = A~
2
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>
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>^</tt>
679 notation is used. E.g.
<tt>^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>^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
^@
</tt> notation means all
693 parents of
<tt>r1
</tt>.
<tt>r1
^!
</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">
705 F^! D G H D F
</tt></pre>
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>
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>
717 <div id=
"footer-text">
718 Last updated
2010-
07-
15 22:
23:
57 UTC