Documentation/git-rev-list.txt

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