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