1GIT-REV-LIST(1) Git Manual GIT-REV-LIST(1)
2
6 git-rev-list - Lists commit objects in reverse chronological order
7
9 git rev-list [ --max-count=<number> ]
10 [ --skip=<number> ]
11 [ --max-age=<timestamp> ]
12 [ --min-age=<timestamp> ]
13 [ --sparse ]
14 [ --merges ]
15 [ --no-merges ]
16 [ --min-parents=<number> ]
17 [ --no-min-parents ]
18 [ --max-parents=<number> ]
19 [ --no-max-parents ]
20 [ --first-parent ]
21 [ --remove-empty ]
22 [ --full-history ]
23 [ --not ]
24 [ --all ]
25 [ --branches[=<pattern>] ]
26 [ --tags[=<pattern>] ]
27 [ --remotes[=<pattern>] ]
28 [ --glob=<glob-pattern> ]
29 [ --ignore-missing ]
30 [ --stdin ]
31 [ --quiet ]
32 [ --topo-order ]
33 [ --parents ]
34 [ --timestamp ]
35 [ --left-right ]
36 [ --left-only ]
37 [ --right-only ]
38 [ --cherry-mark ]
39 [ --cherry-pick ]
40 [ --encoding=<encoding> ]
41 [ --(author|committer|grep)=<pattern> ]
42 [ --regexp-ignore-case | -i ]
43 [ --extended-regexp | -E ]
44 [ --fixed-strings | -F ]
45 [ --date=<format>]
46 [ [ --objects | --objects-edge | --objects-edge-aggressive ]
47 [ --unpacked ]
48 [ --filter=<filter-spec> [ --filter-print-omitted ] ] ]
49 [ --missing=<missing-action> ]
50 [ --pretty | --header ]
51 [ --bisect ]
52 [ --bisect-vars ]
53 [ --bisect-all ]
54 [ --merge ]
55 [ --reverse ]
56 [ --walk-reflogs ]
57 [ --no-walk ] [ --do-walk ]
58 [ --count ]
59 [ --use-bitmap-index ]
60 <commit>... [ -- <paths>... ]
61
64 List commits that are reachable by following the parent links from the
65 given commit(s), but exclude commits that are reachable from the one(s)
66 given with a ^ in front of them. The output is given in reverse
67 chronological order by default.
68 You can think of this as a set operation. Commits given on the command
70 line form a set of commits that are reachable from any of them, and
71 then commits reachable from any of the ones given with ^ in front are
72 subtracted from that set. The remaining commits are what comes out in
73 the command’s output. Various other options and paths parameters can be
74 used to further limit the result.
75 Thus, the following command:
77 $ git rev-list foo bar ^baz
79 means "list all the commits which are reachable from foo or bar, but
82 not from baz".
83 A special notation "<commit1>..<commit2>" can be used as a short-hand
85 for "^'<commit1>' <commit2>". For example, either of the following may
86 be used interchangeably:
87 $ git rev-list origin..HEAD
89 $ git rev-list HEAD ^origin
90 Another special notation is "<commit1>...<commit2>" which is useful for
93 merges. The resulting set of commits is the symmetric difference
94 between the two operands. The following two commands are equivalent:
95 $ git rev-list A B --not $(git merge-base --all A B)
97 $ git rev-list A...B
98 rev-list is a very essential Git command, since it provides the ability
101 to build and traverse commit ancestry graphs. For this reason, it has a
102 lot of different options that enables it to be used by commands as
103 different as git bisect and git repack.
104
106 Commit Limiting
107 Besides specifying a range of commits that should be listed using the
108 special notations explained in the description, additional commit
109 limiting may be applied.
110 Using more options generally further limits the output (e.g.
112 --since=<date1> limits to commits newer than <date1>, and using it with
113 --grep=<pattern> further limits to commits whose log message has a line
114 that matches <pattern>), unless otherwise noted.
115 Note that these are applied before commit ordering and formatting
117 options, such as --reverse.
118 -<number>, -n <number>, --max-count=<number>
120 Limit the number of commits to output.
121 --skip=<number>
123 Skip number commits before starting to show the commit output.
124 --since=<date>, --after=<date>
126 Show commits more recent than a specific date.
127 --until=<date>, --before=<date>
129 Show commits older than a specific date.
130 --max-age=<timestamp>, --min-age=<timestamp>
132 Limit the commits output to specified time range.
133 --author=<pattern>, --committer=<pattern>
135 Limit the commits output to ones with author/committer header lines
136 that match the specified pattern (regular expression). With more
137 than one --author=<pattern>, commits whose author matches any of
138 the given patterns are chosen (similarly for multiple
139 --committer=<pattern>).
140 --grep-reflog=<pattern>
142 Limit the commits output to ones with reflog entries that match the
143 specified pattern (regular expression). With more than one
144 --grep-reflog, commits whose reflog message matches any of the
145 given patterns are chosen. It is an error to use this option unless
146 --walk-reflogs is in use.
147 --grep=<pattern>
149 Limit the commits output to ones with log message that matches the
150 specified pattern (regular expression). With more than one
151 --grep=<pattern>, commits whose message matches any of the given
152 patterns are chosen (but see --all-match).
153 --all-match
155 Limit the commits output to ones that match all given --grep,
156 instead of ones that match at least one.
157 --invert-grep
159 Limit the commits output to ones with log message that do not match
160 the pattern specified with --grep=<pattern>.
161 -i, --regexp-ignore-case
163 Match the regular expression limiting patterns without regard to
164 letter case.
165 --basic-regexp
167 Consider the limiting patterns to be basic regular expressions;
168 this is the default.
169 -E, --extended-regexp
171 Consider the limiting patterns to be extended regular expressions
172 instead of the default basic regular expressions.
173 -F, --fixed-strings
175 Consider the limiting patterns to be fixed strings (don’t interpret
176 pattern as a regular expression).
177 -P, --perl-regexp
179 Consider the limiting patterns to be Perl-compatible regular
180 expressions.
181 Support for these types of regular expressions is an optional
183 compile-time dependency. If Git wasn’t compiled with support for
184 them providing this option will cause it to die.
185 --remove-empty
187 Stop when a given path disappears from the tree.
188 --merges
190 Print only merge commits. This is exactly the same as
191 --min-parents=2.
192 --no-merges
194 Do not print commits with more than one parent. This is exactly the
195 same as --max-parents=1.
196 --min-parents=<number>, --max-parents=<number>, --no-min-parents,
198 --no-max-parents
199 Show only commits which have at least (or at most) that many parent
200 commits. In particular, --max-parents=1 is the same as --no-merges,
201 --min-parents=2 is the same as --merges. --max-parents=0 gives all
202 root commits and --min-parents=3 all octopus merges.
203 --no-min-parents and --no-max-parents reset these limits (to no
205 limit) again. Equivalent forms are --min-parents=0 (any commit has
206 0 or more parents) and --max-parents=-1 (negative numbers denote no
207 upper limit).
208 --first-parent
210 Follow only the first parent commit upon seeing a merge commit.
211 This option can give a better overview when viewing the evolution
212 of a particular topic branch, because merges into a topic branch
213 tend to be only about adjusting to updated upstream from time to
214 time, and this option allows you to ignore the individual commits
215 brought in to your history by such a merge. Cannot be combined with
216 --bisect.
217 --not
219 Reverses the meaning of the ^ prefix (or lack thereof) for all
220 following revision specifiers, up to the next --not.
221 --all
223 Pretend as if all the refs in refs/, along with HEAD, are listed on
224 the command line as <commit>.
225 --branches[=<pattern>]
227 Pretend as if all the refs in refs/heads are listed on the command
228 line as <commit>. If <pattern> is given, limit branches to ones
229 matching given shell glob. If pattern lacks ?, *, or [, /* at the
230 end is implied.
231 --tags[=<pattern>]
233 Pretend as if all the refs in refs/tags are listed on the command
234 line as <commit>. If <pattern> is given, limit tags to ones
235 matching given shell glob. If pattern lacks ?, *, or [, /* at the
236 end is implied.
237 --remotes[=<pattern>]
239 Pretend as if all the refs in refs/remotes are listed on the
240 command line as <commit>. If <pattern> is given, limit
241 remote-tracking branches to ones matching given shell glob. If
242 pattern lacks ?, *, or [, /* at the end is implied.
243 --glob=<glob-pattern>
245 Pretend as if all the refs matching shell glob <glob-pattern> are
246 listed on the command line as <commit>. Leading refs/, is
247 automatically prepended if missing. If pattern lacks ?, *, or [, /*
248 at the end is implied.
249 --exclude=<glob-pattern>
251 Do not include refs matching <glob-pattern> that the next --all,
252 --branches, --tags, --remotes, or --glob would otherwise consider.
253 Repetitions of this option accumulate exclusion patterns up to the
254 next --all, --branches, --tags, --remotes, or --glob option (other
255 options or arguments do not clear accumulated patterns).
256 The patterns given should not begin with refs/heads, refs/tags, or
258 refs/remotes when applied to --branches, --tags, or --remotes,
259 respectively, and they must begin with refs/ when applied to --glob
260 or --all. If a trailing /* is intended, it must be given
261 explicitly.
262 --reflog
264 Pretend as if all objects mentioned by reflogs are listed on the
265 command line as <commit>.
266 --single-worktree
268 By default, all working trees will be examined by the following
269 options when there are more than one (see git-worktree(1)): --all,
270 --reflog and --indexed-objects. This option forces them to examine
271 the current working tree only.
272 --ignore-missing
274 Upon seeing an invalid object name in the input, pretend as if the
275 bad input was not given.
276 --stdin
278 In addition to the <commit> listed on the command line, read them
279 from the standard input. If a -- separator is seen, stop reading
280 commits and start reading paths to limit the result.
281 --quiet
283 Don’t print anything to standard output. This form is primarily
284 meant to allow the caller to test the exit status to see if a range
285 of objects is fully connected (or not). It is faster than
286 redirecting stdout to /dev/null as the output does not have to be
287 formatted.
288 --cherry-mark
290 Like --cherry-pick (see below) but mark equivalent commits with =
291 rather than omitting them, and inequivalent ones with +.
292 --cherry-pick
294 Omit any commit that introduces the same change as another commit
295 on the “other side” when the set of commits are limited with
296 symmetric difference.
297 For example, if you have two branches, A and B, a usual way to list
299 all commits on only one side of them is with --left-right (see the
300 example below in the description of the --left-right option).
301 However, it shows the commits that were cherry-picked from the
302 other branch (for example, “3rd on b” may be cherry-picked from
303 branch A). With this option, such pairs of commits are excluded
304 from the output.
305 --left-only, --right-only
307 List only commits on the respective side of a symmetric difference,
308 i.e. only those which would be marked < resp. > by --left-right.
309 For example, --cherry-pick --right-only A...B omits those commits
311 from B which are in A or are patch-equivalent to a commit in A. In
312 other words, this lists the + commits from git cherry A B. More
313 precisely, --cherry-pick --right-only --no-merges gives the exact
314 list.
315 --cherry
317 A synonym for --right-only --cherry-mark --no-merges; useful to
318 limit the output to the commits on our side and mark those that
319 have been applied to the other side of a forked history with git
320 log --cherry upstream...mybranch, similar to git cherry upstream
321 mybranch.
322 -g, --walk-reflogs
324 Instead of walking the commit ancestry chain, walk reflog entries
325 from the most recent one to older ones. When this option is used
326 you cannot specify commits to exclude (that is, ^commit,
327 commit1..commit2, and commit1...commit2 notations cannot be used).
328 With --pretty format other than oneline (for obvious reasons), this
330 causes the output to have two extra lines of information taken from
331 the reflog. The reflog designator in the output may be shown as
332 ref@{Nth} (where Nth is the reverse-chronological index in the
333 reflog) or as ref@{timestamp} (with the timestamp for that entry),
334 depending on a few rules:
335 1. If the starting point is specified as ref@{Nth}, show the index
337 format.
338 2. If the starting point was specified as ref@{now}, show the
340 timestamp format.
341 3. If neither was used, but --date was given on the command line,
343 show the timestamp in the format requested by --date.
344 4. Otherwise, show the index format.
346 Under --pretty=oneline, the commit message is prefixed with this
348 information on the same line. This option cannot be combined with
349 --reverse. See also git-reflog(1).
350 --merge
352 After a failed merge, show refs that touch files having a conflict
353 and don’t exist on all heads to merge.
354 --boundary
356 Output excluded boundary commits. Boundary commits are prefixed
357 with -.
358 --use-bitmap-index
360 Try to speed up the traversal using the pack bitmap index (if one
361 is available). Note that when traversing with --objects, trees and
362 blobs will not have their associated path printed.
363 --progress=<header>
365 Show progress reports on stderr as objects are considered. The
366 <header> text will be printed with each progress update.
367 History Simplification
369 Sometimes you are only interested in parts of the history, for example
370 the commits modifying a particular <path>. But there are two parts of
371 History Simplification, one part is selecting the commits and the other
372 is how to do it, as there are various strategies to simplify the
373 history.
374 The following options select the commits to be shown:
376 <paths>
378 Commits modifying the given <paths> are selected.
379 --simplify-by-decoration
381 Commits that are referred by some branch or tag are selected.
382 Note that extra commits can be shown to give a meaningful history.
384 The following options affect the way the simplification is performed:
386 Default mode
388 Simplifies the history to the simplest history explaining the final
389 state of the tree. Simplest because it prunes some side branches if
390 the end result is the same (i.e. merging branches with the same
391 content)
392 --full-history
394 Same as the default mode, but does not prune some history.
395 --dense
397 Only the selected commits are shown, plus some to have a meaningful
398 history.
399 --sparse
401 All commits in the simplified history are shown.
402 --simplify-merges
404 Additional option to --full-history to remove some needless merges
405 from the resulting history, as there are no selected commits
406 contributing to this merge.
407 --ancestry-path
409 When given a range of commits to display (e.g. commit1..commit2 or
410 commit2 ^commit1), only display commits that exist directly on the
411 ancestry chain between the commit1 and commit2, i.e. commits that
412 are both descendants of commit1, and ancestors of commit2.
413 A more detailed explanation follows.
415 Suppose you specified foo as the <paths>. We shall call commits that
417 modify foo !TREESAME, and the rest TREESAME. (In a diff filtered for
418 foo, they look different and equal, respectively.)
419 In the following, we will always refer to the same example history to
421 illustrate the differences between simplification settings. We assume
422 that you are filtering for a file foo in this commit graph:
423 .-A---M---N---O---P---Q
425 / / / / / /
426 I B C D E Y
427 \ / / / / /
428 `-------------' X
429 The horizontal line of history A---Q is taken to be the first parent of
432 each merge. The commits are:
433 · I is the initial commit, in which foo exists with contents “asdf”,
435 and a file quux exists with contents “quux”. Initial commits are
436 compared to an empty tree, so I is !TREESAME.
437 · In A, foo contains just “foo”.
439 · B contains the same change as A. Its merge M is trivial and hence
441 TREESAME to all parents.
442 · C does not change foo, but its merge N changes it to “foobar”, so
444 it is not TREESAME to any parent.
445 · D sets foo to “baz”. Its merge O combines the strings from N and D
447 to “foobarbaz”; i.e., it is not TREESAME to any parent.
448 · E changes quux to “xyzzy”, and its merge P combines the strings to
450 “quux xyzzy”. P is TREESAME to O, but not to E.
451 · X is an independent root commit that added a new file side, and Y
453 modified it. Y is TREESAME to X. Its merge Q added side to P, and
454 Q is TREESAME to P, but not to Y.
455 rev-list walks backwards through history, including or excluding
457 commits based on whether --full-history and/or parent rewriting (via
458 --parents or --children) are used. The following settings are
459 available.
460 Default mode
462 Commits are included if they are not TREESAME to any parent (though
463 this can be changed, see --sparse below). If the commit was a
464 merge, and it was TREESAME to one parent, follow only that parent.
465 (Even if there are several TREESAME parents, follow only one of
466 them.) Otherwise, follow all parents.
467 This results in:
469 .-A---N---O
471 / / /
472 I---------D
473 Note how the rule to only follow the TREESAME parent, if one is
475 available, removed B from consideration entirely. C was considered
476 via N, but is TREESAME. Root commits are compared to an empty tree,
477 so I is !TREESAME.
478 Parent/child relations are only visible with --parents, but that
480 does not affect the commits selected in default mode, so we have
481 shown the parent lines.
482 --full-history without parent rewriting
484 This mode differs from the default in one point: always follow all
485 parents of a merge, even if it is TREESAME to one of them. Even if
486 more than one side of the merge has commits that are included, this
487 does not imply that the merge itself is! In the example, we get
488 I A B N D O P Q
490 M was excluded because it is TREESAME to both parents. E, C and B
492 were all walked, but only B was !TREESAME, so the others do not
493 appear.
494 Note that without parent rewriting, it is not really possible to
496 talk about the parent/child relationships between the commits, so
497 we show them disconnected.
498 --full-history with parent rewriting
500 Ordinary commits are only included if they are !TREESAME (though
501 this can be changed, see --sparse below).
502 Merges are always included. However, their parent list is
504 rewritten: Along each parent, prune away commits that are not
505 included themselves. This results in
506 .-A---M---N---O---P---Q
508 / / / / /
509 I B / D /
510 \ / / / /
511 `-------------'
512 Compare to --full-history without rewriting above. Note that E was
514 pruned away because it is TREESAME, but the parent list of P was
515 rewritten to contain E's parent I. The same happened for C and N,
516 and X, Y and Q.
517 In addition to the above settings, you can change whether TREESAME
519 affects inclusion:
520 --dense
522 Commits that are walked are included if they are not TREESAME to
523 any parent.
524 --sparse
526 All commits that are walked are included.
527 Note that without --full-history, this still simplifies merges: if
529 one of the parents is TREESAME, we follow only that one, so the
530 other sides of the merge are never walked.
531 --simplify-merges
533 First, build a history graph in the same way that --full-history
534 with parent rewriting does (see above).
535 Then simplify each commit C to its replacement C' in the final
537 history according to the following rules:
538 · Set C' to C.
540 · Replace each parent P of C' with its simplification P'. In the
542 process, drop parents that are ancestors of other parents or
543 that are root commits TREESAME to an empty tree, and remove
544 duplicates, but take care to never drop all parents that we are
545 TREESAME to.
546 · If after this parent rewriting, C' is a root or merge commit
548 (has zero or >1 parents), a boundary commit, or !TREESAME, it
549 remains. Otherwise, it is replaced with its only parent.
550 The effect of this is best shown by way of comparing to
552 --full-history with parent rewriting. The example turns into:
553 .-A---M---N---O
555 / / /
556 I B D
557 \ / /
558 `---------'
559 Note the major differences in N, P, and Q over --full-history:
561 · N's parent list had I removed, because it is an ancestor of the
563 other parent M. Still, N remained because it is !TREESAME.
564 · P's parent list similarly had I removed. P was then removed
566 completely, because it had one parent and is TREESAME.
567 · Q's parent list had Y simplified to X. X was then removed,
569 because it was a TREESAME root. Q was then removed completely,
570 because it had one parent and is TREESAME.
571 Finally, there is a fifth simplification mode available:
573 --ancestry-path
575 Limit the displayed commits to those directly on the ancestry chain
576 between the “from” and “to” commits in the given commit range. I.e.
577 only display commits that are ancestor of the “to” commit and
578 descendants of the “from” commit.
579 As an example use case, consider the following commit history:
581 D---E-------F
583 / \ \
584 B---C---G---H---I---J
585 / \
586 A-------K---------------L--M
587 A regular D..M computes the set of commits that are ancestors of M,
589 but excludes the ones that are ancestors of D. This is useful to
590 see what happened to the history leading to M since D, in the sense
591 that “what does M have that did not exist in D”. The result in this
592 example would be all the commits, except A and B (and D itself, of
593 course).
594 When we want to find out what commits in M are contaminated with
596 the bug introduced by D and need fixing, however, we might want to
597 view only the subset of D..M that are actually descendants of D,
598 i.e. excluding C and K. This is exactly what the --ancestry-path
599 option does. Applied to the D..M range, it results in:
600 E-------F
602 \ \
603 G---H---I---J
604 \
605 L--M
606 The --simplify-by-decoration option allows you to view only the big
609 picture of the topology of the history, by omitting commits that are
610 not referenced by tags. Commits are marked as !TREESAME (in other
611 words, kept after history simplification rules described above) if (1)
612 they are referenced by tags, or (2) they change the contents of the
613 paths given on the command line. All other commits are marked as
614 TREESAME (subject to be simplified away).
615 Bisection Helpers
617 --bisect
618 Limit output to the one commit object which is roughly halfway
619 between included and excluded commits. Note that the bad bisection
620 ref refs/bisect/bad is added to the included commits (if it exists)
621 and the good bisection refs refs/bisect/good-* are added to the
622 excluded commits (if they exist). Thus, supposing there are no refs
623 in refs/bisect/, if
624 $ git rev-list --bisect foo ^bar ^baz
626 outputs midpoint, the output of the two commands
628 $ git rev-list foo ^midpoint
630 $ git rev-list midpoint ^bar ^baz
631 would be of roughly the same length. Finding the change which
633 introduces a regression is thus reduced to a binary search:
634 repeatedly generate and test new 'midpoint’s until the commit chain
635 is of length one. Cannot be combined with --first-parent.
636 --bisect-vars
638 This calculates the same as --bisect, except that refs in
639 refs/bisect/ are not used, and except that this outputs text ready
640 to be eval’ed by the shell. These lines will assign the name of the
641 midpoint revision to the variable bisect_rev, and the expected
642 number of commits to be tested after bisect_rev is tested to
643 bisect_nr, the expected number of commits to be tested if
644 bisect_rev turns out to be good to bisect_good, the expected number
645 of commits to be tested if bisect_rev turns out to be bad to
646 bisect_bad, and the number of commits we are bisecting right now to
647 bisect_all.
648 --bisect-all
650 This outputs all the commit objects between the included and
651 excluded commits, ordered by their distance to the included and
652 excluded commits. Refs in refs/bisect/ are not used. The farthest
653 from them is displayed first. (This is the only one displayed by
654 --bisect.)
655 This is useful because it makes it easy to choose a good commit to
657 test when you want to avoid to test some of them for some reason
658 (they may not compile for example).
659 This option can be used along with --bisect-vars, in this case,
661 after all the sorted commit objects, there will be the same text as
662 if --bisect-vars had been used alone.
663 Commit Ordering
665 By default, the commits are shown in reverse chronological order.
666 --date-order
668 Show no parents before all of its children are shown, but otherwise
669 show commits in the commit timestamp order.
670 --author-date-order
672 Show no parents before all of its children are shown, but otherwise
673 show commits in the author timestamp order.
674 --topo-order
676 Show no parents before all of its children are shown, and avoid
677 showing commits on multiple lines of history intermixed.
678 For example, in a commit history like this:
680 ---1----2----4----7
682 \ \
683 3----5----6----8---
684 where the numbers denote the order of commit timestamps, git
686 rev-list and friends with --date-order show the commits in the
687 timestamp order: 8 7 6 5 4 3 2 1.
688 With --topo-order, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5
690 3 1); some older commits are shown before newer ones in order to
691 avoid showing the commits from two parallel development track mixed
692 together.
693 --reverse
695 Output the commits chosen to be shown (see Commit Limiting section
696 above) in reverse order. Cannot be combined with --walk-reflogs.
697 Object Traversal
699 These options are mostly targeted for packing of Git repositories.
700 --objects
702 Print the object IDs of any object referenced by the listed
703 commits. --objects foo ^bar thus means “send me all object IDs
704 which I need to download if I have the commit object bar but not
705 foo”.
706 --in-commit-order
708 Print tree and blob ids in order of the commits. The tree and blob
709 ids are printed after they are first referenced by a commit.
710 --objects-edge
712 Similar to --objects, but also print the IDs of excluded commits
713 prefixed with a “-” character. This is used by git-pack-objects(1)
714 to build a “thin” pack, which records objects in deltified form
715 based on objects contained in these excluded commits to reduce
716 network traffic.
717 --objects-edge-aggressive
719 Similar to --objects-edge, but it tries harder to find excluded
720 commits at the cost of increased time. This is used instead of
721 --objects-edge to build “thin” packs for shallow repositories.
722 --indexed-objects
724 Pretend as if all trees and blobs used by the index are listed on
725 the command line. Note that you probably want to use --objects,
726 too.
727 --unpacked
729 Only useful with --objects; print the object IDs that are not in
730 packs.
731 --filter=<filter-spec>
733 Only useful with one of the --objects*; omits objects (usually
734 blobs) from the list of printed objects. The <filter-spec> may be
735 one of the following:
736 The form --filter=blob:none omits all blobs.
738 The form --filter=blob:limit=<n>[kmg] omits blobs larger than n
740 bytes or units. n may be zero. The suffixes k, m, and g can be used
741 to name units in KiB, MiB, or GiB. For example, blob:limit=1k is
742 the same as blob:limit=1024.
743 The form --filter=sparse:oid=<blob-ish> uses a sparse-checkout
745 specification contained in the blob (or blob-expression) <blob-ish>
746 to omit blobs that would not be not required for a sparse checkout
747 on the requested refs.
748 The form --filter=sparse:path=<path> similarly uses a
750 sparse-checkout specification contained in <path>.
751 --no-filter
753 Turn off any previous --filter= argument.
754 --filter-print-omitted
756 Only useful with --filter=; prints a list of the objects omitted by
757 the filter. Object IDs are prefixed with a “~” character.
758 --missing=<missing-action>
760 A debug option to help with future "partial clone" development.
761 This option specifies how missing objects are handled.
762 The form --missing=error requests that rev-list stop with an error
764 if a missing object is encountered. This is the default action.
765 The form --missing=allow-any will allow object traversal to
767 continue if a missing object is encountered. Missing objects will
768 silently be omitted from the results.
769 The form --missing=allow-promisor is like allow-any, but will only
771 allow object traversal to continue for EXPECTED promisor missing
772 objects. Unexpected missing objects will raise an error.
773 The form --missing=print is like allow-any, but will also print a
775 list of the missing objects. Object IDs are prefixed with a “?”
776 character.
777 --exclude-promisor-objects
779 (For internal use only.) Prefilter object traversal at promisor
780 boundary. This is used with partial clone. This is stronger than
781 --missing=allow-promisor because it limits the traversal, rather
782 than just silencing errors about missing objects.
783 --no-walk[=(sorted|unsorted)]
785 Only show the given commits, but do not traverse their ancestors.
786 This has no effect if a range is specified. If the argument
787 unsorted is given, the commits are shown in the order they were
788 given on the command line. Otherwise (if sorted or no argument was
789 given), the commits are shown in reverse chronological order by
790 commit time. Cannot be combined with --graph.
791 --do-walk
793 Overrides a previous --no-walk.
794 Commit Formatting
796 Using these options, git-rev-list(1) will act similar to the more
797 specialized family of commit log tools: git-log(1), git-show(1), and
798 git-whatchanged(1)
799 --pretty[=<format>], --format=<format>
801 Pretty-print the contents of the commit logs in a given format,
802 where <format> can be one of oneline, short, medium, full, fuller,
803 email, raw, format:<string> and tformat:<string>. When <format> is
804 none of the above, and has %placeholder in it, it acts as if
805 --pretty=tformat:<format> were given.
806 See the "PRETTY FORMATS" section for some additional details for
808 each format. When =<format> part is omitted, it defaults to medium.
809 Note: you can specify the default pretty format in the repository
811 configuration (see git-config(1)).
812 --abbrev-commit
814 Instead of showing the full 40-byte hexadecimal commit object name,
815 show only a partial prefix. Non default number of digits can be
816 specified with "--abbrev=<n>" (which also modifies diff output, if
817 it is displayed).
818 This should make "--pretty=oneline" a whole lot more readable for
820 people using 80-column terminals.
821 --no-abbrev-commit
823 Show the full 40-byte hexadecimal commit object name. This negates
824 --abbrev-commit and those options which imply it such as
825 "--oneline". It also overrides the log.abbrevCommit variable.
826 --oneline
828 This is a shorthand for "--pretty=oneline --abbrev-commit" used
829 together.
830 --encoding=<encoding>
832 The commit objects record the encoding used for the log message in
833 their encoding header; this option can be used to tell the command
834 to re-code the commit log message in the encoding preferred by the
835 user. For non plumbing commands this defaults to UTF-8. Note that
836 if an object claims to be encoded in X and we are outputting in X,
837 we will output the object verbatim; this means that invalid
838 sequences in the original commit may be copied to the output.
839 --expand-tabs=<n>, --expand-tabs, --no-expand-tabs
841 Perform a tab expansion (replace each tab with enough spaces to
842 fill to the next display column that is multiple of <n>) in the log
843 message before showing it in the output. --expand-tabs is a
844 short-hand for --expand-tabs=8, and --no-expand-tabs is a
845 short-hand for --expand-tabs=0, which disables tab expansion.
846 By default, tabs are expanded in pretty formats that indent the log
848 message by 4 spaces (i.e. medium, which is the default, full, and
849 fuller).
850 --show-signature
852 Check the validity of a signed commit object by passing the
853 signature to gpg --verify and show the output.
854 --relative-date
856 Synonym for --date=relative.
857 --date=<format>
859 Only takes effect for dates shown in human-readable format, such as
860 when using --pretty. log.date config variable sets a default value
861 for the log command’s --date option. By default, dates are shown in
862 the original time zone (either committer’s or author’s). If -local
863 is appended to the format (e.g., iso-local), the user’s local time
864 zone is used instead.
865 --date=relative shows dates relative to the current time, e.g. “2
867 hours ago”. The -local option has no effect for --date=relative.
868 --date=local is an alias for --date=default-local.
870 --date=iso (or --date=iso8601) shows timestamps in a ISO 8601-like
872 format. The differences to the strict ISO 8601 format are:
873 · a space instead of the T date/time delimiter
875 · a space between time and time zone
877 · no colon between hours and minutes of the time zone
879 --date=iso-strict (or --date=iso8601-strict) shows timestamps in
881 strict ISO 8601 format.
882 --date=rfc (or --date=rfc2822) shows timestamps in RFC 2822 format,
884 often found in email messages.
885 --date=short shows only the date, but not the time, in YYYY-MM-DD
887 format.
888 --date=raw shows the date as seconds since the epoch (1970-01-01
890 00:00:00 UTC), followed by a space, and then the timezone as an
891 offset from UTC (a + or - with four digits; the first two are
892 hours, and the second two are minutes). I.e., as if the timestamp
893 were formatted with strftime("%s %z")). Note that the -local option
894 does not affect the seconds-since-epoch value (which is always
895 measured in UTC), but does switch the accompanying timezone value.
896 --date=unix shows the date as a Unix epoch timestamp (seconds since
898 1970). As with --raw, this is always in UTC and therefore -local
899 has no effect.
900 --date=format:... feeds the format ... to your system strftime,
902 except for %z and %Z, which are handled internally. Use
903 --date=format:%c to show the date in your system locale’s preferred
904 format. See the strftime manual for a complete list of format
905 placeholders. When using -local, the correct syntax is
906 --date=format-local:....
907 --date=default is the default format, and is similar to
909 --date=rfc2822, with a few exceptions:
910 · there is no comma after the day-of-week
912 · the time zone is omitted when the local time zone is used
914 --header
916 Print the contents of the commit in raw-format; each record is
917 separated with a NUL character.
918 --parents
920 Print also the parents of the commit (in the form "commit
921 parent..."). Also enables parent rewriting, see History
922 Simplification above.
923 --children
925 Print also the children of the commit (in the form "commit
926 child..."). Also enables parent rewriting, see History
927 Simplification above.
928 --timestamp
930 Print the raw commit timestamp.
931 --left-right
933 Mark which side of a symmetric difference a commit is reachable
934 from. Commits from the left side are prefixed with < and those from
935 the right with >. If combined with --boundary, those commits are
936 prefixed with -.
937 For example, if you have this topology:
939 y---b---b branch B
941 / \ /
942 / .
943 / / \
944 o---x---a---a branch A
945 you would get an output like this:
947 $ git rev-list --left-right --boundary --pretty=oneline A...B
949 >bbbbbbb... 3rd on b
951 >bbbbbbb... 2nd on b
952 <aaaaaaa... 3rd on a
953 <aaaaaaa... 2nd on a
954 -yyyyyyy... 1st on b
955 -xxxxxxx... 1st on a
956 --graph
959 Draw a text-based graphical representation of the commit history on
960 the left hand side of the output. This may cause extra lines to be
961 printed in between commits, in order for the graph history to be
962 drawn properly. Cannot be combined with --no-walk.
963 This enables parent rewriting, see History Simplification above.
965 This implies the --topo-order option by default, but the
967 --date-order option may also be specified.
968 --show-linear-break[=<barrier>]
970 When --graph is not used, all history branches are flattened which
971 can make it hard to see that the two consecutive commits do not
972 belong to a linear branch. This option puts a barrier in between
973 them in that case. If <barrier> is specified, it is the string that
974 will be shown instead of the default one.
975 --count
977 Print a number stating how many commits would have been listed, and
978 suppress all other output. When used together with --left-right,
979 instead print the counts for left and right commits, separated by a
980 tab. When used together with --cherry-mark, omit patch equivalent
981 commits from these counts and print the count for equivalent
982 commits separated by a tab.
983
985 If the commit is a merge, and if the pretty-format is not oneline,
986 email or raw, an additional line is inserted before the Author: line.
987 This line begins with "Merge: " and the sha1s of ancestral commits are
988 printed, separated by spaces. Note that the listed commits may not
989 necessarily be the list of the direct parent commits if you have
990 limited your view of history: for example, if you are only interested
991 in changes related to a certain directory or file.
992 There are several built-in formats, and you can define additional
994 formats by setting a pretty.<name> config option to either another
995 format name, or a format: string, as described below (see git-
996 config(1)). Here are the details of the built-in formats:
997 · oneline
999 <sha1> <title line>
1001 This is designed to be as compact as possible.
1003 · short
1005 commit <sha1>
1007 Author: <author>
1008 <title line>
1010 · medium
1012 commit <sha1>
1014 Author: <author>
1015 Date: <author date>
1016 <title line>
1018 <full commit message>
1020 · full
1022 commit <sha1>
1024 Author: <author>
1025 Commit: <committer>
1026 <title line>
1028 <full commit message>
1030 · fuller
1032 commit <sha1>
1034 Author: <author>
1035 AuthorDate: <author date>
1036 Commit: <committer>
1037 CommitDate: <committer date>
1038 <title line>
1040 <full commit message>
1042 · email
1044 From <sha1> <date>
1046 From: <author>
1047 Date: <author date>
1048 Subject: [PATCH] <title line>
1049 <full commit message>
1051 · raw
1053 The raw format shows the entire commit exactly as stored in the
1055 commit object. Notably, the SHA-1s are displayed in full,
1056 regardless of whether --abbrev or --no-abbrev are used, and parents
1057 information show the true parent commits, without taking grafts or
1058 history simplification into account. Note that this format affects
1059 the way commits are displayed, but not the way the diff is shown
1060 e.g. with git log --raw. To get full object names in a raw diff
1061 format, use --no-abbrev.
1062 · format:<string>
1064 The format:<string> format allows you to specify which information
1066 you want to show. It works a little bit like printf format, with
1067 the notable exception that you get a newline with %n instead of \n.
1068 E.g, format:"The author of %h was %an, %ar%nThe title was >>%s<<%n"
1070 would show something like this:
1071 The author of fe6e0ee was Junio C Hamano, 23 hours ago
1073 The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<
1074 The placeholders are:
1076 · %H: commit hash
1078 · %h: abbreviated commit hash
1080 · %T: tree hash
1082 · %t: abbreviated tree hash
1084 · %P: parent hashes
1086 · %p: abbreviated parent hashes
1088 · %an: author name
1090 · %aN: author name (respecting .mailmap, see git-shortlog(1) or
1092 git-blame(1))
1093 · %ae: author email
1095 · %aE: author email (respecting .mailmap, see git-shortlog(1) or
1097 git-blame(1))
1098 · %ad: author date (format respects --date= option)
1100 · %aD: author date, RFC2822 style
1102 · %ar: author date, relative
1104 · %at: author date, UNIX timestamp
1106 · %ai: author date, ISO 8601-like format
1108 · %aI: author date, strict ISO 8601 format
1110 · %cn: committer name
1112 · %cN: committer name (respecting .mailmap, see git-shortlog(1)
1114 or git-blame(1))
1115 · %ce: committer email
1117 · %cE: committer email (respecting .mailmap, see git-shortlog(1)
1119 or git-blame(1))
1120 · %cd: committer date (format respects --date= option)
1122 · %cD: committer date, RFC2822 style
1124 · %cr: committer date, relative
1126 · %ct: committer date, UNIX timestamp
1128 · %ci: committer date, ISO 8601-like format
1130 · %cI: committer date, strict ISO 8601 format
1132 · %d: ref names, like the --decorate option of git-log(1)
1134 · %D: ref names without the " (", ")" wrapping.
1136 · %e: encoding
1138 · %s: subject
1140 · %f: sanitized subject line, suitable for a filename
1142 · %b: body
1144 · %B: raw body (unwrapped subject and body)
1146 · %GG: raw verification message from GPG for a signed commit
1148 · %G?: show "G" for a good (valid) signature, "B" for a bad
1150 signature, "U" for a good signature with unknown validity, "X"
1151 for a good signature that has expired, "Y" for a good signature
1152 made by an expired key, "R" for a good signature made by a
1153 revoked key, "E" if the signature cannot be checked (e.g.
1154 missing key) and "N" for no signature
1155 · %GS: show the name of the signer for a signed commit
1157 · %GK: show the key used to sign a signed commit
1159 · %gD: reflog selector, e.g., refs/stash@{1} or refs/stash@{2
1161 minutes ago}; the format follows the rules described for the -g
1162 option. The portion before the @ is the refname as given on the
1163 command line (so git log -g refs/heads/master would yield
1164 refs/heads/master@{0}).
1165 · %gd: shortened reflog selector; same as %gD, but the refname
1167 portion is shortened for human readability (so
1168 refs/heads/master becomes just master).
1169 · %gn: reflog identity name
1171 · %gN: reflog identity name (respecting .mailmap, see git-
1173 shortlog(1) or git-blame(1))
1174 · %ge: reflog identity email
1176 · %gE: reflog identity email (respecting .mailmap, see git-
1178 shortlog(1) or git-blame(1))
1179 · %gs: reflog subject
1181 · %Cred: switch color to red
1183 · %Cgreen: switch color to green
1185 · %Cblue: switch color to blue
1187 · %Creset: reset color
1189 · %C(...): color specification, as described under Values in the
1191 "CONFIGURATION FILE" section of git-config(1). By default,
1192 colors are shown only when enabled for log output (by
1193 color.diff, color.ui, or --color, and respecting the auto
1194 settings of the former if we are going to a terminal).
1195 %C(auto,...) is accepted as a historical synonym for the
1196 default (e.g., %C(auto,red)). Specifying %C(always,...) will
1197 show the colors even when color is not otherwise enabled
1198 (though consider just using `--color=always to enable color for
1199 the whole output, including this format and anything else git
1200 might color). auto alone (i.e. %C(auto)) will turn on auto
1201 coloring on the next placeholders until the color is switched
1202 again.
1203 · %m: left (<), right (>) or boundary (-) mark
1205 · %n: newline
1207 · %%: a raw %
1209 · %x00: print a byte from a hex code
1211 · %w([<w>[,<i1>[,<i2>]]]): switch line wrapping, like the -w
1213 option of git-shortlog(1).
1214 · %<(<N>[,trunc|ltrunc|mtrunc]): make the next placeholder take
1216 at least N columns, padding spaces on the right if necessary.
1217 Optionally truncate at the beginning (ltrunc), the middle
1218 (mtrunc) or the end (trunc) if the output is longer than N
1219 columns. Note that truncating only works correctly with N >= 2.
1220 · %<|(<N>): make the next placeholder take at least until Nth
1222 columns, padding spaces on the right if necessary
1223 · %>(<N>), %>|(<N>): similar to %<(<N>), %<|(<N>) respectively,
1225 but padding spaces on the left
1226 · %>>(<N>), %>>|(<N>): similar to %>(<N>), %>|(<N>) respectively,
1228 except that if the next placeholder takes more spaces than
1229 given and there are spaces on its left, use those spaces
1230 · %><(<N>), %><|(<N>): similar to %<(<N>), %<|(<N>) respectively,
1232 but padding both sides (i.e. the text is centered)
1233 · %(trailers[:options]): display the trailers of the body as
1235 interpreted by git-interpret-trailers(1). The trailers string
1236 may be followed by a colon and zero or more comma-separated
1237 options. If the only option is given, omit non-trailer lines
1238 from the trailer block. If the unfold option is given, behave
1239 as if interpret-trailer’s --unfold option was given. E.g.,
1240 %(trailers:only,unfold) to do both.
1241 Note
1243 Some placeholders may depend on other options given to the revision
1244 traversal engine. For example, the %g* reflog options will insert
1245 an empty string unless we are traversing reflog entries (e.g., by
1246 git log -g). The %d and %D placeholders will use the "short"
1247 decoration format if --decorate was not already provided on the
1248 command line.
1249 If you add a + (plus sign) after % of a placeholder, a line-feed is
1251 inserted immediately before the expansion if and only if the
1252 placeholder expands to a non-empty string.
1253 If you add a - (minus sign) after % of a placeholder, all consecutive
1255 line-feeds immediately preceding the expansion are deleted if and only
1256 if the placeholder expands to an empty string.
1257 If you add a ` ` (space) after % of a placeholder, a space is inserted
1259 immediately before the expansion if and only if the placeholder expands
1260 to a non-empty string.
1261 · tformat:
1263 The tformat: format works exactly like format:, except that it
1265 provides "terminator" semantics instead of "separator" semantics.
1266 In other words, each commit has the message terminator character
1267 (usually a newline) appended, rather than a separator placed
1268 between entries. This means that the final entry of a single-line
1269 format will be properly terminated with a new line, just as the
1270 "oneline" format does. For example:
1271 $ git log -2 --pretty=format:%h 4da45bef \
1273 | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
1274 4da45be
1275 7134973 -- NO NEWLINE
1276 $ git log -2 --pretty=tformat:%h 4da45bef \
1278 | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
1279 4da45be
1280 7134973
1281 In addition, any unrecognized string that has a % in it is
1283 interpreted as if it has tformat: in front of it. For example,
1284 these two are equivalent:
1285 $ git log -2 --pretty=tformat:%h 4da45bef
1287 $ git log -2 --pretty=%h 4da45bef
1288
1291 Part of the git(1) suite
1292Git 2.18.1 05/14/2019 GIT-REV-LIST(1)