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