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