init_buffer(): Kill buf pointer
[git/git.git] / 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 [ \--skip=number ]
14 [ \--max-age=timestamp ]
15 [ \--min-age=timestamp ]
16 [ \--sparse ]
17 [ \--no-merges ]
18 [ \--remove-empty ]
19 [ \--not ]
20 [ \--all ]
21 [ \--stdin ]
22 [ \--topo-order ]
23 [ \--parents ]
24 [ \--left-right ]
25 [ \--cherry-pick ]
26 [ \--encoding[=<encoding>] ]
27 [ \--(author|committer|grep)=<pattern> ]
28 [ [\--objects | \--objects-edge] [ \--unpacked ] ]
29 [ \--pretty | \--header ]
30 [ \--bisect ]
31 [ \--bisect-vars ]
32 [ \--merge ]
33 [ \--reverse ]
34 [ \--walk-reflogs ]
35 <commit>... [ \-- <paths>... ]
36
37 DESCRIPTION
38 -----------
39
40 Lists commit objects in reverse chronological order starting at the
41 given commit(s), taking ancestry relationship into account. This is
42 useful to produce human-readable log output.
43
44 Commits which are stated with a preceding '{caret}' cause listing to
45 stop at that point. Their parents are implied. Thus the following
46 command:
47
48 -----------------------------------------------------------------------
49 $ git-rev-list foo bar ^baz
50 -----------------------------------------------------------------------
51
52 means "list all the commits which are included in 'foo' and 'bar', but
53 not in 'baz'".
54
55 A special notation "'<commit1>'..'<commit2>'" can be used as a
56 short-hand for "{caret}'<commit1>' '<commit2>'". For example, either of
57 the following may be used interchangeably:
58
59 -----------------------------------------------------------------------
60 $ git-rev-list origin..HEAD
61 $ git-rev-list HEAD ^origin
62 -----------------------------------------------------------------------
63
64 Another special notation is "'<commit1>'...'<commit2>'" which is useful
65 for merges. The resulting set of commits is the symmetric difference
66 between the two operands. The following two commands are equivalent:
67
68 -----------------------------------------------------------------------
69 $ git-rev-list A B --not $(git-merge-base --all A B)
70 $ git-rev-list A...B
71 -----------------------------------------------------------------------
72
73 gitlink:git-rev-list[1] is a very essential git program, since it
74 provides the ability to build and traverse commit ancestry graphs. For
75 this reason, it has a lot of different options that enables it to be
76 used by commands as different as gitlink:git-bisect[1] and
77 gitlink:git-repack[1].
78
79 OPTIONS
80 -------
81
82 Commit Formatting
83 ~~~~~~~~~~~~~~~~~
84
85 Using these options, gitlink:git-rev-list[1] will act similar to the
86 more specialized family of commit log tools: gitlink:git-log[1],
87 gitlink:git-show[1], and gitlink:git-whatchanged[1]
88
89 include::pretty-formats.txt[]
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".
96
97 --header::
98
99 Print the contents of the commit in raw-format; each record is
100 separated with a NUL character.
101
102 --parents::
103
104 Print the parents of the commit.
105
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 +
113 For 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 +
123 you 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
136 Diff Formatting
137 ~~~~~~~~~~~~~~~
138
139 Below are listed options that control the formatting of diff output.
140 Some of them are specific to gitlink:git-rev-list[1], however other diff
141 options may be given. See gitlink:git-diff-files[1] for more options.
142
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
166 Commit Limiting
167 ~~~~~~~~~~~~~~~
168
169 Besides specifying a range of commits that should be listed using the
170 special notations explained in the description, additional commit
171 limiting may be applied.
172
173 --
174
175 -n 'number', --max-count='number'::
176
177 Limit the number of commits output.
178
179 --skip='number'::
180
181 Skip 'number' commits before starting to show the commit output.
182
183 --since='date', --after='date'::
184
185 Show commits more recent than a specific date.
186
187 --until='date', --before='date'::
188
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.
194
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
205 --remove-empty::
206
207 Stop when a given path disappears from the tree.
208
209 --no-merges::
210
211 Do not print commits with more than one parent.
212
213 --not::
214
215 Reverses the meaning of the '{caret}' prefix (or lack thereof)
216 for all following revision specifiers, up to the next '--not'.
217
218 --all::
219
220 Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the
221 command line as '<commit>'.
222
223 --stdin::
224
225 In addition to the '<commit>' listed on the command
226 line, read them from the standard input.
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 +
234 For example, if you have two branches, `A` and `B`, a usual way
235 to list all commits on only one side of them is with
236 `--left-right`, like the example above in the description of
237 that option. It however shows the commits that were cherry-picked
238 from the other branch (for example, "3rd on b" may be cherry-picked
239 from branch A). With this option, such pairs of commits are
240 excluded from the output.
241
242 -g, --walk-reflogs::
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 +
250 With '\--pretty' format other than oneline (for obvious reasons),
251 this causes the output to have two extra lines of information
252 taken from the reflog. By default, 'commit@{Nth}' notation is
253 used in the output. When the starting commit is specified as
254 'commit@{now}', output also uses 'commit@{timestamp}' notation
255 instead. Under '\--pretty=oneline', the commit message is
256 prefixed with this information on the same line.
257
258 --merge::
259
260 After a failed merge, show refs that touch files having a
261 conflict and don't exist on all heads to merge.
262
263 --boundary::
264
265 Output uninteresting commits at the boundary, which are usually
266 not shown.
267
268 --dense, --sparse::
269
270 When optional paths are given, the default behaviour ('--dense') is to
271 only output commits that changes at least one of them, and also ignore
272 merges that do not touch the given paths.
273
274 Use the '--sparse' flag to makes the command output all eligible commits
275 (still subject to count and age limitation), but apply merge
276 simplification nevertheless.
277
278 --bisect::
279
280 Limit output to the one commit object which is roughly halfway between
281 the included and excluded commits. Thus, if
282
283 -----------------------------------------------------------------------
284 $ git-rev-list --bisect foo ^bar ^baz
285 -----------------------------------------------------------------------
286
287 outputs 'midpoint', the output of the two commands
288
289 -----------------------------------------------------------------------
290 $ git-rev-list foo ^midpoint
291 $ git-rev-list midpoint ^bar ^baz
292 -----------------------------------------------------------------------
293
294 would be of roughly the same length. Finding the change which
295 introduces a regression is thus reduced to a binary search: repeatedly
296 generate and test new 'midpoint's until the commit chain is of length
297 one.
298
299 --bisect-vars::
300
301 This calculates the same as `--bisect`, but outputs text ready
302 to be eval'ed by the shell. These lines will assign the name of
303 the midpoint revision to the variable `bisect_rev`, and the
304 expected number of commits to be tested after `bisect_rev` is
305 tested to `bisect_nr`, the expected number of commits to be
306 tested if `bisect_rev` turns out to be good to `bisect_good`,
307 the expected number of commits to be tested if `bisect_rev`
308 turns out to be bad to `bisect_bad`, and the number of commits
309 we are bisecting right now to `bisect_all`.
310
311 --
312
313 Commit Ordering
314 ~~~~~~~~~~~~~~~
315
316 By 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
329 --reverse::
330
331 Output the commits in reverse order.
332
333 Object Traversal
334 ~~~~~~~~~~~~~~~~
335
336 These 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.
357
358 Author
359 ------
360 Written by Linus Torvalds <torvalds@osdl.org>
361
362 Documentation
363 --------------
364 Documentation by David Greaves, Junio C Hamano, Jonas Fonseca
365 and the git-list <git@vger.kernel.org>.
366
367 GIT
368 ---
369 Part of the gitlink:git[7] suite