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