| 1 | Commit Limiting |
| 2 | ~~~~~~~~~~~~~~~ |
| 3 | |
| 4 | Besides specifying a range of commits that should be listed using the |
| 5 | special notations explained in the description, additional commit |
| 6 | limiting may be applied. |
| 7 | |
| 8 | Using more options generally further limits the output (e.g. |
| 9 | `--since=<date1>` limits to commits newer than _<date1>_, and using it |
| 10 | with `--grep=<pattern>` further limits to commits whose log message |
| 11 | has a line that matches _<pattern>_), unless otherwise noted. |
| 12 | |
| 13 | Note that these are applied before commit |
| 14 | ordering and formatting options, such as `--reverse`. |
| 15 | |
| 16 | `-<number>`:: |
| 17 | `-n <number>`:: |
| 18 | `--max-count=<number>`:: |
| 19 | Limit the output to the first _<number>_ commits that would be shown. |
| 20 | |
| 21 | `--max-count-oldest=<number>`:: |
| 22 | Limit the output to the last _<number>_ commits that would be shown. |
| 23 | |
| 24 | `--skip=<number>`:: |
| 25 | Skip _<number>_ commits before starting to show the commit output. |
| 26 | |
| 27 | `--since=<date>`:: |
| 28 | `--after=<date>`:: |
| 29 | Show commits more recent than _<date>_. As a special case, |
| 30 | 'today' means the last midnight. |
| 31 | |
| 32 | `--since-as-filter=<date>`:: |
| 33 | Show all commits more recent than _<date>_. This visits |
| 34 | all commits in the range, rather than stopping at the first commit which |
| 35 | is older than _<date>_. |
| 36 | |
| 37 | `--until=<date>`:: |
| 38 | `--before=<date>`:: |
| 39 | Show commits older than _<date>_. |
| 40 | |
| 41 | ifdef::git-rev-list[] |
| 42 | `--max-age=<timestamp>`:: |
| 43 | `--min-age=<timestamp>`:: |
| 44 | Limit the commits output to specified time range. |
| 45 | endif::git-rev-list[] |
| 46 | |
| 47 | `--author=<pattern>`:: |
| 48 | `--committer=<pattern>`:: |
| 49 | Limit the commits output to ones with author/committer |
| 50 | header lines that match the _<pattern>_ regular |
| 51 | expression. With more than one `--author=<pattern>`, |
| 52 | commits whose author matches any of the _<pattern>_ are |
| 53 | chosen (similarly for multiple `--committer=<pattern>`). |
| 54 | |
| 55 | `--grep-reflog=<pattern>`:: |
| 56 | Limit the commits output to ones with reflog entries that |
| 57 | match the _<pattern>_ regular expression. With |
| 58 | more than one `--grep-reflog`, commits whose reflog message |
| 59 | matches any of the given patterns are chosen. It is an |
| 60 | error to use this option unless `--walk-reflogs` is in use. |
| 61 | |
| 62 | `--grep=<pattern>`:: |
| 63 | Limit the commits output to ones with a log message that |
| 64 | matches the _<pattern>_ regular expression. With |
| 65 | more than one `--grep=<pattern>`, commits whose message |
| 66 | matches any of the _<pattern>_ are chosen (but see |
| 67 | `--all-match`). |
| 68 | ifndef::git-rev-list[] |
| 69 | + |
| 70 | When `--notes` is in effect, the message from the notes is |
| 71 | matched as if it were part of the log message. |
| 72 | endif::git-rev-list[] |
| 73 | |
| 74 | `--all-match`:: |
| 75 | Limit the commits output to ones that match all given `--grep`, |
| 76 | instead of ones that match at least one. |
| 77 | |
| 78 | `--invert-grep`:: |
| 79 | Limit the commits output to ones with a log message that do not |
| 80 | match the _<pattern>_ specified with `--grep=<pattern>`. |
| 81 | |
| 82 | `-i`:: |
| 83 | `--regexp-ignore-case`:: |
| 84 | Match the regular expression limiting patterns without regard to letter |
| 85 | case. |
| 86 | |
| 87 | `--basic-regexp`:: |
| 88 | Consider the limiting patterns to be basic regular expressions; |
| 89 | this is the default. |
| 90 | |
| 91 | `-E`:: |
| 92 | `--extended-regexp`:: |
| 93 | Consider the limiting patterns to be extended regular expressions |
| 94 | instead of the default basic regular expressions. |
| 95 | |
| 96 | `-F`:: |
| 97 | `--fixed-strings`:: |
| 98 | Consider the limiting patterns to be fixed strings (don't interpret |
| 99 | pattern as a regular expression). |
| 100 | |
| 101 | `-P`:: |
| 102 | `--perl-regexp`:: |
| 103 | Consider the limiting patterns to be Perl-compatible regular |
| 104 | expressions. |
| 105 | + |
| 106 | Support for these types of regular expressions is an optional |
| 107 | compile-time dependency. If Git wasn't compiled with support for them |
| 108 | providing this option will cause it to die. |
| 109 | |
| 110 | `--remove-empty`:: |
| 111 | Stop when a given path disappears from the tree. |
| 112 | |
| 113 | `--merges`:: |
| 114 | Print only merge commits. This is exactly the same as `--min-parents=2`. |
| 115 | |
| 116 | `--no-merges`:: |
| 117 | Do not print commits with more than one parent. This is |
| 118 | exactly the same as `--max-parents=1`. |
| 119 | |
| 120 | `--min-parents=<number>`:: |
| 121 | `--max-parents=<number>`:: |
| 122 | `--no-min-parents`:: |
| 123 | `--no-max-parents`:: |
| 124 | Show only commits which have at least (or at most) that many parent |
| 125 | commits. In particular, `--max-parents=1` is the same as `--no-merges`, |
| 126 | `--min-parents=2` is the same as `--merges`. `--max-parents=0` |
| 127 | gives all root commits and `--min-parents=3` all octopus merges. |
| 128 | + |
| 129 | `--no-min-parents` and `--no-max-parents` reset these limits (to no limit) |
| 130 | again. Equivalent forms are `--min-parents=0` (any commit has 0 or more |
| 131 | parents) and `--max-parents=-1` (negative numbers denote no upper limit). |
| 132 | |
| 133 | `--first-parent`:: |
| 134 | When finding commits to include, follow only the first |
| 135 | parent commit upon seeing a merge commit. This option |
| 136 | can give a better overview when viewing the evolution of |
| 137 | a particular topic branch, because merges into a topic |
| 138 | branch tend to be only about adjusting to updated upstream |
| 139 | from time to time, and this option allows you to ignore |
| 140 | the individual commits brought in to your history by such |
| 141 | a merge. |
| 142 | ifdef::git-log[] |
| 143 | + |
| 144 | This option also changes default diff format for merge commits |
| 145 | to `first-parent`, see `--diff-merges=first-parent` for details. |
| 146 | endif::git-log[] |
| 147 | |
| 148 | `--exclude-first-parent-only`:: |
| 149 | When finding commits to exclude (with a '{caret}'), follow only |
| 150 | the first parent commit upon seeing a merge commit. |
| 151 | This can be used to find the set of changes in a topic branch |
| 152 | from the point where it diverged from the remote branch, given |
| 153 | that arbitrary merges can be valid topic branch changes. |
| 154 | |
| 155 | `--maximal-only`:: |
| 156 | Restrict the output commits to be those that are not reachable |
| 157 | from any other commits in the revision range. |
| 158 | |
| 159 | `--not`:: |
| 160 | Reverses the meaning of the '{caret}' prefix (or lack thereof) |
| 161 | for all following revision specifiers, up to the next `--not`. |
| 162 | When used on the command line before --stdin, the revisions passed |
| 163 | through stdin will not be affected by it. Conversely, when passed |
| 164 | via standard input, the revisions passed on the command line will |
| 165 | not be affected by it. |
| 166 | |
| 167 | `--all`:: |
| 168 | Pretend as if all the refs in `refs/`, along with `HEAD`, are |
| 169 | listed on the command line as _<commit>_. |
| 170 | |
| 171 | `--branches[=<pattern>]`:: |
| 172 | Pretend as if all the refs in `refs/heads` are listed |
| 173 | on the command line as _<commit>_. If _<pattern>_ is given, limit |
| 174 | branches to ones matching given shell glob. If _<pattern>_ lacks '?', |
| 175 | '{asterisk}', or '[', '/{asterisk}' at the end is implied. |
| 176 | |
| 177 | `--tags[=<pattern>]`:: |
| 178 | Pretend as if all the refs in `refs/tags` are listed |
| 179 | on the command line as _<commit>_. If _<pattern>_ is given, limit |
| 180 | tags to ones matching given shell glob. If pattern lacks '?', '{asterisk}', |
| 181 | or '[', '/{asterisk}' at the end is implied. |
| 182 | |
| 183 | `--remotes[=<pattern>]`:: |
| 184 | Pretend as if all the refs in `refs/remotes` are listed |
| 185 | on the command line as _<commit>_. If _<pattern>_ is given, limit |
| 186 | remote-tracking branches to ones matching given shell glob. |
| 187 | If pattern lacks '?', '{asterisk}', or '[', '/{asterisk}' at the end is implied. |
| 188 | |
| 189 | `--glob=<glob-pattern>`:: |
| 190 | Pretend as if all the refs matching shell glob _<glob-pattern>_ |
| 191 | are listed on the command line as _<commit>_. Leading 'refs/', |
| 192 | is automatically prepended if missing. If pattern lacks '?', '{asterisk}', |
| 193 | or '[', '/{asterisk}' at the end is implied. |
| 194 | |
| 195 | `--exclude=<glob-pattern>`:: |
| 196 | |
| 197 | Do not include refs matching _<glob-pattern>_ that the next `--all`, |
| 198 | `--branches`, `--tags`, `--remotes`, or `--glob` would otherwise |
| 199 | consider. Repetitions of this option accumulate exclusion patterns |
| 200 | up to the next `--all`, `--branches`, `--tags`, `--remotes`, or |
| 201 | `--glob` option (other options or arguments do not clear |
| 202 | accumulated patterns). |
| 203 | + |
| 204 | The patterns given should not begin with `refs/heads`, `refs/tags`, or |
| 205 | `refs/remotes` when applied to `--branches`, `--tags`, or `--remotes`, |
| 206 | respectively, and they must begin with `refs/` when applied to `--glob` |
| 207 | or `--all`. If a trailing '/{asterisk}' is intended, it must be given |
| 208 | explicitly. |
| 209 | |
| 210 | `--exclude-hidden=(fetch|receive|uploadpack)`:: |
| 211 | Do not include refs that would be hidden by `git-fetch`, |
| 212 | `git-receive-pack` or `git-upload-pack` by consulting the appropriate |
| 213 | `fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs` |
| 214 | configuration along with `transfer.hideRefs` (see |
| 215 | linkgit:git-config[1]). This option affects the next pseudo-ref option |
| 216 | `--all` or `--glob` and is cleared after processing them. |
| 217 | |
| 218 | `--reflog`:: |
| 219 | Pretend as if all objects mentioned by reflogs are listed on the |
| 220 | command line as _<commit>_. |
| 221 | |
| 222 | `--alternate-refs`:: |
| 223 | Pretend as if all objects mentioned as ref tips of alternate |
| 224 | repositories were listed on the command line. An alternate |
| 225 | repository is any repository whose object directory is specified |
| 226 | in `objects/info/alternates`. The set of included objects may |
| 227 | be modified by `core.alternateRefsCommand`, etc. See |
| 228 | linkgit:git-config[1]. |
| 229 | |
| 230 | `--single-worktree`:: |
| 231 | By default, all working trees will be examined by the |
| 232 | following options when there are more than one (see |
| 233 | linkgit:git-worktree[1]): `--all`, `--reflog` and |
| 234 | `--indexed-objects`. |
| 235 | This option forces them to examine the current working tree |
| 236 | only. |
| 237 | |
| 238 | `--ignore-missing`:: |
| 239 | Upon seeing an invalid object name in the input, pretend as if |
| 240 | the bad input was not given. |
| 241 | |
| 242 | ifndef::git-rev-list[] |
| 243 | `--bisect`:: |
| 244 | Pretend as if the bad bisection ref `refs/bisect/bad` |
| 245 | was listed and as if it was followed by `--not` and the good |
| 246 | bisection refs `refs/bisect/good-*` on the command |
| 247 | line. |
| 248 | endif::git-rev-list[] |
| 249 | |
| 250 | `--stdin`:: |
| 251 | In addition to getting arguments from the command line, read |
| 252 | them from standard input as well. This accepts commits and |
| 253 | pseudo-options like `--all` and `--glob=`. When a `--` separator |
| 254 | is seen, the following input is treated as paths and used to |
| 255 | limit the result. Flags like `--not` which are read via standard input |
| 256 | are only respected for arguments passed in the same way and will not |
| 257 | influence any subsequent command line arguments. |
| 258 | |
| 259 | ifdef::git-rev-list[] |
| 260 | `--quiet`:: |
| 261 | Don't print anything to standard output. This form |
| 262 | is primarily meant to allow the caller to |
| 263 | test the exit status to see if a range of objects is fully |
| 264 | connected (or not). It is faster than redirecting stdout |
| 265 | to `/dev/null` as the output does not have to be formatted. |
| 266 | |
| 267 | `--disk-usage`:: |
| 268 | `--disk-usage=human`:: |
| 269 | Suppress normal output; instead, print the sum of the bytes used |
| 270 | for on-disk storage by the selected commits or objects. This is |
| 271 | equivalent to piping the output into `git cat-file |
| 272 | --batch-check='%(objectsize:disk)'`, except that it runs much |
| 273 | faster (especially with `--use-bitmap-index`). See the `CAVEATS` |
| 274 | section in linkgit:git-cat-file[1] for the limitations of what |
| 275 | "on-disk storage" means. |
| 276 | With the optional value `human`, on-disk storage size is shown |
| 277 | in human-readable string(e.g. 12.24 Kib, 3.50 Mib). |
| 278 | endif::git-rev-list[] |
| 279 | |
| 280 | `--cherry-mark`:: |
| 281 | Like `--cherry-pick` (see below) but mark equivalent commits |
| 282 | with `=` rather than omitting them, and inequivalent ones with `+`. |
| 283 | |
| 284 | `--cherry-pick`:: |
| 285 | Omit any commit that introduces the same change as |
| 286 | another commit on the ``other side'' when the set of |
| 287 | commits are limited with symmetric difference. |
| 288 | + |
| 289 | For example, if you have two branches, `A` and `B`, a usual way |
| 290 | to list all commits on only one side of them is with |
| 291 | `--left-right` (see the example below in the description of |
| 292 | the `--left-right` option). However, it shows the commits that were |
| 293 | cherry-picked from the other branch (for example, ``3rd on b'' may be |
| 294 | cherry-picked from branch A). With this option, such pairs of commits are |
| 295 | excluded from the output. |
| 296 | |
| 297 | `--left-only`:: |
| 298 | `--right-only`:: |
| 299 | List only commits on the respective side of a symmetric difference, |
| 300 | i.e. only those which would be marked `<` resp. `>` by |
| 301 | `--left-right`. |
| 302 | + |
| 303 | For example, `--cherry-pick --right-only A...B` omits those |
| 304 | commits from `B` which are in `A` or are patch-equivalent to a commit in |
| 305 | `A`. In other words, this lists the `+` commits from `git cherry A B`. |
| 306 | More precisely, `--cherry-pick --right-only --no-merges` gives the exact |
| 307 | list. |
| 308 | |
| 309 | `--cherry`:: |
| 310 | A synonym for `--right-only --cherry-mark --no-merges`; useful to |
| 311 | limit the output to the commits on our side and mark those that |
| 312 | have been applied to the other side of a forked history with |
| 313 | `git log --cherry upstream...mybranch`, similar to |
| 314 | `git cherry upstream mybranch`. |
| 315 | |
| 316 | `-g`:: |
| 317 | `--walk-reflogs`:: |
| 318 | Instead of walking the commit ancestry chain, walk |
| 319 | reflog entries from the most recent one to older ones. |
| 320 | When this option is used you cannot specify commits to |
| 321 | exclude (that is, `^<commit>`, `<commit1>..<commit2>`, |
| 322 | and `<commit1>...<commit2>` notations cannot be used). |
| 323 | + |
| 324 | With `--pretty` format other than `oneline` and `reference` (for obvious reasons), |
| 325 | this causes the output to have two extra lines of information |
| 326 | taken from the reflog. The reflog designator in the output may be shown |
| 327 | as `ref@{<Nth>}` (where _<Nth>_ is the reverse-chronological index in the |
| 328 | reflog) or as `ref@{<timestamp>}` (with the _<timestamp>_ for that entry), |
| 329 | depending on a few rules: |
| 330 | + |
| 331 | -- |
| 332 | 1. If the starting point is specified as `ref@{<Nth>}`, show the index |
| 333 | format. |
| 334 | + |
| 335 | 2. If the starting point was specified as `ref@{now}`, show the |
| 336 | timestamp format. |
| 337 | + |
| 338 | 3. If neither was used, but `--date` was given on the command line, show |
| 339 | the timestamp in the format requested by `--date`. |
| 340 | + |
| 341 | 4. Otherwise, show the index format. |
| 342 | -- |
| 343 | + |
| 344 | Under `--pretty=oneline`, the commit message is |
| 345 | prefixed with this information on the same line. |
| 346 | This option cannot be combined with `--reverse`. |
| 347 | See also linkgit:git-reflog[1]. |
| 348 | + |
| 349 | Under `--pretty=reference`, this information will not be shown at all. |
| 350 | |
| 351 | `--merge`:: |
| 352 | Show commits touching conflicted paths in the range `HEAD...<other>`, |
| 353 | where `<other>` is the first existing pseudoref in `MERGE_HEAD`, |
| 354 | `CHERRY_PICK_HEAD`, `REVERT_HEAD` or `REBASE_HEAD`. Only works |
| 355 | when the index has unmerged entries. This option can be used to show |
| 356 | relevant commits when resolving conflicts from a 3-way merge. |
| 357 | |
| 358 | `--boundary`:: |
| 359 | Output excluded boundary commits. Boundary commits are |
| 360 | prefixed with `-`. |
| 361 | |
| 362 | ifdef::git-rev-list[] |
| 363 | `--use-bitmap-index`:: |
| 364 | |
| 365 | Try to speed up the traversal using the pack bitmap index (if |
| 366 | one is available). Note that when traversing with `--objects`, |
| 367 | trees and blobs will not have their associated path printed. |
| 368 | |
| 369 | `--progress=<header>`:: |
| 370 | Show progress reports on stderr as objects are considered. The |
| 371 | `<header>` text will be printed with each progress update. |
| 372 | |
| 373 | `-z`:: |
| 374 | Instead of being newline-delimited, each outputted object and its |
| 375 | accompanying metadata is delimited using NUL bytes. Output is printed |
| 376 | in the following form: |
| 377 | + |
| 378 | ----------------------------------------------------------------------- |
| 379 | <OID> NUL [<token>=<value> NUL]... |
| 380 | ----------------------------------------------------------------------- |
| 381 | + |
| 382 | Additional object metadata, such as object paths or boundary objects, is |
| 383 | printed using the `<token>=<value>` form. Token values are printed as-is |
| 384 | without any encoding/truncation. An OID entry never contains a '=' character |
| 385 | and thus is used to signal the start of a new object record. Examples: |
| 386 | + |
| 387 | ----------------------------------------------------------------------- |
| 388 | <OID> NUL |
| 389 | <OID> NUL path=<path> NUL |
| 390 | <OID> NUL boundary=yes NUL |
| 391 | <OID> NUL missing=yes NUL [<token>=<value> NUL]... |
| 392 | ----------------------------------------------------------------------- |
| 393 | + |
| 394 | This mode is only compatible with the `--objects`, `--boundary`, and |
| 395 | `--missing` output options. |
| 396 | endif::git-rev-list[] |
| 397 | |
| 398 | History Simplification |
| 399 | ~~~~~~~~~~~~~~~~~~~~~~ |
| 400 | |
| 401 | Sometimes you are only interested in parts of the history, for example the |
| 402 | commits modifying a particular <path>. But there are two parts of |
| 403 | 'History Simplification', one part is selecting the commits and the other |
| 404 | is how to do it, as there are various strategies to simplify the history. |
| 405 | |
| 406 | The following options select the commits to be shown: |
| 407 | |
| 408 | `<paths>`:: |
| 409 | Commits modifying the given <paths> are selected. |
| 410 | |
| 411 | `--simplify-by-decoration`:: |
| 412 | Commits that are referred by some branch or tag are selected. |
| 413 | |
| 414 | Note that extra commits can be shown to give a meaningful history. |
| 415 | |
| 416 | The following options affect the way the simplification is performed: |
| 417 | |
| 418 | `Default mode`:: |
| 419 | Simplifies the history to the simplest history explaining the |
| 420 | final state of the tree. Simplest because it prunes some side |
| 421 | branches if the end result is the same (i.e. merging branches |
| 422 | with the same content) |
| 423 | |
| 424 | `--show-pulls`:: |
| 425 | Include all commits from the default mode, but also any merge |
| 426 | commits that are not TREESAME to the first parent but are |
| 427 | TREESAME to a later parent. This mode is helpful for showing |
| 428 | the merge commits that "first introduced" a change to a branch. |
| 429 | |
| 430 | `--full-history`:: |
| 431 | Same as the default mode, but does not prune some history. |
| 432 | |
| 433 | `--dense`:: |
| 434 | Only the selected commits are shown, plus some to have a |
| 435 | meaningful history. |
| 436 | |
| 437 | `--sparse`:: |
| 438 | All commits in the simplified history are shown. |
| 439 | |
| 440 | `--simplify-merges`:: |
| 441 | Additional option to `--full-history` to remove some needless |
| 442 | merges from the resulting history, as there are no selected |
| 443 | commits contributing to this merge. |
| 444 | |
| 445 | `--ancestry-path[=<commit>]`:: |
| 446 | When given a range of commits to display (e.g. `<commit1>..<commit2>` |
| 447 | or `<commit2> ^<commit1>`), and a commit _<commit>_ in that range, |
| 448 | only display commits in that range |
| 449 | that are ancestors of _<commit>_, descendants of _<commit>_, or |
| 450 | _<commit>_ itself. If no commit is specified, use _<commit1>_ (the |
| 451 | excluded part of the range) as _<commit>_. Can be passed multiple |
| 452 | times; if so, a commit is included if it is any of the commits |
| 453 | given or if it is an ancestor or descendant of one of them. |
| 454 | |
| 455 | A more detailed explanation follows. |
| 456 | |
| 457 | Suppose you specified `foo` as the _<paths>_. We shall call commits |
| 458 | that modify `foo` !TREESAME, and the rest TREESAME. (In a diff |
| 459 | filtered for `foo`, they look different and equal, respectively.) |
| 460 | |
| 461 | In the following, we will always refer to the same example history to |
| 462 | illustrate the differences between simplification settings. We assume |
| 463 | that you are filtering for a file `foo` in this commit graph: |
| 464 | |
| 465 | ----------------------------------------------------------------------- |
| 466 | .-A---M---N---O---P---Q |
| 467 | / / / / / / |
| 468 | I B C D E Y |
| 469 | \ / / / / / |
| 470 | `-------------' X |
| 471 | ----------------------------------------------------------------------- |
| 472 | |
| 473 | The horizontal line of history A---Q is taken to be the first parent of |
| 474 | each merge. The commits are: |
| 475 | |
| 476 | * `I` is the initial commit, in which `foo` exists with contents |
| 477 | `asdf`, and a file `quux` exists with contents `quux`. Initial |
| 478 | commits are compared to an empty tree, so `I` is !TREESAME. |
| 479 | |
| 480 | * In `A`, `foo` contains just `foo`. |
| 481 | |
| 482 | * `B` contains the same change as `A`. Its merge `M` is trivial and |
| 483 | hence TREESAME to all parents. |
| 484 | |
| 485 | * `C` does not change `foo`, but its merge `N` changes it to `foobar`, |
| 486 | so it is not TREESAME to any parent. |
| 487 | |
| 488 | * `D` sets `foo` to `baz`. Its merge `O` combines the strings from |
| 489 | `N` and `D` to `foobarbaz`; i.e., it is not TREESAME to any parent. |
| 490 | |
| 491 | * `E` changes `quux` to `xyzzy`, and its merge `P` combines the |
| 492 | strings to `quux xyzzy`. `P` is TREESAME to `O`, but not to `E`. |
| 493 | |
| 494 | * `X` is an independent root commit that added a new file `side`, and `Y` |
| 495 | modified it. `Y` is TREESAME to `X`. Its merge `Q` added `side` to `P`, and |
| 496 | `Q` is TREESAME to `P`, but not to `Y`. |
| 497 | |
| 498 | `rev-list` walks backwards through history, including or excluding |
| 499 | commits based on whether `--full-history` and/or parent rewriting |
| 500 | (via `--parents` or `--children`) are used. The following settings |
| 501 | are available. |
| 502 | |
| 503 | Default mode:: |
| 504 | Commits are included if they are not TREESAME to any parent |
| 505 | (though this can be changed, see `--sparse` below). If the |
| 506 | commit was a merge, and it was TREESAME to one parent, follow |
| 507 | only that parent. (Even if there are several TREESAME |
| 508 | parents, follow only one of them.) Otherwise, follow all |
| 509 | parents. |
| 510 | + |
| 511 | This results in: |
| 512 | + |
| 513 | ----------------------------------------------------------------------- |
| 514 | .-A---N---O |
| 515 | / / / |
| 516 | I---------D |
| 517 | ----------------------------------------------------------------------- |
| 518 | + |
| 519 | Note how the rule to only follow the TREESAME parent, if one is |
| 520 | available, removed `B` from consideration entirely. `C` was |
| 521 | considered via `N`, but is TREESAME. Root commits are compared to an |
| 522 | empty tree, so `I` is !TREESAME. |
| 523 | + |
| 524 | Parent/child relations are only visible with `--parents`, but that does |
| 525 | not affect the commits selected in default mode, so we have shown the |
| 526 | parent lines. |
| 527 | |
| 528 | `--full-history` without parent rewriting:: |
| 529 | This mode differs from the default in one point: always follow |
| 530 | all parents of a merge, even if it is TREESAME to one of them. |
| 531 | Even if more than one side of the merge has commits that are |
| 532 | included, this does not imply that the merge itself is! In |
| 533 | the example, we get |
| 534 | + |
| 535 | ----------------------------------------------------------------------- |
| 536 | I A B N D O P Q |
| 537 | ----------------------------------------------------------------------- |
| 538 | + |
| 539 | `M` was excluded because it is TREESAME to both parents. `E`, |
| 540 | `C` and `B` were all walked, but only `B` was !TREESAME, so the others |
| 541 | do not appear. |
| 542 | + |
| 543 | Note that without parent rewriting, it is not really possible to talk |
| 544 | about the parent/child relationships between the commits, so we show |
| 545 | them disconnected. |
| 546 | |
| 547 | `--full-history` with parent rewriting:: |
| 548 | Ordinary commits are only included if they are !TREESAME |
| 549 | (though this can be changed, see `--sparse` below). |
| 550 | + |
| 551 | Merges are always included. However, their parent list is rewritten: |
| 552 | Along each parent, prune away commits that are not included |
| 553 | themselves. This results in |
| 554 | + |
| 555 | ----------------------------------------------------------------------- |
| 556 | .-A---M---N---O---P---Q |
| 557 | / / / / / |
| 558 | I B / D / |
| 559 | \ / / / / |
| 560 | `-------------' |
| 561 | ----------------------------------------------------------------------- |
| 562 | + |
| 563 | Compare to `--full-history` without rewriting above. Note that `E` |
| 564 | was pruned away because it is TREESAME, but the parent list of P was |
| 565 | rewritten to contain `E`'s parent `I`. The same happened for `C` and |
| 566 | `N`, and `X`, `Y` and `Q`. |
| 567 | |
| 568 | In addition to the above settings, you can change whether TREESAME |
| 569 | affects inclusion: |
| 570 | |
| 571 | `--dense`:: |
| 572 | Commits that are walked are included if they are not TREESAME |
| 573 | to any parent. |
| 574 | |
| 575 | `--sparse`:: |
| 576 | All commits that are walked are included. |
| 577 | + |
| 578 | Note that without `--full-history`, this still simplifies merges: if |
| 579 | one of the parents is TREESAME, we follow only that one, so the other |
| 580 | sides of the merge are never walked. |
| 581 | |
| 582 | `--simplify-merges`:: |
| 583 | First, build a history graph in the same way that |
| 584 | `--full-history` with parent rewriting does (see above). |
| 585 | + |
| 586 | Then simplify each commit `C` to its replacement `C'` in the final |
| 587 | history according to the following rules: |
| 588 | + |
| 589 | -- |
| 590 | * Set `C'` to `C`. |
| 591 | + |
| 592 | * Replace each parent `P` of `C'` with its simplification `P'`. In |
| 593 | the process, drop parents that are ancestors of other parents or that are |
| 594 | root commits TREESAME to an empty tree, and remove duplicates, but take care |
| 595 | to never drop all parents that we are TREESAME to. |
| 596 | + |
| 597 | * If after this parent rewriting, `C'` is a root or merge commit (has |
| 598 | zero or >1 parents), a boundary commit, or !TREESAME, it remains. |
| 599 | Otherwise, it is replaced with its only parent. |
| 600 | -- |
| 601 | + |
| 602 | The effect of this is best shown by way of comparing to |
| 603 | `--full-history` with parent rewriting. The example turns into: |
| 604 | + |
| 605 | ----------------------------------------------------------------------- |
| 606 | .-A---M---N---O |
| 607 | / / / |
| 608 | I B D |
| 609 | \ / / |
| 610 | `---------' |
| 611 | ----------------------------------------------------------------------- |
| 612 | + |
| 613 | Note the major differences in `N`, `P`, and `Q` over `--full-history`: |
| 614 | + |
| 615 | -- |
| 616 | * `N`'s parent list had `I` removed, because it is an ancestor of the |
| 617 | other parent `M`. Still, `N` remained because it is !TREESAME. |
| 618 | + |
| 619 | * `P`'s parent list similarly had `I` removed. `P` was then |
| 620 | removed completely, because it had one parent and is TREESAME. |
| 621 | + |
| 622 | * `Q`'s parent list had `Y` simplified to `X`. `X` was then removed, because it |
| 623 | was a TREESAME root. `Q` was then removed completely, because it had one |
| 624 | parent and is TREESAME. |
| 625 | -- |
| 626 | |
| 627 | There is another simplification mode available: |
| 628 | |
| 629 | `--ancestry-path[=<commit>]`:: |
| 630 | Limit the displayed commits to those which are an ancestor of |
| 631 | _<commit>_, or which are a descendant of _<commit>_, or are _<commit>_ |
| 632 | itself. |
| 633 | + |
| 634 | As an example use case, consider the following commit history: |
| 635 | + |
| 636 | ----------------------------------------------------------------------- |
| 637 | D---E-------F |
| 638 | / \ \ |
| 639 | B---C---G---H---I---J |
| 640 | / \ |
| 641 | A-------K---------------L--M |
| 642 | ----------------------------------------------------------------------- |
| 643 | + |
| 644 | A regular 'D..M' computes the set of commits that are ancestors of `M`, |
| 645 | but excludes the ones that are ancestors of `D`. This is useful to see |
| 646 | what happened to the history leading to `M` since `D`, in the sense |
| 647 | that "what does `M` have that did not exist in `D`". The result in this |
| 648 | example would be all the commits, except `A` and `B` (and `D` itself, |
| 649 | of course). |
| 650 | + |
| 651 | When we want to find out what commits in `M` are contaminated with the |
| 652 | bug introduced by `D` and need fixing, however, we might want to view |
| 653 | only the subset of `D..M` that are actually descendants of `D`, i.e. |
| 654 | excluding `C` and `K`. This is exactly what the `--ancestry-path` |
| 655 | option does. Applied to the `D..M` range, it results in: |
| 656 | + |
| 657 | ----------------------------------------------------------------------- |
| 658 | E-------F |
| 659 | \ \ |
| 660 | G---H---I---J |
| 661 | \ |
| 662 | L--M |
| 663 | ----------------------------------------------------------------------- |
| 664 | + |
| 665 | We can also use `--ancestry-path=D` instead of `--ancestry-path` which |
| 666 | means the same thing when applied to the `D..M` range but is just more |
| 667 | explicit. |
| 668 | + |
| 669 | If we instead are interested in a given topic within this range, and all |
| 670 | commits affected by that topic, we may only want to view the subset of |
| 671 | `D..M` which contain that topic in their ancestry path. So, using |
| 672 | `--ancestry-path=H D..M` for example would result in: |
| 673 | + |
| 674 | ----------------------------------------------------------------------- |
| 675 | E |
| 676 | \ |
| 677 | C---G---H---I---J |
| 678 | \ |
| 679 | L--M |
| 680 | ----------------------------------------------------------------------- |
| 681 | + |
| 682 | Whereas `--ancestry-path=K D..M` would result in |
| 683 | + |
| 684 | ----------------------------------------------------------------------- |
| 685 | K---------------L--M |
| 686 | ----------------------------------------------------------------------- |
| 687 | |
| 688 | Before discussing another option, `--show-pulls`, we need to |
| 689 | create a new example history. |
| 690 | |
| 691 | A common problem users face when looking at simplified history is that a |
| 692 | commit they know changed a file somehow does not appear in the file's |
| 693 | simplified history. Let's demonstrate a new example and show how options |
| 694 | such as `--full-history` and `--simplify-merges` works in that case: |
| 695 | |
| 696 | ----------------------------------------------------------------------- |
| 697 | .-A---M-----C--N---O---P |
| 698 | / / \ \ \/ / / |
| 699 | I B \ R-'`-Z' / |
| 700 | \ / \/ / |
| 701 | \ / /\ / |
| 702 | `---X--' `---Y--' |
| 703 | ----------------------------------------------------------------------- |
| 704 | |
| 705 | For this example, suppose `I` created `file.txt` which was modified by |
| 706 | `A`, `B`, and `X` in different ways. The single-parent commits `C`, `Z`, |
| 707 | and `Y` do not change `file.txt`. The merge commit `M` was created by |
| 708 | resolving the merge conflict to include both changes from `A` and `B` |
| 709 | and hence is not TREESAME to either. The merge commit `R`, however, was |
| 710 | created by ignoring the contents of `file.txt` at `M` and taking only |
| 711 | the contents of `file.txt` at `X`. Hence, `R` is TREESAME to `X` but not |
| 712 | `M`. Finally, the natural merge resolution to create `N` is to take the |
| 713 | contents of `file.txt` at `R`, so `N` is TREESAME to `R` but not `C`. |
| 714 | The merge commits `O` and `P` are TREESAME to their first parents, but |
| 715 | not to their second parents, `Z` and `Y` respectively. |
| 716 | |
| 717 | When using the default mode, `N` and `R` both have a TREESAME parent, so |
| 718 | those edges are walked and the others are ignored. The resulting history |
| 719 | graph is: |
| 720 | |
| 721 | ----------------------------------------------------------------------- |
| 722 | I---X |
| 723 | ----------------------------------------------------------------------- |
| 724 | |
| 725 | When using `--full-history`, Git walks every edge. This will discover |
| 726 | the commits `A` and `B` and the merge `M`, but also will reveal the |
| 727 | merge commits `O` and `P`. With parent rewriting, the resulting graph is: |
| 728 | |
| 729 | ----------------------------------------------------------------------- |
| 730 | .-A---M--------N---O---P |
| 731 | / / \ \ \/ / / |
| 732 | I B \ R-'`--' / |
| 733 | \ / \/ / |
| 734 | \ / /\ / |
| 735 | `---X--' `------' |
| 736 | ----------------------------------------------------------------------- |
| 737 | |
| 738 | Here, the merge commits `O` and `P` contribute extra noise, as they did |
| 739 | not actually contribute a change to `file.txt`. They only merged a topic |
| 740 | that was based on an older version of `file.txt`. This is a common |
| 741 | issue in repositories using a workflow where many contributors work in |
| 742 | parallel and merge their topic branches along a single trunk: many |
| 743 | unrelated merges appear in the `--full-history` results. |
| 744 | |
| 745 | When using the `--simplify-merges` option, the commits `O` and `P` |
| 746 | disappear from the results. This is because the rewritten second parents |
| 747 | of `O` and `P` are reachable from their first parents. Those edges are |
| 748 | removed and then the commits look like single-parent commits that are |
| 749 | TREESAME to their parent. This also happens to the commit `N`, resulting |
| 750 | in a history view as follows: |
| 751 | |
| 752 | ----------------------------------------------------------------------- |
| 753 | .-A---M--. |
| 754 | / / \ |
| 755 | I B R |
| 756 | \ / / |
| 757 | \ / / |
| 758 | `---X--' |
| 759 | ----------------------------------------------------------------------- |
| 760 | |
| 761 | In this view, we see all of the important single-parent changes from |
| 762 | `A`, `B`, and `X`. We also see the carefully-resolved merge `M` and the |
| 763 | not-so-carefully-resolved merge `R`. This is usually enough information |
| 764 | to determine why the commits `A` and `B` "disappeared" from history in |
| 765 | the default view. However, there are a few issues with this approach. |
| 766 | |
| 767 | The first issue is performance. Unlike any previous option, the |
| 768 | `--simplify-merges` option requires walking the entire commit history |
| 769 | before returning a single result. This can make the option difficult to |
| 770 | use for very large repositories. |
| 771 | |
| 772 | The second issue is one of auditing. When many contributors are working |
| 773 | on the same repository, it is important which merge commits introduced |
| 774 | a change into an important branch. The problematic merge `R` above is |
| 775 | not likely to be the merge commit that was used to merge into an |
| 776 | important branch. Instead, the merge `N` was used to merge `R` and `X` |
| 777 | into the important branch. This commit may have information about why |
| 778 | the change `X` came to override the changes from `A` and `B` in its |
| 779 | commit message. |
| 780 | |
| 781 | `--show-pulls`:: |
| 782 | In addition to the commits shown in the default history, show |
| 783 | each merge commit that is not TREESAME to its first parent but |
| 784 | is TREESAME to a later parent. |
| 785 | + |
| 786 | When a merge commit is included by `--show-pulls`, the merge is |
| 787 | treated as if it "pulled" the change from another branch. When using |
| 788 | `--show-pulls` on this example (and no other options) the resulting |
| 789 | graph is: |
| 790 | + |
| 791 | ----------------------------------------------------------------------- |
| 792 | I---X---R---N |
| 793 | ----------------------------------------------------------------------- |
| 794 | + |
| 795 | Here, the merge commits `R` and `N` are included because they pulled |
| 796 | the commits `X` and `R` into the base branch, respectively. These |
| 797 | merges are the reason the commits `A` and `B` do not appear in the |
| 798 | default history. |
| 799 | + |
| 800 | When `--show-pulls` is paired with `--simplify-merges`, the |
| 801 | graph includes all of the necessary information: |
| 802 | + |
| 803 | ----------------------------------------------------------------------- |
| 804 | .-A---M--. N |
| 805 | / / \ / |
| 806 | I B R |
| 807 | \ / / |
| 808 | \ / / |
| 809 | `---X--' |
| 810 | ----------------------------------------------------------------------- |
| 811 | + |
| 812 | Notice that since `M` is reachable from `R`, the edge from `N` to `M` |
| 813 | was simplified away. However, `N` still appears in the history as an |
| 814 | important commit because it "pulled" the change `R` into the main |
| 815 | branch. |
| 816 | |
| 817 | The `--simplify-by-decoration` option allows you to view only the |
| 818 | big picture of the topology of the history, by omitting commits |
| 819 | that are not referenced by tags. Commits are marked as !TREESAME |
| 820 | (in other words, kept after history simplification rules described |
| 821 | above) if (1) they are referenced by tags, or (2) they change the |
| 822 | contents of the paths given on the command line. All other |
| 823 | commits are marked as TREESAME (subject to be simplified away). |
| 824 | |
| 825 | ifndef::git-shortlog[] |
| 826 | ifdef::git-rev-list[] |
| 827 | Bisection Helpers |
| 828 | ~~~~~~~~~~~~~~~~~ |
| 829 | |
| 830 | `--bisect`:: |
| 831 | Limit output to the one commit object which is roughly halfway between |
| 832 | included and excluded commits. Note that the bad bisection ref |
| 833 | `refs/bisect/bad` is added to the included commits (if it |
| 834 | exists) and the good bisection refs `refs/bisect/good-*` are |
| 835 | added to the excluded commits (if they exist). Thus, supposing there |
| 836 | are no refs in `refs/bisect/`, if |
| 837 | + |
| 838 | ----------------------------------------------------------------------- |
| 839 | $ git rev-list --bisect foo ^bar ^baz |
| 840 | ----------------------------------------------------------------------- |
| 841 | + |
| 842 | outputs 'midpoint', the output of the two commands |
| 843 | + |
| 844 | ----------------------------------------------------------------------- |
| 845 | $ git rev-list foo ^midpoint |
| 846 | $ git rev-list midpoint ^bar ^baz |
| 847 | ----------------------------------------------------------------------- |
| 848 | + |
| 849 | would be of roughly the same length. Finding the change which |
| 850 | introduces a regression is thus reduced to a binary search: repeatedly |
| 851 | generate and test new 'midpoint's until the commit chain is of length |
| 852 | one. |
| 853 | |
| 854 | `--bisect-vars`:: |
| 855 | This calculates the same as `--bisect`, except that refs in |
| 856 | `refs/bisect/` are not used, and except that this outputs |
| 857 | text ready to be eval'ed by the shell. These lines will assign the |
| 858 | name of the midpoint revision to the variable `bisect_rev`, and the |
| 859 | expected number of commits to be tested after `bisect_rev` is tested |
| 860 | to `bisect_nr`, the expected number of commits to be tested if |
| 861 | `bisect_rev` turns out to be good to `bisect_good`, the expected |
| 862 | number of commits to be tested if `bisect_rev` turns out to be bad to |
| 863 | `bisect_bad`, and the number of commits we are bisecting right now to |
| 864 | `bisect_all`. |
| 865 | |
| 866 | `--bisect-all`:: |
| 867 | This outputs all the commit objects between the included and excluded |
| 868 | commits, ordered by their distance to the included and excluded |
| 869 | commits. Refs in `refs/bisect/` are not used. The farthest |
| 870 | from them is displayed first. (This is the only one displayed by |
| 871 | `--bisect`.) |
| 872 | + |
| 873 | This is useful because it makes it easy to choose a good commit to |
| 874 | test when you want to avoid to test some of them for some reason (they |
| 875 | may not compile for example). |
| 876 | + |
| 877 | This option can be used along with `--bisect-vars`, in this case, |
| 878 | after all the sorted commit objects, there will be the same text as if |
| 879 | `--bisect-vars` had been used alone. |
| 880 | endif::git-rev-list[] |
| 881 | endif::git-shortlog[] |
| 882 | |
| 883 | ifndef::git-shortlog[] |
| 884 | Commit Ordering |
| 885 | ~~~~~~~~~~~~~~~ |
| 886 | |
| 887 | By default, the commits are shown in reverse chronological order. |
| 888 | |
| 889 | `--date-order`:: |
| 890 | Show no parents before all of its children are shown, but |
| 891 | otherwise show commits in the commit timestamp order. |
| 892 | |
| 893 | `--author-date-order`:: |
| 894 | Show no parents before all of its children are shown, but |
| 895 | otherwise show commits in the author timestamp order. |
| 896 | |
| 897 | `--topo-order`:: |
| 898 | Show no parents before all of its children are shown, and |
| 899 | avoid showing commits on multiple lines of history |
| 900 | intermixed. |
| 901 | + |
| 902 | For example, in a commit history like this: |
| 903 | + |
| 904 | ---------------------------------------------------------------- |
| 905 | |
| 906 | ---1----2----4----7 |
| 907 | \ \ |
| 908 | 3----5----6----8--- |
| 909 | |
| 910 | ---------------------------------------------------------------- |
| 911 | + |
| 912 | where the numbers denote the order of commit timestamps, `git |
| 913 | rev-list` and friends with `--date-order` show the commits in the |
| 914 | timestamp order: 8 7 6 5 4 3 2 1. |
| 915 | + |
| 916 | With `--topo-order`, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5 |
| 917 | 3 1); some older commits are shown before newer ones in order to |
| 918 | avoid showing the commits from two parallel development track mixed |
| 919 | together. |
| 920 | |
| 921 | `--reverse`:: |
| 922 | Output the commits chosen to be shown (see 'Commit Limiting' |
| 923 | section above) in reverse order. Cannot be combined with |
| 924 | `--walk-reflogs`. |
| 925 | endif::git-shortlog[] |
| 926 | |
| 927 | ifndef::git-shortlog[] |
| 928 | Object Traversal |
| 929 | ~~~~~~~~~~~~~~~~ |
| 930 | |
| 931 | These options are mostly targeted for packing of Git repositories. |
| 932 | |
| 933 | ifdef::git-rev-list[] |
| 934 | `--objects`:: |
| 935 | Print the object IDs of any object referenced by the listed |
| 936 | commits. `--objects foo ^bar` thus means "send me |
| 937 | all object IDs which I need to download if I have the commit |
| 938 | object `bar` but not `foo`". See also `--object-names` below. |
| 939 | |
| 940 | `--in-commit-order`:: |
| 941 | Print tree and blob ids in order of the commits. The tree |
| 942 | and blob ids are printed after they are first referenced |
| 943 | by a commit. |
| 944 | |
| 945 | `--objects-edge`:: |
| 946 | Similar to `--objects`, but also print the IDs of excluded |
| 947 | commits prefixed with a "`-`" character. This is used by |
| 948 | linkgit:git-pack-objects[1] to build a ``thin'' pack, which records |
| 949 | objects in deltified form based on objects contained in these |
| 950 | excluded commits to reduce network traffic. |
| 951 | |
| 952 | `--objects-edge-aggressive`:: |
| 953 | Similar to `--objects-edge`, but it tries harder to find excluded |
| 954 | commits at the cost of increased time. This is used instead of |
| 955 | `--objects-edge` to build ``thin'' packs for shallow repositories. |
| 956 | |
| 957 | `--indexed-objects`:: |
| 958 | Pretend as if all trees and blobs used by the index are listed |
| 959 | on the command line. Note that you probably want to use |
| 960 | `--objects`, too. |
| 961 | |
| 962 | `--unpacked`:: |
| 963 | Only useful with `--objects`; print the object IDs that are not |
| 964 | in packs. |
| 965 | |
| 966 | `--object-names`:: |
| 967 | Only useful with `--objects`; print the names of the object IDs |
| 968 | that are found. This is the default behavior. Note that the |
| 969 | "name" of each object is ambiguous, and mostly intended as a |
| 970 | hint for packing objects. In particular: no distinction is made between |
| 971 | the names of tags, trees, and blobs; path names may be modified |
| 972 | to remove newlines; and if an object would appear multiple times |
| 973 | with different names, only one name is shown. |
| 974 | |
| 975 | `--no-object-names`:: |
| 976 | Only useful with `--objects`; does not print the names of the object |
| 977 | IDs that are found. This inverts `--object-names`. This flag allows |
| 978 | the output to be more easily parsed by commands such as |
| 979 | linkgit:git-cat-file[1]. |
| 980 | |
| 981 | `--filter=<filter-spec>`:: |
| 982 | Only useful with one of the `--objects*`; omits objects (usually |
| 983 | blobs) from the list of printed objects. The _<filter-spec>_ |
| 984 | may be one of the following: |
| 985 | + |
| 986 | The form `--filter=blob:none` omits all blobs. |
| 987 | + |
| 988 | The form `--filter=blob:limit=<n>[kmg]` omits blobs of size at least _<n>_ |
| 989 | bytes or units. _<n>_ may be zero. The suffixes `k`, `m`, and `g` can be used |
| 990 | to name units in KiB, MiB, or GiB. For example, `blob:limit=1k` |
| 991 | is the same as 'blob:limit=1024'. |
| 992 | + |
| 993 | The form `--filter=object:type=(tag|commit|tree|blob)` omits all objects |
| 994 | which are not of the requested type. Note that explicitly provided objects |
| 995 | ignore filters and are always printed unless `--filter-provided-objects` is |
| 996 | also specified. |
| 997 | + |
| 998 | The form `--filter=sparse:oid=<blob-ish>` uses a sparse-checkout |
| 999 | specification contained in the blob (or blob-expression) _<blob-ish>_ |
| 1000 | to omit blobs that would not be required for a sparse checkout on |
| 1001 | the requested refs. |
| 1002 | + |
| 1003 | The form `--filter=tree:<depth>` omits all blobs and trees whose depth |
| 1004 | from the root tree is >= _<depth>_ (minimum depth if an object is located |
| 1005 | at multiple depths in the commits traversed). _<depth>_=0 will not include |
| 1006 | any trees or blobs unless included explicitly in the command-line (or |
| 1007 | standard input when `--stdin` is used). _<depth>_=1 will include only the |
| 1008 | tree and blobs which are referenced directly by a commit reachable from |
| 1009 | _<commit>_ or an explicitly-given object. _<depth>_=2 is like <depth>=1 |
| 1010 | while also including trees and blobs one more level removed from an |
| 1011 | explicitly-given commit or tree. |
| 1012 | + |
| 1013 | Note that the form `--filter=sparse:path=<path>` that wants to read |
| 1014 | from an arbitrary path on the filesystem has been dropped for security |
| 1015 | reasons. |
| 1016 | + |
| 1017 | Multiple `--filter=` flags can be specified to combine filters. Only |
| 1018 | objects which are accepted by every filter are included. |
| 1019 | + |
| 1020 | The form `--filter=combine:<filter1>+<filter2>+...<filterN>` can also be |
| 1021 | used to combined several filters, but this is harder than just repeating |
| 1022 | the `--filter` flag and is usually not necessary. Filters are joined by |
| 1023 | '{plus}' and individual filters are %-encoded (i.e. URL-encoded). |
| 1024 | Besides the '{plus}' and '%' characters, the following characters are |
| 1025 | reserved and also must be encoded: `~!@#$^&*()[]{}\;",<>?`+'`+ |
| 1026 | as well as all characters with ASCII code <= `0x20`, which includes |
| 1027 | space and newline. |
| 1028 | + |
| 1029 | Other arbitrary characters can also be encoded. For instance, |
| 1030 | `combine:tree:3+blob:none` and `combine:tree%3A3+blob%3Anone` are |
| 1031 | equivalent. |
| 1032 | |
| 1033 | `--no-filter`:: |
| 1034 | Turn off any previous `--filter=` argument. |
| 1035 | |
| 1036 | `--filter-provided-objects`:: |
| 1037 | Filter the list of explicitly provided objects, which would otherwise |
| 1038 | always be printed even if they did not match any of the filters. Only |
| 1039 | useful with `--filter=`. |
| 1040 | |
| 1041 | `--filter-print-omitted`:: |
| 1042 | Only useful with `--filter=`; prints a list of the objects omitted |
| 1043 | by the filter. Object IDs are prefixed with a ``~'' character. |
| 1044 | |
| 1045 | `--missing=<missing-action>`:: |
| 1046 | A debug option to help with future "partial clone" development. |
| 1047 | This option specifies how missing objects are handled. |
| 1048 | + |
| 1049 | The form `--missing=error` requests that rev-list stop with an error if |
| 1050 | a missing object is encountered. This is the default action. |
| 1051 | + |
| 1052 | The form `--missing=allow-any` will allow object traversal to continue |
| 1053 | if a missing object is encountered. Missing objects will silently be |
| 1054 | omitted from the results. |
| 1055 | + |
| 1056 | The form `--missing=allow-promisor` is like `allow-any`, but will only |
| 1057 | allow object traversal to continue for EXPECTED promisor missing objects. |
| 1058 | Unexpected missing objects will raise an error. |
| 1059 | + |
| 1060 | The form `--missing=print` is like `allow-any`, but will also print a |
| 1061 | list of the missing objects. Object IDs are prefixed with a ``?'' character. |
| 1062 | + |
| 1063 | The form `--missing=print-info` is like `print`, but will also print additional |
| 1064 | information about the missing object inferred from its containing object. The |
| 1065 | information is all printed on the same line with the missing object ID in the |
| 1066 | form: `?<oid> [<token>=<value>]...`. The `<token>=<value>` pairs containing |
| 1067 | additional information are separated from each other by a _SP_. The value is |
| 1068 | encoded in a token specific fashion, but _SP_ or _LF_ contained in value are always |
| 1069 | expected to be represented in such a way that the resulting encoded value does |
| 1070 | not have either of these two problematic bytes. Each `<token>=<value>` may be |
| 1071 | one of the following: |
| 1072 | + |
| 1073 | -- |
| 1074 | * The `path=<path>` shows the path of the missing object inferred from a |
| 1075 | containing object. A path containing _SP_ or special characters is enclosed in |
| 1076 | double-quotes in the C style as needed. |
| 1077 | + |
| 1078 | * The `type=<type>` shows the type of the missing object inferred from a |
| 1079 | containing object. |
| 1080 | -- |
| 1081 | + |
| 1082 | If some tips passed to the traversal are missing, they will be |
| 1083 | considered as missing too, and the traversal will ignore them. In case |
| 1084 | we cannot get their Object ID though, an error will be raised. |
| 1085 | |
| 1086 | `--exclude-promisor-objects`:: |
| 1087 | (For internal use only.) Prefilter object traversal at |
| 1088 | promisor boundary. This is used with partial clone. This is |
| 1089 | stronger than `--missing=allow-promisor` because it limits the |
| 1090 | traversal, rather than just silencing errors about missing |
| 1091 | objects. |
| 1092 | endif::git-rev-list[] |
| 1093 | |
| 1094 | `--no-walk[=(sorted|unsorted)]`:: |
| 1095 | Only show the given commits, but do not traverse their ancestors. |
| 1096 | This has no effect if a range is specified. If the argument |
| 1097 | `unsorted` is given, the commits are shown in the order they were |
| 1098 | given on the command line. Otherwise (if `sorted` or no argument |
| 1099 | was given), the commits are shown in reverse chronological order |
| 1100 | by commit time. |
| 1101 | Cannot be combined with `--graph`. |
| 1102 | |
| 1103 | `--do-walk`:: |
| 1104 | Overrides a previous `--no-walk`. |
| 1105 | endif::git-shortlog[] |
| 1106 | |
| 1107 | ifndef::git-shortlog,git-replay[] |
| 1108 | Commit Formatting |
| 1109 | ~~~~~~~~~~~~~~~~~ |
| 1110 | |
| 1111 | ifdef::git-rev-list[] |
| 1112 | Using these options, linkgit:git-rev-list[1] will act similar to the |
| 1113 | more specialized family of commit log tools: |
| 1114 | ifndef::with-breaking-changes[] |
| 1115 | linkgit:git-log[1], linkgit:git-show[1], and linkgit:git-whatchanged[1]. |
| 1116 | endif::with-breaking-changes[] |
| 1117 | ifdef::with-breaking-changes[] |
| 1118 | linkgit:git-log[1] and linkgit:git-show[1]. |
| 1119 | endif::with-breaking-changes[] |
| 1120 | endif::git-rev-list[] |
| 1121 | |
| 1122 | include::pretty-options.adoc[] |
| 1123 | |
| 1124 | `--relative-date`:: |
| 1125 | Synonym for `--date=relative`. |
| 1126 | |
| 1127 | `--date=<format>`:: |
| 1128 | Only takes effect for dates shown in human-readable format, such |
| 1129 | as when using `--pretty`. `log.date` config variable sets a default |
| 1130 | value for the log command's `--date` option. By default, dates |
| 1131 | are shown in the original time zone (either committer's or |
| 1132 | author's). If `-local` is appended to the format (e.g., |
| 1133 | `iso-local`), the user's local time zone is used instead. |
| 1134 | + |
| 1135 | -- |
| 1136 | `--date=relative` shows dates relative to the current time, |
| 1137 | e.g. ``2 hours ago''. The `-local` option has no effect for |
| 1138 | `--date=relative`. |
| 1139 | |
| 1140 | `--date=local` is an alias for `--date=default-local`. |
| 1141 | |
| 1142 | `--date=iso` (or `--date=iso8601`) shows timestamps in a ISO 8601-like format. |
| 1143 | The differences to the strict ISO 8601 format are: |
| 1144 | |
| 1145 | - a space instead of the `T` date/time delimiter |
| 1146 | - a space between time and time zone |
| 1147 | - no colon between hours and minutes of the time zone |
| 1148 | |
| 1149 | `--date=iso-strict` (or `--date=iso8601-strict`) shows timestamps in strict |
| 1150 | ISO 8601 format. |
| 1151 | |
| 1152 | `--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822 |
| 1153 | format, often found in email messages. |
| 1154 | |
| 1155 | `--date=short` shows only the date, but not the time, in `YYYY-MM-DD` format. |
| 1156 | |
| 1157 | `--date=raw` shows the date as seconds since the epoch (1970-01-01 |
| 1158 | 00:00:00 UTC), followed by a space, and then the timezone as an offset |
| 1159 | from UTC (a `+` or `-` with four digits; the first two are hours, and |
| 1160 | the second two are minutes). I.e., as if the timestamp were formatted |
| 1161 | with `strftime("%s %z")`). |
| 1162 | Note that the `-local` option does not affect the seconds-since-epoch |
| 1163 | value (which is always measured in UTC), but does switch the accompanying |
| 1164 | timezone value. |
| 1165 | |
| 1166 | `--date=human` shows the timezone if the timezone does not match the |
| 1167 | current time-zone, and doesn't print the whole date if that matches |
| 1168 | (ie skip printing year for dates that are "this year", but also skip |
| 1169 | the whole date itself if it's in the last few days and we can just say |
| 1170 | what weekday it was). For older dates the hour and minute is also |
| 1171 | omitted. |
| 1172 | |
| 1173 | `--date=unix` shows the date as a Unix epoch timestamp (seconds since |
| 1174 | 1970). As with `--raw`, this is always in UTC and therefore `-local` |
| 1175 | has no effect. |
| 1176 | |
| 1177 | `--date=format:<format>` feeds the _<format>_ to your system `strftime`, |
| 1178 | except for `%s`, `%z`, and `%Z`, which are handled internally. |
| 1179 | Use `--date=format:%c` to show the date in your system locale's |
| 1180 | preferred format. See the `strftime`(3) manual for a complete list of |
| 1181 | format placeholders. When using `-local`, the correct syntax is |
| 1182 | `--date=format-local:<format>`. |
| 1183 | |
| 1184 | `--date=default` is the default format, and is based on ctime(3) |
| 1185 | output. It shows a single line with three-letter day of the week, |
| 1186 | three-letter month, day-of-month, hour-minute-seconds in "HH:MM:SS" |
| 1187 | format, followed by 4-digit year, plus timezone information, unless |
| 1188 | the local time zone is used, e.g. `Thu Jan 1 00:00:00 1970 +0000`. |
| 1189 | -- |
| 1190 | |
| 1191 | ifdef::git-rev-list[] |
| 1192 | `--header`:: |
| 1193 | Print the contents of the commit in raw-format; each record is |
| 1194 | separated with a NUL character. |
| 1195 | |
| 1196 | `--no-commit-header`:: |
| 1197 | Suppress the header line containing "commit" and the object ID printed before |
| 1198 | the specified format. This has no effect on the built-in formats; only custom |
| 1199 | formats are affected. |
| 1200 | |
| 1201 | `--commit-header`:: |
| 1202 | Overrides a previous `--no-commit-header`. |
| 1203 | endif::git-rev-list[] |
| 1204 | |
| 1205 | `--parents`:: |
| 1206 | Print also the parents of the commit (in the form "commit parent..."). |
| 1207 | Also enables parent rewriting, see 'History Simplification' above. |
| 1208 | |
| 1209 | `--children`:: |
| 1210 | Print also the children of the commit (in the form "commit child..."). |
| 1211 | Also enables parent rewriting, see 'History Simplification' above. |
| 1212 | |
| 1213 | ifdef::git-rev-list[] |
| 1214 | `--timestamp`:: |
| 1215 | Print the raw commit timestamp. |
| 1216 | endif::git-rev-list[] |
| 1217 | |
| 1218 | `--left-right`:: |
| 1219 | Mark which side of a symmetric difference a commit is reachable from. |
| 1220 | Commits from the left side are prefixed with `<` and those from |
| 1221 | the right with `>`. If combined with `--boundary`, those |
| 1222 | commits are prefixed with `-`. |
| 1223 | + |
| 1224 | For example, if you have this topology: |
| 1225 | + |
| 1226 | ----------------------------------------------------------------------- |
| 1227 | y---b---b branch B |
| 1228 | / \ / |
| 1229 | / . |
| 1230 | / / \ |
| 1231 | o---x---a---a branch A |
| 1232 | ----------------------------------------------------------------------- |
| 1233 | + |
| 1234 | you would get an output like this: |
| 1235 | + |
| 1236 | ----------------------------------------------------------------------- |
| 1237 | $ git rev-list --left-right --boundary --pretty=oneline A...B |
| 1238 | |
| 1239 | >bbbbbbb... 3rd on b |
| 1240 | >bbbbbbb... 2nd on b |
| 1241 | <aaaaaaa... 3rd on a |
| 1242 | <aaaaaaa... 2nd on a |
| 1243 | -yyyyyyy... 1st on b |
| 1244 | -xxxxxxx... 1st on a |
| 1245 | ----------------------------------------------------------------------- |
| 1246 | |
| 1247 | `--graph`:: |
| 1248 | Draw a text-based graphical representation of the commit history |
| 1249 | on the left hand side of the output. This may cause extra lines |
| 1250 | to be printed in between commits, in order for the graph history |
| 1251 | to be drawn properly. |
| 1252 | Cannot be combined with `--no-walk`. |
| 1253 | + |
| 1254 | This enables parent rewriting, see 'History Simplification' above. |
| 1255 | + |
| 1256 | This implies the `--topo-order` option by default, but the |
| 1257 | `--date-order` option may also be specified. |
| 1258 | |
| 1259 | `--show-linear-break[=<barrier>]`:: |
| 1260 | When `--graph` is not used, all history branches are flattened |
| 1261 | which can make it hard to see that the two consecutive commits |
| 1262 | do not belong to a linear branch. This option puts a barrier |
| 1263 | in between them in that case. If _<barrier>_ is specified, it |
| 1264 | is the string that will be shown instead of the default one. |
| 1265 | |
| 1266 | `--graph-lane-limit=<n>`:: |
| 1267 | When `--graph` is used, limit the number of graph lanes to be shown. |
| 1268 | Lanes over the limit are replaced with a truncation mark '~'. |
| 1269 | By default it is set to 0 (no limit), zero and negative values |
| 1270 | are ignored and treated as no limit. |
| 1271 | |
| 1272 | ifdef::git-rev-list[] |
| 1273 | `--count`:: |
| 1274 | Print a number stating how many commits would have been |
| 1275 | listed, and suppress all other output. When used together |
| 1276 | with `--left-right`, instead print the counts for left and |
| 1277 | right commits, separated by a tab. When used together with |
| 1278 | `--cherry-mark`, omit patch equivalent commits from these |
| 1279 | counts and print the count for equivalent commits separated |
| 1280 | by a tab. |
| 1281 | endif::git-rev-list[] |
| 1282 | endif::git-shortlog,git-replay[] |