| 1 | SPECIFYING REVISIONS |
| 2 | -------------------- |
| 3 | |
| 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. |
| 9 | |
| 10 | NOTE: This document shows the "raw" syntax as seen by git. The shell |
| 11 | and other UIs might require additional quoting to protect special |
| 12 | characters 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 | + |
| 81 | Note that any of the 'refs/*' cases above may come either from |
| 82 | the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file. |
| 83 | While the ref name encoding is unspecified, UTF-8 is preferred as |
| 84 | some 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 | If the push destination is a URL and exactly one configured remote uses |
| 131 | that URL for pushing, '@\{push}' reports that remote's remote-tracking |
| 132 | branch. |
| 133 | + |
| 134 | Here's an example to make it more clear: |
| 135 | + |
| 136 | ------------------------------ |
| 137 | $ git config push.default current |
| 138 | $ git config remote.pushdefault myfork |
| 139 | $ git switch -c mybranch origin/master |
| 140 | |
| 141 | $ git rev-parse --symbolic-full-name @{upstream} |
| 142 | refs/remotes/origin/master |
| 143 | |
| 144 | $ git rev-parse --symbolic-full-name @{push} |
| 145 | refs/remotes/myfork/mybranch |
| 146 | ------------------------------ |
| 147 | + |
| 148 | Note in the example that we set up a triangular workflow, where we pull |
| 149 | from one location and push to another. In a non-triangular workflow, |
| 150 | '@\{push}' is the same as '@\{upstream}', and there is no need for it. |
| 151 | + |
| 152 | This suffix is also accepted when spelled in uppercase, and means the same |
| 153 | thing no matter the case. |
| 154 | |
| 155 | '<rev>{caret}[<n>]', e.g. 'HEAD{caret}, v1.5.1{caret}0':: |
| 156 | A suffix '{caret}' to a revision parameter means the first parent of |
| 157 | that commit object. '{caret}<n>' means the <n>th parent (i.e. |
| 158 | '<rev>{caret}' |
| 159 | is equivalent to '<rev>{caret}1'). As a special rule, |
| 160 | '<rev>{caret}0' means the commit itself and is used when '<rev>' is the |
| 161 | object name of a tag object that refers to a commit object. |
| 162 | |
| 163 | '<rev>{tilde}[<n>]', e.g. 'HEAD{tilde}, master{tilde}3':: |
| 164 | A suffix '{tilde}' to a revision parameter means the first parent of |
| 165 | that commit object. |
| 166 | A suffix '{tilde}<n>' to a revision parameter means the commit |
| 167 | object that is the <n>th generation ancestor of the named |
| 168 | commit object, following only the first parents. I.e. '<rev>{tilde}3' is |
| 169 | equivalent to '<rev>{caret}{caret}{caret}' which is equivalent to |
| 170 | '<rev>{caret}1{caret}1{caret}1'. See below for an illustration of |
| 171 | the usage of this form. |
| 172 | |
| 173 | '<rev>{caret}{<type>}', e.g. 'v0.99.8{caret}\{commit\}':: |
| 174 | A suffix '{caret}' followed by an object type name enclosed in |
| 175 | brace pair means dereference the object at '<rev>' recursively until |
| 176 | an object of type '<type>' is found or the object cannot be |
| 177 | dereferenced anymore (in which case, barf). |
| 178 | For example, if '<rev>' is a commit-ish, '<rev>{caret}\{commit\}' |
| 179 | describes the corresponding commit object. |
| 180 | Similarly, if '<rev>' is a tree-ish, '<rev>{caret}\{tree\}' |
| 181 | describes the corresponding tree object. |
| 182 | '<rev>{caret}0' |
| 183 | is a short-hand for '<rev>{caret}\{commit\}'. |
| 184 | + |
| 185 | '<rev>{caret}\{object\}' can be used to make sure '<rev>' names an |
| 186 | object that exists, without requiring '<rev>' to be a tag, and |
| 187 | without dereferencing '<rev>'; because a tag is already an object, |
| 188 | it does not have to be dereferenced even once to get to an object. |
| 189 | + |
| 190 | '<rev>{caret}\{tag\}' can be used to ensure that '<rev>' identifies an |
| 191 | existing tag object. |
| 192 | |
| 193 | '<rev>{caret}{}', e.g. 'v0.99.8{caret}{}':: |
| 194 | A suffix '{caret}' followed by an empty brace pair |
| 195 | means the object could be a tag, |
| 196 | and dereference the tag recursively until a non-tag object is |
| 197 | found. |
| 198 | |
| 199 | '<rev>{caret}{/<text>}', e.g. 'HEAD^{/fix nasty bug}':: |
| 200 | A suffix '{caret}' to a revision parameter, followed by a brace |
| 201 | pair that contains a text led by a slash, |
| 202 | is the same as the ':/fix nasty bug' syntax below except that |
| 203 | it returns the youngest matching commit which is reachable from |
| 204 | the '<rev>' before '{caret}'. |
| 205 | |
| 206 | ':/<text>', e.g. ':/fix nasty bug':: |
| 207 | A colon, followed by a slash, followed by a text, names |
| 208 | a commit whose commit message matches the specified regular expression. |
| 209 | This name returns the youngest matching commit which is |
| 210 | reachable from any ref, including HEAD. |
| 211 | The regular expression can match any part of the |
| 212 | commit message. To match messages starting with a string, one can use |
| 213 | e.g. ':/^foo'. The special sequence ':/!' is reserved for modifiers to what |
| 214 | is matched. ':/!-foo' performs a negative match, while ':/!!foo' matches a |
| 215 | literal '!' character, followed by 'foo'. Any other sequence beginning with |
| 216 | ':/!' is reserved for now. |
| 217 | Depending on the given text, the shell's word splitting rules might |
| 218 | require additional quoting. |
| 219 | |
| 220 | '<rev>:<path>', e.g. 'HEAD:README', 'master:./README':: |
| 221 | A suffix ':' followed by a path names the blob or tree |
| 222 | at the given path in the tree-ish object named by the part |
| 223 | before the colon. |
| 224 | A path starting with './' or '../' is relative to the current working directory. |
| 225 | The given path will be converted to be relative to the working tree's root directory. |
| 226 | This is most useful to address a blob or tree from a commit or tree that has |
| 227 | the same tree structure as the working tree. |
| 228 | |
| 229 | ':[<n>:]<path>', e.g. ':0:README', ':README':: |
| 230 | A colon, optionally followed by a stage number (0 to 3) and a |
| 231 | colon, followed by a path, names a blob object in the |
| 232 | index at the given path. A missing stage number (and the colon |
| 233 | that follows it) names a stage 0 entry. During a merge, stage |
| 234 | 1 is the common ancestor, stage 2 is the target branch's version |
| 235 | (typically the current branch), and stage 3 is the version from |
| 236 | the branch which is being merged. |
| 237 | |
| 238 | Here is an illustration, by Jon Loeliger. Both commit nodes B |
| 239 | and C are parents of commit node A. Parent commits are ordered |
| 240 | left-to-right. |
| 241 | |
| 242 | ........................................ |
| 243 | G H I J |
| 244 | \ / \ / |
| 245 | D E F |
| 246 | \ | / \ |
| 247 | \ | / | |
| 248 | \|/ | |
| 249 | B C |
| 250 | \ / |
| 251 | \ / |
| 252 | A |
| 253 | ........................................ |
| 254 | |
| 255 | A = = A^0 |
| 256 | B = A^ = A^1 = A~1 |
| 257 | C = = A^2 |
| 258 | D = A^^ = A^1^1 = A~2 |
| 259 | E = B^2 = A^^2 |
| 260 | F = B^3 = A^^3 |
| 261 | G = A^^^ = A^1^1^1 = A~3 |
| 262 | H = D^2 = B^^2 = A^^^2 = A~2^2 |
| 263 | I = F^ = B^3^ = A^^3^ |
| 264 | J = F^2 = B^3^2 = A^^3^2 |
| 265 | |
| 266 | |
| 267 | SPECIFYING RANGES |
| 268 | ----------------- |
| 269 | |
| 270 | History traversing commands such as `git log` operate on a set |
| 271 | of commits, not just a single commit. |
| 272 | |
| 273 | For these commands, |
| 274 | specifying a single revision, using the notation described in the |
| 275 | previous section, means the set of commits `reachable` from the given |
| 276 | commit. |
| 277 | |
| 278 | Specifying several revisions means the set of commits reachable from |
| 279 | any of the given commits. |
| 280 | |
| 281 | A commit's reachable set is the commit itself and the commits in |
| 282 | its ancestry chain. |
| 283 | |
| 284 | There are several notations to specify a set of connected commits |
| 285 | (called a "revision range"), illustrated below. |
| 286 | |
| 287 | |
| 288 | Commit Exclusions |
| 289 | ~~~~~~~~~~~~~~~~~ |
| 290 | |
| 291 | '{caret}<rev>' (caret) Notation:: |
| 292 | To exclude commits reachable from a commit, a prefix '{caret}' |
| 293 | notation is used. E.g. '{caret}r1 r2' means commits reachable |
| 294 | from 'r2' but exclude the ones reachable from 'r1' (i.e. 'r1' and |
| 295 | its ancestors). |
| 296 | |
| 297 | Dotted Range Notations |
| 298 | ~~~~~~~~~~~~~~~~~~~~~~ |
| 299 | |
| 300 | The '..' (two-dot) Range Notation:: |
| 301 | The '{caret}r1 r2' set operation appears so often that there is a shorthand |
| 302 | for it. When you have two commits 'r1' and 'r2' (named according |
| 303 | to the syntax explained in SPECIFYING REVISIONS above), you can ask |
| 304 | for commits that are reachable from r2 excluding those that are reachable |
| 305 | from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'. |
| 306 | |
| 307 | The '\...' (three-dot) Symmetric Difference Notation:: |
| 308 | A similar notation 'r1\...r2' is called symmetric difference |
| 309 | of 'r1' and 'r2' and is defined as |
| 310 | 'r1 r2 --not $(git merge-base --all r1 r2)'. |
| 311 | It is the set of commits that are reachable from either one of |
| 312 | 'r1' (left side) or 'r2' (right side) but not from both. |
| 313 | |
| 314 | In these two shorthand notations, you can omit one end and let it default to HEAD. |
| 315 | For example, 'origin..' is a shorthand for 'origin..HEAD' and asks "What |
| 316 | did I do since I forked from the origin branch?" Similarly, '..origin' |
| 317 | is a shorthand for 'HEAD..origin' and asks "What did the origin do since |
| 318 | I forked from them?" Note that '..' would mean 'HEAD..HEAD' which is an |
| 319 | empty range that is both reachable and unreachable from HEAD. |
| 320 | |
| 321 | Commands that are specifically designed to take two distinct ranges |
| 322 | (e.g. "git range-diff R1 R2" to compare two ranges) do exist, but |
| 323 | they are exceptions. Unless otherwise noted, all "git" commands |
| 324 | that operate on a set of commits work on a single revision range. |
| 325 | In other words, writing two "two-dot range notation" next to each |
| 326 | other, e.g. |
| 327 | |
| 328 | $ git log A..B C..D |
| 329 | |
| 330 | does *not* specify two revision ranges for most commands. Instead |
| 331 | it will name a single connected set of commits, i.e. those that are |
| 332 | reachable from either B or D but are reachable from neither A or C. |
| 333 | In a linear history like this: |
| 334 | |
| 335 | ---A---B---o---o---C---D |
| 336 | |
| 337 | because A and B are reachable from C, the revision range specified |
| 338 | by these two dotted ranges is a single commit D. |
| 339 | |
| 340 | |
| 341 | Other <rev>{caret} Parent Shorthand Notations |
| 342 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 343 | Three other shorthands exist, particularly useful for merge commits, |
| 344 | for naming a set that is formed by a commit and its parent commits. |
| 345 | |
| 346 | The 'r1{caret}@' notation means all parents of 'r1'. |
| 347 | |
| 348 | The 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents. |
| 349 | By itself, this notation denotes the single commit 'r1'. |
| 350 | |
| 351 | The '<rev>{caret}-[<n>]' notation includes '<rev>' but excludes the <n>th |
| 352 | parent (i.e. a shorthand for '<rev>{caret}<n>..<rev>'), with '<n>' = 1 if |
| 353 | not given. This is typically useful for merge commits where you |
| 354 | can just pass '<commit>{caret}-' to get all the commits in the branch |
| 355 | that was merged in merge commit '<commit>' (including '<commit>' |
| 356 | itself). |
| 357 | |
| 358 | While '<rev>{caret}<n>' was about specifying a single commit parent, these |
| 359 | three notations also consider its parents. For example you can say |
| 360 | 'HEAD{caret}2{caret}@', however you cannot say 'HEAD{caret}@{caret}2'. |
| 361 | |
| 362 | Revision Range Summary |
| 363 | ---------------------- |
| 364 | |
| 365 | '<rev>':: |
| 366 | Include commits that are reachable from <rev> (i.e. <rev> and its |
| 367 | ancestors). |
| 368 | |
| 369 | '{caret}<rev>':: |
| 370 | Exclude commits that are reachable from <rev> (i.e. <rev> and its |
| 371 | ancestors). |
| 372 | |
| 373 | '<rev1>..<rev2>':: |
| 374 | Include commits that are reachable from <rev2> but exclude |
| 375 | those that are reachable from <rev1>. When either <rev1> or |
| 376 | <rev2> is omitted, it defaults to `HEAD`. |
| 377 | |
| 378 | '<rev1>\...<rev2>':: |
| 379 | Include commits that are reachable from either <rev1> or |
| 380 | <rev2> but exclude those that are reachable from both. When |
| 381 | either <rev1> or <rev2> is omitted, it defaults to `HEAD`. |
| 382 | |
| 383 | '<rev>{caret}@', e.g. 'HEAD{caret}@':: |
| 384 | A suffix '{caret}' followed by an at sign is the same as listing |
| 385 | all parents of '<rev>' (meaning, include anything reachable from |
| 386 | its parents, but not the commit itself). |
| 387 | |
| 388 | '<rev>{caret}!', e.g. 'HEAD{caret}!':: |
| 389 | A suffix '{caret}' followed by an exclamation mark is the same |
| 390 | as giving commit '<rev>' and all its parents prefixed with |
| 391 | '{caret}' to exclude them (and their ancestors). |
| 392 | |
| 393 | '<rev>{caret}-<n>', e.g. 'HEAD{caret}-, HEAD{caret}-2':: |
| 394 | Equivalent to '<rev>{caret}<n>..<rev>', with '<n>' = 1 if not |
| 395 | given. |
| 396 | |
| 397 | Here are a handful of examples using the Loeliger illustration above, |
| 398 | with each step in the notation's expansion and selection carefully |
| 399 | spelt out: |
| 400 | |
| 401 | .... |
| 402 | Args Expanded arguments Selected commits |
| 403 | D G H D |
| 404 | D F G H I J D F |
| 405 | ^G D H D |
| 406 | ^D B E I J F B |
| 407 | ^D B C E I J F B C |
| 408 | C I J F C |
| 409 | B..C = ^B C C |
| 410 | B...C = B ^F C G H D E B C |
| 411 | B^- = B^..B |
| 412 | = ^B^1 B E I J F B |
| 413 | C^@ = C^1 |
| 414 | = F I J F |
| 415 | B^@ = B^1 B^2 B^3 |
| 416 | = D E F D G H E F I J |
| 417 | C^! = C ^C^@ |
| 418 | = C ^C^1 |
| 419 | = C ^F C |
| 420 | B^! = B ^B^@ |
| 421 | = B ^B^1 ^B^2 ^B^3 |
| 422 | = B ^D ^E ^F B |
| 423 | F^! D = F ^I ^J D G H D F |
| 424 | .... |