Documentation / git-rev-list.txton commit Makefile: rebuild git.o on version change, clean up git$X flags (54dadbd)
   1git-rev-list(1)
   2===============
   3
   4NAME
   5----
   6git-rev-list - Lists commit objects in reverse chronological order
   7
   8
   9SYNOPSIS
  10--------
  11[verse]
  12'git-rev-list' [ \--max-count=number ]
  13             [ \--skip=number ]
  14             [ \--max-age=timestamp ]
  15             [ \--min-age=timestamp ]
  16             [ \--sparse ]
  17             [ \--no-merges ]
  18             [ \--remove-empty ]
  19             [ \--full-history ]
  20             [ \--not ]
  21             [ \--all ]
  22             [ \--stdin ]
  23             [ \--topo-order ]
  24             [ \--parents ]
  25             [ \--timestamp ]
  26             [ \--left-right ]
  27             [ \--cherry-pick ]
  28             [ \--encoding[=<encoding>] ]
  29             [ \--(author|committer|grep)=<pattern> ]
  30             [ \--regexp-ignore-case ] [ \--extended-regexp ]
  31             [ \--date={local|relative|default} ]
  32             [ [\--objects | \--objects-edge] [ \--unpacked ] ]
  33             [ \--pretty | \--header ]
  34             [ \--bisect ]
  35             [ \--bisect-vars ]
  36             [ \--merge ]
  37             [ \--reverse ]
  38             [ \--walk-reflogs ]
  39             <commit>... [ \-- <paths>... ]
  40
  41DESCRIPTION
  42-----------
  43
  44Lists commit objects in reverse chronological order starting at the
  45given commit(s), taking ancestry relationship into account.  This is
  46useful to produce human-readable log output.
  47
  48Commits which are stated with a preceding '{caret}' cause listing to
  49stop at that point. Their parents are implied. Thus the following
  50command:
  51
  52-----------------------------------------------------------------------
  53        $ git-rev-list foo bar ^baz
  54-----------------------------------------------------------------------
  55
  56means "list all the commits which are included in 'foo' and 'bar', but
  57not in 'baz'".
  58
  59A special notation "'<commit1>'..'<commit2>'" can be used as a
  60short-hand for "{caret}'<commit1>' '<commit2>'". For example, either of
  61the following may be used interchangeably:
  62
  63-----------------------------------------------------------------------
  64        $ git-rev-list origin..HEAD
  65        $ git-rev-list HEAD ^origin
  66-----------------------------------------------------------------------
  67
  68Another special notation is "'<commit1>'...'<commit2>'" which is useful
  69for merges.  The resulting set of commits is the symmetric difference
  70between the two operands.  The following two commands are equivalent:
  71
  72-----------------------------------------------------------------------
  73        $ git-rev-list A B --not $(git-merge-base --all A B)
  74        $ git-rev-list A...B
  75-----------------------------------------------------------------------
  76
  77gitlink:git-rev-list[1] is a very essential git program, since it
  78provides the ability to build and traverse commit ancestry graphs. For
  79this reason, it has a lot of different options that enables it to be
  80used by commands as different as gitlink:git-bisect[1] and
  81gitlink:git-repack[1].
  82
  83OPTIONS
  84-------
  85
  86Commit Formatting
  87~~~~~~~~~~~~~~~~~
  88
  89Using these options, gitlink:git-rev-list[1] will act similar to the
  90more specialized family of commit log tools: gitlink:git-log[1],
  91gitlink:git-show[1], and gitlink:git-whatchanged[1]
  92
  93include::pretty-options.txt[]
  94
  95--relative-date::
  96
  97        Synonym for `--date=relative`.
  98
  99--date={relative,local,default}::
 100
 101        Only takes effect for dates shown in human-readable format, such
 102        as when using "--pretty".
 103+
 104`--date=relative` shows dates relative to the current time,
 105e.g. "2 hours ago".
 106+
 107`--date=local` shows timestamps in user's local timezone.
 108+
 109`--date=default` shows timestamps in the original timezone
 110(either committer's or author's).
 111
 112--header::
 113
 114        Print the contents of the commit in raw-format; each record is
 115        separated with a NUL character.
 116
 117--parents::
 118
 119        Print the parents of the commit.
 120
 121--timestamp::
 122        Print the raw commit timestamp.
 123
 124--left-right::
 125
 126        Mark which side of a symmetric diff a commit is reachable from.
 127        Commits from the left side are prefixed with `<` and those from
 128        the right with `>`.  If combined with `--boundary`, those
 129        commits are prefixed with `-`.
 130+
 131For example, if you have this topology:
 132+
 133-----------------------------------------------------------------------
 134             y---b---b  branch B
 135            / \ /
 136           /   .
 137          /   / \
 138         o---x---a---a  branch A
 139-----------------------------------------------------------------------
 140+
 141you would get an output line this:
 142+
 143-----------------------------------------------------------------------
 144        $ git rev-list --left-right --boundary --pretty=oneline A...B
 145
 146        >bbbbbbb... 3rd on b
 147        >bbbbbbb... 2nd on b
 148        <aaaaaaa... 3rd on a
 149        <aaaaaaa... 2nd on a
 150        -yyyyyyy... 1st on b
 151        -xxxxxxx... 1st on a
 152-----------------------------------------------------------------------
 153
 154Diff Formatting
 155~~~~~~~~~~~~~~~
 156
 157Below are listed options that control the formatting of diff output.
 158Some of them are specific to gitlink:git-rev-list[1], however other diff
 159options may be given. See gitlink:git-diff-files[1] for more options.
 160
 161-c::
 162
 163        This flag changes the way a merge commit is displayed.  It shows
 164        the differences from each of the parents to the merge result
 165        simultaneously instead of showing pairwise diff between a parent
 166        and the result one at a time. Furthermore, it lists only files
 167        which were modified from all parents.
 168
 169--cc::
 170
 171        This flag implies the '-c' options and further compresses the
 172        patch output by omitting hunks that show differences from only
 173        one parent, or show the same change from all but one parent for
 174        an Octopus merge.
 175
 176-r::
 177
 178        Show recursive diffs.
 179
 180-t::
 181
 182        Show the tree objects in the diff output. This implies '-r'.
 183
 184Commit Limiting
 185~~~~~~~~~~~~~~~
 186
 187Besides specifying a range of commits that should be listed using the
 188special notations explained in the description, additional commit
 189limiting may be applied.
 190
 191--
 192
 193-n 'number', --max-count='number'::
 194
 195        Limit the number of commits output.
 196
 197--skip='number'::
 198
 199        Skip 'number' commits before starting to show the commit output.
 200
 201--since='date', --after='date'::
 202
 203        Show commits more recent than a specific date.
 204
 205--until='date', --before='date'::
 206
 207        Show commits older than a specific date.
 208
 209--max-age='timestamp', --min-age='timestamp'::
 210
 211        Limit the commits output to specified time range.
 212
 213--author='pattern', --committer='pattern'::
 214
 215        Limit the commits output to ones with author/committer
 216        header lines that match the specified pattern (regular expression).
 217
 218--grep='pattern'::
 219
 220        Limit the commits output to ones with log message that
 221        matches the specified pattern (regular expression).
 222
 223--regexp-ignore-case::
 224
 225        Match the regexp limiting patterns without regard to letters case.
 226
 227--extended-regexp::
 228
 229        Consider the limiting patterns to be extended regular expressions
 230        instead of the default basic regular expressions.
 231
 232--remove-empty::
 233
 234        Stop when a given path disappears from the tree.
 235
 236--full-history::
 237
 238        Show also parts of history irrelevant to current state of a given
 239        path. This turns off history simplification, which removed merges
 240        which didn't change anything at all at some child. It will still actually
 241        simplify away merges that didn't change anything at all into either
 242        child.
 243
 244--no-merges::
 245
 246        Do not print commits with more than one parent.
 247
 248--not::
 249
 250        Reverses the meaning of the '{caret}' prefix (or lack thereof)
 251        for all following revision specifiers, up to the next '--not'.
 252
 253--all::
 254
 255        Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the
 256        command line as '<commit>'.
 257
 258--stdin::
 259
 260        In addition to the '<commit>' listed on the command
 261        line, read them from the standard input.
 262
 263--cherry-pick::
 264
 265        Omit any commit that introduces the same change as
 266        another commit on the "other side" when the set of
 267        commits are limited with symmetric difference.
 268+
 269For example, if you have two branches, `A` and `B`, a usual way
 270to list all commits on only one side of them is with
 271`--left-right`, like the example above in the description of
 272that option.  It however shows the commits that were cherry-picked
 273from the other branch (for example, "3rd on b" may be cherry-picked
 274from branch A).  With this option, such pairs of commits are
 275excluded from the output.
 276
 277-g, --walk-reflogs::
 278
 279        Instead of walking the commit ancestry chain, walk
 280        reflog entries from the most recent one to older ones.
 281        When this option is used you cannot specify commits to
 282        exclude (that is, '{caret}commit', 'commit1..commit2',
 283        nor 'commit1...commit2' notations cannot be used).
 284+
 285With '\--pretty' format other than oneline (for obvious reasons),
 286this causes the output to have two extra lines of information
 287taken from the reflog.  By default, 'commit@\{Nth}' notation is
 288used in the output.  When the starting commit is specified as
 289'commit@{now}', output also uses 'commit@\{timestamp}' notation
 290instead.  Under '\--pretty=oneline', the commit message is
 291prefixed with this information on the same line.
 292
 293--merge::
 294
 295        After a failed merge, show refs that touch files having a
 296        conflict and don't exist on all heads to merge.
 297
 298--boundary::
 299
 300        Output uninteresting commits at the boundary, which are usually
 301        not shown.
 302
 303--dense, --sparse::
 304
 305When optional paths are given, the default behaviour ('--dense') is to
 306only output commits that changes at least one of them, and also ignore
 307merges that do not touch the given paths.
 308
 309Use the '--sparse' flag to makes the command output all eligible commits
 310(still subject to count and age limitation), but apply merge
 311simplification nevertheless.
 312
 313--bisect::
 314
 315Limit output to the one commit object which is roughly halfway between
 316the included and excluded commits. Thus, if
 317
 318-----------------------------------------------------------------------
 319        $ git-rev-list --bisect foo ^bar ^baz
 320-----------------------------------------------------------------------
 321
 322outputs 'midpoint', the output of the two commands
 323
 324-----------------------------------------------------------------------
 325        $ git-rev-list foo ^midpoint
 326        $ git-rev-list midpoint ^bar ^baz
 327-----------------------------------------------------------------------
 328
 329would be of roughly the same length.  Finding the change which
 330introduces a regression is thus reduced to a binary search: repeatedly
 331generate and test new 'midpoint's until the commit chain is of length
 332one.
 333
 334--bisect-vars::
 335
 336This calculates the same as `--bisect`, but outputs text ready
 337to be eval'ed by the shell. These lines will assign the name of
 338the midpoint revision to the variable `bisect_rev`, and the
 339expected number of commits to be tested after `bisect_rev` is
 340tested to `bisect_nr`, the expected number of commits to be
 341tested if `bisect_rev` turns out to be good to `bisect_good`,
 342the expected number of commits to be tested if `bisect_rev`
 343turns out to be bad to `bisect_bad`, and the number of commits
 344we are bisecting right now to `bisect_all`.
 345
 346--
 347
 348Commit Ordering
 349~~~~~~~~~~~~~~~
 350
 351By default, the commits are shown in reverse chronological order.
 352
 353--topo-order::
 354
 355        This option makes them appear in topological order (i.e.
 356        descendant commits are shown before their parents).
 357
 358--date-order::
 359
 360        This option is similar to '--topo-order' in the sense that no
 361        parent comes before all of its children, but otherwise things
 362        are still ordered in the commit timestamp order.
 363
 364--reverse::
 365
 366        Output the commits in reverse order.
 367
 368Object Traversal
 369~~~~~~~~~~~~~~~~
 370
 371These options are mostly targeted for packing of git repositories.
 372
 373--objects::
 374
 375        Print the object IDs of any object referenced by the listed
 376        commits.  'git-rev-list --objects foo ^bar' thus means "send me
 377        all object IDs which I need to download if I have the commit
 378        object 'bar', but not 'foo'".
 379
 380--objects-edge::
 381
 382        Similar to '--objects', but also print the IDs of excluded
 383        commits prefixed with a "-" character.  This is used by
 384        gitlink:git-pack-objects[1] to build "thin" pack, which records
 385        objects in deltified form based on objects contained in these
 386        excluded commits to reduce network traffic.
 387
 388--unpacked::
 389
 390        Only useful with '--objects'; print the object IDs that are not
 391        in packs.
 392
 393
 394include::pretty-formats.txt[]
 395
 396
 397Author
 398------
 399Written by Linus Torvalds <torvalds@osdl.org>
 400
 401Documentation
 402--------------
 403Documentation by David Greaves, Junio C Hamano, Jonas Fonseca
 404and the git-list <git@vger.kernel.org>.
 405
 406GIT
 407---
 408Part of the gitlink:git[7] suite