revision.c: --reflog add HEAD reflog from all worktrees
[git/git.git] / Documentation / rev-list-options.txt
CommitLineData
fdcf39e5
MV
1Commit Limiting
2~~~~~~~~~~~~~~~
3
4Besides specifying a range of commits that should be listed using the
5special notations explained in the description, additional commit
a23e3138
JH
6limiting may be applied.
7
8Using more options generally further limits the output (e.g.
9`--since=<date1>` limits to commits newer than `<date1>`, and using it
10with `--grep=<pattern>` further limits to commits whose log message
11has a line that matches `<pattern>`), unless otherwise noted.
12
13Note that these are applied before commit
14ordering and formatting options, such as `--reverse`.
fdcf39e5
MV
15
16--
17
70c2a258
NTND
18-<number>::
19-n <number>::
982962ce 20--max-count=<number>::
841d8118 21 Limit the number of commits to output.
fdcf39e5 22
982962ce 23--skip=<number>::
fdcf39e5
MV
24 Skip 'number' commits before starting to show the commit output.
25
982962ce
MM
26--since=<date>::
27--after=<date>::
fdcf39e5
MV
28 Show commits more recent than a specific date.
29
982962ce
MM
30--until=<date>::
31--before=<date>::
fdcf39e5
MV
32 Show commits older than a specific date.
33
56b6d01d 34ifdef::git-rev-list[]
982962ce
MM
35--max-age=<timestamp>::
36--min-age=<timestamp>::
fdcf39e5 37 Limit the commits output to specified time range.
56b6d01d 38endif::git-rev-list[]
fdcf39e5 39
982962ce
MM
40--author=<pattern>::
41--committer=<pattern>::
fdcf39e5 42 Limit the commits output to ones with author/committer
a23e3138
JH
43 header lines that match the specified pattern (regular
44 expression). With more than one `--author=<pattern>`,
45 commits whose author matches any of the given patterns are
46 chosen (similarly for multiple `--committer=<pattern>`).
fdcf39e5 47
72fd13f7 48--grep-reflog=<pattern>::
72fd13f7
NTND
49 Limit the commits output to ones with reflog entries that
50 match the specified pattern (regular expression). With
51 more than one `--grep-reflog`, commits whose reflog message
baa6378f
JH
52 matches any of the given patterns are chosen. It is an
53 error to use this option unless `--walk-reflogs` is in use.
72fd13f7 54
982962ce 55--grep=<pattern>::
fdcf39e5 56 Limit the commits output to ones with log message that
a23e3138
JH
57 matches the specified pattern (regular expression). With
58 more than one `--grep=<pattern>`, commits whose message
59 matches any of the given patterns are chosen (but see
60 `--all-match`).
2aea7a51 61ifndef::git-rev-list[]
38cfe915 62+
7348cdeb
MG
63When `--show-notes` is in effect, the message from the notes is
64matched as if it were part of the log message.
2aea7a51 65endif::git-rev-list[]
fdcf39e5 66
7756ba74 67--all-match::
4528aa1a 68 Limit the commits output to ones that match all given `--grep`,
a23e3138 69 instead of ones that match at least one.
7756ba74 70
22dfa8a2
CJ
71--invert-grep::
72 Limit the commits output to ones with log message that do not
73 match the pattern specified with `--grep=<pattern>`.
74
3240240f
SB
75-i::
76--regexp-ignore-case::
19d6eb41
JSJ
77 Match the regular expression limiting patterns without regard to letter
78 case.
fdcf39e5 79
727b6fc3 80--basic-regexp::
727b6fc3
JH
81 Consider the limiting patterns to be basic regular expressions;
82 this is the default.
83
3240240f
SB
84-E::
85--extended-regexp::
fdcf39e5
MV
86 Consider the limiting patterns to be extended regular expressions
87 instead of the default basic regular expressions.
88
3240240f
SB
89-F::
90--fixed-strings::
dc1c0fff
JN
91 Consider the limiting patterns to be fixed strings (don't interpret
92 pattern as a regular expression).
93
7531a2dd 94-P::
727b6fc3 95--perl-regexp::
d048cb13
ÆAB
96 Consider the limiting patterns to be Perl-compatible regular
97 expressions.
98+
99Support for these types of regular expressions is an optional
100compile-time dependency. If Git wasn't compiled with support for them
101providing this option will cause it to die.
727b6fc3 102
fdcf39e5 103--remove-empty::
fdcf39e5
MV
104 Stop when a given path disappears from the tree.
105
2657420d 106--merges::
6a6ebded 107 Print only merge commits. This is exactly the same as `--min-parents=2`.
2657420d 108
fdcf39e5 109--no-merges::
6a6ebded
MG
110 Do not print commits with more than one parent. This is
111 exactly the same as `--max-parents=1`.
112
113--min-parents=<number>::
114--max-parents=<number>::
115--no-min-parents::
116--no-max-parents::
5104d21f 117 Show only commits which have at least (or at most) that many parent
6a6ebded
MG
118 commits. In particular, `--max-parents=1` is the same as `--no-merges`,
119 `--min-parents=2` is the same as `--merges`. `--max-parents=0`
120 gives all root commits and `--min-parents=3` all octopus merges.
121+
122`--no-min-parents` and `--no-max-parents` reset these limits (to no limit)
123again. Equivalent forms are `--min-parents=0` (any commit has 0 or more
124parents) and `--max-parents=-1` (negative numbers denote no upper limit).
fdcf39e5
MV
125
126--first-parent::
127 Follow only the first parent commit upon seeing a merge
128 commit. This option can give a better overview when
129 viewing the evolution of a particular topic branch,
130 because merges into a topic branch tend to be only about
131 adjusting to updated upstream from time to time, and
132 this option allows you to ignore the individual commits
f88851c6
KD
133 brought in to your history by such a merge. Cannot be
134 combined with --bisect.
fdcf39e5
MV
135
136--not::
fdcf39e5 137 Reverses the meaning of the '{caret}' prefix (or lack thereof)
4528aa1a 138 for all following revision specifiers, up to the next `--not`.
fdcf39e5
MV
139
140--all::
209df269
NTND
141 Pretend as if all the refs in `refs/`, along with `HEAD`, are
142 listed on the command line as '<commit>'.
c2e6385d 143
62b4698e 144--branches[=<pattern>]::
cc1b8d8b 145 Pretend as if all the refs in `refs/heads` are listed
62b4698e 146 on the command line as '<commit>'. If '<pattern>' is given, limit
b09fe971 147 branches to ones matching given shell glob. If pattern lacks '?',
e34bb2e7 148 '{asterisk}', or '[', '/{asterisk}' at the end is implied.
c2e6385d 149
62b4698e 150--tags[=<pattern>]::
cc1b8d8b 151 Pretend as if all the refs in `refs/tags` are listed
62b4698e 152 on the command line as '<commit>'. If '<pattern>' is given, limit
e34bb2e7
CMN
153 tags to ones matching given shell glob. If pattern lacks '?', '{asterisk}',
154 or '[', '/{asterisk}' at the end is implied.
c2e6385d 155
62b4698e 156--remotes[=<pattern>]::
cc1b8d8b 157 Pretend as if all the refs in `refs/remotes` are listed
62b4698e 158 on the command line as '<commit>'. If '<pattern>' is given, limit
0e615b25 159 remote-tracking branches to ones matching given shell glob.
e34bb2e7 160 If pattern lacks '?', '{asterisk}', or '[', '/{asterisk}' at the end is implied.
fdcf39e5 161
62b4698e
ŠN
162--glob=<glob-pattern>::
163 Pretend as if all the refs matching shell glob '<glob-pattern>'
d08bae7e 164 are listed on the command line as '<commit>'. Leading 'refs/',
e34bb2e7
CMN
165 is automatically prepended if missing. If pattern lacks '?', '{asterisk}',
166 or '[', '/{asterisk}' at the end is implied.
d08bae7e 167
574d370b
JS
168--exclude=<glob-pattern>::
169
170 Do not include refs matching '<glob-pattern>' that the next `--all`,
171 `--branches`, `--tags`, `--remotes`, or `--glob` would otherwise
172 consider. Repetitions of this option accumulate exclusion patterns
173 up to the next `--all`, `--branches`, `--tags`, `--remotes`, or
174 `--glob` option (other options or arguments do not clear
f745acb0 175 accumulated patterns).
574d370b
JS
176+
177The patterns given should not begin with `refs/heads`, `refs/tags`, or
178`refs/remotes` when applied to `--branches`, `--tags`, or `--remotes`,
179respectively, and they must begin with `refs/` when applied to `--glob`
180or `--all`. If a trailing '/{asterisk}' is intended, it must be given
181explicitly.
182
41d018d1
JK
183--reflog::
184 Pretend as if all objects mentioned by reflogs are listed on the
185 command line as `<commit>`.
186
cc243c3c 187--ignore-missing::
cc243c3c
JH
188 Upon seeing an invalid object name in the input, pretend as if
189 the bad input was not given.
d08bae7e 190
af06e93a
CC
191ifndef::git-rev-list[]
192--bisect::
cc1b8d8b 193 Pretend as if the bad bisection ref `refs/bisect/bad`
af06e93a 194 was listed and as if it was followed by `--not` and the good
cc1b8d8b 195 bisection refs `refs/bisect/good-*` on the command
f88851c6 196 line. Cannot be combined with --first-parent.
af06e93a
CC
197endif::git-rev-list[]
198
fdcf39e5 199--stdin::
fdcf39e5 200 In addition to the '<commit>' listed on the command
04b125de 201 line, read them from the standard input. If a `--` separator is
60da8b15
JH
202 seen, stop reading commits and start reading paths to limit the
203 result.
fdcf39e5 204
8b3dce56 205ifdef::git-rev-list[]
fdcf39e5 206--quiet::
fdcf39e5
MV
207 Don't print anything to standard output. This form
208 is primarily meant to allow the caller to
209 test the exit status to see if a range of objects is fully
210 connected (or not). It is faster than redirecting stdout
4528aa1a 211 to `/dev/null` as the output does not have to be formatted.
adf60f14 212endif::git-rev-list[]
fdcf39e5 213
cb56e309 214--cherry-mark::
cb56e309
MG
215 Like `--cherry-pick` (see below) but mark equivalent commits
216 with `=` rather than omitting them, and inequivalent ones with `+`.
217
fdcf39e5 218--cherry-pick::
fdcf39e5 219 Omit any commit that introduces the same change as
4528aa1a 220 another commit on the ``other side'' when the set of
fdcf39e5
MV
221 commits are limited with symmetric difference.
222+
223For example, if you have two branches, `A` and `B`, a usual way
224to list all commits on only one side of them is with
3add01bb 225`--left-right` (see the example below in the description of
19d6eb41
JSJ
226the `--left-right` option). However, it shows the commits that were
227cherry-picked from the other branch (for example, ``3rd on b'' may be
228cherry-picked from branch A). With this option, such pairs of commits are
fdcf39e5
MV
229excluded from the output.
230
59c8afdf
MG
231--left-only::
232--right-only::
27ac8371 233 List only commits on the respective side of a symmetric difference,
59c8afdf
MG
234 i.e. only those which would be marked `<` resp. `>` by
235 `--left-right`.
236+
237For example, `--cherry-pick --right-only A...B` omits those
238commits from `B` which are in `A` or are patch-equivalent to a commit in
6cf378f0 239`A`. In other words, this lists the `+` commits from `git cherry A B`.
59c8afdf
MG
240More precisely, `--cherry-pick --right-only --no-merges` gives the exact
241list.
242
94f605ec 243--cherry::
94f605ec
MG
244 A synonym for `--right-only --cherry-mark --no-merges`; useful to
245 limit the output to the commits on our side and mark those that
246 have been applied to the other side of a forked history with
247 `git log --cherry upstream...mybranch`, similar to
248 `git cherry upstream mybranch`.
249
3240240f
SB
250-g::
251--walk-reflogs::
fdcf39e5
MV
252 Instead of walking the commit ancestry chain, walk
253 reflog entries from the most recent one to older ones.
254 When this option is used you cannot specify commits to
255 exclude (that is, '{caret}commit', 'commit1..commit2',
a58088ab 256 and 'commit1\...commit2' notations cannot be used).
fdcf39e5 257+
4528aa1a 258With `--pretty` format other than `oneline` (for obvious reasons),
fdcf39e5 259this causes the output to have two extra lines of information
83c9f95c
JK
260taken from the reflog. The reflog designator in the output may be shown
261as `ref@{Nth}` (where `Nth` is the reverse-chronological index in the
262reflog) or as `ref@{timestamp}` (with the timestamp for that entry),
263depending on a few rules:
264+
265--
2661. If the starting point is specified as `ref@{Nth}`, show the index
267format.
268+
2692. If the starting point was specified as `ref@{now}`, show the
270timestamp format.
271+
2723. If neither was used, but `--date` was given on the command line, show
273the timestamp in the format requested by `--date`.
274+
2754. Otherwise, show the index format.
276--
277+
278Under `--pretty=oneline`, the commit message is
fdcf39e5 279prefixed with this information on the same line.
4528aa1a 280This option cannot be combined with `--reverse`.
fdcf39e5
MV
281See also linkgit:git-reflog[1].
282
283--merge::
fdcf39e5
MV
284 After a failed merge, show refs that touch files having a
285 conflict and don't exist on all heads to merge.
286
287--boundary::
e32db66d
KB
288 Output excluded boundary commits. Boundary commits are
289 prefixed with `-`.
fdcf39e5 290
aa32939f
VM
291ifdef::git-rev-list[]
292--use-bitmap-index::
293
294 Try to speed up the traversal using the pack bitmap index (if
295 one is available). Note that when traversing with `--objects`,
296 trees and blobs will not have their associated path printed.
434ea3cd
JK
297
298--progress=<header>::
299 Show progress reports on stderr as objects are considered. The
300 `<header>` text will be printed with each progress update.
aa32939f
VM
301endif::git-rev-list[]
302
70d9895e
TR
303--
304
305History Simplification
306~~~~~~~~~~~~~~~~~~~~~~
307
7bc2508b
SB
308Sometimes you are only interested in parts of the history, for example the
309commits modifying a particular <path>. But there are two parts of
310'History Simplification', one part is selecting the commits and the other
311is how to do it, as there are various strategies to simplify the history.
312
313The following options select the commits to be shown:
314
315<paths>::
7bc2508b
SB
316 Commits modifying the given <paths> are selected.
317
318--simplify-by-decoration::
7bc2508b
SB
319 Commits that are referred by some branch or tag are selected.
320
321Note that extra commits can be shown to give a meaningful history.
322
323The following options affect the way the simplification is performed:
324
325Default mode::
7bc2508b
SB
326 Simplifies the history to the simplest history explaining the
327 final state of the tree. Simplest because it prunes some side
328 branches if the end result is the same (i.e. merging branches
329 with the same content)
330
331--full-history::
df6b0cad 332 Same as the default mode, but does not prune some history.
7bc2508b
SB
333
334--dense::
7bc2508b
SB
335 Only the selected commits are shown, plus some to have a
336 meaningful history.
337
338--sparse::
7bc2508b
SB
339 All commits in the simplified history are shown.
340
341--simplify-merges::
4528aa1a 342 Additional option to `--full-history` to remove some needless
7bc2508b
SB
343 merges from the resulting history, as there are no selected
344 commits contributing to this merge.
345
57456ef4 346--ancestry-path::
57456ef4
JH
347 When given a range of commits to display (e.g. 'commit1..commit2'
348 or 'commit2 {caret}commit1'), only display commits that exist
349 directly on the ancestry chain between the 'commit1' and
350 'commit2', i.e. commits that are both descendants of 'commit1',
351 and ancestors of 'commit2'.
352
7bc2508b 353A more detailed explanation follows.
70d9895e
TR
354
355Suppose you specified `foo` as the <paths>. We shall call commits
356that modify `foo` !TREESAME, and the rest TREESAME. (In a diff
357filtered for `foo`, they look different and equal, respectively.)
358
359In the following, we will always refer to the same example history to
360illustrate the differences between simplification settings. We assume
361that you are filtering for a file `foo` in this commit graph:
362-----------------------------------------------------------------------
143f1eaf
KB
363 .-A---M---N---O---P---Q
364 / / / / / /
365 I B C D E Y
366 \ / / / / /
367 `-------------' X
70d9895e 368-----------------------------------------------------------------------
143f1eaf 369The horizontal line of history A---Q is taken to be the first parent of
70d9895e
TR
370each merge. The commits are:
371
372* `I` is the initial commit, in which `foo` exists with contents
4528aa1a 373 ``asdf'', and a file `quux` exists with contents ``quux''. Initial
70d9895e
TR
374 commits are compared to an empty tree, so `I` is !TREESAME.
375
4528aa1a 376* In `A`, `foo` contains just ``foo''.
70d9895e
TR
377
378* `B` contains the same change as `A`. Its merge `M` is trivial and
379 hence TREESAME to all parents.
380
4528aa1a 381* `C` does not change `foo`, but its merge `N` changes it to ``foobar'',
70d9895e
TR
382 so it is not TREESAME to any parent.
383
4528aa1a
JSJ
384* `D` sets `foo` to ``baz''. Its merge `O` combines the strings from
385 `N` and `D` to ``foobarbaz''; i.e., it is not TREESAME to any parent.
70d9895e 386
4528aa1a
JSJ
387* `E` changes `quux` to ``xyzzy'', and its merge `P` combines the
388 strings to ``quux xyzzy''. `P` is TREESAME to `O`, but not to `E`.
70d9895e 389
17b83d71 390* `X` is an independent root commit that added a new file `side`, and `Y`
143f1eaf
KB
391 modified it. `Y` is TREESAME to `X`. Its merge `Q` added `side` to `P`, and
392 `Q` is TREESAME to `P`, but not to `Y`.
393
4528aa1a
JSJ
394`rev-list` walks backwards through history, including or excluding
395commits based on whether `--full-history` and/or parent rewriting
396(via `--parents` or `--children`) are used. The following settings
70d9895e
TR
397are available.
398
399Default mode::
70d9895e 400 Commits are included if they are not TREESAME to any parent
4528aa1a 401 (though this can be changed, see `--sparse` below). If the
70d9895e
TR
402 commit was a merge, and it was TREESAME to one parent, follow
403 only that parent. (Even if there are several TREESAME
404 parents, follow only one of them.) Otherwise, follow all
405 parents.
406+
407This results in:
408+
409-----------------------------------------------------------------------
410 .-A---N---O
f70d0586 411 / / /
70d9895e
TR
412 I---------D
413-----------------------------------------------------------------------
414+
415Note how the rule to only follow the TREESAME parent, if one is
416available, removed `B` from consideration entirely. `C` was
417considered via `N`, but is TREESAME. Root commits are compared to an
418empty tree, so `I` is !TREESAME.
419+
4528aa1a 420Parent/child relations are only visible with `--parents`, but that does
70d9895e
TR
421not affect the commits selected in default mode, so we have shown the
422parent lines.
423
424--full-history without parent rewriting::
70d9895e
TR
425 This mode differs from the default in one point: always follow
426 all parents of a merge, even if it is TREESAME to one of them.
427 Even if more than one side of the merge has commits that are
428 included, this does not imply that the merge itself is! In
429 the example, we get
430+
431-----------------------------------------------------------------------
143f1eaf 432 I A B N D O P Q
70d9895e
TR
433-----------------------------------------------------------------------
434+
d0af663e 435`M` was excluded because it is TREESAME to both parents. `E`,
70d9895e
TR
436`C` and `B` were all walked, but only `B` was !TREESAME, so the others
437do not appear.
438+
439Note that without parent rewriting, it is not really possible to talk
440about the parent/child relationships between the commits, so we show
441them disconnected.
442
443--full-history with parent rewriting::
70d9895e 444 Ordinary commits are only included if they are !TREESAME
4528aa1a 445 (though this can be changed, see `--sparse` below).
70d9895e
TR
446+
447Merges are always included. However, their parent list is rewritten:
448Along each parent, prune away commits that are not included
449themselves. This results in
450+
451-----------------------------------------------------------------------
143f1eaf 452 .-A---M---N---O---P---Q
70d9895e
TR
453 / / / / /
454 I B / D /
455 \ / / / /
456 `-------------'
457-----------------------------------------------------------------------
458+
4528aa1a 459Compare to `--full-history` without rewriting above. Note that `E`
70d9895e
TR
460was pruned away because it is TREESAME, but the parent list of P was
461rewritten to contain `E`'s parent `I`. The same happened for `C` and
143f1eaf 462`N`, and `X`, `Y` and `Q`.
70d9895e
TR
463
464In addition to the above settings, you can change whether TREESAME
465affects inclusion:
466
3240240f 467--dense::
70d9895e
TR
468 Commits that are walked are included if they are not TREESAME
469 to any parent.
470
3240240f 471--sparse::
70d9895e
TR
472 All commits that are walked are included.
473+
4528aa1a 474Note that without `--full-history`, this still simplifies merges: if
70d9895e
TR
475one of the parents is TREESAME, we follow only that one, so the other
476sides of the merge are never walked.
fdcf39e5 477
d266a988 478--simplify-merges::
d266a988 479 First, build a history graph in the same way that
4528aa1a 480 `--full-history` with parent rewriting does (see above).
d266a988
TR
481+
482Then simplify each commit `C` to its replacement `C'` in the final
483history according to the following rules:
484+
485--
486* Set `C'` to `C`.
487+
488* Replace each parent `P` of `C'` with its simplification `P'`. In
143f1eaf
KB
489 the process, drop parents that are ancestors of other parents or that are
490 root commits TREESAME to an empty tree, and remove duplicates, but take care
491 to never drop all parents that we are TREESAME to.
d266a988
TR
492+
493* If after this parent rewriting, `C'` is a root or merge commit (has
494 zero or >1 parents), a boundary commit, or !TREESAME, it remains.
495 Otherwise, it is replaced with its only parent.
496--
497+
498The effect of this is best shown by way of comparing to
4528aa1a 499`--full-history` with parent rewriting. The example turns into:
d266a988
TR
500+
501-----------------------------------------------------------------------
502 .-A---M---N---O
503 / / /
504 I B D
505 \ / /
506 `---------'
507-----------------------------------------------------------------------
508+
19d6eb41 509Note the major differences in `N`, `P`, and `Q` over `--full-history`:
d266a988
TR
510+
511--
512* `N`'s parent list had `I` removed, because it is an ancestor of the
513 other parent `M`. Still, `N` remained because it is !TREESAME.
514+
515* `P`'s parent list similarly had `I` removed. `P` was then
516 removed completely, because it had one parent and is TREESAME.
143f1eaf
KB
517+
518* `Q`'s parent list had `Y` simplified to `X`. `X` was then removed, because it
519 was a TREESAME root. `Q` was then removed completely, because it had one
520 parent and is TREESAME.
d266a988 521--
fdcf39e5 522
57456ef4
JH
523Finally, there is a fifth simplification mode available:
524
525--ancestry-path::
57456ef4 526 Limit the displayed commits to those directly on the ancestry
4528aa1a
JSJ
527 chain between the ``from'' and ``to'' commits in the given commit
528 range. I.e. only display commits that are ancestor of the ``to''
19d6eb41 529 commit and descendants of the ``from'' commit.
57456ef4
JH
530+
531As an example use case, consider the following commit history:
532+
533-----------------------------------------------------------------------
534 D---E-------F
535 / \ \
536 B---C---G---H---I---J
537 / \
538 A-------K---------------L--M
539-----------------------------------------------------------------------
540+
541A regular 'D..M' computes the set of commits that are ancestors of `M`,
542but excludes the ones that are ancestors of `D`. This is useful to see
543what happened to the history leading to `M` since `D`, in the sense
4528aa1a 544that ``what does `M` have that did not exist in `D`''. The result in this
57456ef4
JH
545example would be all the commits, except `A` and `B` (and `D` itself,
546of course).
547+
548When we want to find out what commits in `M` are contaminated with the
549bug introduced by `D` and need fixing, however, we might want to view
550only the subset of 'D..M' that are actually descendants of `D`, i.e.
4528aa1a 551excluding `C` and `K`. This is exactly what the `--ancestry-path`
57456ef4
JH
552option does. Applied to the 'D..M' range, it results in:
553+
554-----------------------------------------------------------------------
555 E-------F
556 \ \
557 G---H---I---J
558 \
559 L--M
560-----------------------------------------------------------------------
561
4528aa1a 562The `--simplify-by-decoration` option allows you to view only the
3fcfd662
NS
563big picture of the topology of the history, by omitting commits
564that are not referenced by tags. Commits are marked as !TREESAME
565(in other words, kept after history simplification rules described
566above) if (1) they are referenced by tags, or (2) they change the
567contents of the paths given on the command line. All other
568commits are marked as TREESAME (subject to be simplified away).
569
fdcf39e5 570ifdef::git-rev-list[]
70d9895e
TR
571Bisection Helpers
572~~~~~~~~~~~~~~~~~
573
fdcf39e5 574--bisect::
4528aa1a
JSJ
575 Limit output to the one commit object which is roughly halfway between
576 included and excluded commits. Note that the bad bisection ref
577 `refs/bisect/bad` is added to the included commits (if it
578 exists) and the good bisection refs `refs/bisect/good-*` are
579 added to the excluded commits (if they exist). Thus, supposing there
580 are no refs in `refs/bisect/`, if
581+
fdcf39e5 582-----------------------------------------------------------------------
6514aa36 583 $ git rev-list --bisect foo ^bar ^baz
fdcf39e5 584-----------------------------------------------------------------------
4528aa1a 585+
fdcf39e5 586outputs 'midpoint', the output of the two commands
4528aa1a 587+
fdcf39e5 588-----------------------------------------------------------------------
6514aa36
CC
589 $ git rev-list foo ^midpoint
590 $ git rev-list midpoint ^bar ^baz
fdcf39e5 591-----------------------------------------------------------------------
4528aa1a 592+
fdcf39e5
MV
593would be of roughly the same length. Finding the change which
594introduces a regression is thus reduced to a binary search: repeatedly
595generate and test new 'midpoint's until the commit chain is of length
f88851c6 596one. Cannot be combined with --first-parent.
fdcf39e5
MV
597
598--bisect-vars::
4528aa1a
JSJ
599 This calculates the same as `--bisect`, except that refs in
600 `refs/bisect/` are not used, and except that this outputs
601 text ready to be eval'ed by the shell. These lines will assign the
602 name of the midpoint revision to the variable `bisect_rev`, and the
603 expected number of commits to be tested after `bisect_rev` is tested
604 to `bisect_nr`, the expected number of commits to be tested if
605 `bisect_rev` turns out to be good to `bisect_good`, the expected
606 number of commits to be tested if `bisect_rev` turns out to be bad to
607 `bisect_bad`, and the number of commits we are bisecting right now to
608 `bisect_all`.
fdcf39e5
MV
609
610--bisect-all::
4528aa1a
JSJ
611 This outputs all the commit objects between the included and excluded
612 commits, ordered by their distance to the included and excluded
613 commits. Refs in `refs/bisect/` are not used. The farthest
614 from them is displayed first. (This is the only one displayed by
615 `--bisect`.)
3d2d4f96 616+
fdcf39e5
MV
617This is useful because it makes it easy to choose a good commit to
618test when you want to avoid to test some of them for some reason (they
619may not compile for example).
3d2d4f96 620+
fdcf39e5
MV
621This option can be used along with `--bisect-vars`, in this case,
622after all the sorted commit objects, there will be the same text as if
623`--bisect-vars` had been used alone.
624endif::git-rev-list[]
625
fdcf39e5
MV
626
627Commit Ordering
628~~~~~~~~~~~~~~~
629
630By default, the commits are shown in reverse chronological order.
631
3f0350cc
JH
632--date-order::
633 Show no parents before all of its children are shown, but
634 otherwise show commits in the commit timestamp order.
fdcf39e5 635
81c6b38b
JH
636--author-date-order::
637 Show no parents before all of its children are shown, but
638 otherwise show commits in the author timestamp order.
639
3f0350cc
JH
640--topo-order::
641 Show no parents before all of its children are shown, and
642 avoid showing commits on multiple lines of history
643 intermixed.
644+
645For example, in a commit history like this:
646+
647----------------------------------------------------------------
fdcf39e5 648
3f0350cc
JH
649 ---1----2----4----7
650 \ \
651 3----5----6----8---
fdcf39e5 652
3f0350cc
JH
653----------------------------------------------------------------
654+
655where the numbers denote the order of commit timestamps, `git
656rev-list` and friends with `--date-order` show the commits in the
657timestamp order: 8 7 6 5 4 3 2 1.
658+
659With `--topo-order`, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5
6603 1); some older commits are shown before newer ones in order to
661avoid showing the commits from two parallel development track mixed
662together.
fdcf39e5
MV
663
664--reverse::
04be6947
PB
665 Output the commits chosen to be shown (see Commit Limiting
666 section above) in reverse order. Cannot be combined with
667 `--walk-reflogs`.
fdcf39e5
MV
668
669Object Traversal
670~~~~~~~~~~~~~~~~
671
2de9b711 672These options are mostly targeted for packing of Git repositories.
fdcf39e5 673
3cab02de 674ifdef::git-rev-list[]
fdcf39e5 675--objects::
fdcf39e5 676 Print the object IDs of any object referenced by the listed
4528aa1a 677 commits. `--objects foo ^bar` thus means ``send me
fdcf39e5 678 all object IDs which I need to download if I have the commit
4528aa1a 679 object _bar_ but not _foo_''.
fdcf39e5
MV
680
681--objects-edge::
4528aa1a
JSJ
682 Similar to `--objects`, but also print the IDs of excluded
683 commits prefixed with a ``-'' character. This is used by
8297643f 684 linkgit:git-pack-objects[1] to build a ``thin'' pack, which records
fdcf39e5
MV
685 objects in deltified form based on objects contained in these
686 excluded commits to reduce network traffic.
687
1684c1b2 688--objects-edge-aggressive::
689 Similar to `--objects-edge`, but it tries harder to find excluded
2dacf26d 690 commits at the cost of increased time. This is used instead of
691 `--objects-edge` to build ``thin'' packs for shallow repositories.
1684c1b2 692
3cab02de
JH
693--indexed-objects::
694 Pretend as if all trees and blobs used by the index are listed
695 on the command line. Note that you probably want to use
696 `--objects`, too.
697
fdcf39e5 698--unpacked::
4528aa1a 699 Only useful with `--objects`; print the object IDs that are not
fdcf39e5 700 in packs.
3cab02de 701endif::git-rev-list[]
fdcf39e5 702
ca92e59e 703--no-walk[=(sorted|unsorted)]::
ca92e59e
MZ
704 Only show the given commits, but do not traverse their ancestors.
705 This has no effect if a range is specified. If the argument
19d6eb41 706 `unsorted` is given, the commits are shown in the order they were
4528aa1a 707 given on the command line. Otherwise (if `sorted` or no argument
19d6eb41 708 was given), the commits are shown in reverse chronological order
ca92e59e 709 by commit time.
695985f4 710 Cannot be combined with `--graph`.
fdcf39e5
MV
711
712--do-walk::
4528aa1a 713 Overrides a previous `--no-walk`.
f98fd436
MG
714
715Commit Formatting
716~~~~~~~~~~~~~~~~~
717
718ifdef::git-rev-list[]
719Using these options, linkgit:git-rev-list[1] will act similar to the
720more specialized family of commit log tools: linkgit:git-log[1],
721linkgit:git-show[1], and linkgit:git-whatchanged[1]
722endif::git-rev-list[]
723
724include::pretty-options.txt[]
725
726--relative-date::
f98fd436
MG
727 Synonym for `--date=relative`.
728
4b1c5e1d 729--date=<format>::
f98fd436 730 Only takes effect for dates shown in human-readable format, such
4528aa1a 731 as when using `--pretty`. `log.date` config variable sets a default
add00ba2
JK
732 value for the log command's `--date` option. By default, dates
733 are shown in the original time zone (either committer's or
734 author's). If `-local` is appended to the format (e.g.,
735 `iso-local`), the user's local time zone is used instead.
f98fd436
MG
736+
737`--date=relative` shows dates relative to the current time,
1a2a1e8e
JK
738e.g. ``2 hours ago''. The `-local` option has no effect for
739`--date=relative`.
f98fd436 740+
add00ba2 741`--date=local` is an alias for `--date=default-local`.
f98fd436 742+
466fb674
BB
743`--date=iso` (or `--date=iso8601`) shows timestamps in a ISO 8601-like format.
744The differences to the strict ISO 8601 format are:
745
746 - a space instead of the `T` date/time delimiter
747 - a space between time and time zone
748 - no colon between hours and minutes of the time zone
749
750+
751`--date=iso-strict` (or `--date=iso8601-strict`) shows timestamps in strict
752ISO 8601 format.
f98fd436
MG
753+
754`--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822
19d6eb41 755format, often found in email messages.
f98fd436 756+
19d6eb41 757`--date=short` shows only the date, but not the time, in `YYYY-MM-DD` format.
f98fd436 758+
442f6fd3
JH
759`--date=raw` shows the date as seconds since the epoch (1970-01-01
76000:00:00 UTC), followed by a space, and then the timezone as an offset
761from UTC (a `+` or `-` with four digits; the first two are hours, and
762the second two are minutes). I.e., as if the timestamp were formatted
763with `strftime("%s %z")`).
1a2a1e8e
JK
764Note that the `-local` option does not affect the seconds-since-epoch
765value (which is always measured in UTC), but does switch the accompanying
766timezone value.
f98fd436 767+
642833db
JK
768`--date=unix` shows the date as a Unix epoch timestamp (seconds since
7691970). As with `--raw`, this is always in UTC and therefore `-local`
770has no effect.
f98fd436 771+
c3fbf81a
RS
772`--date=format:...` feeds the format `...` to your system `strftime`,
773except for %z and %Z, which are handled internally.
aa1462cc
JK
774Use `--date=format:%c` to show the date in your system locale's
775preferred format. See the `strftime` manual for a complete list of
add00ba2
JK
776format placeholders. When using `-local`, the correct syntax is
777`--date=format-local:...`.
aa1462cc 778+
add00ba2
JK
779`--date=default` is the default format, and is similar to
780`--date=rfc2822`, with a few exceptions:
781
782 - there is no comma after the day-of-week
783
784 - the time zone is omitted when the local time zone is used
f98fd436
MG
785
786ifdef::git-rev-list[]
787--header::
f98fd436
MG
788 Print the contents of the commit in raw-format; each record is
789 separated with a NUL character.
790endif::git-rev-list[]
791
792--parents::
f98fd436
MG
793 Print also the parents of the commit (in the form "commit parent...").
794 Also enables parent rewriting, see 'History Simplification' below.
795
796--children::
f98fd436
MG
797 Print also the children of the commit (in the form "commit child...").
798 Also enables parent rewriting, see 'History Simplification' below.
799
800ifdef::git-rev-list[]
801--timestamp::
802 Print the raw commit timestamp.
803endif::git-rev-list[]
804
805--left-right::
27ac8371 806 Mark which side of a symmetric difference a commit is reachable from.
f98fd436
MG
807 Commits from the left side are prefixed with `<` and those from
808 the right with `>`. If combined with `--boundary`, those
809 commits are prefixed with `-`.
810+
811For example, if you have this topology:
812+
813-----------------------------------------------------------------------
814 y---b---b branch B
815 / \ /
816 / .
817 / / \
818 o---x---a---a branch A
819-----------------------------------------------------------------------
820+
821you would get an output like this:
822+
823-----------------------------------------------------------------------
824 $ git rev-list --left-right --boundary --pretty=oneline A...B
825
826 >bbbbbbb... 3rd on b
827 >bbbbbbb... 2nd on b
828 <aaaaaaa... 3rd on a
829 <aaaaaaa... 2nd on a
830 -yyyyyyy... 1st on b
831 -xxxxxxx... 1st on a
832-----------------------------------------------------------------------
833
834--graph::
f98fd436
MG
835 Draw a text-based graphical representation of the commit history
836 on the left hand side of the output. This may cause extra lines
837 to be printed in between commits, in order for the graph history
838 to be drawn properly.
695985f4 839 Cannot be combined with `--no-walk`.
f98fd436
MG
840+
841This enables parent rewriting, see 'History Simplification' below.
842+
4528aa1a
JSJ
843This implies the `--topo-order` option by default, but the
844`--date-order` option may also be specified.
f98fd436 845
1b32dece
NTND
846--show-linear-break[=<barrier>]::
847 When --graph is not used, all history branches are flattened
848 which can make it hard to see that the two consecutive commits
849 do not belong to a linear branch. This option puts a barrier
850 in between them in that case. If `<barrier>` is specified, it
851 is the string that will be shown instead of the default one.
852
f98fd436
MG
853ifdef::git-rev-list[]
854--count::
855 Print a number stating how many commits would have been
856 listed, and suppress all other output. When used together
4528aa1a 857 with `--left-right`, instead print the counts for left and
b388e14b 858 right commits, separated by a tab. When used together with
4528aa1a 859 `--cherry-mark`, omit patch equivalent commits from these
b388e14b
MG
860 counts and print the count for equivalent commits separated
861 by a tab.
f98fd436
MG
862endif::git-rev-list[]
863
f98fd436
MG
864ifndef::git-rev-list[]
865Diff Formatting
866~~~~~~~~~~~~~~~
867
19d6eb41 868Listed below are options that control the formatting of diff output.
f98fd436
MG
869Some of them are specific to linkgit:git-rev-list[1], however other diff
870options may be given. See linkgit:git-diff-files[1] for more options.
871
872-c::
f98fd436
MG
873 With this option, diff output for a merge commit
874 shows the differences from each of the parents to the merge result
875 simultaneously instead of showing pairwise diff between a parent
876 and the result one at a time. Furthermore, it lists only files
877 which were modified from all parents.
878
879--cc::
4528aa1a 880 This flag implies the `-c` option and further compresses the
f98fd436
MG
881 patch output by omitting uninteresting hunks whose contents in
882 the parents have only two variants and the merge result picks
883 one of them without modification.
884
885-m::
f98fd436
MG
886 This flag makes the merge commits show the full diff like
887 regular commits; for each merge parent, a separate log entry
888 and diff is generated. An exception is that only diff against
4528aa1a 889 the first parent is shown when `--first-parent` option is given;
f98fd436
MG
890 in that case, the output represents the changes the merge
891 brought _into_ the then-current branch.
892
893-r::
f98fd436
MG
894 Show recursive diffs.
895
896-t::
4528aa1a 897 Show the tree objects in the diff output. This implies `-r`.
f98fd436 898endif::git-rev-list[]