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