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