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