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 --pretty[='<format>']::
  83
  84         Pretty print the contents of the commit logs in a given format,
  85         where '<format>' can be one of 'raw', 'medium', 'short', 'full',
  86         and 'oneline'. When left out the format default to 'medium'.
  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 --since='date', --after='date'::
 147
 148         Show commits more recent than a specific date.
 149
 150 --until='date', --before='date'::
 151
 152         Show commits older than a specific date.
 153
 154 --max-age='timestamp', --min-age='timestamp'::
 155
 156         Limit the commits output to specified time range.
 157
 158 --author='pattern', --committer='pattern'::
 159
 160         Limit the commits output to ones with author/committer
 161         header lines that match the specified pattern.
 162
 163 --grep='pattern'::
 164
 165         Limit the commits output to ones with log message that
 166         matches the specified pattern.
 167
 168 --remove-empty::
 169
 170         Stop when a given path disappears from the tree.
 171
 172 --no-merges::
 173
 174         Do not print commits with more than one parent.
 175
 176 --not::
 177
 178         Reverses the meaning of the '{caret}' prefix (or lack thereof)
 179         for all following revision specifiers, up to the next '--not'.
 180
 181 --all::
 182
 183         Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the
 184         command line as '<commit>'.
 185
 186 --stdin::
 187
 188         In addition to the '<commit>' listed on the command
 189         line, read them from the standard input.
 190
 191 --merge::
 192
 193         After a failed merge, show refs that touch files having a
 194         conflict and don't exist on all heads to merge.
 195
 196 --boundary::
 197
 198         Output uninteresting commits at the boundary, which are usually
 199         not shown.
 200
 201 --dense, --sparse::
 202
 203 When optional paths are given, the default behaviour ('--dense') is to
 204 only output commits that changes at least one of them, and also ignore
 205 merges that do not touch the given paths.
 206
 207 Use the '--sparse' flag to makes the command output all eligible commits
 208 (still subject to count and age limitation), but apply merge
 209 simplification nevertheless.
 210
 211 --bisect::
 212
 213 Limit output to the one commit object which is roughly halfway between
 214 the included and excluded commits. Thus, if
 215
 216 -----------------------------------------------------------------------
 217         $ git-rev-list --bisect foo ^bar ^baz
 218 -----------------------------------------------------------------------
 219
 220 outputs 'midpoint', the output of the two commands
 221
 222 -----------------------------------------------------------------------
 223         $ git-rev-list foo ^midpoint
 224         $ git-rev-list midpoint ^bar ^baz
 225 -----------------------------------------------------------------------
 226
 227 would be of roughly the same length.  Finding the change which
 228 introduces a regression is thus reduced to a binary search: repeatedly
 229 generate and test new 'midpoint's until the commit chain is of length
 230 one.
 231
 232 --
 233
 234 Commit Ordering
 235 ~~~~~~~~~~~~~~~
 236
 237 By default, the commits are shown in reverse chronological order.
 238
 239 --topo-order::
 240
 241         This option makes them appear in topological order (i.e.
 242         descendant commits are shown before their parents).
 243
 244 --date-order::
 245
 246         This option is similar to '--topo-order' in the sense that no
 247         parent comes before all of its children, but otherwise things
 248         are still ordered in the commit timestamp order.
 249
 250 Object Traversal
 251 ~~~~~~~~~~~~~~~~
 252
 253 These options are mostly targeted for packing of git repositories.
 254
 255 --objects::
 256
 257         Print the object IDs of any object referenced by the listed
 258         commits.  'git-rev-list --objects foo ^bar' thus means "send me
 259         all object IDs which I need to download if I have the commit
 260         object 'bar', but not 'foo'".
 261
 262 --objects-edge::
 263
 264         Similar to '--objects', but also print the IDs of excluded
 265         commits prefixed with a "-" character.  This is used by
 266         gitlink:git-pack-objects[1] to build "thin" pack, which records
 267         objects in deltified form based on objects contained in these
 268         excluded commits to reduce network traffic.
 269
 270 --unpacked::
 271
 272         Only useful with '--objects'; print the object IDs that are not
 273         in packs.
 274
 275 Author
 276 ------
 277 Written by Linus Torvalds <torvalds@osdl.org>
 278
 279 Documentation
 280 --------------
 281 Documentation by David Greaves, Junio C Hamano, Jonas Fonseca
 282 and the git-list <git@vger.kernel.org>.
 283
 284 GIT
 285 ---
 286 Part of the gitlink:git[7] suite