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