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