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 [<options>] <commit>... [[--] <path>...]
10
12 List commits that are reachable by following the parent links from the
13 given commit(s), but exclude commits that are reachable from the one(s)
14 given with a ^ in front of them. The output is given in reverse
15 chronological order by default.
16 You can think of this as a set operation. Commits given on the command
18 line form a set of commits that are reachable from any of them, and
19 then commits reachable from any of the ones given with ^ in front are
20 subtracted from that set. The remaining commits are what comes out in
21 the command’s output. Various other options and paths parameters can be
22 used to further limit the result.
23 Thus, the following command:
25 $ git rev-list foo bar ^baz
27 means "list all the commits which are reachable from foo or bar, but
29 not from baz".
30 A special notation "<commit1>..<commit2>" can be used as a short-hand
32 for "^'<commit1>' <commit2>". For example, either of the following may
33 be used interchangeably:
34 $ git rev-list origin..HEAD
36 $ git rev-list HEAD ^origin
37 Another special notation is "<commit1>...<commit2>" which is useful for
39 merges. The resulting set of commits is the symmetric difference
40 between the two operands. The following two commands are equivalent:
41 $ git rev-list A B --not $(git merge-base --all A B)
43 $ git rev-list A...B
44 rev-list is a very essential Git command, since it provides the ability
46 to build and traverse commit ancestry graphs. For this reason, it has a
47 lot of different options that enables it to be used by commands as
48 different as git bisect and git repack.
49
51 Commit Limiting
52 Besides specifying a range of commits that should be listed using the
53 special notations explained in the description, additional commit
54 limiting may be applied.
55 Using more options generally further limits the output (e.g.
57 --since=<date1> limits to commits newer than <date1>, and using it with
58 --grep=<pattern> further limits to commits whose log message has a line
59 that matches <pattern>), unless otherwise noted.
60 Note that these are applied before commit ordering and formatting
62 options, such as --reverse.
63 -<number>, -n <number>, --max-count=<number>
65 Limit the number of commits to output.
66 --skip=<number>
68 Skip number commits before starting to show the commit output.
69 --since=<date>, --after=<date>
71 Show commits more recent than a specific date.
72 --until=<date>, --before=<date>
74 Show commits older than a specific date.
75 --max-age=<timestamp>, --min-age=<timestamp>
77 Limit the commits output to specified time range.
78 --author=<pattern>, --committer=<pattern>
80 Limit the commits output to ones with author/committer header lines
81 that match the specified pattern (regular expression). With more
82 than one --author=<pattern>, commits whose author matches any of
83 the given patterns are chosen (similarly for multiple
84 --committer=<pattern>).
85 --grep-reflog=<pattern>
87 Limit the commits output to ones with reflog entries that match the
88 specified pattern (regular expression). With more than one
89 --grep-reflog, commits whose reflog message matches any of the
90 given patterns are chosen. It is an error to use this option unless
91 --walk-reflogs is in use.
92 --grep=<pattern>
94 Limit the commits output to ones with log message that matches the
95 specified pattern (regular expression). With more than one
96 --grep=<pattern>, commits whose message matches any of the given
97 patterns are chosen (but see --all-match).
98 --all-match
100 Limit the commits output to ones that match all given --grep,
101 instead of ones that match at least one.
102 --invert-grep
104 Limit the commits output to ones with log message that do not match
105 the pattern specified with --grep=<pattern>.
106 -i, --regexp-ignore-case
108 Match the regular expression limiting patterns without regard to
109 letter case.
110 --basic-regexp
112 Consider the limiting patterns to be basic regular expressions;
113 this is the default.
114 -E, --extended-regexp
116 Consider the limiting patterns to be extended regular expressions
117 instead of the default basic regular expressions.
118 -F, --fixed-strings
120 Consider the limiting patterns to be fixed strings (don’t interpret
121 pattern as a regular expression).
122 -P, --perl-regexp
124 Consider the limiting patterns to be Perl-compatible regular
125 expressions.
126 Support for these types of regular expressions is an optional
128 compile-time dependency. If Git wasn’t compiled with support for
129 them providing this option will cause it to die.
130 --remove-empty
132 Stop when a given path disappears from the tree.
133 --merges
135 Print only merge commits. This is exactly the same as
136 --min-parents=2.
137 --no-merges
139 Do not print commits with more than one parent. This is exactly the
140 same as --max-parents=1.
141 --min-parents=<number>, --max-parents=<number>, --no-min-parents,
143 --no-max-parents
144 Show only commits which have at least (or at most) that many parent
145 commits. In particular, --max-parents=1 is the same as --no-merges,
146 --min-parents=2 is the same as --merges. --max-parents=0 gives all
147 root commits and --min-parents=3 all octopus merges.
148 --no-min-parents and --no-max-parents reset these limits (to no
150 limit) again. Equivalent forms are --min-parents=0 (any commit has
151 0 or more parents) and --max-parents=-1 (negative numbers denote no
152 upper limit).
153 --first-parent
155 Follow only the first parent commit upon seeing a merge commit.
156 This option can give a better overview when viewing the evolution
157 of a particular topic branch, because merges into a topic branch
158 tend to be only about adjusting to updated upstream from time to
159 time, and this option allows you to ignore the individual commits
160 brought in to your history by such a merge. Cannot be combined with
161 --bisect.
162 --not
164 Reverses the meaning of the ^ prefix (or lack thereof) for all
165 following revision specifiers, up to the next --not.
166 --all
168 Pretend as if all the refs in refs/, along with HEAD, are listed on
169 the command line as <commit>.
170 --branches[=<pattern>]
172 Pretend as if all the refs in refs/heads are listed on the command
173 line as <commit>. If <pattern> is given, limit branches to ones
174 matching given shell glob. If pattern lacks ?, *, or [, /* at the
175 end is implied.
176 --tags[=<pattern>]
178 Pretend as if all the refs in refs/tags are listed on the command
179 line as <commit>. If <pattern> is given, limit tags to ones
180 matching given shell glob. If pattern lacks ?, *, or [, /* at the
181 end is implied.
182 --remotes[=<pattern>]
184 Pretend as if all the refs in refs/remotes are listed on the
185 command line as <commit>. If <pattern> is given, limit
186 remote-tracking branches to ones matching given shell glob. If
187 pattern lacks ?, *, or [, /* at the end is implied.
188 --glob=<glob-pattern>
190 Pretend as if all the refs matching shell glob <glob-pattern> are
191 listed on the command line as <commit>. Leading refs/, is
192 automatically prepended if missing. If pattern lacks ?, *, or [, /*
193 at the end is implied.
194 --exclude=<glob-pattern>
196 Do not include refs matching <glob-pattern> that the next --all,
197 --branches, --tags, --remotes, or --glob would otherwise consider.
198 Repetitions of this option accumulate exclusion patterns up to the
199 next --all, --branches, --tags, --remotes, or --glob option (other
200 options or arguments do not clear accumulated patterns).
201 The patterns given should not begin with refs/heads, refs/tags, or
203 refs/remotes when applied to --branches, --tags, or --remotes,
204 respectively, and they must begin with refs/ when applied to --glob
205 or --all. If a trailing /* is intended, it must be given
206 explicitly.
207 --reflog
209 Pretend as if all objects mentioned by reflogs are listed on the
210 command line as <commit>.
211 --alternate-refs
213 Pretend as if all objects mentioned as ref tips of alternate
214 repositories were listed on the command line. An alternate
215 repository is any repository whose object directory is specified in
216 objects/info/alternates. The set of included objects may be
217 modified by core.alternateRefsCommand, etc. See git-config(1).
218 --single-worktree
220 By default, all working trees will be examined by the following
221 options when there are more than one (see git-worktree(1)): --all,
222 --reflog and --indexed-objects. This option forces them to examine
223 the current working tree only.
224 --ignore-missing
226 Upon seeing an invalid object name in the input, pretend as if the
227 bad input was not given.
228 --stdin
230 In addition to the <commit> listed on the command line, read them
231 from the standard input. If a -- separator is seen, stop reading
232 commits and start reading paths to limit the result.
233 --quiet
235 Don’t print anything to standard output. This form is primarily
236 meant to allow the caller to test the exit status to see if a range
237 of objects is fully connected (or not). It is faster than
238 redirecting stdout to /dev/null as the output does not have to be
239 formatted.
240 --cherry-mark
242 Like --cherry-pick (see below) but mark equivalent commits with =
243 rather than omitting them, and inequivalent ones with +.
244 --cherry-pick
246 Omit any commit that introduces the same change as another commit
247 on the “other side” when the set of commits are limited with
248 symmetric difference.
249 For example, if you have two branches, A and B, a usual way to list
251 all commits on only one side of them is with --left-right (see the
252 example below in the description of the --left-right option).
253 However, it shows the commits that were cherry-picked from the
254 other branch (for example, “3rd on b” may be cherry-picked from
255 branch A). With this option, such pairs of commits are excluded
256 from the output.
257 --left-only, --right-only
259 List only commits on the respective side of a symmetric difference,
260 i.e. only those which would be marked < resp. > by --left-right.
261 For example, --cherry-pick --right-only A...B omits those commits
263 from B which are in A or are patch-equivalent to a commit in A. In
264 other words, this lists the + commits from git cherry A B. More
265 precisely, --cherry-pick --right-only --no-merges gives the exact
266 list.
267 --cherry
269 A synonym for --right-only --cherry-mark --no-merges; useful to
270 limit the output to the commits on our side and mark those that
271 have been applied to the other side of a forked history with git
272 log --cherry upstream...mybranch, similar to git cherry upstream
273 mybranch.
274 -g, --walk-reflogs
276 Instead of walking the commit ancestry chain, walk reflog entries
277 from the most recent one to older ones. When this option is used
278 you cannot specify commits to exclude (that is, ^commit,
279 commit1..commit2, and commit1...commit2 notations cannot be used).
280 With --pretty format other than oneline and reference (for obvious
282 reasons), this causes the output to have two extra lines of
283 information taken from the reflog. The reflog designator in the
284 output may be shown as ref@{Nth} (where Nth is the
285 reverse-chronological index in the reflog) or as ref@{timestamp}
286 (with the timestamp for that entry), depending on a few rules:
287 1. If the starting point is specified as ref@{Nth}, show the index
289 format.
290 2. If the starting point was specified as ref@{now}, show the
292 timestamp format.
293 3. If neither was used, but --date was given on the command line,
295 show the timestamp in the format requested by --date.
296 4. Otherwise, show the index format.
298 Under --pretty=oneline, the commit message is prefixed with this
300 information on the same line. This option cannot be combined with
301 --reverse. See also git-reflog(1).
302 Under --pretty=reference, this information will not be shown at
304 all.
305 --merge
307 After a failed merge, show refs that touch files having a conflict
308 and don’t exist on all heads to merge.
309 --boundary
311 Output excluded boundary commits. Boundary commits are prefixed
312 with -.
313 --use-bitmap-index
315 Try to speed up the traversal using the pack bitmap index (if one
316 is available). Note that when traversing with --objects, trees and
317 blobs will not have their associated path printed.
318 --progress=<header>
320 Show progress reports on stderr as objects are considered. The
321 <header> text will be printed with each progress update.
322 History Simplification
324 Sometimes you are only interested in parts of the history, for example
325 the commits modifying a particular <path>. But there are two parts of
326 History Simplification, one part is selecting the commits and the other
327 is how to do it, as there are various strategies to simplify the
328 history.
329 The following options select the commits to be shown:
331 <paths>
333 Commits modifying the given <paths> are selected.
334 --simplify-by-decoration
336 Commits that are referred by some branch or tag are selected.
337 Note that extra commits can be shown to give a meaningful history.
339 The following options affect the way the simplification is performed:
341 Default mode
343 Simplifies the history to the simplest history explaining the final
344 state of the tree. Simplest because it prunes some side branches if
345 the end result is the same (i.e. merging branches with the same
346 content)
347 --full-history
349 Same as the default mode, but does not prune some history.
350 --dense
352 Only the selected commits are shown, plus some to have a meaningful
353 history.
354 --sparse
356 All commits in the simplified history are shown.
357 --simplify-merges
359 Additional option to --full-history to remove some needless merges
360 from the resulting history, as there are no selected commits
361 contributing to this merge.
362 --ancestry-path
364 When given a range of commits to display (e.g. commit1..commit2 or
365 commit2 ^commit1), only display commits that exist directly on the
366 ancestry chain between the commit1 and commit2, i.e. commits that
367 are both descendants of commit1, and ancestors of commit2.
368 A more detailed explanation follows.
370 Suppose you specified foo as the <paths>. We shall call commits that
372 modify foo !TREESAME, and the rest TREESAME. (In a diff filtered for
373 foo, they look different and equal, respectively.)
374 In the following, we will always refer to the same example history to
376 illustrate the differences between simplification settings. We assume
377 that you are filtering for a file foo in this commit graph:
378 .-A---M---N---O---P---Q
380 / / / / / /
381 I B C D E Y
382 \ / / / / /
383 `-------------' X
384 The horizontal line of history A---Q is taken to be the first parent of
386 each merge. The commits are:
387 · I is the initial commit, in which foo exists with contents “asdf”,
389 and a file quux exists with contents “quux”. Initial commits are
390 compared to an empty tree, so I is !TREESAME.
391 · In A, foo contains just “foo”.
393 · B contains the same change as A. Its merge M is trivial and hence
395 TREESAME to all parents.
396 · C does not change foo, but its merge N changes it to “foobar”, so
398 it is not TREESAME to any parent.
399 · D sets foo to “baz”. Its merge O combines the strings from N and D
401 to “foobarbaz”; i.e., it is not TREESAME to any parent.
402 · E changes quux to “xyzzy”, and its merge P combines the strings to
404 “quux xyzzy”. P is TREESAME to O, but not to E.
405 · X is an independent root commit that added a new file side, and Y
407 modified it. Y is TREESAME to X. Its merge Q added side to P, and
408 Q is TREESAME to P, but not to Y.
409 rev-list walks backwards through history, including or excluding
411 commits based on whether --full-history and/or parent rewriting (via
412 --parents or --children) are used. The following settings are
413 available.
414 Default mode
416 Commits are included if they are not TREESAME to any parent (though
417 this can be changed, see --sparse below). If the commit was a
418 merge, and it was TREESAME to one parent, follow only that parent.
419 (Even if there are several TREESAME parents, follow only one of
420 them.) Otherwise, follow all parents.
421 This results in:
423 .-A---N---O
425 / / /
426 I---------D
427 Note how the rule to only follow the TREESAME parent, if one is
429 available, removed B from consideration entirely. C was considered
430 via N, but is TREESAME. Root commits are compared to an empty tree,
431 so I is !TREESAME.
432 Parent/child relations are only visible with --parents, but that
434 does not affect the commits selected in default mode, so we have
435 shown the parent lines.
436 --full-history without parent rewriting
438 This mode differs from the default in one point: always follow all
439 parents of a merge, even if it is TREESAME to one of them. Even if
440 more than one side of the merge has commits that are included, this
441 does not imply that the merge itself is! In the example, we get
442 I A B N D O P Q
444 M was excluded because it is TREESAME to both parents. E, C and B
446 were all walked, but only B was !TREESAME, so the others do not
447 appear.
448 Note that without parent rewriting, it is not really possible to
450 talk about the parent/child relationships between the commits, so
451 we show them disconnected.
452 --full-history with parent rewriting
454 Ordinary commits are only included if they are !TREESAME (though
455 this can be changed, see --sparse below).
456 Merges are always included. However, their parent list is
458 rewritten: Along each parent, prune away commits that are not
459 included themselves. This results in
460 .-A---M---N---O---P---Q
462 / / / / /
463 I B / D /
464 \ / / / /
465 `-------------'
466 Compare to --full-history without rewriting above. Note that E was
468 pruned away because it is TREESAME, but the parent list of P was
469 rewritten to contain E's parent I. The same happened for C and N,
470 and X, Y and Q.
471 In addition to the above settings, you can change whether TREESAME
473 affects inclusion:
474 --dense
476 Commits that are walked are included if they are not TREESAME to
477 any parent.
478 --sparse
480 All commits that are walked are included.
481 Note that without --full-history, this still simplifies merges: if
483 one of the parents is TREESAME, we follow only that one, so the
484 other sides of the merge are never walked.
485 --simplify-merges
487 First, build a history graph in the same way that --full-history
488 with parent rewriting does (see above).
489 Then simplify each commit C to its replacement C' in the final
491 history according to the following rules:
492 · Set C' to C.
494 · Replace each parent P of C' with its simplification P'. In the
496 process, drop parents that are ancestors of other parents or
497 that are root commits TREESAME to an empty tree, and remove
498 duplicates, but take care to never drop all parents that we are
499 TREESAME to.
500 · If after this parent rewriting, C' is a root or merge commit
502 (has zero or >1 parents), a boundary commit, or !TREESAME, it
503 remains. Otherwise, it is replaced with its only parent.
504 The effect of this is best shown by way of comparing to
506 --full-history with parent rewriting. The example turns into:
507 .-A---M---N---O
509 / / /
510 I B D
511 \ / /
512 `---------'
513 Note the major differences in N, P, and Q over --full-history:
515 · N's parent list had I removed, because it is an ancestor of the
517 other parent M. Still, N remained because it is !TREESAME.
518 · P's parent list similarly had I removed. P was then removed
520 completely, because it had one parent and is TREESAME.
521 · Q's parent list had Y simplified to X. X was then removed,
523 because it was a TREESAME root. Q was then removed completely,
524 because it had one parent and is TREESAME.
525 Finally, there is a fifth simplification mode available:
527 --ancestry-path
529 Limit the displayed commits to those directly on the ancestry chain
530 between the “from” and “to” commits in the given commit range. I.e.
531 only display commits that are ancestor of the “to” commit and
532 descendants of the “from” commit.
533 As an example use case, consider the following commit history:
535 D---E-------F
537 / \ \
538 B---C---G---H---I---J
539 / \
540 A-------K---------------L--M
541 A regular D..M computes the set of commits that are ancestors of M,
543 but excludes the ones that are ancestors of D. This is useful to
544 see what happened to the history leading to M since D, in the sense
545 that “what does M have that did not exist in D”. The result in this
546 example would be all the commits, except A and B (and D itself, of
547 course).
548 When we want to find out what commits in M are contaminated with
550 the bug introduced by D and need fixing, however, we might want to
551 view only the subset of D..M that are actually descendants of D,
552 i.e. excluding C and K. This is exactly what the --ancestry-path
553 option does. Applied to the D..M range, it results in:
554 E-------F
556 \ \
557 G---H---I---J
558 \
559 L--M
560 The --simplify-by-decoration option allows you to view only the big
562 picture of the topology of the history, by omitting commits that are
563 not referenced by tags. Commits are marked as !TREESAME (in other
564 words, kept after history simplification rules described above) if (1)
565 they are referenced by tags, or (2) they change the contents of the
566 paths given on the command line. All other commits are marked as
567 TREESAME (subject to be simplified away).
568 Bisection Helpers
570 --bisect
571 Limit output to the one commit object which is roughly halfway
572 between included and excluded commits. Note that the bad bisection
573 ref refs/bisect/bad is added to the included commits (if it exists)
574 and the good bisection refs refs/bisect/good-* are added to the
575 excluded commits (if they exist). Thus, supposing there are no refs
576 in refs/bisect/, if
577 $ git rev-list --bisect foo ^bar ^baz
579 outputs midpoint, the output of the two commands
581 $ git rev-list foo ^midpoint
583 $ git rev-list midpoint ^bar ^baz
584 would be of roughly the same length. Finding the change which
586 introduces a regression is thus reduced to a binary search:
587 repeatedly generate and test new 'midpoint’s until the commit chain
588 is of length one. Cannot be combined with --first-parent.
589 --bisect-vars
591 This calculates the same as --bisect, except that refs in
592 refs/bisect/ are not used, and except that this outputs text ready
593 to be eval’ed by the shell. These lines will assign the name of the
594 midpoint revision to the variable bisect_rev, and the expected
595 number of commits to be tested after bisect_rev is tested to
596 bisect_nr, the expected number of commits to be tested if
597 bisect_rev turns out to be good to bisect_good, the expected number
598 of commits to be tested if bisect_rev turns out to be bad to
599 bisect_bad, and the number of commits we are bisecting right now to
600 bisect_all.
601 --bisect-all
603 This outputs all the commit objects between the included and
604 excluded commits, ordered by their distance to the included and
605 excluded commits. Refs in refs/bisect/ are not used. The farthest
606 from them is displayed first. (This is the only one displayed by
607 --bisect.)
608 This is useful because it makes it easy to choose a good commit to
610 test when you want to avoid to test some of them for some reason
611 (they may not compile for example).
612 This option can be used along with --bisect-vars, in this case,
614 after all the sorted commit objects, there will be the same text as
615 if --bisect-vars had been used alone.
616 Commit Ordering
618 By default, the commits are shown in reverse chronological order.
619 --date-order
621 Show no parents before all of its children are shown, but otherwise
622 show commits in the commit timestamp order.
623 --author-date-order
625 Show no parents before all of its children are shown, but otherwise
626 show commits in the author timestamp order.
627 --topo-order
629 Show no parents before all of its children are shown, and avoid
630 showing commits on multiple lines of history intermixed.
631 For example, in a commit history like this:
633 ---1----2----4----7
635 \ \
636 3----5----6----8---
637 where the numbers denote the order of commit timestamps, git
639 rev-list and friends with --date-order show the commits in the
640 timestamp order: 8 7 6 5 4 3 2 1.
641 With --topo-order, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5
643 3 1); some older commits are shown before newer ones in order to
644 avoid showing the commits from two parallel development track mixed
645 together.
646 --reverse
648 Output the commits chosen to be shown (see Commit Limiting section
649 above) in reverse order. Cannot be combined with --walk-reflogs.
650 Object Traversal
652 These options are mostly targeted for packing of Git repositories.
653 --objects
655 Print the object IDs of any object referenced by the listed
656 commits. --objects foo ^bar thus means “send me all object IDs
657 which I need to download if I have the commit object bar but not
658 foo”.
659 --in-commit-order
661 Print tree and blob ids in order of the commits. The tree and blob
662 ids are printed after they are first referenced by a commit.
663 --objects-edge
665 Similar to --objects, but also print the IDs of excluded commits
666 prefixed with a “-” character. This is used by git-pack-objects(1)
667 to build a “thin” pack, which records objects in deltified form
668 based on objects contained in these excluded commits to reduce
669 network traffic.
670 --objects-edge-aggressive
672 Similar to --objects-edge, but it tries harder to find excluded
673 commits at the cost of increased time. This is used instead of
674 --objects-edge to build “thin” packs for shallow repositories.
675 --indexed-objects
677 Pretend as if all trees and blobs used by the index are listed on
678 the command line. Note that you probably want to use --objects,
679 too.
680 --unpacked
682 Only useful with --objects; print the object IDs that are not in
683 packs.
684 --object-names
686 Only useful with --objects; print the names of the object IDs that
687 are found. This is the default behavior.
688 --no-object-names
690 Only useful with --objects; does not print the names of the object
691 IDs that are found. This inverts --object-names. This flag allows
692 the output to be more easily parsed by commands such as git-cat-
693 file(1).
694 --filter=<filter-spec>
696 Only useful with one of the --objects*; omits objects (usually
697 blobs) from the list of printed objects. The <filter-spec> may be
698 one of the following:
699 The form --filter=blob:none omits all blobs.
701 The form --filter=blob:limit=<n>[kmg] omits blobs larger than n
703 bytes or units. n may be zero. The suffixes k, m, and g can be used
704 to name units in KiB, MiB, or GiB. For example, blob:limit=1k is
705 the same as blob:limit=1024.
706 The form --filter=sparse:oid=<blob-ish> uses a sparse-checkout
708 specification contained in the blob (or blob-expression) <blob-ish>
709 to omit blobs that would not be not required for a sparse checkout
710 on the requested refs.
711 The form --filter=tree:<depth> omits all blobs and trees whose
713 depth from the root tree is >= <depth> (minimum depth if an object
714 is located at multiple depths in the commits traversed). <depth>=0
715 will not include any trees or blobs unless included explicitly in
716 the command-line (or standard input when --stdin is used).
717 <depth>=1 will include only the tree and blobs which are referenced
718 directly by a commit reachable from <commit> or an explicitly-given
719 object. <depth>=2 is like <depth>=1 while also including trees and
720 blobs one more level removed from an explicitly-given commit or
721 tree.
722 Note that the form --filter=sparse:path=<path> that wants to read
724 from an arbitrary path on the filesystem has been dropped for
725 security reasons.
726 Multiple --filter= flags can be specified to combine filters. Only
728 objects which are accepted by every filter are included.
729 The form --filter=combine:<filter1>+<filter2>+...<filterN> can also
731 be used to combined several filters, but this is harder than just
732 repeating the --filter flag and is usually not necessary. Filters
733 are joined by + and individual filters are %-encoded (i.e.
734 URL-encoded). Besides the + and % characters, the following
735 characters are reserved and also must be encoded:
736 ~!@#$^&*()[]{}\;",<>?'` as well as all characters with ASCII code
737 <= 0x20, which includes space and newline.
738 Other arbitrary characters can also be encoded. For instance,
740 combine:tree:3+blob:none and combine:tree%3A3+blob%3Anone are
741 equivalent.
742 --no-filter
744 Turn off any previous --filter= argument.
745 --filter-print-omitted
747 Only useful with --filter=; prints a list of the objects omitted by
748 the filter. Object IDs are prefixed with a “~” character.
749 --missing=<missing-action>
751 A debug option to help with future "partial clone" development.
752 This option specifies how missing objects are handled.
753 The form --missing=error requests that rev-list stop with an error
755 if a missing object is encountered. This is the default action.
756 The form --missing=allow-any will allow object traversal to
758 continue if a missing object is encountered. Missing objects will
759 silently be omitted from the results.
760 The form --missing=allow-promisor is like allow-any, but will only
762 allow object traversal to continue for EXPECTED promisor missing
763 objects. Unexpected missing objects will raise an error.
764 The form --missing=print is like allow-any, but will also print a
766 list of the missing objects. Object IDs are prefixed with a “?”
767 character.
768 --exclude-promisor-objects
770 (For internal use only.) Prefilter object traversal at promisor
771 boundary. This is used with partial clone. This is stronger than
772 --missing=allow-promisor because it limits the traversal, rather
773 than just silencing errors about missing objects.
774 --no-walk[=(sorted|unsorted)]
776 Only show the given commits, but do not traverse their ancestors.
777 This has no effect if a range is specified. If the argument
778 unsorted is given, the commits are shown in the order they were
779 given on the command line. Otherwise (if sorted or no argument was
780 given), the commits are shown in reverse chronological order by
781 commit time. Cannot be combined with --graph.
782 --do-walk
784 Overrides a previous --no-walk.
785 Commit Formatting
787 Using these options, git-rev-list(1) will act similar to the more
788 specialized family of commit log tools: git-log(1), git-show(1), and
789 git-whatchanged(1)
790 --pretty[=<format>], --format=<format>
792 Pretty-print the contents of the commit logs in a given format,
793 where <format> can be one of oneline, short, medium, full, fuller,
794 reference, email, raw, format:<string> and tformat:<string>. When
795 <format> is none of the above, and has %placeholder in it, it acts
796 as if --pretty=tformat:<format> were given.
797 See the "PRETTY FORMATS" section for some additional details for
799 each format. When =<format> part is omitted, it defaults to medium.
800 Note: you can specify the default pretty format in the repository
802 configuration (see git-config(1)).
803 --abbrev-commit
805 Instead of showing the full 40-byte hexadecimal commit object name,
806 show only a partial prefix. Non default number of digits can be
807 specified with "--abbrev=<n>" (which also modifies diff output, if
808 it is displayed).
809 This should make "--pretty=oneline" a whole lot more readable for
811 people using 80-column terminals.
812 --no-abbrev-commit
814 Show the full 40-byte hexadecimal commit object name. This negates
815 --abbrev-commit and those options which imply it such as
816 "--oneline". It also overrides the log.abbrevCommit variable.
817 --oneline
819 This is a shorthand for "--pretty=oneline --abbrev-commit" used
820 together.
821 --encoding=<encoding>
823 The commit objects record the encoding used for the log message in
824 their encoding header; this option can be used to tell the command
825 to re-code the commit log message in the encoding preferred by the
826 user. For non plumbing commands this defaults to UTF-8. Note that
827 if an object claims to be encoded in X and we are outputting in X,
828 we will output the object verbatim; this means that invalid
829 sequences in the original commit may be copied to the output.
830 --expand-tabs=<n>, --expand-tabs, --no-expand-tabs
832 Perform a tab expansion (replace each tab with enough spaces to
833 fill to the next display column that is multiple of <n>) in the log
834 message before showing it in the output. --expand-tabs is a
835 short-hand for --expand-tabs=8, and --no-expand-tabs is a
836 short-hand for --expand-tabs=0, which disables tab expansion.
837 By default, tabs are expanded in pretty formats that indent the log
839 message by 4 spaces (i.e. medium, which is the default, full, and
840 fuller).
841 --show-signature
843 Check the validity of a signed commit object by passing the
844 signature to gpg --verify and show the output.
845 --relative-date
847 Synonym for --date=relative.
848 --date=<format>
850 Only takes effect for dates shown in human-readable format, such as
851 when using --pretty. log.date config variable sets a default value
852 for the log command’s --date option. By default, dates are shown in
853 the original time zone (either committer’s or author’s). If -local
854 is appended to the format (e.g., iso-local), the user’s local time
855 zone is used instead.
856 --date=relative shows dates relative to the current time, e.g. “2
858 hours ago”. The -local option has no effect for --date=relative.
859 --date=local is an alias for --date=default-local.
861 --date=iso (or --date=iso8601) shows timestamps in a ISO 8601-like
863 format. The differences to the strict ISO 8601 format are:
864 · a space instead of the T date/time delimiter
866 · a space between time and time zone
868 · no colon between hours and minutes of the time zone
870 --date=iso-strict (or --date=iso8601-strict) shows timestamps in
872 strict ISO 8601 format.
873 --date=rfc (or --date=rfc2822) shows timestamps in RFC 2822 format,
875 often found in email messages.
876 --date=short shows only the date, but not the time, in YYYY-MM-DD
878 format.
879 --date=raw shows the date as seconds since the epoch (1970-01-01
881 00:00:00 UTC), followed by a space, and then the timezone as an
882 offset from UTC (a + or - with four digits; the first two are
883 hours, and the second two are minutes). I.e., as if the timestamp
884 were formatted with strftime("%s %z")). Note that the -local option
885 does not affect the seconds-since-epoch value (which is always
886 measured in UTC), but does switch the accompanying timezone value.
887 --date=human shows the timezone if the timezone does not match the
889 current time-zone, and doesn’t print the whole date if that matches
890 (ie skip printing year for dates that are "this year", but also
891 skip the whole date itself if it’s in the last few days and we can
892 just say what weekday it was). For older dates the hour and minute
893 is also omitted.
894 --date=unix shows the date as a Unix epoch timestamp (seconds since
896 1970). As with --raw, this is always in UTC and therefore -local
897 has no effect.
898 --date=format:... feeds the format ... to your system strftime,
900 except for %z and %Z, which are handled internally. Use
901 --date=format:%c to show the date in your system locale’s preferred
902 format. See the strftime manual for a complete list of format
903 placeholders. When using -local, the correct syntax is
904 --date=format-local:....
905 --date=default is the default format, and is similar to
907 --date=rfc2822, with a few exceptions:
908 · there is no comma after the day-of-week
910 · the time zone is omitted when the local time zone is used
912 --header
914 Print the contents of the commit in raw-format; each record is
915 separated with a NUL character.
916 --parents
918 Print also the parents of the commit (in the form "commit parent...
919 "). Also enables parent rewriting, see History Simplification
920 above.
921 --children
923 Print also the children of the commit (in the form "commit child...
924 "). Also enables parent rewriting, see History Simplification
925 above.
926 --timestamp
928 Print the raw commit timestamp.
929 --left-right
931 Mark which side of a symmetric difference a commit is reachable
932 from. Commits from the left side are prefixed with < and those from
933 the right with >. If combined with --boundary, those commits are
934 prefixed with -.
935 For example, if you have this topology:
937 y---b---b branch B
939 / \ /
940 / .
941 / / \
942 o---x---a---a branch A
943 you would get an output like this:
945 $ git rev-list --left-right --boundary --pretty=oneline A...B
947 >bbbbbbb... 3rd on b
949 >bbbbbbb... 2nd on b
950 <aaaaaaa... 3rd on a
951 <aaaaaaa... 2nd on a
952 -yyyyyyy... 1st on b
953 -xxxxxxx... 1st on a
954 --graph
956 Draw a text-based graphical representation of the commit history on
957 the left hand side of the output. This may cause extra lines to be
958 printed in between commits, in order for the graph history to be
959 drawn properly. Cannot be combined with --no-walk.
960 This enables parent rewriting, see History Simplification above.
962 This implies the --topo-order option by default, but the
964 --date-order option may also be specified.
965 --show-linear-break[=<barrier>]
967 When --graph is not used, all history branches are flattened which
968 can make it hard to see that the two consecutive commits do not
969 belong to a linear branch. This option puts a barrier in between
970 them in that case. If <barrier> is specified, it is the string that
971 will be shown instead of the default one.
972 --count
974 Print a number stating how many commits would have been listed, and
975 suppress all other output. When used together with --left-right,
976 instead print the counts for left and right commits, separated by a
977 tab. When used together with --cherry-mark, omit patch equivalent
978 commits from these counts and print the count for equivalent
979 commits separated by a tab.
980
982 If the commit is a merge, and if the pretty-format is not oneline,
983 email or raw, an additional line is inserted before the Author: line.
984 This line begins with "Merge: " and the hashes of ancestral commits are
985 printed, separated by spaces. Note that the listed commits may not
986 necessarily be the list of the direct parent commits if you have
987 limited your view of history: for example, if you are only interested
988 in changes related to a certain directory or file.
989 There are several built-in formats, and you can define additional
991 formats by setting a pretty.<name> config option to either another
992 format name, or a format: string, as described below (see git-
993 config(1)). Here are the details of the built-in formats:
994 · oneline
996 <hash> <title line>
998 This is designed to be as compact as possible.
1000 · short
1002 commit <hash>
1004 Author: <author>
1005 <title line>
1007 · medium
1009 commit <hash>
1011 Author: <author>
1012 Date: <author date>
1013 <title line>
1015 <full commit message>
1017 · full
1019 commit <hash>
1021 Author: <author>
1022 Commit: <committer>
1023 <title line>
1025 <full commit message>
1027 · fuller
1029 commit <hash>
1031 Author: <author>
1032 AuthorDate: <author date>
1033 Commit: <committer>
1034 CommitDate: <committer date>
1035 <title line>
1037 <full commit message>
1039 · reference
1041 <abbrev hash> (<title line>, <short author date>)
1043 This format is used to refer to another commit in a commit message
1045 and is the same as --pretty='format:%C(auto)%h (%s, %ad)'. By
1046 default, the date is formatted with --date=short unless another
1047 --date option is explicitly specified. As with any format: with
1048 format placeholders, its output is not affected by other options
1049 like --decorate and --walk-reflogs.
1050 · email
1052 From <hash> <date>
1054 From: <author>
1055 Date: <author date>
1056 Subject: [PATCH] <title line>
1057 <full commit message>
1059 · raw
1061 The raw format shows the entire commit exactly as stored in the
1063 commit object. Notably, the hashes are displayed in full,
1064 regardless of whether --abbrev or --no-abbrev are used, and parents
1065 information show the true parent commits, without taking grafts or
1066 history simplification into account. Note that this format affects
1067 the way commits are displayed, but not the way the diff is shown
1068 e.g. with git log --raw. To get full object names in a raw diff
1069 format, use --no-abbrev.
1070 · format:<string>
1072 The format:<string> format allows you to specify which information
1074 you want to show. It works a little bit like printf format, with
1075 the notable exception that you get a newline with %n instead of \n.
1076 E.g, format:"The author of %h was %an, %ar%nThe title was >>%s<<%n"
1078 would show something like this:
1079 The author of fe6e0ee was Junio C Hamano, 23 hours ago
1081 The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<
1082 The placeholders are:
1084 · Placeholders that expand to a single literal character:
1086 %n
1088 newline
1089 %%
1091 a raw %
1092 %x00
1094 print a byte from a hex code
1095 · Placeholders that affect formatting of later placeholders:
1097 %Cred
1099 switch color to red
1100 %Cgreen
1102 switch color to green
1103 %Cblue
1105 switch color to blue
1106 %Creset
1108 reset color
1109 %C(...)
1111 color specification, as described under Values in the
1112 "CONFIGURATION FILE" section of git-config(1). By default,
1113 colors are shown only when enabled for log output (by
1114 color.diff, color.ui, or --color, and respecting the auto
1115 settings of the former if we are going to a terminal).
1116 %C(auto,...) is accepted as a historical synonym for the
1117 default (e.g., %C(auto,red)). Specifying %C(always,...)
1118 will show the colors even when color is not otherwise
1119 enabled (though consider just using --color=always to
1120 enable color for the whole output, including this format
1121 and anything else git might color). auto alone (i.e.
1122 %C(auto)) will turn on auto coloring on the next
1123 placeholders until the color is switched again.
1124 %m
1126 left (<), right (>) or boundary (-) mark
1127 %w([<w>[,<i1>[,<i2>]]])
1129 switch line wrapping, like the -w option of git-
1130 shortlog(1).
1131 %<(<N>[,trunc|ltrunc|mtrunc])
1133 make the next placeholder take at least N columns, padding
1134 spaces on the right if necessary. Optionally truncate at
1135 the beginning (ltrunc), the middle (mtrunc) or the end
1136 (trunc) if the output is longer than N columns. Note that
1137 truncating only works correctly with N >= 2.
1138 %<|(<N>)
1140 make the next placeholder take at least until Nth columns,
1141 padding spaces on the right if necessary
1142 %>(<N>), %>|(<N>)
1144 similar to %<(<N>), %<|(<N>) respectively, but padding
1145 spaces on the left
1146 %>>(<N>), %>>|(<N>)
1148 similar to %>(<N>), %>|(<N>) respectively, except that if
1149 the next placeholder takes more spaces than given and there
1150 are spaces on its left, use those spaces
1151 %><(<N>), %><|(<N>)
1153 similar to %<(<N>), %<|(<N>) respectively, but padding both
1154 sides (i.e. the text is centered)
1155 · Placeholders that expand to information extracted from the
1157 commit:
1158 %H
1160 commit hash
1161 %h
1163 abbreviated commit hash
1164 %T
1166 tree hash
1167 %t
1169 abbreviated tree hash
1170 %P
1172 parent hashes
1173 %p
1175 abbreviated parent hashes
1176 %an
1178 author name
1179 %aN
1181 author name (respecting .mailmap, see git-shortlog(1) or
1182 git-blame(1))
1183 %ae
1185 author email
1186 %aE
1188 author email (respecting .mailmap, see git-shortlog(1) or
1189 git-blame(1))
1190 %al
1192 author email local-part (the part before the @ sign)
1193 %aL
1195 author local-part (see %al) respecting .mailmap, see git-
1196 shortlog(1) or git-blame(1))
1197 %ad
1199 author date (format respects --date= option)
1200 %aD
1202 author date, RFC2822 style
1203 %ar
1205 author date, relative
1206 %at
1208 author date, UNIX timestamp
1209 %ai
1211 author date, ISO 8601-like format
1212 %aI
1214 author date, strict ISO 8601 format
1215 %as
1217 author date, short format (YYYY-MM-DD)
1218 %cn
1220 committer name
1221 %cN
1223 committer name (respecting .mailmap, see git-shortlog(1) or
1224 git-blame(1))
1225 %ce
1227 committer email
1228 %cE
1230 committer email (respecting .mailmap, see git-shortlog(1)
1231 or git-blame(1))
1232 %cl
1234 author email local-part (the part before the @ sign)
1235 %cL
1237 author local-part (see %cl) respecting .mailmap, see git-
1238 shortlog(1) or git-blame(1))
1239 %cd
1241 committer date (format respects --date= option)
1242 %cD
1244 committer date, RFC2822 style
1245 %cr
1247 committer date, relative
1248 %ct
1250 committer date, UNIX timestamp
1251 %ci
1253 committer date, ISO 8601-like format
1254 %cI
1256 committer date, strict ISO 8601 format
1257 %cs
1259 committer date, short format (YYYY-MM-DD)
1260 %d
1262 ref names, like the --decorate option of git-log(1)
1263 %D
1265 ref names without the " (", ")" wrapping.
1266 %S
1268 ref name given on the command line by which the commit was
1269 reached (like git log --source), only works with git log
1270 %e
1272 encoding
1273 %s
1275 subject
1276 %f
1278 sanitized subject line, suitable for a filename
1279 %b
1281 body
1282 %B
1284 raw body (unwrapped subject and body)
1285 %GG
1287 raw verification message from GPG for a signed commit
1288 %G?
1290 show "G" for a good (valid) signature, "B" for a bad
1291 signature, "U" for a good signature with unknown validity,
1292 "X" for a good signature that has expired, "Y" for a good
1293 signature made by an expired key, "R" for a good signature
1294 made by a revoked key, "E" if the signature cannot be
1295 checked (e.g. missing key) and "N" for no signature
1296 %GS
1298 show the name of the signer for a signed commit
1299 %GK
1301 show the key used to sign a signed commit
1302 %GF
1304 show the fingerprint of the key used to sign a signed
1305 commit
1306 %GP
1308 show the fingerprint of the primary key whose subkey was
1309 used to sign a signed commit
1310 %GT
1312 show the trust level for the key used to sign a signed
1313 commit
1314 %gD
1316 reflog selector, e.g., refs/stash@{1} or refs/stash@{2
1317 minutes ago}; the format follows the rules described for
1318 the -g option. The portion before the @ is the refname as
1319 given on the command line (so git log -g refs/heads/master
1320 would yield refs/heads/master@{0}).
1321 %gd
1323 shortened reflog selector; same as %gD, but the refname
1324 portion is shortened for human readability (so
1325 refs/heads/master becomes just master).
1326 %gn
1328 reflog identity name
1329 %gN
1331 reflog identity name (respecting .mailmap, see git-
1332 shortlog(1) or git-blame(1))
1333 %ge
1335 reflog identity email
1336 %gE
1338 reflog identity email (respecting .mailmap, see git-
1339 shortlog(1) or git-blame(1))
1340 %gs
1342 reflog subject
1343 %(trailers[:options])
1345 display the trailers of the body as interpreted by git-
1346 interpret-trailers(1). The trailers string may be followed
1347 by a colon and zero or more comma-separated options:
1348 · key=<K>: only show trailers with specified key.
1350 Matching is done case-insensitively and trailing colon
1351 is optional. If option is given multiple times trailer
1352 lines matching any of the keys are shown. This option
1353 automatically enables the only option so that
1354 non-trailer lines in the trailer block are hidden. If
1355 that is not desired it can be disabled with only=false.
1356 E.g., %(trailers:key=Reviewed-by) shows trailer lines
1357 with key Reviewed-by.
1358 · only[=val]: select whether non-trailer lines from the
1360 trailer block should be included. The only keyword may
1361 optionally be followed by an equal sign and one of
1362 true, on, yes to omit or false, off, no to show the
1363 non-trailer lines. If option is given without value it
1364 is enabled. If given multiple times the last value is
1365 used.
1366 · separator=<SEP>: specify a separator inserted between
1368 trailer lines. When this option is not given each
1369 trailer line is terminated with a line feed character.
1370 The string SEP may contain the literal formatting codes
1371 described above. To use comma as separator one must use
1372 %x2C as it would otherwise be parsed as next option. If
1373 separator option is given multiple times only the last
1374 one is used. E.g., %(trailers:key=Ticket,separator=%x2C
1375 ) shows all trailer lines whose key is "Ticket"
1376 separated by a comma and a space.
1377 · unfold[=val]: make it behave as if interpret-trailer’s
1379 --unfold option was given. In same way as to for only
1380 it can be followed by an equal sign and explicit value.
1381 E.g., %(trailers:only,unfold=true) unfolds and shows
1382 all trailer lines.
1383 · valueonly[=val]: skip over the key part of the trailer
1385 line and only show the value part. Also this optionally
1386 allows explicit value.
1387 Note
1389 Some placeholders may depend on other options given to the revision
1390 traversal engine. For example, the %g* reflog options will insert
1391 an empty string unless we are traversing reflog entries (e.g., by
1392 git log -g). The %d and %D placeholders will use the "short"
1393 decoration format if --decorate was not already provided on the
1394 command line.
1395 If you add a + (plus sign) after % of a placeholder, a line-feed is
1397 inserted immediately before the expansion if and only if the
1398 placeholder expands to a non-empty string.
1399 If you add a - (minus sign) after % of a placeholder, all consecutive
1401 line-feeds immediately preceding the expansion are deleted if and only
1402 if the placeholder expands to an empty string.
1403 If you add a ` ` (space) after % of a placeholder, a space is inserted
1405 immediately before the expansion if and only if the placeholder expands
1406 to a non-empty string.
1407 · tformat:
1409 The tformat: format works exactly like format:, except that it
1411 provides "terminator" semantics instead of "separator" semantics.
1412 In other words, each commit has the message terminator character
1413 (usually a newline) appended, rather than a separator placed
1414 between entries. This means that the final entry of a single-line
1415 format will be properly terminated with a new line, just as the
1416 "oneline" format does. For example:
1417 $ git log -2 --pretty=format:%h 4da45bef \
1419 | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
1420 4da45be
1421 7134973 -- NO NEWLINE
1422 $ git log -2 --pretty=tformat:%h 4da45bef \
1424 | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
1425 4da45be
1426 7134973
1427 In addition, any unrecognized string that has a % in it is
1429 interpreted as if it has tformat: in front of it. For example,
1430 these two are equivalent:
1431 $ git log -2 --pretty=tformat:%h 4da45bef
1433 $ git log -2 --pretty=%h 4da45bef
1434
1436 Part of the git(1) suite
1437Git 2.26.2 2020-04-20 GIT-REV-LIST(1)