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