color: introduce support for colorizing stderr
[git/debian.git] / Documentation / revisions.txt
blobdfcc49c72c0fe8f90c5e66d8de30d7ad27582c2b
1 SPECIFYING REVISIONS
2 --------------------
4 A revision parameter '<rev>' typically, but not necessarily, names a
5 commit object.  It uses what is called an 'extended SHA-1'
6 syntax.  Here are various ways to spell object names.  The
7 ones listed near the end of this list name trees and
8 blobs contained in a commit.
10 '<sha1>', e.g. 'dae86e1950b1277e545cee180551750029cfe735', 'dae86e'::
11   The full SHA-1 object name (40-byte hexadecimal string), or
12   a leading substring that is unique within the repository.
13   E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both
14   name the same commit object if there is no other object in
15   your repository whose object name starts with dae86e.
17 '<describeOutput>', e.g. 'v1.7.4.2-679-g3bee7fb'::
18   Output from `git describe`; i.e. a closest tag, optionally
19   followed by a dash and a number of commits, followed by a dash, a
20   'g', and an abbreviated object name.
22 '<refname>', e.g. 'master', 'heads/master', 'refs/heads/master'::
23   A symbolic ref name.  E.g. 'master' typically means the commit
24   object referenced by 'refs/heads/master'.  If you
25   happen to have both 'heads/master' and 'tags/master', you can
26   explicitly say 'heads/master' to tell Git which one you mean.
27   When ambiguous, a '<refname>' is disambiguated by taking the
28   first match in the following rules:
30   . If '$GIT_DIR/<refname>' exists, that is what you mean (this is usually
31     useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD`
32     and `CHERRY_PICK_HEAD`);
34   . otherwise, 'refs/<refname>' if it exists;
36   . otherwise, 'refs/tags/<refname>' if it exists;
38   . otherwise, 'refs/heads/<refname>' if it exists;
40   . otherwise, 'refs/remotes/<refname>' if it exists;
42   . otherwise, 'refs/remotes/<refname>/HEAD' if it exists.
44 `HEAD` names the commit on which you based the changes in the working tree.
45 `FETCH_HEAD` records the branch which you fetched from a remote repository
46 with your last `git fetch` invocation.
47 `ORIG_HEAD` is created by commands that move your `HEAD` in a drastic
48 way, to record the position of the `HEAD` before their operation, so that
49 you can easily change the tip of the branch back to the state before you ran
50 them.
51 `MERGE_HEAD` records the commit(s) which you are merging into your branch
52 when you run `git merge`.
53 `CHERRY_PICK_HEAD` records the commit which you are cherry-picking
54 when you run `git cherry-pick`.
56 Note that any of the 'refs/*' cases above may come either from
57 the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file.
58 While the ref name encoding is unspecified, UTF-8 is preferred as
59 some output processing may assume ref names in UTF-8.
61 '@'::
62   '@' alone is a shortcut for `HEAD`.
64 '<refname>@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}'::
65   A ref followed by the suffix '@' with a date specification
66   enclosed in a brace
67   pair (e.g. '\{yesterday\}', '{1 month 2 weeks 3 days 1 hour 1
68   second ago}' or '{1979-02-26 18:30:00}') specifies the value
69   of the ref at a prior point in time.  This suffix may only be
70   used immediately following a ref name and the ref must have an
71   existing log ('$GIT_DIR/logs/<ref>'). Note that this looks up the state
72   of your *local* ref at a given time; e.g., what was in your local
73   'master' branch last week. If you want to look at commits made during
74   certain times, see `--since` and `--until`.
76 '<refname>@{<n>}', e.g. 'master@\{1\}'::
77   A ref followed by the suffix '@' with an ordinal specification
78   enclosed in a brace pair (e.g. '\{1\}', '\{15\}') specifies
79   the n-th prior value of that ref.  For example 'master@\{1\}'
80   is the immediate prior value of 'master' while 'master@\{5\}'
81   is the 5th prior value of 'master'. This suffix may only be used
82   immediately following a ref name and the ref must have an existing
83   log ('$GIT_DIR/logs/<refname>').
85 '@{<n>}', e.g. '@\{1\}'::
86   You can use the '@' construct with an empty ref part to get at a
87   reflog entry of the current branch. For example, if you are on
88   branch 'blabla' then '@\{1\}' means the same as 'blabla@\{1\}'.
90 '@{-<n>}', e.g. '@{-1}'::
91   The construct '@{-<n>}' means the <n>th branch/commit checked out
92   before the current one.
94 '<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}'::
95   The suffix '@\{upstream\}' to a branchname (short form '<branchname>@\{u\}')
96   refers to the branch that the branch specified by branchname is set to build on
97   top of (configured with `branch.<name>.remote` and
98   `branch.<name>.merge`).  A missing branchname defaults to the
99   current one. These suffixes are also accepted when spelled in uppercase, and
100   they mean the same thing no matter the case.
102 '<branchname>@\{push\}', e.g. 'master@\{push\}', '@\{push\}'::
103   The suffix '@\{push}' reports the branch "where we would push to" if
104   `git push` were run while `branchname` was checked out (or the current
105   `HEAD` if no branchname is specified). Since our push destination is
106   in a remote repository, of course, we report the local tracking branch
107   that corresponds to that branch (i.e., something in 'refs/remotes/').
109 Here's an example to make it more clear:
111 ------------------------------
112 $ git config push.default current
113 $ git config remote.pushdefault myfork
114 $ git checkout -b mybranch origin/master
116 $ git rev-parse --symbolic-full-name @{upstream}
117 refs/remotes/origin/master
119 $ git rev-parse --symbolic-full-name @{push}
120 refs/remotes/myfork/mybranch
121 ------------------------------
123 Note in the example that we set up a triangular workflow, where we pull
124 from one location and push to another. In a non-triangular workflow,
125 '@\{push}' is the same as '@\{upstream}', and there is no need for it.
127 This suffix is also accepted when spelled in uppercase, and means the same
128 thing no matter the case.
130 '<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0'::
131   A suffix '{caret}' to a revision parameter means the first parent of
132   that commit object.  '{caret}<n>' means the <n>th parent (i.e.
133   '<rev>{caret}'
134   is equivalent to '<rev>{caret}1').  As a special rule,
135   '<rev>{caret}0' means the commit itself and is used when '<rev>' is the
136   object name of a tag object that refers to a commit object.
138 '<rev>{tilde}<n>', e.g. 'master{tilde}3'::
139   A suffix '{tilde}<n>' to a revision parameter means the commit
140   object that is the <n>th generation ancestor of the named
141   commit object, following only the first parents.  I.e. '<rev>{tilde}3' is
142   equivalent to '<rev>{caret}{caret}{caret}' which is equivalent to
143   '<rev>{caret}1{caret}1{caret}1'.  See below for an illustration of
144   the usage of this form.
146 '<rev>{caret}{<type>}', e.g. 'v0.99.8{caret}\{commit\}'::
147   A suffix '{caret}' followed by an object type name enclosed in
148   brace pair means dereference the object at '<rev>' recursively until
149   an object of type '<type>' is found or the object cannot be
150   dereferenced anymore (in which case, barf).
151   For example, if '<rev>' is a commit-ish, '<rev>{caret}\{commit\}'
152   describes the corresponding commit object.
153   Similarly, if '<rev>' is a tree-ish, '<rev>{caret}\{tree\}'
154   describes the corresponding tree object.
155   '<rev>{caret}0'
156   is a short-hand for '<rev>{caret}\{commit\}'.
158 'rev{caret}\{object\}' can be used to make sure 'rev' names an
159 object that exists, without requiring 'rev' to be a tag, and
160 without dereferencing 'rev'; because a tag is already an object,
161 it does not have to be dereferenced even once to get to an object.
163 'rev{caret}\{tag\}' can be used to ensure that 'rev' identifies an
164 existing tag object.
166 '<rev>{caret}{}', e.g. 'v0.99.8{caret}{}'::
167   A suffix '{caret}' followed by an empty brace pair
168   means the object could be a tag,
169   and dereference the tag recursively until a non-tag object is
170   found.
172 '<rev>{caret}{/<text>}', e.g. 'HEAD^{/fix nasty bug}'::
173   A suffix '{caret}' to a revision parameter, followed by a brace
174   pair that contains a text led by a slash,
175   is the same as the ':/fix nasty bug' syntax below except that
176   it returns the youngest matching commit which is reachable from
177   the '<rev>' before '{caret}'.
179 ':/<text>', e.g. ':/fix nasty bug'::
180   A colon, followed by a slash, followed by a text, names
181   a commit whose commit message matches the specified regular expression.
182   This name returns the youngest matching commit which is
183   reachable from any ref. The regular expression can match any part of the
184   commit message. To match messages starting with a string, one can use
185   e.g. ':/^foo'. The special sequence ':/!' is reserved for modifiers to what
186   is matched. ':/!-foo' performs a negative match, while ':/!!foo' matches a
187   literal '!' character, followed by 'foo'. Any other sequence beginning with
188   ':/!' is reserved for now.
190 '<rev>:<path>', e.g. 'HEAD:README', ':README', 'master:./README'::
191   A suffix ':' followed by a path names the blob or tree
192   at the given path in the tree-ish object named by the part
193   before the colon.
194   ':path' (with an empty part before the colon)
195   is a special case of the syntax described next: content
196   recorded in the index at the given path.
197   A path starting with './' or '../' is relative to the current working directory.
198   The given path will be converted to be relative to the working tree's root directory.
199   This is most useful to address a blob or tree from a commit or tree that has
200   the same tree structure as the working tree.
202 ':<n>:<path>', e.g. ':0:README', ':README'::
203   A colon, optionally followed by a stage number (0 to 3) and a
204   colon, followed by a path, names a blob object in the
205   index at the given path. A missing stage number (and the colon
206   that follows it) names a stage 0 entry. During a merge, stage
207   1 is the common ancestor, stage 2 is the target branch's version
208   (typically the current branch), and stage 3 is the version from
209   the branch which is being merged.
211 Here is an illustration, by Jon Loeliger.  Both commit nodes B
212 and C are parents of commit node A.  Parent commits are ordered
213 left-to-right.
215 ........................................
216 G   H   I   J
217  \ /     \ /
218   D   E   F
219    \  |  / \
220     \ | /   |
221      \|/    |
222       B     C
223        \   /
224         \ /
225          A
226 ........................................
228     A =      = A^0
229     B = A^   = A^1     = A~1
230     C = A^2  = A^2
231     D = A^^  = A^1^1   = A~2
232     E = B^2  = A^^2
233     F = B^3  = A^^3
234     G = A^^^ = A^1^1^1 = A~3
235     H = D^2  = B^^2    = A^^^2  = A~2^2
236     I = F^   = B^3^    = A^^3^
237     J = F^2  = B^3^2   = A^^3^2
240 SPECIFYING RANGES
241 -----------------
243 History traversing commands such as `git log` operate on a set
244 of commits, not just a single commit.
246 For these commands,
247 specifying a single revision, using the notation described in the
248 previous section, means the set of commits `reachable` from the given
249 commit.
251 A commit's reachable set is the commit itself and the commits in
252 its ancestry chain.
255 Commit Exclusions
256 ~~~~~~~~~~~~~~~~~
258 '{caret}<rev>' (caret) Notation::
259  To exclude commits reachable from a commit, a prefix '{caret}'
260  notation is used.  E.g. '{caret}r1 r2' means commits reachable
261  from 'r2' but exclude the ones reachable from 'r1' (i.e. 'r1' and
262  its ancestors).
264 Dotted Range Notations
265 ~~~~~~~~~~~~~~~~~~~~~~
267 The '..' (two-dot) Range Notation::
268  The '{caret}r1 r2' set operation appears so often that there is a shorthand
269  for it.  When you have two commits 'r1' and 'r2' (named according
270  to the syntax explained in SPECIFYING REVISIONS above), you can ask
271  for commits that are reachable from r2 excluding those that are reachable
272  from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.
274 The '...' (three-dot) Symmetric Difference Notation::
275  A similar notation 'r1\...r2' is called symmetric difference
276  of 'r1' and 'r2' and is defined as
277  'r1 r2 --not $(git merge-base --all r1 r2)'.
278  It is the set of commits that are reachable from either one of
279  'r1' (left side) or 'r2' (right side) but not from both.
281 In these two shorthand notations, you can omit one end and let it default to HEAD.
282 For example, 'origin..' is a shorthand for 'origin..HEAD' and asks "What
283 did I do since I forked from the origin branch?"  Similarly, '..origin'
284 is a shorthand for 'HEAD..origin' and asks "What did the origin do since
285 I forked from them?"  Note that '..' would mean 'HEAD..HEAD' which is an
286 empty range that is both reachable and unreachable from HEAD.
288 Other <rev>{caret} Parent Shorthand Notations
289 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
290 Three other shorthands exist, particularly useful for merge commits,
291 for naming a set that is formed by a commit and its parent commits.
293 The 'r1{caret}@' notation means all parents of 'r1'.
295 The 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents.
296 By itself, this notation denotes the single commit 'r1'.
298 The '<rev>{caret}-<n>' notation includes '<rev>' but excludes the <n>th
299 parent (i.e. a shorthand for '<rev>{caret}<n>..<rev>'), with '<n>' = 1 if
300 not given. This is typically useful for merge commits where you
301 can just pass '<commit>{caret}-' to get all the commits in the branch
302 that was merged in merge commit '<commit>' (including '<commit>'
303 itself).
305 While '<rev>{caret}<n>' was about specifying a single commit parent, these
306 three notations also consider its parents. For example you can say
307 'HEAD{caret}2{caret}@', however you cannot say 'HEAD{caret}@{caret}2'.
309 Revision Range Summary
310 ----------------------
312 '<rev>'::
313         Include commits that are reachable from <rev> (i.e. <rev> and its
314         ancestors).
316 '{caret}<rev>'::
317         Exclude commits that are reachable from <rev> (i.e. <rev> and its
318         ancestors).
320 '<rev1>..<rev2>'::
321         Include commits that are reachable from <rev2> but exclude
322         those that are reachable from <rev1>.  When either <rev1> or
323         <rev2> is omitted, it defaults to `HEAD`.
325 '<rev1>\...<rev2>'::
326         Include commits that are reachable from either <rev1> or
327         <rev2> but exclude those that are reachable from both.  When
328         either <rev1> or <rev2> is omitted, it defaults to `HEAD`.
330 '<rev>{caret}@', e.g. 'HEAD{caret}@'::
331   A suffix '{caret}' followed by an at sign is the same as listing
332   all parents of '<rev>' (meaning, include anything reachable from
333   its parents, but not the commit itself).
335 '<rev>{caret}!', e.g. 'HEAD{caret}!'::
336   A suffix '{caret}' followed by an exclamation mark is the same
337   as giving commit '<rev>' and then all its parents prefixed with
338   '{caret}' to exclude them (and their ancestors).
340 '<rev>{caret}-<n>', e.g. 'HEAD{caret}-, HEAD{caret}-2'::
341         Equivalent to '<rev>{caret}<n>..<rev>', with '<n>' = 1 if not
342         given.
344 Here are a handful of examples using the Loeliger illustration above,
345 with each step in the notation's expansion and selection carefully
346 spelt out:
348    Args   Expanded arguments    Selected commits
349    D                            G H D
350    D F                          G H I J D F
351    ^G D                         H D
352    ^D B                         E I J F B
353    ^D B C                       E I J F B C
354    C                            I J F C
355    B..C   = ^B C                C
356    B...C  = B ^F C              G H D E B C
357    B^-    = B^..B
358           = ^B^1 B              E I J F B
359    C^@    = C^1
360           = F                   I J F
361    B^@    = B^1 B^2 B^3
362           = D E F               D G H E F I J
363    C^!    = C ^C^@
364           = C ^C^1
365           = C ^F                C
366    B^!    = B ^B^@
367           = B ^B^1 ^B^2 ^B^3
368           = B ^D ^E ^F          B
369    F^! D  = F ^I ^J D           G H D F