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              [ [\--objects | \--objects-edge] [ \--unpacked ] ]
  24              [ \--pretty | \--header ]
  25              [ \--bisect ]
  26              [ \--merge ]
  27              <commit>... [ \-- <paths>... ]
  28
  29 DESCRIPTION
  30 -----------
  31
  32 Lists commit objects in reverse chronological order starting at the
  33 given commit(s), taking ancestry relationship into account.  This is
  34 useful to produce human-readable log output.
  35
  36 Commits which are stated with a preceding '{caret}' cause listing to
  37 stop at that point. Their parents are implied. Thus the following
  38 command:
  39
  40 -----------------------------------------------------------------------
  41         $ git-rev-list foo bar ^baz
  42 -----------------------------------------------------------------------
  43
  44 means "list all the commits which are included in 'foo' and 'bar', but
  45 not in 'baz'".
  46
  47 A special notation "'<commit1>'..'<commit2>'" can be used as a
  48 short-hand for "{caret}'<commit1>' '<commit2>'". For example, either of
  49 the following may be used interchangeably:
  50
  51 -----------------------------------------------------------------------
  52         $ git-rev-list origin..HEAD
  53         $ git-rev-list HEAD ^origin
  54 -----------------------------------------------------------------------
  55
  56 Another special notation is "'<commit1>'...'<commit2>'" which is useful
  57 for merges.  The resulting set of commits is the symmetric difference
  58 between the two operands.  The following two commands are equivalent:
  59
  60 -----------------------------------------------------------------------
  61         $ git-rev-list A B --not $(git-merge-base --all A B)
  62         $ git-rev-list A...B
  63 -----------------------------------------------------------------------
  64
  65 gitlink:git-rev-list[1] is a very essential git program, since it
  66 provides the ability to build and traverse commit ancestry graphs. For
  67 this reason, it has a lot of different options that enables it to be
  68 used by commands as different as gitlink:git-bisect[1] and
  69 gitlink:git-repack[1].
  70
  71 OPTIONS
  72 -------
  73
  74 Commit Formatting
  75 ~~~~~~~~~~~~~~~~~
  76
  77 Using these options, gitlink:git-rev-list[1] will act similar to the
  78 more specialized family of commit log tools: gitlink:git-log[1],
  79 gitlink:git-show[1], and gitlink:git-whatchanged[1]
  80
  81 --pretty[='<format>']::
  82
  83         Pretty print the contents of the commit logs in a given format,
  84         where '<format>' can be one of 'raw', 'medium', 'short', 'full',
  85         and 'oneline'. When left out the format default to 'medium'.
  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 --since='date', --after='date'::
 146
 147         Show commits more recent than a specific date.
 148
 149 --until='date', --before='date'::
 150
 151         Show commits older than a specific date.
 152
 153 --max-age='timestamp', --min-age='timestamp'::
 154
 155         Limit the commits output to specified time range.
 156
 157 --remove-empty::
 158
 159         Stop when a given path disappears from the tree.
 160
 161 --no-merges::
 162
 163         Do not print commits with more than one parent.
 164
 165 --not::
 166
 167         Reverses the meaning of the '{caret}' prefix (or lack thereof)
 168         for all following revision specifiers, up to the next '--not'.
 169
 170 --all::
 171
 172         Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the
 173         command line as '<commit>'.
 174
 175 --stdin::
 176
 177         In addition to the '<commit>' listed on the command
 178         line, read them from the standard input.
 179
 180 --merge::
 181
 182         After a failed merge, show refs that touch files having a
 183         conflict and don't exist on all heads to merge.
 184
 185 --boundary::
 186
 187         Output uninteresting commits at the boundary, which are usually
 188         not shown.
 189
 190 --dense, --sparse::
 191
 192 When optional paths are given, the default behaviour ('--dense') is to
 193 only output commits that changes at least one of them, and also ignore
 194 merges that do not touch the given paths.
 195
 196 Use the '--sparse' flag to makes the command output all eligible commits
 197 (still subject to count and age limitation), but apply merge
 198 simplification nevertheless.
 199
 200 --bisect::
 201
 202 Limit output to the one commit object which is roughly halfway between
 203 the included and excluded commits. Thus, if
 204
 205 -----------------------------------------------------------------------
 206         $ git-rev-list --bisect foo ^bar ^baz
 207 -----------------------------------------------------------------------
 208
 209 outputs 'midpoint', the output of the two commands
 210
 211 -----------------------------------------------------------------------
 212         $ git-rev-list foo ^midpoint
 213         $ git-rev-list midpoint ^bar ^baz
 214 -----------------------------------------------------------------------
 215
 216 would be of roughly the same length.  Finding the change which
 217 introduces a regression is thus reduced to a binary search: repeatedly
 218 generate and test new 'midpoint's until the commit chain is of length
 219 one.
 220
 221 --
 222
 223 Commit Ordering
 224 ~~~~~~~~~~~~~~~
 225
 226 By default, the commits are shown in reverse chronological order.
 227
 228 --topo-order::
 229
 230         This option makes them appear in topological order (i.e.
 231         descendant commits are shown before their parents).
 232
 233 --date-order::
 234
 235         This option is similar to '--topo-order' in the sense that no
 236         parent comes before all of its children, but otherwise things
 237         are still ordered in the commit timestamp order.
 238
 239 Object Traversal
 240 ~~~~~~~~~~~~~~~~
 241
 242 These options are mostly targeted for packing of git repositories.
 243
 244 --objects::
 245
 246         Print the object IDs of any object referenced by the listed
 247         commits.  'git-rev-list --objects foo ^bar' thus means "send me
 248         all object IDs which I need to download if I have the commit
 249         object 'bar', but not 'foo'".
 250
 251 --objects-edge::
 252
 253         Similar to '--objects', but also print the IDs of excluded
 254         commits prefixed with a "-" character.  This is used by
 255         gitlink:git-pack-objects[1] to build "thin" pack, which records
 256         objects in deltified form based on objects contained in these
 257         excluded commits to reduce network traffic.
 258
 259 --unpacked::
 260
 261         Only useful with '--objects'; print the object IDs that are not
 262         in packs.
 263
 264 Author
 265 ------
 266 Written by Linus Torvalds <torvalds@osdl.org>
 267
 268 Documentation
 269 --------------
 270 Documentation by David Greaves, Junio C Hamano, Jonas Fonseca
 271 and the git-list <git@vger.kernel.org>.
 272
 273 GIT
 274 ---
 275 Part of the gitlink:git[7] suite