init_buffer(): Kill buf pointer
[git/git.git] / Documentation / git-rev-list.txt
CommitLineData
2cf565c5
DG
1git-rev-list(1)
2===============
2cf565c5
DG
3
4NAME
5----
6git-rev-list - Lists commit objects in reverse chronological order
7
8
9SYNOPSIS
10--------
353ce815 11[verse]
69e0c256 12'git-rev-list' [ \--max-count=number ]
d5db6c9e 13 [ \--skip=number ]
353ce815
JF
14 [ \--max-age=timestamp ]
15 [ \--min-age=timestamp ]
16 [ \--sparse ]
17 [ \--no-merges ]
93b74bca 18 [ \--remove-empty ]
0d2c9d67 19 [ \--not ]
353ce815 20 [ \--all ]
42cabc34 21 [ \--stdin ]
765ac8ec 22 [ \--topo-order ]
353ce815 23 [ \--parents ]
b24bace5 24 [ \--left-right ]
55a643ed 25 [ \--cherry-pick ]
7cbcf4d5 26 [ \--encoding[=<encoding>] ]
bd95fcd3 27 [ \--(author|committer|grep)=<pattern> ]
ec579767 28 [ [\--objects | \--objects-edge] [ \--unpacked ] ]
353ce815
JF
29 [ \--pretty | \--header ]
30 [ \--bisect ]
457f08a0 31 [ \--bisect-vars ]
d249b455 32 [ \--merge ]
9c5e66e9 33 [ \--reverse ]
4d12a471 34 [ \--walk-reflogs ]
353ce815 35 <commit>... [ \-- <paths>... ]
2cf565c5
DG
36
37DESCRIPTION
38-----------
8c02eee2 39
2cf565c5 40Lists commit objects in reverse chronological order starting at the
adcd3512 41given commit(s), taking ancestry relationship into account. This is
2cf565c5
DG
42useful to produce human-readable log output.
43
8c02eee2
JF
44Commits which are stated with a preceding '{caret}' cause listing to
45stop at that point. Their parents are implied. Thus the following
46command:
47
48-----------------------------------------------------------------------
49 $ git-rev-list foo bar ^baz
50-----------------------------------------------------------------------
51
adcd3512
MU
52means "list all the commits which are included in 'foo' and 'bar', but
53not in 'baz'".
54
8c02eee2
JF
55A special notation "'<commit1>'..'<commit2>'" can be used as a
56short-hand for "{caret}'<commit1>' '<commit2>'". For example, either of
57the following may be used interchangeably:
69e0c256 58
8c02eee2
JF
59-----------------------------------------------------------------------
60 $ git-rev-list origin..HEAD
61 $ git-rev-list HEAD ^origin
62-----------------------------------------------------------------------
63
64Another special notation is "'<commit1>'...'<commit2>'" which is useful
65for merges. The resulting set of commits is the symmetric difference
0d2c9d67
RS
66between the two operands. The following two commands are equivalent:
67
8c02eee2
JF
68-----------------------------------------------------------------------
69 $ git-rev-list A B --not $(git-merge-base --all A B)
70 $ git-rev-list A...B
71-----------------------------------------------------------------------
72
73gitlink:git-rev-list[1] is a very essential git program, since it
74provides the ability to build and traverse commit ancestry graphs. For
75this reason, it has a lot of different options that enables it to be
76used by commands as different as gitlink:git-bisect[1] and
77gitlink:git-repack[1].
69e0c256 78
df8baa42
JF
79OPTIONS
80-------
8c02eee2
JF
81
82Commit Formatting
83~~~~~~~~~~~~~~~~~
84
85Using these options, gitlink:git-rev-list[1] will act similar to the
86more specialized family of commit log tools: gitlink:git-log[1],
87gitlink:git-show[1], and gitlink:git-whatchanged[1]
88
5d1faf87 89include::pretty-formats.txt[]
8c02eee2
JF
90
91--relative-date::
92
93 Show dates relative to the current time, e.g. "2 hours ago".
94 Only takes effect for dates shown in human-readable format, such
95 as when using "--pretty".
df8baa42 96
69e0c256 97--header::
8c02eee2
JF
98
99 Print the contents of the commit in raw-format; each record is
100 separated with a NUL character.
69e0c256 101
f443455a 102--parents::
8c02eee2 103
f443455a
ML
104 Print the parents of the commit.
105
b24bace5
BG
106--left-right::
107
108 Mark which side of a symmetric diff a commit is reachable from.
109 Commits from the left side are prefixed with `<` and those from
110 the right with `>`. If combined with `--boundary`, those
111 commits are prefixed with `-`.
112+
113For example, if you have this topology:
114+
115-----------------------------------------------------------------------
116 y---b---b branch B
117 / \ /
118 / .
119 / / \
120 o---x---a---a branch A
121-----------------------------------------------------------------------
122+
123you would get an output line this:
124+
125-----------------------------------------------------------------------
126 $ git rev-list --left-right --boundary --pretty=oneline A...B
127
128 >bbbbbbb... 3rd on b
129 >bbbbbbb... 2nd on b
130 <aaaaaaa... 3rd on a
131 <aaaaaaa... 2nd on a
132 -yyyyyyy... 1st on b
133 -xxxxxxx... 1st on a
134-----------------------------------------------------------------------
135
8c02eee2
JF
136Diff Formatting
137~~~~~~~~~~~~~~~
df8baa42 138
8c02eee2
JF
139Below are listed options that control the formatting of diff output.
140Some of them are specific to gitlink:git-rev-list[1], however other diff
141options may be given. See gitlink:git-diff-files[1] for more options.
ec579767 142
8c02eee2
JF
143-c::
144
145 This flag changes the way a merge commit is displayed. It shows
146 the differences from each of the parents to the merge result
147 simultaneously instead of showing pairwise diff between a parent
148 and the result one at a time. Furthermore, it lists only files
149 which were modified from all parents.
150
151--cc::
152
153 This flag implies the '-c' options and further compresses the
154 patch output by omitting hunks that show differences from only
155 one parent, or show the same change from all but one parent for
156 an Octopus merge.
157
158-r::
159
160 Show recursive diffs.
161
162-t::
163
164 Show the tree objects in the diff output. This implies '-r'.
165
166Commit Limiting
167~~~~~~~~~~~~~~~
168
169Besides specifying a range of commits that should be listed using the
170special notations explained in the description, additional commit
171limiting may be applied.
172
173--
174
175-n 'number', --max-count='number'::
69e0c256 176
69e0c256
JH
177 Limit the number of commits output.
178
d5db6c9e
JH
179--skip='number'::
180
181 Skip 'number' commits before starting to show the commit output.
182
8c02eee2
JF
183--since='date', --after='date'::
184
185 Show commits more recent than a specific date.
186
187--until='date', --before='date'::
69e0c256 188
8c02eee2
JF
189 Show commits older than a specific date.
190
191--max-age='timestamp', --min-age='timestamp'::
192
193 Limit the commits output to specified time range.
69e0c256 194
bd95fcd3
JH
195--author='pattern', --committer='pattern'::
196
197 Limit the commits output to ones with author/committer
198 header lines that match the specified pattern.
199
200--grep='pattern'::
201
202 Limit the commits output to ones with log message that
203 matches the specified pattern.
204
93b74bca 205--remove-empty::
8c02eee2 206
93b74bca
JH
207 Stop when a given path disappears from the tree.
208
f443455a 209--no-merges::
8c02eee2 210
f443455a
ML
211 Do not print commits with more than one parent.
212
0d2c9d67 213--not::
8c02eee2
JF
214
215 Reverses the meaning of the '{caret}' prefix (or lack thereof)
216 for all following revision specifiers, up to the next '--not'.
0d2c9d67 217
69e0c256 218--all::
69e0c256 219
8c02eee2
JF
220 Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the
221 command line as '<commit>'.
69e0c256 222
42cabc34
JH
223--stdin::
224
225 In addition to the '<commit>' listed on the command
226 line, read them from the standard input.
55a643ed
JH
227
228--cherry-pick::
229
230 Omit any commit that introduces the same change as
231 another commit on the "other side" when the set of
232 commits are limited with symmetric difference.
233+
234For example, if you have two branches, `A` and `B`, a usual way
235to list all commits on only one side of them is with
236`--left-right`, like the example above in the description of
237that option. It however shows the commits that were cherry-picked
238from the other branch (for example, "3rd on b" may be cherry-picked
239from branch A). With this option, such pairs of commits are
240excluded from the output.
42cabc34 241
084ae0a7 242-g, --walk-reflogs::
911cedc9
JH
243
244 Instead of walking the commit ancestry chain, walk
245 reflog entries from the most recent one to older ones.
246 When this option is used you cannot specify commits to
247 exclude (that is, '{caret}commit', 'commit1..commit2',
248 nor 'commit1...commit2' notations cannot be used).
249+
250With '\--pretty' format other than oneline (for obvious reasons),
251this causes the output to have two extra lines of information
252taken from the reflog. By default, 'commit@{Nth}' notation is
253used in the output. When the starting commit is specified as
254'commit@{now}', output also uses 'commit@{timestamp}' notation
4d12a471
JH
255instead. Under '\--pretty=oneline', the commit message is
256prefixed with this information on the same line.
911cedc9 257
d249b455 258--merge::
8c02eee2 259
d249b455
UZ
260 After a failed merge, show refs that touch files having a
261 conflict and don't exist on all heads to merge.
262
8c02eee2
JF
263--boundary::
264
265 Output uninteresting commits at the boundary, which are usually
266 not shown.
267
268--dense, --sparse::
269
270When optional paths are given, the default behaviour ('--dense') is to
271only output commits that changes at least one of them, and also ignore
272merges that do not touch the given paths.
273
274Use the '--sparse' flag to makes the command output all eligible commits
275(still subject to count and age limitation), but apply merge
276simplification nevertheless.
277
278--bisect::
279
280Limit output to the one commit object which is roughly halfway between
281the included and excluded commits. Thus, if
282
283-----------------------------------------------------------------------
284 $ git-rev-list --bisect foo ^bar ^baz
285-----------------------------------------------------------------------
286
287outputs 'midpoint', the output of the two commands
288
289-----------------------------------------------------------------------
290 $ git-rev-list foo ^midpoint
291 $ git-rev-list midpoint ^bar ^baz
292-----------------------------------------------------------------------
293
294would be of roughly the same length. Finding the change which
295introduces a regression is thus reduced to a binary search: repeatedly
296generate and test new 'midpoint's until the commit chain is of length
297one.
298
457f08a0
JH
299--bisect-vars::
300
301This calculates the same as `--bisect`, but outputs text ready
302to be eval'ed by the shell. These lines will assign the name of
303the midpoint revision to the variable `bisect_rev`, and the
304expected number of commits to be tested after `bisect_rev` is
305tested to `bisect_nr`, the expected number of commits to be
306tested if `bisect_rev` turns out to be good to `bisect_good`,
307the expected number of commits to be tested if `bisect_rev`
308turns out to be bad to `bisect_bad`, and the number of commits
309we are bisecting right now to `bisect_all`.
310
8c02eee2
JF
311--
312
313Commit Ordering
314~~~~~~~~~~~~~~~
315
316By default, the commits are shown in reverse chronological order.
317
318--topo-order::
319
320 This option makes them appear in topological order (i.e.
321 descendant commits are shown before their parents).
322
323--date-order::
324
325 This option is similar to '--topo-order' in the sense that no
326 parent comes before all of its children, but otherwise things
327 are still ordered in the commit timestamp order.
328
9c5e66e9
JS
329--reverse::
330
331 Output the commits in reverse order.
332
8c02eee2
JF
333Object Traversal
334~~~~~~~~~~~~~~~~
335
336These options are mostly targeted for packing of git repositories.
337
338--objects::
339
340 Print the object IDs of any object referenced by the listed
341 commits. 'git-rev-list --objects foo ^bar' thus means "send me
342 all object IDs which I need to download if I have the commit
343 object 'bar', but not 'foo'".
344
345--objects-edge::
346
347 Similar to '--objects', but also print the IDs of excluded
348 commits prefixed with a "-" character. This is used by
349 gitlink:git-pack-objects[1] to build "thin" pack, which records
350 objects in deltified form based on objects contained in these
351 excluded commits to reduce network traffic.
352
353--unpacked::
354
355 Only useful with '--objects'; print the object IDs that are not
356 in packs.
3dfb9278 357
2cf565c5
DG
358Author
359------
360Written by Linus Torvalds <torvalds@osdl.org>
361
362Documentation
363--------------
8c02eee2
JF
364Documentation by David Greaves, Junio C Hamano, Jonas Fonseca
365and the git-list <git@vger.kernel.org>.
2cf565c5
DG
366
367GIT
368---
a7154e91 369Part of the gitlink:git[7] suite