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