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 reachable from any of
18 the commits given on the command line form a set, and then commits
19 reachable from any of the ones given with ^ in front are subtracted
20 from that set. The remaining commits are what comes out in the
21 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 be
33 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 an essential Git command, since it provides the ability to
46 build and traverse commit ancestry graphs. For this reason, it has a
47 lot of different options that enable 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 --since-as-filter=<date>
74 Show all commits more recent than a specific date. This visits all
75 commits in the range, rather than stopping at the first commit
76 which is older than a specific date.
77 --until=<date>, --before=<date>
79 Show commits older than a specific date.
80 --max-age=<timestamp>, --min-age=<timestamp>
82 Limit the commits output to specified time range.
83 --author=<pattern>, --committer=<pattern>
85 Limit the commits output to ones with author/committer header lines
86 that match the specified pattern (regular expression). With more
87 than one --author=<pattern>, commits whose author matches any of
88 the given patterns are chosen (similarly for multiple
89 --committer=<pattern>).
90 --grep-reflog=<pattern>
92 Limit the commits output to ones with reflog entries that match the
93 specified pattern (regular expression). With more than one
94 --grep-reflog, commits whose reflog message matches any of the
95 given patterns are chosen. It is an error to use this option unless
96 --walk-reflogs is in use.
97 --grep=<pattern>
99 Limit the commits output to ones with a log message that matches
100 the specified pattern (regular expression). With more than one
101 --grep=<pattern>, commits whose message matches any of the given
102 patterns are chosen (but see --all-match).
103 --all-match
105 Limit the commits output to ones that match all given --grep,
106 instead of ones that match at least one.
107 --invert-grep
109 Limit the commits output to ones with a log message that do not
110 match the pattern specified with --grep=<pattern>.
111 -i, --regexp-ignore-case
113 Match the regular expression limiting patterns without regard to
114 letter case.
115 --basic-regexp
117 Consider the limiting patterns to be basic regular expressions;
118 this is the default.
119 -E, --extended-regexp
121 Consider the limiting patterns to be extended regular expressions
122 instead of the default basic regular expressions.
123 -F, --fixed-strings
125 Consider the limiting patterns to be fixed strings (don’t interpret
126 pattern as a regular expression).
127 -P, --perl-regexp
129 Consider the limiting patterns to be Perl-compatible regular
130 expressions.
131 Support for these types of regular expressions is an optional
133 compile-time dependency. If Git wasn’t compiled with support for
134 them providing this option will cause it to die.
135 --remove-empty
137 Stop when a given path disappears from the tree.
138 --merges
140 Print only merge commits. This is exactly the same as
141 --min-parents=2.
142 --no-merges
144 Do not print commits with more than one parent. This is exactly the
145 same as --max-parents=1.
146 --min-parents=<number>, --max-parents=<number>, --no-min-parents,
148 --no-max-parents
149 Show only commits which have at least (or at most) that many parent
150 commits. In particular, --max-parents=1 is the same as --no-merges,
151 --min-parents=2 is the same as --merges. --max-parents=0 gives all
152 root commits and --min-parents=3 all octopus merges.
153 --no-min-parents and --no-max-parents reset these limits (to no
155 limit) again. Equivalent forms are --min-parents=0 (any commit has
156 0 or more parents) and --max-parents=-1 (negative numbers denote no
157 upper limit).
158 --first-parent
160 When finding commits to include, follow only the first parent
161 commit upon seeing a merge commit. This option can give a better
162 overview when viewing the evolution of a particular topic branch,
163 because merges into a topic branch tend to be only about adjusting
164 to updated upstream from time to time, and this option allows you
165 to ignore the individual commits brought in to your history by such
166 a merge.
167 --exclude-first-parent-only
169 When finding commits to exclude (with a ^), follow only the first
170 parent commit upon seeing a merge commit. This can be used to find
171 the set of changes in a topic branch from the point where it
172 diverged from the remote branch, given that arbitrary merges can be
173 valid topic branch changes.
174 --not
176 Reverses the meaning of the ^ prefix (or lack thereof) for all
177 following revision specifiers, up to the next --not. When used on
178 the command line before --stdin, the revisions passed through stdin
179 will not be affected by it. Conversely, when passed via standard
180 input, the revisions passed on the command line will not be
181 affected by it.
182 --all
184 Pretend as if all the refs in refs/, along with HEAD, are listed on
185 the command line as <commit>.
186 --branches[=<pattern>]
188 Pretend as if all the refs in refs/heads are listed on the command
189 line as <commit>. If <pattern> is given, limit branches to ones
190 matching given shell glob. If pattern lacks ?, *, or [, /* at the
191 end is implied.
192 --tags[=<pattern>]
194 Pretend as if all the refs in refs/tags are listed on the command
195 line as <commit>. If <pattern> is given, limit tags to ones
196 matching given shell glob. If pattern lacks ?, *, or [, /* at the
197 end is implied.
198 --remotes[=<pattern>]
200 Pretend as if all the refs in refs/remotes are listed on the
201 command line as <commit>. If <pattern> is given, limit
202 remote-tracking branches to ones matching given shell glob. If
203 pattern lacks ?, *, or [, /* at the end is implied.
204 --glob=<glob-pattern>
206 Pretend as if all the refs matching shell glob <glob-pattern> are
207 listed on the command line as <commit>. Leading refs/, is
208 automatically prepended if missing. If pattern lacks ?, *, or [, /*
209 at the end is implied.
210 --exclude=<glob-pattern>
212 Do not include refs matching <glob-pattern> that the next --all,
213 --branches, --tags, --remotes, or --glob would otherwise consider.
214 Repetitions of this option accumulate exclusion patterns up to the
215 next --all, --branches, --tags, --remotes, or --glob option (other
216 options or arguments do not clear accumulated patterns).
217 The patterns given should not begin with refs/heads, refs/tags, or
219 refs/remotes when applied to --branches, --tags, or --remotes,
220 respectively, and they must begin with refs/ when applied to --glob
221 or --all. If a trailing /* is intended, it must be given
222 explicitly.
223 --exclude-hidden=[fetch|receive|uploadpack]
225 Do not include refs that would be hidden by git-fetch,
226 git-receive-pack or git-upload-pack by consulting the appropriate
227 fetch.hideRefs, receive.hideRefs or uploadpack.hideRefs
228 configuration along with transfer.hideRefs (see git-config(1)).
229 This option affects the next pseudo-ref option --all or --glob and
230 is cleared after processing them.
231 --reflog
233 Pretend as if all objects mentioned by reflogs are listed on the
234 command line as <commit>.
235 --alternate-refs
237 Pretend as if all objects mentioned as ref tips of alternate
238 repositories were listed on the command line. An alternate
239 repository is any repository whose object directory is specified in
240 objects/info/alternates. The set of included objects may be
241 modified by core.alternateRefsCommand, etc. See git-config(1).
242 --single-worktree
244 By default, all working trees will be examined by the following
245 options when there are more than one (see git-worktree(1)): --all,
246 --reflog and --indexed-objects. This option forces them to examine
247 the current working tree only.
248 --ignore-missing
250 Upon seeing an invalid object name in the input, pretend as if the
251 bad input was not given.
252 --stdin
254 In addition to getting arguments from the command line, read them
255 from standard input as well. This accepts commits and
256 pseudo-options like --all and --glob=. When a -- separator is seen,
257 the following input is treated as paths and used to limit the
258 result. Flags like --not which are read via standard input are only
259 respected for arguments passed in the same way and will not
260 influence any subsequent command line arguments.
261 --quiet
263 Don’t print anything to standard output. This form is primarily
264 meant to allow the caller to test the exit status to see if a range
265 of objects is fully connected (or not). It is faster than
266 redirecting stdout to /dev/null as the output does not have to be
267 formatted.
268 --disk-usage, --disk-usage=human
270 Suppress normal output; instead, print the sum of the bytes used
271 for on-disk storage by the selected commits or objects. This is
272 equivalent to piping the output into git cat-file
273 --batch-check='%(objectsize:disk)', except that it runs much faster
274 (especially with --use-bitmap-index). See the CAVEATS section in
275 git-cat-file(1) for the limitations of what "on-disk storage"
276 means. With the optional value human, on-disk storage size is shown
277 in human-readable string(e.g. 12.24 Kib, 3.50 Mib).
278 --cherry-mark
280 Like --cherry-pick (see below) but mark equivalent commits with =
281 rather than omitting them, and inequivalent ones with +.
282 --cherry-pick
284 Omit any commit that introduces the same change as another commit
285 on the “other side” when the set of commits are limited with
286 symmetric difference.
287 For example, if you have two branches, A and B, a usual way to list
289 all commits on only one side of them is with --left-right (see the
290 example below in the description of the --left-right option).
291 However, it shows the commits that were cherry-picked from the
292 other branch (for example, “3rd on b” may be cherry-picked from
293 branch A). With this option, such pairs of commits are excluded
294 from the output.
295 --left-only, --right-only
297 List only commits on the respective side of a symmetric difference,
298 i.e. only those which would be marked < resp. > by --left-right.
299 For example, --cherry-pick --right-only A...B omits those commits
301 from B which are in A or are patch-equivalent to a commit in A. In
302 other words, this lists the + commits from git cherry A B. More
303 precisely, --cherry-pick --right-only --no-merges gives the exact
304 list.
305 --cherry
307 A synonym for --right-only --cherry-mark --no-merges; useful to
308 limit the output to the commits on our side and mark those that
309 have been applied to the other side of a forked history with git
310 log --cherry upstream...mybranch, similar to git cherry upstream
311 mybranch.
312 -g, --walk-reflogs
314 Instead of walking the commit ancestry chain, walk reflog entries
315 from the most recent one to older ones. When this option is used
316 you cannot specify commits to exclude (that is, ^commit,
317 commit1..commit2, and commit1...commit2 notations cannot be used).
318 With --pretty format other than oneline and reference (for obvious
320 reasons), this causes the output to have two extra lines of
321 information taken from the reflog. The reflog designator in the
322 output may be shown as ref@{Nth} (where Nth is the
323 reverse-chronological index in the reflog) or as ref@{timestamp}
324 (with the timestamp for that entry), depending on a few rules:
325 1. If the starting point is specified as ref@{Nth}, show the index
327 format.
328 2. If the starting point was specified as ref@{now}, show the
330 timestamp format.
331 3. If neither was used, but --date was given on the command line,
333 show the timestamp in the format requested by --date.
334 4. Otherwise, show the index format.
336 Under --pretty=oneline, the commit message is prefixed with this
338 information on the same line. This option cannot be combined with
339 --reverse. See also git-reflog(1).
340 Under --pretty=reference, this information will not be shown at
342 all.
343 --merge
345 After a failed merge, show refs that touch files having a conflict
346 and don’t exist on all heads to merge.
347 --boundary
349 Output excluded boundary commits. Boundary commits are prefixed
350 with -.
351 --use-bitmap-index
353 Try to speed up the traversal using the pack bitmap index (if one
354 is available). Note that when traversing with --objects, trees and
355 blobs will not have their associated path printed.
356 --progress=<header>
358 Show progress reports on stderr as objects are considered. The
359 <header> text will be printed with each progress update.
360 History Simplification
362 Sometimes you are only interested in parts of the history, for example
363 the commits modifying a particular <path>. But there are two parts of
364 History Simplification, one part is selecting the commits and the other
365 is how to do it, as there are various strategies to simplify the
366 history.
367 The following options select the commits to be shown:
369 <paths>
371 Commits modifying the given <paths> are selected.
372 --simplify-by-decoration
374 Commits that are referred by some branch or tag are selected.
375 Note that extra commits can be shown to give a meaningful history.
377 The following options affect the way the simplification is performed:
379 Default mode
381 Simplifies the history to the simplest history explaining the final
382 state of the tree. Simplest because it prunes some side branches if
383 the end result is the same (i.e. merging branches with the same
384 content)
385 --show-pulls
387 Include all commits from the default mode, but also any merge
388 commits that are not TREESAME to the first parent but are TREESAME
389 to a later parent. This mode is helpful for showing the merge
390 commits that "first introduced" a change to a branch.
391 --full-history
393 Same as the default mode, but does not prune some history.
394 --dense
396 Only the selected commits are shown, plus some to have a meaningful
397 history.
398 --sparse
400 All commits in the simplified history are shown.
401 --simplify-merges
403 Additional option to --full-history to remove some needless merges
404 from the resulting history, as there are no selected commits
405 contributing to this merge.
406 --ancestry-path[=<commit>]
408 When given a range of commits to display (e.g. commit1..commit2 or
409 commit2 ^commit1), only display commits in that range that are
410 ancestors of <commit>, descendants of <commit>, or <commit> itself.
411 If no commit is specified, use commit1 (the excluded part of the
412 range) as <commit>. Can be passed multiple times; if so, a commit
413 is included if it is any of the commits given or if it is an
414 ancestor or descendant of one of them.
415 A more detailed explanation follows.
417 Suppose you specified foo as the <paths>. We shall call commits that
419 modify foo !TREESAME, and the rest TREESAME. (In a diff filtered for
420 foo, they look different and equal, respectively.)
421 In the following, we will always refer to the same example history to
423 illustrate the differences between simplification settings. We assume
424 that you are filtering for a file foo in this commit graph:
425 .-A---M---N---O---P---Q
427 / / / / / /
428 I B C D E Y
429 \ / / / / /
430 `-------------' X
431 The horizontal line of history A---Q is taken to be the first parent of
433 each merge. The commits are:
434 • I is the initial commit, in which foo exists with contents “asdf”,
436 and a file quux exists with contents “quux”. Initial commits are
437 compared to an empty tree, so I is !TREESAME.
438 • In A, foo contains just “foo”.
440 • B contains the same change as A. Its merge M is trivial and hence
442 TREESAME to all parents.
443 • C does not change foo, but its merge N changes it to “foobar”, so
445 it is not TREESAME to any parent.
446 • D sets foo to “baz”. Its merge O combines the strings from N and D
448 to “foobarbaz”; i.e., it is not TREESAME to any parent.
449 • E changes quux to “xyzzy”, and its merge P combines the strings to
451 “quux xyzzy”. P is TREESAME to O, but not to E.
452 • X is an independent root commit that added a new file side, and Y
454 modified it. Y is TREESAME to X. Its merge Q added side to P, and
455 Q is TREESAME to P, but not to Y.
456 rev-list walks backwards through history, including or excluding
458 commits based on whether --full-history and/or parent rewriting (via
459 --parents or --children) are used. The following settings are
460 available.
461 Default mode
463 Commits are included if they are not TREESAME to any parent (though
464 this can be changed, see --sparse below). If the commit was a
465 merge, and it was TREESAME to one parent, follow only that parent.
466 (Even if there are several TREESAME parents, follow only one of
467 them.) Otherwise, follow all parents.
468 This results in:
470 .-A---N---O
472 / / /
473 I---------D
474 Note how the rule to only follow the TREESAME parent, if one is
476 available, removed B from consideration entirely. C was considered
477 via N, but is TREESAME. Root commits are compared to an empty tree,
478 so I is !TREESAME.
479 Parent/child relations are only visible with --parents, but that
481 does not affect the commits selected in default mode, so we have
482 shown the parent lines.
483 --full-history without parent rewriting
485 This mode differs from the default in one point: always follow all
486 parents of a merge, even if it is TREESAME to one of them. Even if
487 more than one side of the merge has commits that are included, this
488 does not imply that the merge itself is! In the example, we get
489 I A B N D O P Q
491 M was excluded because it is TREESAME to both parents. E, C and B
493 were all walked, but only B was !TREESAME, so the others do not
494 appear.
495 Note that without parent rewriting, it is not really possible to
497 talk about the parent/child relationships between the commits, so
498 we show them disconnected.
499 --full-history with parent rewriting
501 Ordinary commits are only included if they are !TREESAME (though
502 this can be changed, see --sparse below).
503 Merges are always included. However, their parent list is
505 rewritten: Along each parent, prune away commits that are not
506 included themselves. This results in
507 .-A---M---N---O---P---Q
509 / / / / /
510 I B / D /
511 \ / / / /
512 `-------------'
513 Compare to --full-history without rewriting above. Note that E was
515 pruned away because it is TREESAME, but the parent list of P was
516 rewritten to contain E's parent I. The same happened for C and N,
517 and X, Y and Q.
518 In addition to the above settings, you can change whether TREESAME
520 affects inclusion:
521 --dense
523 Commits that are walked are included if they are not TREESAME to
524 any parent.
525 --sparse
527 All commits that are walked are included.
528 Note that without --full-history, this still simplifies merges: if
530 one of the parents is TREESAME, we follow only that one, so the
531 other sides of the merge are never walked.
532 --simplify-merges
534 First, build a history graph in the same way that --full-history
535 with parent rewriting does (see above).
536 Then simplify each commit C to its replacement C' in the final
538 history according to the following rules:
539 • Set C' to C.
541 • Replace each parent P of C' with its simplification P'. In the
543 process, drop parents that are ancestors of other parents or
544 that are root commits TREESAME to an empty tree, and remove
545 duplicates, but take care to never drop all parents that we are
546 TREESAME to.
547 • If after this parent rewriting, C' is a root or merge commit
549 (has zero or >1 parents), a boundary commit, or !TREESAME, it
550 remains. Otherwise, it is replaced with its only parent.
551 The effect of this is best shown by way of comparing to
553 --full-history with parent rewriting. The example turns into:
554 .-A---M---N---O
556 / / /
557 I B D
558 \ / /
559 `---------'
560 Note the major differences in N, P, and Q over --full-history:
562 • N's parent list had I removed, because it is an ancestor of the
564 other parent M. Still, N remained because it is !TREESAME.
565 • P's parent list similarly had I removed. P was then removed
567 completely, because it had one parent and is TREESAME.
568 • Q's parent list had Y simplified to X. X was then removed,
570 because it was a TREESAME root. Q was then removed completely,
571 because it had one parent and is TREESAME.
572 There is another simplification mode available:
574 --ancestry-path[=<commit>]
576 Limit the displayed commits to those which are an ancestor of
577 <commit>, or which are a descendant of <commit>, or are <commit>
578 itself.
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 We can also use --ancestry-path=D instead of --ancestry-path which
608 means the same thing when applied to the D..M range but is just
609 more explicit.
610 If we instead are interested in a given topic within this range,
612 and all commits affected by that topic, we may only want to view
613 the subset of D..M which contain that topic in their ancestry path.
614 So, using --ancestry-path=H D..M for example would result in:
615 E
617 \
618 G---H---I---J
619 \
620 L--M
621 Whereas --ancestry-path=K D..M would result in
623 K---------------L--M
625 Before discussing another option, --show-pulls, we need to create a new
627 example history.
628 A common problem users face when looking at simplified history is that
630 a commit they know changed a file somehow does not appear in the file’s
631 simplified history. Let’s demonstrate a new example and show how
632 options such as --full-history and --simplify-merges works in that
633 case:
634 .-A---M-----C--N---O---P
636 / / \ \ \/ / /
637 I B \ R-'`-Z' /
638 \ / \/ /
639 \ / /\ /
640 `---X--' `---Y--'
641 For this example, suppose I created file.txt which was modified by A,
643 B, and X in different ways. The single-parent commits C, Z, and Y do
644 not change file.txt. The merge commit M was created by resolving the
645 merge conflict to include both changes from A and B and hence is not
646 TREESAME to either. The merge commit R, however, was created by
647 ignoring the contents of file.txt at M and taking only the contents of
648 file.txt at X. Hence, R is TREESAME to X but not M. Finally, the
649 natural merge resolution to create N is to take the contents of
650 file.txt at R, so N is TREESAME to R but not C. The merge commits O and
651 P are TREESAME to their first parents, but not to their second parents,
652 Z and Y respectively.
653 When using the default mode, N and R both have a TREESAME parent, so
655 those edges are walked and the others are ignored. The resulting
656 history graph is:
657 I---X
659 When using --full-history, Git walks every edge. This will discover the
661 commits A and B and the merge M, but also will reveal the merge commits
662 O and P. With parent rewriting, the resulting graph is:
663 .-A---M--------N---O---P
665 / / \ \ \/ / /
666 I B \ R-'`--' /
667 \ / \/ /
668 \ / /\ /
669 `---X--' `------'
670 Here, the merge commits O and P contribute extra noise, as they did not
672 actually contribute a change to file.txt. They only merged a topic that
673 was based on an older version of file.txt. This is a common issue in
674 repositories using a workflow where many contributors work in parallel
675 and merge their topic branches along a single trunk: many unrelated
676 merges appear in the --full-history results.
677 When using the --simplify-merges option, the commits O and P disappear
679 from the results. This is because the rewritten second parents of O and
680 P are reachable from their first parents. Those edges are removed and
681 then the commits look like single-parent commits that are TREESAME to
682 their parent. This also happens to the commit N, resulting in a history
683 view as follows:
684 .-A---M--.
686 / / \
687 I B R
688 \ / /
689 \ / /
690 `---X--'
691 In this view, we see all of the important single-parent changes from A,
693 B, and X. We also see the carefully-resolved merge M and the
694 not-so-carefully-resolved merge R. This is usually enough information
695 to determine why the commits A and B "disappeared" from history in the
696 default view. However, there are a few issues with this approach.
697 The first issue is performance. Unlike any previous option, the
699 --simplify-merges option requires walking the entire commit history
700 before returning a single result. This can make the option difficult to
701 use for very large repositories.
702 The second issue is one of auditing. When many contributors are working
704 on the same repository, it is important which merge commits introduced
705 a change into an important branch. The problematic merge R above is not
706 likely to be the merge commit that was used to merge into an important
707 branch. Instead, the merge N was used to merge R and X into the
708 important branch. This commit may have information about why the change
709 X came to override the changes from A and B in its commit message.
710 --show-pulls
712 In addition to the commits shown in the default history, show each
713 merge commit that is not TREESAME to its first parent but is
714 TREESAME to a later parent.
715 When a merge commit is included by --show-pulls, the merge is
717 treated as if it "pulled" the change from another branch. When
718 using --show-pulls on this example (and no other options) the
719 resulting graph is:
720 I---X---R---N
722 Here, the merge commits R and N are included because they pulled
724 the commits X and R into the base branch, respectively. These
725 merges are the reason the commits A and B do not appear in the
726 default history.
727 When --show-pulls is paired with --simplify-merges, the graph
729 includes all of the necessary information:
730 .-A---M--. N
732 / / \ /
733 I B R
734 \ / /
735 \ / /
736 `---X--'
737 Notice that since M is reachable from R, the edge from N to M was
739 simplified away. However, N still appears in the history as an
740 important commit because it "pulled" the change R into the main
741 branch.
742 The --simplify-by-decoration option allows you to view only the big
744 picture of the topology of the history, by omitting commits that are
745 not referenced by tags. Commits are marked as !TREESAME (in other
746 words, kept after history simplification rules described above) if (1)
747 they are referenced by tags, or (2) they change the contents of the
748 paths given on the command line. All other commits are marked as
749 TREESAME (subject to be simplified away).
750 Bisection Helpers
752 --bisect
753 Limit output to the one commit object which is roughly halfway
754 between included and excluded commits. Note that the bad bisection
755 ref refs/bisect/bad is added to the included commits (if it exists)
756 and the good bisection refs refs/bisect/good-* are added to the
757 excluded commits (if they exist). Thus, supposing there are no refs
758 in refs/bisect/, if
759 $ git rev-list --bisect foo ^bar ^baz
761 outputs midpoint, the output of the two commands
763 $ git rev-list foo ^midpoint
765 $ git rev-list midpoint ^bar ^baz
766 would be of roughly the same length. Finding the change which
768 introduces a regression is thus reduced to a binary search:
769 repeatedly generate and test new 'midpoint’s until the commit chain
770 is of length one.
771 --bisect-vars
773 This calculates the same as --bisect, except that refs in
774 refs/bisect/ are not used, and except that this outputs text ready
775 to be eval’ed by the shell. These lines will assign the name of the
776 midpoint revision to the variable bisect_rev, and the expected
777 number of commits to be tested after bisect_rev is tested to
778 bisect_nr, the expected number of commits to be tested if
779 bisect_rev turns out to be good to bisect_good, the expected number
780 of commits to be tested if bisect_rev turns out to be bad to
781 bisect_bad, and the number of commits we are bisecting right now to
782 bisect_all.
783 --bisect-all
785 This outputs all the commit objects between the included and
786 excluded commits, ordered by their distance to the included and
787 excluded commits. Refs in refs/bisect/ are not used. The farthest
788 from them is displayed first. (This is the only one displayed by
789 --bisect.)
790 This is useful because it makes it easy to choose a good commit to
792 test when you want to avoid to test some of them for some reason
793 (they may not compile for example).
794 This option can be used along with --bisect-vars, in this case,
796 after all the sorted commit objects, there will be the same text as
797 if --bisect-vars had been used alone.
798 Commit Ordering
800 By default, the commits are shown in reverse chronological order.
801 --date-order
803 Show no parents before all of its children are shown, but otherwise
804 show commits in the commit timestamp order.
805 --author-date-order
807 Show no parents before all of its children are shown, but otherwise
808 show commits in the author timestamp order.
809 --topo-order
811 Show no parents before all of its children are shown, and avoid
812 showing commits on multiple lines of history intermixed.
813 For example, in a commit history like this:
815 ---1----2----4----7
817 \ \
818 3----5----6----8---
819 where the numbers denote the order of commit timestamps, git
821 rev-list and friends with --date-order show the commits in the
822 timestamp order: 8 7 6 5 4 3 2 1.
823 With --topo-order, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5
825 3 1); some older commits are shown before newer ones in order to
826 avoid showing the commits from two parallel development track mixed
827 together.
828 --reverse
830 Output the commits chosen to be shown (see Commit Limiting section
831 above) in reverse order. Cannot be combined with --walk-reflogs.
832 Object Traversal
834 These options are mostly targeted for packing of Git repositories.
835 --objects
837 Print the object IDs of any object referenced by the listed
838 commits. --objects foo ^bar thus means “send me all object IDs
839 which I need to download if I have the commit object bar but not
840 foo”. See also --object-names below.
841 --in-commit-order
843 Print tree and blob ids in order of the commits. The tree and blob
844 ids are printed after they are first referenced by a commit.
845 --objects-edge
847 Similar to --objects, but also print the IDs of excluded commits
848 prefixed with a “-” character. This is used by git-pack-objects(1)
849 to build a “thin” pack, which records objects in deltified form
850 based on objects contained in these excluded commits to reduce
851 network traffic.
852 --objects-edge-aggressive
854 Similar to --objects-edge, but it tries harder to find excluded
855 commits at the cost of increased time. This is used instead of
856 --objects-edge to build “thin” packs for shallow repositories.
857 --indexed-objects
859 Pretend as if all trees and blobs used by the index are listed on
860 the command line. Note that you probably want to use --objects,
861 too.
862 --unpacked
864 Only useful with --objects; print the object IDs that are not in
865 packs.
866 --object-names
868 Only useful with --objects; print the names of the object IDs that
869 are found. This is the default behavior. Note that the "name" of
870 each object is ambiguous, and mostly intended as a hint for packing
871 objects. In particular: no distinction is made between the names of
872 tags, trees, and blobs; path names may be modified to remove
873 newlines; and if an object would appear multiple times with
874 different names, only one name is shown.
875 --no-object-names
877 Only useful with --objects; does not print the names of the object
878 IDs that are found. This inverts --object-names. This flag allows
879 the output to be more easily parsed by commands such as git-cat-
880 file(1).
881 --filter=<filter-spec>
883 Only useful with one of the --objects*; omits objects (usually
884 blobs) from the list of printed objects. The <filter-spec> may be
885 one of the following:
886 The form --filter=blob:none omits all blobs.
888 The form --filter=blob:limit=<n>[kmg] omits blobs larger than n
890 bytes or units. n may be zero. The suffixes k, m, and g can be used
891 to name units in KiB, MiB, or GiB. For example, blob:limit=1k is
892 the same as blob:limit=1024.
893 The form --filter=object:type=(tag|commit|tree|blob) omits all
895 objects which are not of the requested type.
896 The form --filter=sparse:oid=<blob-ish> uses a sparse-checkout
898 specification contained in the blob (or blob-expression) <blob-ish>
899 to omit blobs that would not be required for a sparse checkout on
900 the requested refs.
901 The form --filter=tree:<depth> omits all blobs and trees whose
903 depth from the root tree is >= <depth> (minimum depth if an object
904 is located at multiple depths in the commits traversed). <depth>=0
905 will not include any trees or blobs unless included explicitly in
906 the command-line (or standard input when --stdin is used).
907 <depth>=1 will include only the tree and blobs which are referenced
908 directly by a commit reachable from <commit> or an explicitly-given
909 object. <depth>=2 is like <depth>=1 while also including trees and
910 blobs one more level removed from an explicitly-given commit or
911 tree.
912 Note that the form --filter=sparse:path=<path> that wants to read
914 from an arbitrary path on the filesystem has been dropped for
915 security reasons.
916 Multiple --filter= flags can be specified to combine filters. Only
918 objects which are accepted by every filter are included.
919 The form --filter=combine:<filter1>+<filter2>+...<filterN> can also
921 be used to combined several filters, but this is harder than just
922 repeating the --filter flag and is usually not necessary. Filters
923 are joined by + and individual filters are %-encoded (i.e.
924 URL-encoded). Besides the + and % characters, the following
925 characters are reserved and also must be encoded:
926 ~!@#$^&*()[]{}\;",<>?'` as well as all characters with ASCII code
927 <= 0x20, which includes space and newline.
928 Other arbitrary characters can also be encoded. For instance,
930 combine:tree:3+blob:none and combine:tree%3A3+blob%3Anone are
931 equivalent.
932 --no-filter
934 Turn off any previous --filter= argument.
935 --filter-provided-objects
937 Filter the list of explicitly provided objects, which would
938 otherwise always be printed even if they did not match any of the
939 filters. Only useful with --filter=.
940 --filter-print-omitted
942 Only useful with --filter=; prints a list of the objects omitted by
943 the filter. Object IDs are prefixed with a “~” character.
944 --missing=<missing-action>
946 A debug option to help with future "partial clone" development.
947 This option specifies how missing objects are handled.
948 The form --missing=error requests that rev-list stop with an error
950 if a missing object is encountered. This is the default action.
951 The form --missing=allow-any will allow object traversal to
953 continue if a missing object is encountered. Missing objects will
954 silently be omitted from the results.
955 The form --missing=allow-promisor is like allow-any, but will only
957 allow object traversal to continue for EXPECTED promisor missing
958 objects. Unexpected missing objects will raise an error.
959 The form --missing=print is like allow-any, but will also print a
961 list of the missing objects. Object IDs are prefixed with a “?”
962 character.
963 --exclude-promisor-objects
965 (For internal use only.) Prefilter object traversal at promisor
966 boundary. This is used with partial clone. This is stronger than
967 --missing=allow-promisor because it limits the traversal, rather
968 than just silencing errors about missing objects.
969 --no-walk[=(sorted|unsorted)]
971 Only show the given commits, but do not traverse their ancestors.
972 This has no effect if a range is specified. If the argument
973 unsorted is given, the commits are shown in the order they were
974 given on the command line. Otherwise (if sorted or no argument was
975 given), the commits are shown in reverse chronological order by
976 commit time. Cannot be combined with --graph.
977 --do-walk
979 Overrides a previous --no-walk.
980 Commit Formatting
982 Using these options, git-rev-list(1) will act similar to the more
983 specialized family of commit log tools: git-log(1), git-show(1), and
984 git-whatchanged(1)
985 --pretty[=<format>], --format=<format>
987 Pretty-print the contents of the commit logs in a given format,
988 where <format> can be one of oneline, short, medium, full, fuller,
989 reference, email, raw, format:<string> and tformat:<string>. When
990 <format> is none of the above, and has %placeholder in it, it acts
991 as if --pretty=tformat:<format> were given.
992 See the "PRETTY FORMATS" section for some additional details for
994 each format. When =<format> part is omitted, it defaults to medium.
995 Note: you can specify the default pretty format in the repository
997 configuration (see git-config(1)).
998 --abbrev-commit
1000 Instead of showing the full 40-byte hexadecimal commit object name,
1001 show a prefix that names the object uniquely. "--abbrev=<n>" (which
1002 also modifies diff output, if it is displayed) option can be used
1003 to specify the minimum length of the prefix.
1004 This should make "--pretty=oneline" a whole lot more readable for
1006 people using 80-column terminals.
1007 --no-abbrev-commit
1009 Show the full 40-byte hexadecimal commit object name. This negates
1010 --abbrev-commit, either explicit or implied by other options such
1011 as "--oneline". It also overrides the log.abbrevCommit variable.
1012 --oneline
1014 This is a shorthand for "--pretty=oneline --abbrev-commit" used
1015 together.
1016 --encoding=<encoding>
1018 Commit objects record the character encoding used for the log
1019 message in their encoding header; this option can be used to tell
1020 the command to re-code the commit log message in the encoding
1021 preferred by the user. For non plumbing commands this defaults to
1022 UTF-8. Note that if an object claims to be encoded in X and we are
1023 outputting in X, we will output the object verbatim; this means
1024 that invalid sequences in the original commit may be copied to the
1025 output. Likewise, if iconv(3) fails to convert the commit, we will
1026 quietly output the original object verbatim.
1027 --expand-tabs=<n>, --expand-tabs, --no-expand-tabs
1029 Perform a tab expansion (replace each tab with enough spaces to
1030 fill to the next display column that is a multiple of <n>) in the
1031 log message before showing it in the output. --expand-tabs is a
1032 short-hand for --expand-tabs=8, and --no-expand-tabs is a
1033 short-hand for --expand-tabs=0, which disables tab expansion.
1034 By default, tabs are expanded in pretty formats that indent the log
1036 message by 4 spaces (i.e. medium, which is the default, full, and
1037 fuller).
1038 --show-signature
1040 Check the validity of a signed commit object by passing the
1041 signature to gpg --verify and show the output.
1042 --relative-date
1044 Synonym for --date=relative.
1045 --date=<format>
1047 Only takes effect for dates shown in human-readable format, such as
1048 when using --pretty. log.date config variable sets a default value
1049 for the log command’s --date option. By default, dates are shown in
1050 the original time zone (either committer’s or author’s). If -local
1051 is appended to the format (e.g., iso-local), the user’s local time
1052 zone is used instead.
1053 --date=relative shows dates relative to the current time, e.g. “2
1055 hours ago”. The -local option has no effect for --date=relative.
1056 --date=local is an alias for --date=default-local.
1058 --date=iso (or --date=iso8601) shows timestamps in a ISO 8601-like
1060 format. The differences to the strict ISO 8601 format are:
1061 • a space instead of the T date/time delimiter
1063 • a space between time and time zone
1065 • no colon between hours and minutes of the time zone
1067 --date=iso-strict (or --date=iso8601-strict) shows timestamps in
1069 strict ISO 8601 format.
1070 --date=rfc (or --date=rfc2822) shows timestamps in RFC 2822 format,
1072 often found in email messages.
1073 --date=short shows only the date, but not the time, in YYYY-MM-DD
1075 format.
1076 --date=raw shows the date as seconds since the epoch (1970-01-01
1078 00:00:00 UTC), followed by a space, and then the timezone as an
1079 offset from UTC (a + or - with four digits; the first two are
1080 hours, and the second two are minutes). I.e., as if the timestamp
1081 were formatted with strftime("%s %z")). Note that the -local option
1082 does not affect the seconds-since-epoch value (which is always
1083 measured in UTC), but does switch the accompanying timezone value.
1084 --date=human shows the timezone if the timezone does not match the
1086 current time-zone, and doesn’t print the whole date if that matches
1087 (ie skip printing year for dates that are "this year", but also
1088 skip the whole date itself if it’s in the last few days and we can
1089 just say what weekday it was). For older dates the hour and minute
1090 is also omitted.
1091 --date=unix shows the date as a Unix epoch timestamp (seconds since
1093 1970). As with --raw, this is always in UTC and therefore -local
1094 has no effect.
1095 --date=format:... feeds the format ... to your system strftime,
1097 except for %s, %z, and %Z, which are handled internally. Use
1098 --date=format:%c to show the date in your system locale’s preferred
1099 format. See the strftime manual for a complete list of format
1100 placeholders. When using -local, the correct syntax is
1101 --date=format-local:....
1102 --date=default is the default format, and is based on ctime(3)
1104 output. It shows a single line with three-letter day of the week,
1105 three-letter month, day-of-month, hour-minute-seconds in "HH:MM:SS"
1106 format, followed by 4-digit year, plus timezone information, unless
1107 the local time zone is used, e.g. Thu Jan 1 00:00:00 1970 +0000.
1108 --header
1110 Print the contents of the commit in raw-format; each record is
1111 separated with a NUL character.
1112 --no-commit-header
1114 Suppress the header line containing "commit" and the object ID
1115 printed before the specified format. This has no effect on the
1116 built-in formats; only custom formats are affected.
1117 --commit-header
1119 Overrides a previous --no-commit-header.
1120 --parents
1122 Print also the parents of the commit (in the form "commit parent...
1123 "). Also enables parent rewriting, see History Simplification
1124 above.
1125 --children
1127 Print also the children of the commit (in the form "commit child...
1128 "). Also enables parent rewriting, see History Simplification
1129 above.
1130 --timestamp
1132 Print the raw commit timestamp.
1133 --left-right
1135 Mark which side of a symmetric difference a commit is reachable
1136 from. Commits from the left side are prefixed with < and those from
1137 the right with >. If combined with --boundary, those commits are
1138 prefixed with -.
1139 For example, if you have this topology:
1141 y---b---b branch B
1143 / \ /
1144 / .
1145 / / \
1146 o---x---a---a branch A
1147 you would get an output like this:
1149 $ git rev-list --left-right --boundary --pretty=oneline A...B
1151 >bbbbbbb... 3rd on b
1153 >bbbbbbb... 2nd on b
1154 <aaaaaaa... 3rd on a
1155 <aaaaaaa... 2nd on a
1156 -yyyyyyy... 1st on b
1157 -xxxxxxx... 1st on a
1158 --graph
1160 Draw a text-based graphical representation of the commit history on
1161 the left hand side of the output. This may cause extra lines to be
1162 printed in between commits, in order for the graph history to be
1163 drawn properly. Cannot be combined with --no-walk.
1164 This enables parent rewriting, see History Simplification above.
1166 This implies the --topo-order option by default, but the
1168 --date-order option may also be specified.
1169 --show-linear-break[=<barrier>]
1171 When --graph is not used, all history branches are flattened which
1172 can make it hard to see that the two consecutive commits do not
1173 belong to a linear branch. This option puts a barrier in between
1174 them in that case. If <barrier> is specified, it is the string that
1175 will be shown instead of the default one.
1176 --count
1178 Print a number stating how many commits would have been listed, and
1179 suppress all other output. When used together with --left-right,
1180 instead print the counts for left and right commits, separated by a
1181 tab. When used together with --cherry-mark, omit patch equivalent
1182 commits from these counts and print the count for equivalent
1183 commits separated by a tab.
1184
1186 If the commit is a merge, and if the pretty-format is not oneline,
1187 email or raw, an additional line is inserted before the Author: line.
1188 This line begins with "Merge: " and the hashes of ancestral commits are
1189 printed, separated by spaces. Note that the listed commits may not
1190 necessarily be the list of the direct parent commits if you have
1191 limited your view of history: for example, if you are only interested
1192 in changes related to a certain directory or file.
1193 There are several built-in formats, and you can define additional
1195 formats by setting a pretty.<name> config option to either another
1196 format name, or a format: string, as described below (see git-
1197 config(1)). Here are the details of the built-in formats:
1198 • oneline
1200 <hash> <title-line>
1202 This is designed to be as compact as possible.
1204 • short
1206 commit <hash>
1208 Author: <author>
1209 <title-line>
1211 • medium
1213 commit <hash>
1215 Author: <author>
1216 Date: <author-date>
1217 <title-line>
1219 <full-commit-message>
1221 • full
1223 commit <hash>
1225 Author: <author>
1226 Commit: <committer>
1227 <title-line>
1229 <full-commit-message>
1231 • fuller
1233 commit <hash>
1235 Author: <author>
1236 AuthorDate: <author-date>
1237 Commit: <committer>
1238 CommitDate: <committer-date>
1239 <title-line>
1241 <full-commit-message>
1243 • reference
1245 <abbrev-hash> (<title-line>, <short-author-date>)
1247 This format is used to refer to another commit in a commit message
1249 and is the same as --pretty='format:%C(auto)%h (%s, %ad)'. By
1250 default, the date is formatted with --date=short unless another
1251 --date option is explicitly specified. As with any format: with
1252 format placeholders, its output is not affected by other options
1253 like --decorate and --walk-reflogs.
1254 • email
1256 From <hash> <date>
1258 From: <author>
1259 Date: <author-date>
1260 Subject: [PATCH] <title-line>
1261 <full-commit-message>
1263 • mboxrd
1265 Like email, but lines in the commit message starting with "From "
1267 (preceded by zero or more ">") are quoted with ">" so they aren’t
1268 confused as starting a new commit.
1269 • raw
1271 The raw format shows the entire commit exactly as stored in the
1273 commit object. Notably, the hashes are displayed in full,
1274 regardless of whether --abbrev or --no-abbrev are used, and parents
1275 information show the true parent commits, without taking grafts or
1276 history simplification into account. Note that this format affects
1277 the way commits are displayed, but not the way the diff is shown
1278 e.g. with git log --raw. To get full object names in a raw diff
1279 format, use --no-abbrev.
1280 • format:<format-string>
1282 The format:<format-string> format allows you to specify which
1284 information you want to show. It works a little bit like printf
1285 format, with the notable exception that you get a newline with %n
1286 instead of \n.
1287 E.g, format:"The author of %h was %an, %ar%nThe title was >>%s<<%n"
1289 would show something like this:
1290 The author of fe6e0ee was Junio C Hamano, 23 hours ago
1292 The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<
1293 The placeholders are:
1295 • Placeholders that expand to a single literal character:
1297 %n
1299 newline
1300 %%
1302 a raw %
1303 %x00
1305 %x followed by two hexadecimal digits is replaced with a
1306 byte with the hexadecimal digits' value (we will call this
1307 "literal formatting code" in the rest of this document).
1308 • Placeholders that affect formatting of later placeholders:
1310 %Cred
1312 switch color to red
1313 %Cgreen
1315 switch color to green
1316 %Cblue
1318 switch color to blue
1319 %Creset
1321 reset color
1322 %C(...)
1324 color specification, as described under Values in the
1325 "CONFIGURATION FILE" section of git-config(1). By default,
1326 colors are shown only when enabled for log output (by
1327 color.diff, color.ui, or --color, and respecting the auto
1328 settings of the former if we are going to a terminal).
1329 %C(auto,...) is accepted as a historical synonym for the
1330 default (e.g., %C(auto,red)). Specifying %C(always,...)
1331 will show the colors even when color is not otherwise
1332 enabled (though consider just using --color=always to
1333 enable color for the whole output, including this format
1334 and anything else git might color). auto alone (i.e.
1335 %C(auto)) will turn on auto coloring on the next
1336 placeholders until the color is switched again.
1337 %m
1339 left (<), right (>) or boundary (-) mark
1340 %w([<w>[,<i1>[,<i2>]]])
1342 switch line wrapping, like the -w option of git-
1343 shortlog(1).
1344 %<( <N> [,trunc|ltrunc|mtrunc])
1346 make the next placeholder take at least N column widths,
1347 padding spaces on the right if necessary. Optionally
1348 truncate (with ellipsis ..) at the left (ltrunc) ..ft, the
1349 middle (mtrunc) mi..le, or the end (trunc) rig.., if the
1350 output is longer than N columns. Note 1: that truncating
1351 only works correctly with N >= 2. Note 2: spaces around the
1352 N and M (see below) values are optional. Note 3: Emojis and
1353 other wide characters will take two display columns, which
1354 may over-run column boundaries. Note 4: decomposed
1355 character combining marks may be misplaced at padding
1356 boundaries.
1357 %<|( <M> )
1359 make the next placeholder take at least until Mth display
1360 column, padding spaces on the right if necessary. Use
1361 negative M values for column positions measured from the
1362 right hand edge of the terminal window.
1363 %>( <N> ), %>|( <M> )
1365 similar to %<( <N> ), %<|( <M> ) respectively, but padding
1366 spaces on the left
1367 %>>( <N> ), %>>|( <M> )
1369 similar to %>( <N> ), %>|( <M> ) respectively, except that
1370 if the next placeholder takes more spaces than given and
1371 there are spaces on its left, use those spaces
1372 %><( <N> ), %><|( <M> )
1374 similar to %<( <N> ), %<|( <M> ) respectively, but padding
1375 both sides (i.e. the text is centered)
1376 • Placeholders that expand to information extracted from the
1378 commit:
1379 %H
1381 commit hash
1382 %h
1384 abbreviated commit hash
1385 %T
1387 tree hash
1388 %t
1390 abbreviated tree hash
1391 %P
1393 parent hashes
1394 %p
1396 abbreviated parent hashes
1397 %an
1399 author name
1400 %aN
1402 author name (respecting .mailmap, see git-shortlog(1) or
1403 git-blame(1))
1404 %ae
1406 author email
1407 %aE
1409 author email (respecting .mailmap, see git-shortlog(1) or
1410 git-blame(1))
1411 %al
1413 author email local-part (the part before the @ sign)
1414 %aL
1416 author local-part (see %al) respecting .mailmap, see git-
1417 shortlog(1) or git-blame(1))
1418 %ad
1420 author date (format respects --date= option)
1421 %aD
1423 author date, RFC2822 style
1424 %ar
1426 author date, relative
1427 %at
1429 author date, UNIX timestamp
1430 %ai
1432 author date, ISO 8601-like format
1433 %aI
1435 author date, strict ISO 8601 format
1436 %as
1438 author date, short format (YYYY-MM-DD)
1439 %ah
1441 author date, human style (like the --date=human option of
1442 git-rev-list(1))
1443 %cn
1445 committer name
1446 %cN
1448 committer name (respecting .mailmap, see git-shortlog(1) or
1449 git-blame(1))
1450 %ce
1452 committer email
1453 %cE
1455 committer email (respecting .mailmap, see git-shortlog(1)
1456 or git-blame(1))
1457 %cl
1459 committer email local-part (the part before the @ sign)
1460 %cL
1462 committer local-part (see %cl) respecting .mailmap, see
1463 git-shortlog(1) or git-blame(1))
1464 %cd
1466 committer date (format respects --date= option)
1467 %cD
1469 committer date, RFC2822 style
1470 %cr
1472 committer date, relative
1473 %ct
1475 committer date, UNIX timestamp
1476 %ci
1478 committer date, ISO 8601-like format
1479 %cI
1481 committer date, strict ISO 8601 format
1482 %cs
1484 committer date, short format (YYYY-MM-DD)
1485 %ch
1487 committer date, human style (like the --date=human option
1488 of git-rev-list(1))
1489 %d
1491 ref names, like the --decorate option of git-log(1)
1492 %D
1494 ref names without the " (", ")" wrapping.
1495 %(decorate[:<options>])
1497 ref names with custom decorations. The decorate string may
1498 be followed by a colon and zero or more comma-separated
1499 options. Option values may contain literal formatting
1500 codes. These must be used for commas (%x2C) and closing
1501 parentheses (%x29), due to their role in the option syntax.
1502 • prefix=<value>: Shown before the list of ref names.
1504 Defaults to " (".
1505 • suffix=<value>: Shown after the list of ref names.
1507 Defaults to ")".
1508 • separator=<value>: Shown between ref names. Defaults to
1510 ", ".
1511 • pointer=<value>: Shown between HEAD and the branch it
1513 points to, if any. Defaults to " -> ".
1514 • tag=<value>: Shown before tag names. Defaults to
1516 "tag: ".
1517 For example, to produce decorations with no wrapping or tag
1519 annotations, and spaces as separators:
1520 + %(decorate:prefix=,suffix=,tag=,separator= )
1522 %(describe[:<options>])
1524 human-readable name, like git-describe(1); empty string for
1525 undescribable commits. The describe string may be followed by a
1526 colon and zero or more comma-separated options. Descriptions
1527 can be inconsistent when tags are added or removed at the same
1528 time.
1529 • tags[=<bool-value>]: Instead of only considering annotated
1531 tags, consider lightweight tags as well.
1532 • abbrev=<number>: Instead of using the default number of
1534 hexadecimal digits (which will vary according to the number
1535 of objects in the repository with a default of 7) of the
1536 abbreviated object name, use <number> digits, or as many
1537 digits as needed to form a unique object name.
1538 • match=<pattern>: Only consider tags matching the given
1540 glob(7) pattern, excluding the "refs/tags/" prefix.
1541 • exclude=<pattern>: Do not consider tags matching the given
1543 glob(7) pattern, excluding the "refs/tags/" prefix.
1544 %S
1546 ref name given on the command line by which the commit was
1547 reached (like git log --source), only works with git log
1548 %e
1550 encoding
1551 %s
1553 subject
1554 %f
1556 sanitized subject line, suitable for a filename
1557 %b
1559 body
1560 %B
1562 raw body (unwrapped subject and body)
1563 %GG
1565 raw verification message from GPG for a signed commit
1566 %G?
1568 show "G" for a good (valid) signature, "B" for a bad signature,
1569 "U" for a good signature with unknown validity, "X" for a good
1570 signature that has expired, "Y" for a good signature made by an
1571 expired key, "R" for a good signature made by a revoked key,
1572 "E" if the signature cannot be checked (e.g. missing key) and
1573 "N" for no signature
1574 %GS
1576 show the name of the signer for a signed commit
1577 %GK
1579 show the key used to sign a signed commit
1580 %GF
1582 show the fingerprint of the key used to sign a signed commit
1583 %GP
1585 show the fingerprint of the primary key whose subkey was used
1586 to sign a signed commit
1587 %GT
1589 show the trust level for the key used to sign a signed commit
1590 %gD
1592 reflog selector, e.g., refs/stash@{1} or refs/stash@{2 minutes
1593 ago}; the format follows the rules described for the -g option.
1594 The portion before the @ is the refname as given on the command
1595 line (so git log -g refs/heads/master would yield
1596 refs/heads/master@{0}).
1597 %gd
1599 shortened reflog selector; same as %gD, but the refname portion
1600 is shortened for human readability (so refs/heads/master
1601 becomes just master).
1602 %gn
1604 reflog identity name
1605 %gN
1607 reflog identity name (respecting .mailmap, see git-shortlog(1)
1608 or git-blame(1))
1609 %ge
1611 reflog identity email
1612 %gE
1614 reflog identity email (respecting .mailmap, see git-shortlog(1)
1615 or git-blame(1))
1616 %gs
1618 reflog subject
1619 %(trailers[:<options>])
1621 display the trailers of the body as interpreted by git-
1622 interpret-trailers(1). The trailers string may be followed by a
1623 colon and zero or more comma-separated options. If any option
1624 is provided multiple times, the last occurrence wins.
1625 • key=<key>: only show trailers with specified <key>.
1627 Matching is done case-insensitively and trailing colon is
1628 optional. If option is given multiple times trailer lines
1629 matching any of the keys are shown. This option
1630 automatically enables the only option so that non-trailer
1631 lines in the trailer block are hidden. If that is not
1632 desired it can be disabled with only=false. E.g.,
1633 %(trailers:key=Reviewed-by) shows trailer lines with key
1634 Reviewed-by.
1635 • only[=<bool>]: select whether non-trailer lines from the
1637 trailer block should be included.
1638 • separator=<sep>: specify a separator inserted between
1640 trailer lines. When this option is not given each trailer
1641 line is terminated with a line feed character. The string
1642 <sep> may contain the literal formatting codes described
1643 above. To use comma as separator one must use %x2C as it
1644 would otherwise be parsed as next option. E.g.,
1645 %(trailers:key=Ticket,separator=%x2C ) shows all trailer
1646 lines whose key is "Ticket" separated by a comma and a
1647 space.
1648 • unfold[=<bool>]: make it behave as if interpret-trailer’s
1650 --unfold option was given. E.g.,
1651 %(trailers:only,unfold=true) unfolds and shows all trailer
1652 lines.
1653 • keyonly[=<bool>]: only show the key part of the trailer.
1655 • valueonly[=<bool>]: only show the value part of the
1657 trailer.
1658 • key_value_separator=<sep>: specify a separator inserted
1660 between trailer lines. When this option is not given each
1661 trailer key-value pair is separated by ": ". Otherwise it
1662 shares the same semantics as separator=<sep> above.
1663 Note
1665 Some placeholders may depend on other options given to the revision
1666 traversal engine. For example, the %g* reflog options will insert
1667 an empty string unless we are traversing reflog entries (e.g., by
1668 git log -g). The %d and %D placeholders will use the "short"
1669 decoration format if --decorate was not already provided on the
1670 command line.
1671 The boolean options accept an optional value [=<bool-value>]. The
1673 values true, false, on, off etc. are all accepted. See the "boolean"
1674 sub-section in "EXAMPLES" in git-config(1). If a boolean option is
1675 given with no value, it’s enabled.
1676 If you add a + (plus sign) after % of a placeholder, a line-feed is
1678 inserted immediately before the expansion if and only if the
1679 placeholder expands to a non-empty string.
1680 If you add a - (minus sign) after % of a placeholder, all consecutive
1682 line-feeds immediately preceding the expansion are deleted if and only
1683 if the placeholder expands to an empty string.
1684 If you add a ` ` (space) after % of a placeholder, a space is inserted
1686 immediately before the expansion if and only if the placeholder expands
1687 to a non-empty string.
1688 • tformat:
1690 The tformat: format works exactly like format:, except that it
1692 provides "terminator" semantics instead of "separator" semantics.
1693 In other words, each commit has the message terminator character
1694 (usually a newline) appended, rather than a separator placed
1695 between entries. This means that the final entry of a single-line
1696 format will be properly terminated with a new line, just as the
1697 "oneline" format does. For example:
1698 $ git log -2 --pretty=format:%h 4da45bef \
1700 | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
1701 4da45be
1702 7134973 -- NO NEWLINE
1703 $ git log -2 --pretty=tformat:%h 4da45bef \
1705 | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
1706 4da45be
1707 7134973
1708 In addition, any unrecognized string that has a % in it is
1710 interpreted as if it has tformat: in front of it. For example,
1711 these two are equivalent:
1712 $ git log -2 --pretty=tformat:%h 4da45bef
1714 $ git log -2 --pretty=%h 4da45bef
1715
1717 • Print the list of commits reachable from the current branch.
1718 git rev-list HEAD
1720 • Print the list of commits on this branch, but not present in the
1722 upstream branch.
1723 git rev-list @{upstream}..HEAD
1725 • Format commits with their author and commit message (see also the
1727 porcelain git-log(1)).
1728 git rev-list --format=medium HEAD
1730 • Format commits along with their diffs (see also the porcelain git-
1732 log(1), which can do this in a single process).
1733 git rev-list HEAD |
1735 git diff-tree --stdin --format=medium -p
1736 • Print the list of commits on the current branch that touched any
1738 file in the Documentation directory.
1739 git rev-list HEAD -- Documentation/
1741 • Print the list of commits authored by you in the past year, on any
1743 branch, tag, or other ref.
1744 git rev-list --author=you@example.com --since=1.year.ago --all
1746 • Print the list of objects reachable from the current branch (i.e.,
1748 all commits and the blobs and trees they contain).
1749 git rev-list --objects HEAD
1751 • Compare the disk size of all reachable objects, versus those
1753 reachable from reflogs, versus the total packed size. This can tell
1754 you whether running git repack -ad might reduce the repository size
1755 (by dropping unreachable objects), and whether expiring reflogs
1756 might help.
1757 # reachable objects
1759 git rev-list --disk-usage --objects --all
1760 # plus reflogs
1761 git rev-list --disk-usage --objects --all --reflog
1762 # total disk size used
1763 du -c .git/objects/pack/*.pack .git/objects/??/*
1764 # alternative to du: add up "size" and "size-pack" fields
1765 git count-objects -v
1766 • Report the disk size of each branch, not including objects used by
1768 the current branch. This can find outliers that are contributing to
1769 a bloated repository size (e.g., because somebody accidentally
1770 committed large build artifacts).
1771 git for-each-ref --format='%(refname)' |
1773 while read branch
1774 do
1775 size=$(git rev-list --disk-usage --objects HEAD..$branch)
1776 echo "$size $branch"
1777 done |
1778 sort -n
1779 • Compare the on-disk size of branches in one group of refs,
1781 excluding another. If you co-mingle objects from multiple remotes
1782 in a single repository, this can show which remotes are
1783 contributing to the repository size (taking the size of origin as a
1784 baseline).
1785 git rev-list --disk-usage --objects --remotes=$suspect --not --remotes=origin
1787
1789 Part of the git(1) suite
1790Git 2.43.0 11/20/2023 GIT-REV-LIST(1)