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