1Commit Limiting 2~~~~~~~~~~~~~~~ 3 4Besides specifying a range of commits that should be listed using the 5special notations explained in the description, additional commit 6limiting may be applied. Note that they are applied before commit 7ordering and formatting options, such as '--reverse'. 8 9-- 10 11-n 'number':: 12--max-count=<number>:: 13 14 Limit the number of commits to output. 15 16--skip=<number>:: 17 18 Skip 'number' commits before starting to show the commit output. 19 20--since=<date>:: 21--after=<date>:: 22 23 Show commits more recent than a specific date. 24 25--until=<date>:: 26--before=<date>:: 27 28 Show commits older than a specific date. 29 30ifdef::git-rev-list[] 31--max-age=<timestamp>:: 32--min-age=<timestamp>:: 33 34 Limit the commits output to specified time range. 35endif::git-rev-list[] 36 37--author=<pattern>:: 38--committer=<pattern>:: 39 40 Limit the commits output to ones with author/committer 41 header lines that match the specified pattern (regular expression). 42 43--grep=<pattern>:: 44 45 Limit the commits output to ones with log message that 46 matches the specified pattern (regular expression). 47 48--all-match:: 49 Limit the commits output to ones that match all given --grep, 50 --author and --committer instead of ones that match at least one. 51 52-i:: 53--regexp-ignore-case:: 54 55 Match the regexp limiting patterns without regard to letters case. 56 57-E:: 58--extended-regexp:: 59 60 Consider the limiting patterns to be extended regular expressions 61 instead of the default basic regular expressions. 62 63-F:: 64--fixed-strings:: 65 66 Consider the limiting patterns to be fixed strings (don't interpret 67 pattern as a regular expression). 68 69--remove-empty:: 70 71 Stop when a given path disappears from the tree. 72 73--merges:: 74 75 Print only merge commits. 76 77--no-merges:: 78 79 Do not print commits with more than one parent. 80 81--first-parent:: 82 Follow only the first parent commit upon seeing a merge 83 commit. This option can give a better overview when 84 viewing the evolution of a particular topic branch, 85 because merges into a topic branch tend to be only about 86 adjusting to updated upstream from time to time, and 87 this option allows you to ignore the individual commits 88 brought in to your history by such a merge. 89 90--not:: 91 92 Reverses the meaning of the '{caret}' prefix (or lack thereof) 93 for all following revision specifiers, up to the next '--not'. 94 95--all:: 96 97 Pretend as if all the refs in `refs/` are listed on the 98 command line as '<commit>'. 99 100--branches[=<pattern>]:: 101 102 Pretend as if all the refs in `refs/heads` are listed 103 on the command line as '<commit>'. If '<pattern>' is given, limit 104 branches to ones matching given shell glob. If pattern lacks '?', 105 '*', or '[', '/*' at the end is implied. 106 107--tags[=<pattern>]:: 108 109 Pretend as if all the refs in `refs/tags` are listed 110 on the command line as '<commit>'. If '<pattern>' is given, limit 111 tags to ones matching given shell glob. If pattern lacks '?', '*', 112 or '[', '/*' at the end is implied. 113 114--remotes[=<pattern>]:: 115 116 Pretend as if all the refs in `refs/remotes` are listed 117 on the command line as '<commit>'. If '<pattern>' is given, limit 118 remote-tracking branches to ones matching given shell glob. 119 If pattern lacks '?', '*', or '[', '/*' at the end is implied. 120 121--glob=<glob-pattern>:: 122 Pretend as if all the refs matching shell glob '<glob-pattern>' 123 are listed on the command line as '<commit>'. Leading 'refs/', 124 is automatically prepended if missing. If pattern lacks '?', '*', 125 or '[', '/*' at the end is implied. 126 127 128ifndef::git-rev-list[] 129--bisect:: 130 131 Pretend as if the bad bisection ref `refs/bisect/bad` 132 was listed and as if it was followed by `--not` and the good 133 bisection refs `refs/bisect/good-*` on the command 134 line. 135endif::git-rev-list[] 136 137--stdin:: 138 139 In addition to the '<commit>' listed on the command 140 line, read them from the standard input. If a '--' separator is 141 seen, stop reading commits and start reading paths to limit the 142 result. 143 144ifdef::git-rev-list[] 145--quiet:: 146 147 Don't print anything to standard output. This form 148 is primarily meant to allow the caller to 149 test the exit status to see if a range of objects is fully 150 connected (or not). It is faster than redirecting stdout 151 to /dev/null as the output does not have to be formatted. 152endif::git-rev-list[] 153 154--cherry-mark:: 155 156 Like `--cherry-pick` (see below) but mark equivalent commits 157 with `=` rather than omitting them, and inequivalent ones with `+`. 158 159--cherry-pick:: 160 161 Omit any commit that introduces the same change as 162 another commit on the "other side" when the set of 163 commits are limited with symmetric difference. 164+ 165For example, if you have two branches, `A` and `B`, a usual way 166to list all commits on only one side of them is with 167`--left-right`, like the example above in the description of 168that option. It however shows the commits that were cherry-picked 169from the other branch (for example, "3rd on b" may be cherry-picked 170from branch A). With this option, such pairs of commits are 171excluded from the output. 172 173--left-only:: 174--right-only:: 175 176 List only commits on the respective side of a symmetric range, 177 i.e. only those which would be marked `<` resp. `>` by 178 `--left-right`. 179+ 180For example, `--cherry-pick --right-only A...B` omits those 181commits from `B` which are in `A` or are patch-equivalent to a commit in 182`A`. In other words, this lists the `{plus}` commits from `git cherry A B`. 183More precisely, `--cherry-pick --right-only --no-merges` gives the exact 184list. 185 186--cherry:: 187 188 A synonym for `--right-only --cherry-mark --no-merges`; useful to 189 limit the output to the commits on our side and mark those that 190 have been applied to the other side of a forked history with 191 `git log --cherry upstream...mybranch`, similar to 192 `git cherry upstream mybranch`. 193 194-g:: 195--walk-reflogs:: 196 197 Instead of walking the commit ancestry chain, walk 198 reflog entries from the most recent one to older ones. 199 When this option is used you cannot specify commits to 200 exclude (that is, '{caret}commit', 'commit1..commit2', 201 nor 'commit1\...commit2' notations cannot be used). 202+ 203With '\--pretty' format other than oneline (for obvious reasons), 204this causes the output to have two extra lines of information 205taken from the reflog. By default, 'commit@\{Nth}' notation is 206used in the output. When the starting commit is specified as 207'commit@\{now}', output also uses 'commit@\{timestamp}' notation 208instead. Under '\--pretty=oneline', the commit message is 209prefixed with this information on the same line. 210This option cannot be combined with '\--reverse'. 211See also linkgit:git-reflog[1]. 212 213--merge:: 214 215 After a failed merge, show refs that touch files having a 216 conflict and don't exist on all heads to merge. 217 218--boundary:: 219 220 Output uninteresting commits at the boundary, which are usually 221 not shown. 222 223-- 224 225History Simplification 226~~~~~~~~~~~~~~~~~~~~~~ 227 228Sometimes you are only interested in parts of the history, for example the 229commits modifying a particular <path>. But there are two parts of 230'History Simplification', one part is selecting the commits and the other 231is how to do it, as there are various strategies to simplify the history. 232 233The following options select the commits to be shown: 234 235<paths>:: 236 237 Commits modifying the given <paths> are selected. 238 239--simplify-by-decoration:: 240 241 Commits that are referred by some branch or tag are selected. 242 243Note that extra commits can be shown to give a meaningful history. 244 245The following options affect the way the simplification is performed: 246 247Default mode:: 248 249 Simplifies the history to the simplest history explaining the 250 final state of the tree. Simplest because it prunes some side 251 branches if the end result is the same (i.e. merging branches 252 with the same content) 253 254--full-history:: 255 256 As the default mode but does not prune some history. 257 258--dense:: 259 260 Only the selected commits are shown, plus some to have a 261 meaningful history. 262 263--sparse:: 264 265 All commits in the simplified history are shown. 266 267--simplify-merges:: 268 269 Additional option to '--full-history' to remove some needless 270 merges from the resulting history, as there are no selected 271 commits contributing to this merge. 272 273--ancestry-path:: 274 275 When given a range of commits to display (e.g. 'commit1..commit2' 276 or 'commit2 {caret}commit1'), only display commits that exist 277 directly on the ancestry chain between the 'commit1' and 278 'commit2', i.e. commits that are both descendants of 'commit1', 279 and ancestors of 'commit2'. 280 281A more detailed explanation follows. 282 283Suppose you specified `foo` as the <paths>. We shall call commits 284that modify `foo` !TREESAME, and the rest TREESAME. (In a diff 285filtered for `foo`, they look different and equal, respectively.) 286 287In the following, we will always refer to the same example history to 288illustrate the differences between simplification settings. We assume 289that you are filtering for a file `foo` in this commit graph: 290----------------------------------------------------------------------- 291 .-A---M---N---O---P 292 / / / / / 293 I B C D E 294 \ / / / / 295 `-------------' 296----------------------------------------------------------------------- 297The horizontal line of history A--P is taken to be the first parent of 298each merge. The commits are: 299 300* `I` is the initial commit, in which `foo` exists with contents 301 "asdf", and a file `quux` exists with contents "quux". Initial 302 commits are compared to an empty tree, so `I` is !TREESAME. 303 304* In `A`, `foo` contains just "foo". 305 306* `B` contains the same change as `A`. Its merge `M` is trivial and 307 hence TREESAME to all parents. 308 309* `C` does not change `foo`, but its merge `N` changes it to "foobar", 310 so it is not TREESAME to any parent. 311 312* `D` sets `foo` to "baz". Its merge `O` combines the strings from 313 `N` and `D` to "foobarbaz"; i.e., it is not TREESAME to any parent. 314 315* `E` changes `quux` to "xyzzy", and its merge `P` combines the 316 strings to "quux xyzzy". Despite appearing interesting, `P` is 317 TREESAME to all parents. 318 319'rev-list' walks backwards through history, including or excluding 320commits based on whether '\--full-history' and/or parent rewriting 321(via '\--parents' or '\--children') are used. The following settings 322are available. 323 324Default mode:: 325 326 Commits are included if they are not TREESAME to any parent 327 (though this can be changed, see '\--sparse' below). If the 328 commit was a merge, and it was TREESAME to one parent, follow 329 only that parent. (Even if there are several TREESAME 330 parents, follow only one of them.) Otherwise, follow all 331 parents. 332+ 333This results in: 334+ 335----------------------------------------------------------------------- 336 .-A---N---O 337 / / / 338 I---------D 339----------------------------------------------------------------------- 340+ 341Note how the rule to only follow the TREESAME parent, if one is 342available, removed `B` from consideration entirely. `C` was 343considered via `N`, but is TREESAME. Root commits are compared to an 344empty tree, so `I` is !TREESAME. 345+ 346Parent/child relations are only visible with --parents, but that does 347not affect the commits selected in default mode, so we have shown the 348parent lines. 349 350--full-history without parent rewriting:: 351 352 This mode differs from the default in one point: always follow 353 all parents of a merge, even if it is TREESAME to one of them. 354 Even if more than one side of the merge has commits that are 355 included, this does not imply that the merge itself is! In 356 the example, we get 357+ 358----------------------------------------------------------------------- 359 I A B N D O 360----------------------------------------------------------------------- 361+ 362`P` and `M` were excluded because they are TREESAME to a parent. `E`, 363`C` and `B` were all walked, but only `B` was !TREESAME, so the others 364do not appear. 365+ 366Note that without parent rewriting, it is not really possible to talk 367about the parent/child relationships between the commits, so we show 368them disconnected. 369 370--full-history with parent rewriting:: 371 372 Ordinary commits are only included if they are !TREESAME 373 (though this can be changed, see '\--sparse' below). 374+ 375Merges are always included. However, their parent list is rewritten: 376Along each parent, prune away commits that are not included 377themselves. This results in 378+ 379----------------------------------------------------------------------- 380 .-A---M---N---O---P 381 / / / / / 382 I B / D / 383 \ / / / / 384 `-------------' 385----------------------------------------------------------------------- 386+ 387Compare to '\--full-history' without rewriting above. Note that `E` 388was pruned away because it is TREESAME, but the parent list of P was 389rewritten to contain `E`'s parent `I`. The same happened for `C` and 390`N`. Note also that `P` was included despite being TREESAME. 391 392In addition to the above settings, you can change whether TREESAME 393affects inclusion: 394 395--dense:: 396 397 Commits that are walked are included if they are not TREESAME 398 to any parent. 399 400--sparse:: 401 402 All commits that are walked are included. 403+ 404Note that without '\--full-history', this still simplifies merges: if 405one of the parents is TREESAME, we follow only that one, so the other 406sides of the merge are never walked. 407 408--simplify-merges:: 409 410 First, build a history graph in the same way that 411 '\--full-history' with parent rewriting does (see above). 412+ 413Then simplify each commit `C` to its replacement `C'` in the final 414history according to the following rules: 415+ 416-- 417* Set `C'` to `C`. 418+ 419* Replace each parent `P` of `C'` with its simplification `P'`. In 420 the process, drop parents that are ancestors of other parents, and 421 remove duplicates. 422+ 423* If after this parent rewriting, `C'` is a root or merge commit (has 424 zero or >1 parents), a boundary commit, or !TREESAME, it remains. 425 Otherwise, it is replaced with its only parent. 426-- 427+ 428The effect of this is best shown by way of comparing to 429'\--full-history' with parent rewriting. The example turns into: 430+ 431----------------------------------------------------------------------- 432 .-A---M---N---O 433 / / / 434 I B D 435 \ / / 436 `---------' 437----------------------------------------------------------------------- 438+ 439Note the major differences in `N` and `P` over '\--full-history': 440+ 441-- 442* `N`'s parent list had `I` removed, because it is an ancestor of the 443 other parent `M`. Still, `N` remained because it is !TREESAME. 444+ 445* `P`'s parent list similarly had `I` removed. `P` was then 446 removed completely, because it had one parent and is TREESAME. 447-- 448 449Finally, there is a fifth simplification mode available: 450 451--ancestry-path:: 452 453 Limit the displayed commits to those directly on the ancestry 454 chain between the "from" and "to" commits in the given commit 455 range. I.e. only display commits that are ancestor of the "to" 456 commit, and descendants of the "from" commit. 457+ 458As an example use case, consider the following commit history: 459+ 460----------------------------------------------------------------------- 461 D---E-------F 462 / \ \ 463 B---C---G---H---I---J 464 / \ 465 A-------K---------------L--M 466----------------------------------------------------------------------- 467+ 468A regular 'D..M' computes the set of commits that are ancestors of `M`, 469but excludes the ones that are ancestors of `D`. This is useful to see 470what happened to the history leading to `M` since `D`, in the sense 471that "what does `M` have that did not exist in `D`". The result in this 472example would be all the commits, except `A` and `B` (and `D` itself, 473of course). 474+ 475When we want to find out what commits in `M` are contaminated with the 476bug introduced by `D` and need fixing, however, we might want to view 477only the subset of 'D..M' that are actually descendants of `D`, i.e. 478excluding `C` and `K`. This is exactly what the '\--ancestry-path' 479option does. Applied to the 'D..M' range, it results in: 480+ 481----------------------------------------------------------------------- 482 E-------F 483 \ \ 484 G---H---I---J 485 \ 486 L--M 487----------------------------------------------------------------------- 488 489The '\--simplify-by-decoration' option allows you to view only the 490big picture of the topology of the history, by omitting commits 491that are not referenced by tags. Commits are marked as !TREESAME 492(in other words, kept after history simplification rules described 493above) if (1) they are referenced by tags, or (2) they change the 494contents of the paths given on the command line. All other 495commits are marked as TREESAME (subject to be simplified away). 496 497ifdef::git-rev-list[] 498Bisection Helpers 499~~~~~~~~~~~~~~~~~ 500 501--bisect:: 502 503Limit output to the one commit object which is roughly halfway between 504included and excluded commits. Note that the bad bisection ref 505`refs/bisect/bad` is added to the included commits (if it 506exists) and the good bisection refs `refs/bisect/good-*` are 507added to the excluded commits (if they exist). Thus, supposing there 508are no refs in `refs/bisect/`, if 509 510----------------------------------------------------------------------- 511 $ git rev-list --bisect foo ^bar ^baz 512----------------------------------------------------------------------- 513 514outputs 'midpoint', the output of the two commands 515 516----------------------------------------------------------------------- 517 $ git rev-list foo ^midpoint 518 $ git rev-list midpoint ^bar ^baz 519----------------------------------------------------------------------- 520 521would be of roughly the same length. Finding the change which 522introduces a regression is thus reduced to a binary search: repeatedly 523generate and test new 'midpoint's until the commit chain is of length 524one. 525 526--bisect-vars:: 527 528This calculates the same as `--bisect`, except that refs in 529`refs/bisect/` are not used, and except that this outputs 530text ready to be eval'ed by the shell. These lines will assign the 531name of the midpoint revision to the variable `bisect_rev`, and the 532expected number of commits to be tested after `bisect_rev` is tested 533to `bisect_nr`, the expected number of commits to be tested if 534`bisect_rev` turns out to be good to `bisect_good`, the expected 535number of commits to be tested if `bisect_rev` turns out to be bad to 536`bisect_bad`, and the number of commits we are bisecting right now to 537`bisect_all`. 538 539--bisect-all:: 540 541This outputs all the commit objects between the included and excluded 542commits, ordered by their distance to the included and excluded 543commits. Refs in `refs/bisect/` are not used. The farthest 544from them is displayed first. (This is the only one displayed by 545`--bisect`.) 546+ 547This is useful because it makes it easy to choose a good commit to 548test when you want to avoid to test some of them for some reason (they 549may not compile for example). 550+ 551This option can be used along with `--bisect-vars`, in this case, 552after all the sorted commit objects, there will be the same text as if 553`--bisect-vars` had been used alone. 554endif::git-rev-list[] 555 556 557Commit Ordering 558~~~~~~~~~~~~~~~ 559 560By default, the commits are shown in reverse chronological order. 561 562--topo-order:: 563 564 This option makes them appear in topological order (i.e. 565 descendant commits are shown before their parents). 566 567--date-order:: 568 569 This option is similar to '--topo-order' in the sense that no 570 parent comes before all of its children, but otherwise things 571 are still ordered in the commit timestamp order. 572 573--reverse:: 574 575 Output the commits in reverse order. 576 Cannot be combined with '\--walk-reflogs'. 577 578Object Traversal 579~~~~~~~~~~~~~~~~ 580 581These options are mostly targeted for packing of git repositories. 582 583--objects:: 584 585 Print the object IDs of any object referenced by the listed 586 commits. '--objects foo ^bar' thus means "send me 587 all object IDs which I need to download if I have the commit 588 object 'bar', but not 'foo'". 589 590--objects-edge:: 591 592 Similar to '--objects', but also print the IDs of excluded 593 commits prefixed with a "-" character. This is used by 594 linkgit:git-pack-objects[1] to build "thin" pack, which records 595 objects in deltified form based on objects contained in these 596 excluded commits to reduce network traffic. 597 598--unpacked:: 599 600 Only useful with '--objects'; print the object IDs that are not 601 in packs. 602 603--no-walk:: 604 605 Only show the given revs, but do not traverse their ancestors. 606 607--do-walk:: 608 609 Overrides a previous --no-walk. 610 611Commit Formatting 612~~~~~~~~~~~~~~~~~ 613 614ifdef::git-rev-list[] 615Using these options, linkgit:git-rev-list[1] will act similar to the 616more specialized family of commit log tools: linkgit:git-log[1], 617linkgit:git-show[1], and linkgit:git-whatchanged[1] 618endif::git-rev-list[] 619 620include::pretty-options.txt[] 621 622--relative-date:: 623 624 Synonym for `--date=relative`. 625 626--date=(relative|local|default|iso|rfc|short|raw):: 627 628 Only takes effect for dates shown in human-readable format, such 629 as when using "--pretty". `log.date` config variable sets a default 630 value for log command's --date option. 631+ 632`--date=relative` shows dates relative to the current time, 633e.g. "2 hours ago". 634+ 635`--date=local` shows timestamps in user's local timezone. 636+ 637`--date=iso` (or `--date=iso8601`) shows timestamps in ISO 8601 format. 638+ 639`--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822 640format, often found in E-mail messages. 641+ 642`--date=short` shows only date but not time, in `YYYY-MM-DD` format. 643+ 644`--date=raw` shows the date in the internal raw git format `%s %z` format. 645+ 646`--date=default` shows timestamps in the original timezone 647(either committer's or author's). 648 649ifdef::git-rev-list[] 650--header:: 651 652 Print the contents of the commit in raw-format; each record is 653 separated with a NUL character. 654endif::git-rev-list[] 655 656--parents:: 657 658 Print also the parents of the commit (in the form "commit parent..."). 659 Also enables parent rewriting, see 'History Simplification' below. 660 661--children:: 662 663 Print also the children of the commit (in the form "commit child..."). 664 Also enables parent rewriting, see 'History Simplification' below. 665 666ifdef::git-rev-list[] 667--timestamp:: 668 Print the raw commit timestamp. 669endif::git-rev-list[] 670 671--left-right:: 672 673 Mark which side of a symmetric diff a commit is reachable from. 674 Commits from the left side are prefixed with `<` and those from 675 the right with `>`. If combined with `--boundary`, those 676 commits are prefixed with `-`. 677+ 678For example, if you have this topology: 679+ 680----------------------------------------------------------------------- 681 y---b---b branch B 682 / \ / 683 / . 684 / / \ 685 o---x---a---a branch A 686----------------------------------------------------------------------- 687+ 688you would get an output like this: 689+ 690----------------------------------------------------------------------- 691 $ git rev-list --left-right --boundary --pretty=oneline A...B 692 693 >bbbbbbb... 3rd on b 694 >bbbbbbb... 2nd on b 695 <aaaaaaa... 3rd on a 696 <aaaaaaa... 2nd on a 697 -yyyyyyy... 1st on b 698 -xxxxxxx... 1st on a 699----------------------------------------------------------------------- 700 701--graph:: 702 703 Draw a text-based graphical representation of the commit history 704 on the left hand side of the output. This may cause extra lines 705 to be printed in between commits, in order for the graph history 706 to be drawn properly. 707+ 708This enables parent rewriting, see 'History Simplification' below. 709+ 710This implies the '--topo-order' option by default, but the 711'--date-order' option may also be specified. 712 713ifdef::git-rev-list[] 714--count:: 715 Print a number stating how many commits would have been 716 listed, and suppress all other output. When used together 717 with '--left-right', instead print the counts for left and 718 right commits, separated by a tab. 719endif::git-rev-list[] 720 721 722ifndef::git-rev-list[] 723Diff Formatting 724~~~~~~~~~~~~~~~ 725 726Below are listed options that control the formatting of diff output. 727Some of them are specific to linkgit:git-rev-list[1], however other diff 728options may be given. See linkgit:git-diff-files[1] for more options. 729 730-c:: 731 732 With this option, diff output for a merge commit 733 shows the differences from each of the parents to the merge result 734 simultaneously instead of showing pairwise diff between a parent 735 and the result one at a time. Furthermore, it lists only files 736 which were modified from all parents. 737 738--cc:: 739 740 This flag implies the '-c' options and further compresses the 741 patch output by omitting uninteresting hunks whose contents in 742 the parents have only two variants and the merge result picks 743 one of them without modification. 744 745-m:: 746 747 This flag makes the merge commits show the full diff like 748 regular commits; for each merge parent, a separate log entry 749 and diff is generated. An exception is that only diff against 750 the first parent is shown when '--first-parent' option is given; 751 in that case, the output represents the changes the merge 752 brought _into_ the then-current branch. 753 754-r:: 755 756 Show recursive diffs. 757 758-t:: 759 760 Show the tree objects in the diff output. This implies '-r'. 761 762-s:: 763 Suppress diff output. 764endif::git-rev-list[]