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