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