Merge branch 'master' into next
[git/wpalmer.git] / Documentation / rev-list-options.txt
blobb9fb7a86bd4bf91205b77275fb51ff13a3bc5622
1 Commit Formatting
2 ~~~~~~~~~~~~~~~~~
4 ifdef::git-rev-list[]
5 Using these options, linkgit:git-rev-list[1] will act similar to the
6 more specialized family of commit log tools: linkgit:git-log[1],
7 linkgit:git-show[1], and linkgit:git-whatchanged[1]
8 endif::git-rev-list[]
10 include::pretty-options.txt[]
12 --relative-date::
14         Synonym for `--date=relative`.
16 --date={relative,local,default,iso,rfc,short,raw}::
18         Only takes effect for dates shown in human-readable format, such
19         as when using "--pretty". `log.date` config variable sets a default
20         value for log command's --date option.
22 `--date=relative` shows dates relative to the current time,
23 e.g. "2 hours ago".
25 `--date=local` shows timestamps in user's local timezone.
27 `--date=iso` (or `--date=iso8601`) shows timestamps in ISO 8601 format.
29 `--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822
30 format, often found in E-mail messages.
32 `--date=short` shows only date but not time, in `YYYY-MM-DD` format.
34 `--date=raw` shows the date in the internal raw git format `%s %z` format.
36 `--date=default` shows timestamps in the original timezone
37 (either committer's or author's).
39 ifdef::git-rev-list[]
40 --header::
42         Print the contents of the commit in raw-format; each record is
43         separated with a NUL character.
44 endif::git-rev-list[]
46 --parents::
48         Print the parents of the commit.  Also enables parent
49         rewriting, see 'History Simplification' below.
51 --children::
53         Print the children of the commit.  Also enables parent
54         rewriting, see 'History Simplification' below.
56 ifdef::git-rev-list[]
57 --timestamp::
58         Print the raw commit timestamp.
59 endif::git-rev-list[]
61 --left-right::
63         Mark which side of a symmetric diff a commit is reachable from.
64         Commits from the left side are prefixed with `<` and those from
65         the right with `>`.  If combined with `--boundary`, those
66         commits are prefixed with `-`.
68 For example, if you have this topology:
70 -----------------------------------------------------------------------
71              y---b---b  branch B
72             / \ /
73            /   .
74           /   / \
75          o---x---a---a  branch A
76 -----------------------------------------------------------------------
78 you would get an output like this:
80 -----------------------------------------------------------------------
81         $ git rev-list --left-right --boundary --pretty=oneline A...B
83         >bbbbbbb... 3rd on b
84         >bbbbbbb... 2nd on b
85         <aaaaaaa... 3rd on a
86         <aaaaaaa... 2nd on a
87         -yyyyyyy... 1st on b
88         -xxxxxxx... 1st on a
89 -----------------------------------------------------------------------
91 --graph::
93         Draw a text-based graphical representation of the commit history
94         on the left hand side of the output.  This may cause extra lines
95         to be printed in between commits, in order for the graph history
96         to be drawn properly.
98 This implies the '--topo-order' option by default, but the
99 '--date-order' option may also be specified.
101 ifndef::git-rev-list[]
102 Diff Formatting
103 ~~~~~~~~~~~~~~~
105 Below are listed options that control the formatting of diff output.
106 Some of them are specific to linkgit:git-rev-list[1], however other diff
107 options may be given. See linkgit:git-diff-files[1] for more options.
109 -c::
111         With this option, diff output for a merge commit
112         shows the differences from each of the parents to the merge result
113         simultaneously instead of showing pairwise diff between a parent
114         and the result one at a time. Furthermore, it lists only files
115         which were modified from all parents.
117 --cc::
119         This flag implies the '-c' options and further compresses the
120         patch output by omitting uninteresting hunks whose contents in
121         the parents have only two variants and the merge result picks
122         one of them without modification.
124 -m::
126         This flag makes the merge commits show the full diff like
127         regular commits; for each merge parent, a separate log entry
128         and diff is generated. An exception is that only diff against
129         the first parent is shown when '--first-parent' option is given;
130         in that case, the output represents the changes the merge
131         brought _into_ the then-current branch.
133 -r::
135         Show recursive diffs.
137 -t::
139         Show the tree objects in the diff output. This implies '-r'.
140 endif::git-rev-list[]
142 Commit Limiting
143 ~~~~~~~~~~~~~~~
145 Besides specifying a range of commits that should be listed using the
146 special notations explained in the description, additional commit
147 limiting may be applied.
151 -n 'number'::
152 --max-count=<number>::
154         Limit the number of commits output.
156 --skip=<number>::
158         Skip 'number' commits before starting to show the commit output.
160 --since=<date>::
161 --after=<date>::
163         Show commits more recent than a specific date.
165 --until=<date>::
166 --before=<date>::
168         Show commits older than a specific date.
170 ifdef::git-rev-list[]
171 --max-age=<timestamp>::
172 --min-age=<timestamp>::
174         Limit the commits output to specified time range.
175 endif::git-rev-list[]
177 --author=<pattern>::
178 --committer=<pattern>::
180         Limit the commits output to ones with author/committer
181         header lines that match the specified pattern (regular expression).
183 --grep=<pattern>::
185         Limit the commits output to ones with log message that
186         matches the specified pattern (regular expression).
188 --all-match::
189         Limit the commits output to ones that match all given --grep,
190         --author and --committer instead of ones that match at least one.
192 -i::
193 --regexp-ignore-case::
195         Match the regexp limiting patterns without regard to letters case.
197 -E::
198 --extended-regexp::
200         Consider the limiting patterns to be extended regular expressions
201         instead of the default basic regular expressions.
203 -F::
204 --fixed-strings::
206         Consider the limiting patterns to be fixed strings (don't interpret
207         pattern as a regular expression).
209 --remove-empty::
211         Stop when a given path disappears from the tree.
213 --merges::
215         Print only merge commits.
217 --no-merges::
219         Do not print commits with more than one parent.
221 --first-parent::
222         Follow only the first parent commit upon seeing a merge
223         commit.  This option can give a better overview when
224         viewing the evolution of a particular topic branch,
225         because merges into a topic branch tend to be only about
226         adjusting to updated upstream from time to time, and
227         this option allows you to ignore the individual commits
228         brought in to your history by such a merge.
230 --not::
232         Reverses the meaning of the '{caret}' prefix (or lack thereof)
233         for all following revision specifiers, up to the next '--not'.
235 --all::
237         Pretend as if all the refs in `refs/` are listed on the
238         command line as '<commit>'.
240 --branches[=pattern]::
242         Pretend as if all the refs in `refs/heads` are listed
243         on the command line as '<commit>'. If `pattern` is given, limit
244         branches to ones matching given shell glob. If pattern lacks '?',
245         '*', or '[', '/*' at the end is implied.
247 --tags[=pattern]::
249         Pretend as if all the refs in `refs/tags` are listed
250         on the command line as '<commit>'. If `pattern` is given, limit
251         tags to ones matching given shell glob. If pattern lacks '?', '*',
252         or '[', '/*' at the end is implied.
254 --remotes[=pattern]::
256         Pretend as if all the refs in `refs/remotes` are listed
257         on the command line as '<commit>'. If `pattern`is given, limit
258         remote tracking branches to ones matching given shell glob.
259         If pattern lacks '?', '*', or '[', '/*' at the end is implied.
261 --glob=glob-pattern::
262         Pretend as if all the refs matching shell glob `glob-pattern`
263         are listed on the command line as '<commit>'. Leading 'refs/',
264         is automatically prepended if missing. If pattern lacks '?', '*',
265         or '[', '/*' at the end is implied.
268 ifndef::git-rev-list[]
269 --bisect::
271         Pretend as if the bad bisection ref `refs/bisect/bad`
272         was listed and as if it was followed by `--not` and the good
273         bisection refs `refs/bisect/good-*` on the command
274         line.
275 endif::git-rev-list[]
277 --stdin::
279         In addition to the '<commit>' listed on the command
280         line, read them from the standard input. If a '--' separator is
281         seen, stop reading commits and start reading paths to limit the
282         result.
284 ifdef::git-rev-list[]
285 --quiet::
287         Don't print anything to standard output.  This form
288         is primarily meant to allow the caller to
289         test the exit status to see if a range of objects is fully
290         connected (or not).  It is faster than redirecting stdout
291         to /dev/null as the output does not have to be formatted.
292 endif::git-rev-list[]
294 --cherry-pick::
296         Omit any commit that introduces the same change as
297         another commit on the "other side" when the set of
298         commits are limited with symmetric difference.
300 For example, if you have two branches, `A` and `B`, a usual way
301 to list all commits on only one side of them is with
302 `--left-right`, like the example above in the description of
303 that option.  It however shows the commits that were cherry-picked
304 from the other branch (for example, "3rd on b" may be cherry-picked
305 from branch A).  With this option, such pairs of commits are
306 excluded from the output.
308 -g::
309 --walk-reflogs::
311         Instead of walking the commit ancestry chain, walk
312         reflog entries from the most recent one to older ones.
313         When this option is used you cannot specify commits to
314         exclude (that is, '{caret}commit', 'commit1..commit2',
315         nor 'commit1...commit2' notations cannot be used).
317 With '\--pretty' format other than oneline (for obvious reasons),
318 this causes the output to have two extra lines of information
319 taken from the reflog.  By default, 'commit@\{Nth}' notation is
320 used in the output.  When the starting commit is specified as
321 'commit@\{now}', output also uses 'commit@\{timestamp}' notation
322 instead.  Under '\--pretty=oneline', the commit message is
323 prefixed with this information on the same line.
324 This option cannot be combined with '\--reverse'.
325 See also linkgit:git-reflog[1].
327 --merge::
329         After a failed merge, show refs that touch files having a
330         conflict and don't exist on all heads to merge.
332 --boundary::
334         Output uninteresting commits at the boundary, which are usually
335         not shown.
339 History Simplification
340 ~~~~~~~~~~~~~~~~~~~~~~
342 Sometimes you are only interested in parts of the history, for example the
343 commits modifying a particular <path>. But there are two parts of
344 'History Simplification', one part is selecting the commits and the other
345 is how to do it, as there are various strategies to simplify the history.
347 The following options select the commits to be shown:
349 <paths>::
351         Commits modifying the given <paths> are selected.
353 --simplify-by-decoration::
355         Commits that are referred by some branch or tag are selected.
357 Note that extra commits can be shown to give a meaningful history.
359 The following options affect the way the simplification is performed:
361 Default mode::
363         Simplifies the history to the simplest history explaining the
364         final state of the tree. Simplest because it prunes some side
365         branches if the end result is the same (i.e. merging branches
366         with the same content)
368 --full-history::
370         As the default mode but does not prune some history.
372 --dense::
374         Only the selected commits are shown, plus some to have a
375         meaningful history.
377 --sparse::
379         All commits in the simplified history are shown.
381 --simplify-merges::
383         Additional option to '--full-history' to remove some needless
384         merges from the resulting history, as there are no selected
385         commits contributing to this merge.
387 A more detailed explanation follows.
389 Suppose you specified `foo` as the <paths>.  We shall call commits
390 that modify `foo` !TREESAME, and the rest TREESAME.  (In a diff
391 filtered for `foo`, they look different and equal, respectively.)
393 In the following, we will always refer to the same example history to
394 illustrate the differences between simplification settings.  We assume
395 that you are filtering for a file `foo` in this commit graph:
396 -----------------------------------------------------------------------
397           .-A---M---N---O---P
398          /     /   /   /   /
399         I     B   C   D   E
400          \   /   /   /   /
401           `-------------'
402 -----------------------------------------------------------------------
403 The horizontal line of history A--P is taken to be the first parent of
404 each merge.  The commits are:
406 * `I` is the initial commit, in which `foo` exists with contents
407   "asdf", and a file `quux` exists with contents "quux".  Initial
408   commits are compared to an empty tree, so `I` is !TREESAME.
410 * In `A`, `foo` contains just "foo".
412 * `B` contains the same change as `A`.  Its merge `M` is trivial and
413   hence TREESAME to all parents.
415 * `C` does not change `foo`, but its merge `N` changes it to "foobar",
416   so it is not TREESAME to any parent.
418 * `D` sets `foo` to "baz".  Its merge `O` combines the strings from
419   `N` and `D` to "foobarbaz"; i.e., it is not TREESAME to any parent.
421 * `E` changes `quux` to "xyzzy", and its merge `P` combines the
422   strings to "quux xyzzy".  Despite appearing interesting, `P` is
423   TREESAME to all parents.
425 'rev-list' walks backwards through history, including or excluding
426 commits based on whether '\--full-history' and/or parent rewriting
427 (via '\--parents' or '\--children') are used.  The following settings
428 are available.
430 Default mode::
432         Commits are included if they are not TREESAME to any parent
433         (though this can be changed, see '\--sparse' below).  If the
434         commit was a merge, and it was TREESAME to one parent, follow
435         only that parent.  (Even if there are several TREESAME
436         parents, follow only one of them.)  Otherwise, follow all
437         parents.
439 This results in:
441 -----------------------------------------------------------------------
442           .-A---N---O
443          /         /
444         I---------D
445 -----------------------------------------------------------------------
447 Note how the rule to only follow the TREESAME parent, if one is
448 available, removed `B` from consideration entirely.  `C` was
449 considered via `N`, but is TREESAME.  Root commits are compared to an
450 empty tree, so `I` is !TREESAME.
452 Parent/child relations are only visible with --parents, but that does
453 not affect the commits selected in default mode, so we have shown the
454 parent lines.
456 --full-history without parent rewriting::
458         This mode differs from the default in one point: always follow
459         all parents of a merge, even if it is TREESAME to one of them.
460         Even if more than one side of the merge has commits that are
461         included, this does not imply that the merge itself is!  In
462         the example, we get
464 -----------------------------------------------------------------------
465         I  A  B  N  D  O
466 -----------------------------------------------------------------------
468 `P` and `M` were excluded because they are TREESAME to a parent.  `E`,
469 `C` and `B` were all walked, but only `B` was !TREESAME, so the others
470 do not appear.
472 Note that without parent rewriting, it is not really possible to talk
473 about the parent/child relationships between the commits, so we show
474 them disconnected.
476 --full-history with parent rewriting::
478         Ordinary commits are only included if they are !TREESAME
479         (though this can be changed, see '\--sparse' below).
481 Merges are always included.  However, their parent list is rewritten:
482 Along each parent, prune away commits that are not included
483 themselves.  This results in
485 -----------------------------------------------------------------------
486           .-A---M---N---O---P
487          /     /   /   /   /
488         I     B   /   D   /
489          \   /   /   /   /
490           `-------------'
491 -----------------------------------------------------------------------
493 Compare to '\--full-history' without rewriting above.  Note that `E`
494 was pruned away because it is TREESAME, but the parent list of P was
495 rewritten to contain `E`'s parent `I`.  The same happened for `C` and
496 `N`.  Note also that `P` was included despite being TREESAME.
498 In addition to the above settings, you can change whether TREESAME
499 affects inclusion:
501 --dense::
503         Commits that are walked are included if they are not TREESAME
504         to any parent.
506 --sparse::
508         All commits that are walked are included.
510 Note that without '\--full-history', this still simplifies merges: if
511 one of the parents is TREESAME, we follow only that one, so the other
512 sides of the merge are never walked.
514 Finally, there is a fourth simplification mode available:
516 --simplify-merges::
518         First, build a history graph in the same way that
519         '\--full-history' with parent rewriting does (see above).
521 Then simplify each commit `C` to its replacement `C'` in the final
522 history according to the following rules:
525 * Set `C'` to `C`.
527 * Replace each parent `P` of `C'` with its simplification `P'`.  In
528   the process, drop parents that are ancestors of other parents, and
529   remove duplicates.
531 * If after this parent rewriting, `C'` is a root or merge commit (has
532   zero or >1 parents), a boundary commit, or !TREESAME, it remains.
533   Otherwise, it is replaced with its only parent.
536 The effect of this is best shown by way of comparing to
537 '\--full-history' with parent rewriting.  The example turns into:
539 -----------------------------------------------------------------------
540           .-A---M---N---O
541          /     /       /
542         I     B       D
543          \   /       /
544           `---------'
545 -----------------------------------------------------------------------
547 Note the major differences in `N` and `P` over '\--full-history':
550 * `N`'s parent list had `I` removed, because it is an ancestor of the
551   other parent `M`.  Still, `N` remained because it is !TREESAME.
553 * `P`'s parent list similarly had `I` removed.  `P` was then
554   removed completely, because it had one parent and is TREESAME.
557 The '\--simplify-by-decoration' option allows you to view only the
558 big picture of the topology of the history, by omitting commits
559 that are not referenced by tags.  Commits are marked as !TREESAME
560 (in other words, kept after history simplification rules described
561 above) if (1) they are referenced by tags, or (2) they change the
562 contents of the paths given on the command line.  All other
563 commits are marked as TREESAME (subject to be simplified away).
565 ifdef::git-rev-list[]
566 Bisection Helpers
567 ~~~~~~~~~~~~~~~~~
569 --bisect::
571 Limit output to the one commit object which is roughly halfway between
572 included and excluded commits. Note that the bad bisection ref
573 `refs/bisect/bad` is added to the included commits (if it
574 exists) and the good bisection refs `refs/bisect/good-*` are
575 added to the excluded commits (if they exist). Thus, supposing there
576 are no refs in `refs/bisect/`, if
578 -----------------------------------------------------------------------
579         $ git rev-list --bisect foo ^bar ^baz
580 -----------------------------------------------------------------------
582 outputs 'midpoint', the output of the two commands
584 -----------------------------------------------------------------------
585         $ git rev-list foo ^midpoint
586         $ git rev-list midpoint ^bar ^baz
587 -----------------------------------------------------------------------
589 would be of roughly the same length.  Finding the change which
590 introduces a regression is thus reduced to a binary search: repeatedly
591 generate and test new 'midpoint's until the commit chain is of length
592 one.
594 --bisect-vars::
596 This calculates the same as `--bisect`, except that refs in
597 `refs/bisect/` are not used, and except that this outputs
598 text ready to be eval'ed by the shell. These lines will assign the
599 name of the midpoint revision to the variable `bisect_rev`, and the
600 expected number of commits to be tested after `bisect_rev` is tested
601 to `bisect_nr`, the expected number of commits to be tested if
602 `bisect_rev` turns out to be good to `bisect_good`, the expected
603 number of commits to be tested if `bisect_rev` turns out to be bad to
604 `bisect_bad`, and the number of commits we are bisecting right now to
605 `bisect_all`.
607 --bisect-all::
609 This outputs all the commit objects between the included and excluded
610 commits, ordered by their distance to the included and excluded
611 commits. Refs in `refs/bisect/` are not used. The farthest
612 from them is displayed first. (This is the only one displayed by
613 `--bisect`.)
615 This is useful because it makes it easy to choose a good commit to
616 test when you want to avoid to test some of them for some reason (they
617 may not compile for example).
619 This option can be used along with `--bisect-vars`, in this case,
620 after all the sorted commit objects, there will be the same text as if
621 `--bisect-vars` had been used alone.
622 endif::git-rev-list[]
625 Commit Ordering
626 ~~~~~~~~~~~~~~~
628 By default, the commits are shown in reverse chronological order.
630 --topo-order::
632         This option makes them appear in topological order (i.e.
633         descendant commits are shown before their parents).
635 --date-order::
637         This option is similar to '--topo-order' in the sense that no
638         parent comes before all of its children, but otherwise things
639         are still ordered in the commit timestamp order.
641 --reverse::
643         Output the commits in reverse order.
644         Cannot be combined with '\--walk-reflogs'.
646 Object Traversal
647 ~~~~~~~~~~~~~~~~
649 These options are mostly targeted for packing of git repositories.
651 --objects::
653         Print the object IDs of any object referenced by the listed
654         commits.  '--objects foo ^bar' thus means "send me
655         all object IDs which I need to download if I have the commit
656         object 'bar', but not 'foo'".
658 --objects-edge::
660         Similar to '--objects', but also print the IDs of excluded
661         commits prefixed with a "-" character.  This is used by
662         linkgit:git-pack-objects[1] to build "thin" pack, which records
663         objects in deltified form based on objects contained in these
664         excluded commits to reduce network traffic.
666 --unpacked::
668         Only useful with '--objects'; print the object IDs that are not
669         in packs.
671 --no-walk::
673         Only show the given revs, but do not traverse their ancestors.
675 --do-walk::
677         Overrides a previous --no-walk.