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