]>
Commit | Line | Data |
---|---|---|
1 | Commit Limiting | |
2 | ~~~~~~~~~~~~~~~ | |
3 | ||
4 | Besides specifying a range of commits that should be listed using the | |
5 | special notations explained in the description, additional commit | |
6 | limiting may be applied. | |
7 | ||
8 | Using more options generally further limits the output (e.g. | |
9 | `--since=<date1>` limits to commits newer than `<date1>`, and using it | |
10 | with `--grep=<pattern>` further limits to commits whose log message | |
11 | has a line that matches `<pattern>`), unless otherwise noted. | |
12 | ||
13 | Note that these are applied before commit | |
14 | ordering and formatting options, such as `--reverse`. | |
15 | ||
16 | -<number>:: | |
17 | -n <number>:: | |
18 | --max-count=<number>:: | |
19 | Limit the number of commits to output. | |
20 | ||
21 | --skip=<number>:: | |
22 | Skip 'number' commits before starting to show the commit output. | |
23 | ||
24 | --since=<date>:: | |
25 | --after=<date>:: | |
26 | Show commits more recent than a specific date. | |
27 | ||
28 | --until=<date>:: | |
29 | --before=<date>:: | |
30 | Show commits older than a specific date. | |
31 | ||
32 | ifdef::git-rev-list[] | |
33 | --max-age=<timestamp>:: | |
34 | --min-age=<timestamp>:: | |
35 | Limit the commits output to specified time range. | |
36 | endif::git-rev-list[] | |
37 | ||
38 | --author=<pattern>:: | |
39 | --committer=<pattern>:: | |
40 | Limit the commits output to ones with author/committer | |
41 | header lines that match the specified pattern (regular | |
42 | expression). With more than one `--author=<pattern>`, | |
43 | commits whose author matches any of the given patterns are | |
44 | chosen (similarly for multiple `--committer=<pattern>`). | |
45 | ||
46 | --grep-reflog=<pattern>:: | |
47 | Limit the commits output to ones with reflog entries that | |
48 | match the specified pattern (regular expression). With | |
49 | more than one `--grep-reflog`, commits whose reflog message | |
50 | matches any of the given patterns are chosen. It is an | |
51 | error to use this option unless `--walk-reflogs` is in use. | |
52 | ||
53 | --grep=<pattern>:: | |
54 | Limit the commits output to ones with log message that | |
55 | matches the specified pattern (regular expression). With | |
56 | more than one `--grep=<pattern>`, commits whose message | |
57 | matches any of the given patterns are chosen (but see | |
58 | `--all-match`). | |
59 | ifndef::git-rev-list[] | |
60 | + | |
61 | When `--show-notes` is in effect, the message from the notes is | |
62 | matched as if it were part of the log message. | |
63 | endif::git-rev-list[] | |
64 | ||
65 | --all-match:: | |
66 | Limit the commits output to ones that match all given `--grep`, | |
67 | instead of ones that match at least one. | |
68 | ||
69 | --invert-grep:: | |
70 | Limit the commits output to ones with log message that do not | |
71 | match the pattern specified with `--grep=<pattern>`. | |
72 | ||
73 | -i:: | |
74 | --regexp-ignore-case:: | |
75 | Match the regular expression limiting patterns without regard to letter | |
76 | case. | |
77 | ||
78 | --basic-regexp:: | |
79 | Consider the limiting patterns to be basic regular expressions; | |
80 | this is the default. | |
81 | ||
82 | -E:: | |
83 | --extended-regexp:: | |
84 | Consider the limiting patterns to be extended regular expressions | |
85 | instead of the default basic regular expressions. | |
86 | ||
87 | -F:: | |
88 | --fixed-strings:: | |
89 | Consider the limiting patterns to be fixed strings (don't interpret | |
90 | pattern as a regular expression). | |
91 | ||
92 | -P:: | |
93 | --perl-regexp:: | |
94 | Consider the limiting patterns to be Perl-compatible regular | |
95 | expressions. | |
96 | + | |
97 | Support for these types of regular expressions is an optional | |
98 | compile-time dependency. If Git wasn't compiled with support for them | |
99 | providing this option will cause it to die. | |
100 | ||
101 | --remove-empty:: | |
102 | Stop when a given path disappears from the tree. | |
103 | ||
104 | --merges:: | |
105 | Print only merge commits. This is exactly the same as `--min-parents=2`. | |
106 | ||
107 | --no-merges:: | |
108 | Do not print commits with more than one parent. This is | |
109 | exactly the same as `--max-parents=1`. | |
110 | ||
111 | --min-parents=<number>:: | |
112 | --max-parents=<number>:: | |
113 | --no-min-parents:: | |
114 | --no-max-parents:: | |
115 | Show only commits which have at least (or at most) that many parent | |
116 | commits. In particular, `--max-parents=1` is the same as `--no-merges`, | |
117 | `--min-parents=2` is the same as `--merges`. `--max-parents=0` | |
118 | gives all root commits and `--min-parents=3` all octopus merges. | |
119 | + | |
120 | `--no-min-parents` and `--no-max-parents` reset these limits (to no limit) | |
121 | again. Equivalent forms are `--min-parents=0` (any commit has 0 or more | |
122 | parents) and `--max-parents=-1` (negative numbers denote no upper limit). | |
123 | ||
124 | --first-parent:: | |
125 | Follow only the first parent commit upon seeing a merge | |
126 | commit. This option can give a better overview when | |
127 | viewing the evolution of a particular topic branch, | |
128 | because merges into a topic branch tend to be only about | |
129 | adjusting to updated upstream from time to time, and | |
130 | this option allows you to ignore the individual commits | |
131 | brought in to your history by such a merge. Cannot be | |
132 | combined with --bisect. | |
133 | ||
134 | --not:: | |
135 | Reverses the meaning of the '{caret}' prefix (or lack thereof) | |
136 | for all following revision specifiers, up to the next `--not`. | |
137 | ||
138 | --all:: | |
139 | Pretend as if all the refs in `refs/`, along with `HEAD`, are | |
140 | listed on the command line as '<commit>'. | |
141 | ||
142 | --branches[=<pattern>]:: | |
143 | Pretend as if all the refs in `refs/heads` are listed | |
144 | on the command line as '<commit>'. If '<pattern>' is given, limit | |
145 | branches to ones matching given shell glob. If pattern lacks '?', | |
146 | '{asterisk}', or '[', '/{asterisk}' at the end is implied. | |
147 | ||
148 | --tags[=<pattern>]:: | |
149 | Pretend as if all the refs in `refs/tags` are listed | |
150 | on the command line as '<commit>'. If '<pattern>' is given, limit | |
151 | tags to ones matching given shell glob. If pattern lacks '?', '{asterisk}', | |
152 | or '[', '/{asterisk}' at the end is implied. | |
153 | ||
154 | --remotes[=<pattern>]:: | |
155 | Pretend as if all the refs in `refs/remotes` are listed | |
156 | on the command line as '<commit>'. If '<pattern>' is given, limit | |
157 | remote-tracking branches to ones matching given shell glob. | |
158 | If pattern lacks '?', '{asterisk}', or '[', '/{asterisk}' at the end is implied. | |
159 | ||
160 | --glob=<glob-pattern>:: | |
161 | Pretend as if all the refs matching shell glob '<glob-pattern>' | |
162 | are listed on the command line as '<commit>'. Leading 'refs/', | |
163 | is automatically prepended if missing. If pattern lacks '?', '{asterisk}', | |
164 | or '[', '/{asterisk}' at the end is implied. | |
165 | ||
166 | --exclude=<glob-pattern>:: | |
167 | ||
168 | Do not include refs matching '<glob-pattern>' that the next `--all`, | |
169 | `--branches`, `--tags`, `--remotes`, or `--glob` would otherwise | |
170 | consider. Repetitions of this option accumulate exclusion patterns | |
171 | up to the next `--all`, `--branches`, `--tags`, `--remotes`, or | |
172 | `--glob` option (other options or arguments do not clear | |
173 | accumulated patterns). | |
174 | + | |
175 | The patterns given should not begin with `refs/heads`, `refs/tags`, or | |
176 | `refs/remotes` when applied to `--branches`, `--tags`, or `--remotes`, | |
177 | respectively, and they must begin with `refs/` when applied to `--glob` | |
178 | or `--all`. If a trailing '/{asterisk}' is intended, it must be given | |
179 | explicitly. | |
180 | ||
181 | --reflog:: | |
182 | Pretend as if all objects mentioned by reflogs are listed on the | |
183 | command line as `<commit>`. | |
184 | ||
185 | --alternate-refs:: | |
186 | Pretend as if all objects mentioned as ref tips of alternate | |
187 | repositories were listed on the command line. An alternate | |
188 | repository is any repository whose object directory is specified | |
189 | in `objects/info/alternates`. The set of included objects may | |
190 | be modified by `core.alternateRefsCommand`, etc. See | |
191 | linkgit:git-config[1]. | |
192 | ||
193 | --single-worktree:: | |
194 | By default, all working trees will be examined by the | |
195 | following options when there are more than one (see | |
196 | linkgit:git-worktree[1]): `--all`, `--reflog` and | |
197 | `--indexed-objects`. | |
198 | This option forces them to examine the current working tree | |
199 | only. | |
200 | ||
201 | --ignore-missing:: | |
202 | Upon seeing an invalid object name in the input, pretend as if | |
203 | the bad input was not given. | |
204 | ||
205 | ifndef::git-rev-list[] | |
206 | --bisect:: | |
207 | Pretend as if the bad bisection ref `refs/bisect/bad` | |
208 | was listed and as if it was followed by `--not` and the good | |
209 | bisection refs `refs/bisect/good-*` on the command | |
210 | line. Cannot be combined with --first-parent. | |
211 | endif::git-rev-list[] | |
212 | ||
213 | --stdin:: | |
214 | In addition to the '<commit>' listed on the command | |
215 | line, read them from the standard input. If a `--` separator is | |
216 | seen, stop reading commits and start reading paths to limit the | |
217 | result. | |
218 | ||
219 | ifdef::git-rev-list[] | |
220 | --quiet:: | |
221 | Don't print anything to standard output. This form | |
222 | is primarily meant to allow the caller to | |
223 | test the exit status to see if a range of objects is fully | |
224 | connected (or not). It is faster than redirecting stdout | |
225 | to `/dev/null` as the output does not have to be formatted. | |
226 | endif::git-rev-list[] | |
227 | ||
228 | --cherry-mark:: | |
229 | Like `--cherry-pick` (see below) but mark equivalent commits | |
230 | with `=` rather than omitting them, and inequivalent ones with `+`. | |
231 | ||
232 | --cherry-pick:: | |
233 | Omit any commit that introduces the same change as | |
234 | another commit on the ``other side'' when the set of | |
235 | commits are limited with symmetric difference. | |
236 | + | |
237 | For example, if you have two branches, `A` and `B`, a usual way | |
238 | to list all commits on only one side of them is with | |
239 | `--left-right` (see the example below in the description of | |
240 | the `--left-right` option). However, it shows the commits that were | |
241 | cherry-picked from the other branch (for example, ``3rd on b'' may be | |
242 | cherry-picked from branch A). With this option, such pairs of commits are | |
243 | excluded from the output. | |
244 | ||
245 | --left-only:: | |
246 | --right-only:: | |
247 | List only commits on the respective side of a symmetric difference, | |
248 | i.e. only those which would be marked `<` resp. `>` by | |
249 | `--left-right`. | |
250 | + | |
251 | For example, `--cherry-pick --right-only A...B` omits those | |
252 | commits from `B` which are in `A` or are patch-equivalent to a commit in | |
253 | `A`. In other words, this lists the `+` commits from `git cherry A B`. | |
254 | More precisely, `--cherry-pick --right-only --no-merges` gives the exact | |
255 | list. | |
256 | ||
257 | --cherry:: | |
258 | A synonym for `--right-only --cherry-mark --no-merges`; useful to | |
259 | limit the output to the commits on our side and mark those that | |
260 | have been applied to the other side of a forked history with | |
261 | `git log --cherry upstream...mybranch`, similar to | |
262 | `git cherry upstream mybranch`. | |
263 | ||
264 | -g:: | |
265 | --walk-reflogs:: | |
266 | Instead of walking the commit ancestry chain, walk | |
267 | reflog entries from the most recent one to older ones. | |
268 | When this option is used you cannot specify commits to | |
269 | exclude (that is, '{caret}commit', 'commit1..commit2', | |
270 | and 'commit1\...commit2' notations cannot be used). | |
271 | + | |
272 | With `--pretty` format other than `oneline` (for obvious reasons), | |
273 | this causes the output to have two extra lines of information | |
274 | taken from the reflog. The reflog designator in the output may be shown | |
275 | as `ref@{Nth}` (where `Nth` is the reverse-chronological index in the | |
276 | reflog) or as `ref@{timestamp}` (with the timestamp for that entry), | |
277 | depending on a few rules: | |
278 | + | |
279 | -- | |
280 | 1. If the starting point is specified as `ref@{Nth}`, show the index | |
281 | format. | |
282 | + | |
283 | 2. If the starting point was specified as `ref@{now}`, show the | |
284 | timestamp format. | |
285 | + | |
286 | 3. If neither was used, but `--date` was given on the command line, show | |
287 | the timestamp in the format requested by `--date`. | |
288 | + | |
289 | 4. Otherwise, show the index format. | |
290 | -- | |
291 | + | |
292 | Under `--pretty=oneline`, the commit message is | |
293 | prefixed with this information on the same line. | |
294 | This option cannot be combined with `--reverse`. | |
295 | See also linkgit:git-reflog[1]. | |
296 | ||
297 | --merge:: | |
298 | After a failed merge, show refs that touch files having a | |
299 | conflict and don't exist on all heads to merge. | |
300 | ||
301 | --boundary:: | |
302 | Output excluded boundary commits. Boundary commits are | |
303 | prefixed with `-`. | |
304 | ||
305 | ifdef::git-rev-list[] | |
306 | --use-bitmap-index:: | |
307 | ||
308 | Try to speed up the traversal using the pack bitmap index (if | |
309 | one is available). Note that when traversing with `--objects`, | |
310 | trees and blobs will not have their associated path printed. | |
311 | ||
312 | --progress=<header>:: | |
313 | Show progress reports on stderr as objects are considered. The | |
314 | `<header>` text will be printed with each progress update. | |
315 | endif::git-rev-list[] | |
316 | ||
317 | History Simplification | |
318 | ~~~~~~~~~~~~~~~~~~~~~~ | |
319 | ||
320 | Sometimes you are only interested in parts of the history, for example the | |
321 | commits modifying a particular <path>. But there are two parts of | |
322 | 'History Simplification', one part is selecting the commits and the other | |
323 | is how to do it, as there are various strategies to simplify the history. | |
324 | ||
325 | The following options select the commits to be shown: | |
326 | ||
327 | <paths>:: | |
328 | Commits modifying the given <paths> are selected. | |
329 | ||
330 | --simplify-by-decoration:: | |
331 | Commits that are referred by some branch or tag are selected. | |
332 | ||
333 | Note that extra commits can be shown to give a meaningful history. | |
334 | ||
335 | The following options affect the way the simplification is performed: | |
336 | ||
337 | Default mode:: | |
338 | Simplifies the history to the simplest history explaining the | |
339 | final state of the tree. Simplest because it prunes some side | |
340 | branches if the end result is the same (i.e. merging branches | |
341 | with the same content) | |
342 | ||
343 | --full-history:: | |
344 | Same as the default mode, but does not prune some history. | |
345 | ||
346 | --dense:: | |
347 | Only the selected commits are shown, plus some to have a | |
348 | meaningful history. | |
349 | ||
350 | --sparse:: | |
351 | All commits in the simplified history are shown. | |
352 | ||
353 | --simplify-merges:: | |
354 | Additional option to `--full-history` to remove some needless | |
355 | merges from the resulting history, as there are no selected | |
356 | commits contributing to this merge. | |
357 | ||
358 | --ancestry-path:: | |
359 | When given a range of commits to display (e.g. 'commit1..commit2' | |
360 | or 'commit2 {caret}commit1'), only display commits that exist | |
361 | directly on the ancestry chain between the 'commit1' and | |
362 | 'commit2', i.e. commits that are both descendants of 'commit1', | |
363 | and ancestors of 'commit2'. | |
364 | ||
365 | A more detailed explanation follows. | |
366 | ||
367 | Suppose you specified `foo` as the <paths>. We shall call commits | |
368 | that modify `foo` !TREESAME, and the rest TREESAME. (In a diff | |
369 | filtered for `foo`, they look different and equal, respectively.) | |
370 | ||
371 | In the following, we will always refer to the same example history to | |
372 | illustrate the differences between simplification settings. We assume | |
373 | that you are filtering for a file `foo` in this commit graph: | |
374 | ----------------------------------------------------------------------- | |
375 | .-A---M---N---O---P---Q | |
376 | / / / / / / | |
377 | I B C D E Y | |
378 | \ / / / / / | |
379 | `-------------' X | |
380 | ----------------------------------------------------------------------- | |
381 | The horizontal line of history A---Q is taken to be the first parent of | |
382 | each merge. The commits are: | |
383 | ||
384 | * `I` is the initial commit, in which `foo` exists with contents | |
385 | ``asdf'', and a file `quux` exists with contents ``quux''. Initial | |
386 | commits are compared to an empty tree, so `I` is !TREESAME. | |
387 | ||
388 | * In `A`, `foo` contains just ``foo''. | |
389 | ||
390 | * `B` contains the same change as `A`. Its merge `M` is trivial and | |
391 | hence TREESAME to all parents. | |
392 | ||
393 | * `C` does not change `foo`, but its merge `N` changes it to ``foobar'', | |
394 | so it is not TREESAME to any parent. | |
395 | ||
396 | * `D` sets `foo` to ``baz''. Its merge `O` combines the strings from | |
397 | `N` and `D` to ``foobarbaz''; i.e., it is not TREESAME to any parent. | |
398 | ||
399 | * `E` changes `quux` to ``xyzzy'', and its merge `P` combines the | |
400 | strings to ``quux xyzzy''. `P` is TREESAME to `O`, but not to `E`. | |
401 | ||
402 | * `X` is an independent root commit that added a new file `side`, and `Y` | |
403 | modified it. `Y` is TREESAME to `X`. Its merge `Q` added `side` to `P`, and | |
404 | `Q` is TREESAME to `P`, but not to `Y`. | |
405 | ||
406 | `rev-list` walks backwards through history, including or excluding | |
407 | commits based on whether `--full-history` and/or parent rewriting | |
408 | (via `--parents` or `--children`) are used. The following settings | |
409 | are available. | |
410 | ||
411 | Default mode:: | |
412 | Commits are included if they are not TREESAME to any parent | |
413 | (though this can be changed, see `--sparse` below). If the | |
414 | commit was a merge, and it was TREESAME to one parent, follow | |
415 | only that parent. (Even if there are several TREESAME | |
416 | parents, follow only one of them.) Otherwise, follow all | |
417 | parents. | |
418 | + | |
419 | This results in: | |
420 | + | |
421 | ----------------------------------------------------------------------- | |
422 | .-A---N---O | |
423 | / / / | |
424 | I---------D | |
425 | ----------------------------------------------------------------------- | |
426 | + | |
427 | Note how the rule to only follow the TREESAME parent, if one is | |
428 | available, removed `B` from consideration entirely. `C` was | |
429 | considered via `N`, but is TREESAME. Root commits are compared to an | |
430 | empty tree, so `I` is !TREESAME. | |
431 | + | |
432 | Parent/child relations are only visible with `--parents`, but that does | |
433 | not affect the commits selected in default mode, so we have shown the | |
434 | parent lines. | |
435 | ||
436 | --full-history without parent rewriting:: | |
437 | This mode differs from the default in one point: always follow | |
438 | all parents of a merge, even if it is TREESAME to one of them. | |
439 | Even if more than one side of the merge has commits that are | |
440 | included, this does not imply that the merge itself is! In | |
441 | the example, we get | |
442 | + | |
443 | ----------------------------------------------------------------------- | |
444 | I A B N D O P Q | |
445 | ----------------------------------------------------------------------- | |
446 | + | |
447 | `M` was excluded because it is TREESAME to both parents. `E`, | |
448 | `C` and `B` were all walked, but only `B` was !TREESAME, so the others | |
449 | do not appear. | |
450 | + | |
451 | Note that without parent rewriting, it is not really possible to talk | |
452 | about the parent/child relationships between the commits, so we show | |
453 | them disconnected. | |
454 | ||
455 | --full-history with parent rewriting:: | |
456 | Ordinary commits are only included if they are !TREESAME | |
457 | (though this can be changed, see `--sparse` below). | |
458 | + | |
459 | Merges are always included. However, their parent list is rewritten: | |
460 | Along each parent, prune away commits that are not included | |
461 | themselves. This results in | |
462 | + | |
463 | ----------------------------------------------------------------------- | |
464 | .-A---M---N---O---P---Q | |
465 | / / / / / | |
466 | I B / D / | |
467 | \ / / / / | |
468 | `-------------' | |
469 | ----------------------------------------------------------------------- | |
470 | + | |
471 | Compare to `--full-history` without rewriting above. Note that `E` | |
472 | was pruned away because it is TREESAME, but the parent list of P was | |
473 | rewritten to contain `E`'s parent `I`. The same happened for `C` and | |
474 | `N`, and `X`, `Y` and `Q`. | |
475 | ||
476 | In addition to the above settings, you can change whether TREESAME | |
477 | affects inclusion: | |
478 | ||
479 | --dense:: | |
480 | Commits that are walked are included if they are not TREESAME | |
481 | to any parent. | |
482 | ||
483 | --sparse:: | |
484 | All commits that are walked are included. | |
485 | + | |
486 | Note that without `--full-history`, this still simplifies merges: if | |
487 | one of the parents is TREESAME, we follow only that one, so the other | |
488 | sides of the merge are never walked. | |
489 | ||
490 | --simplify-merges:: | |
491 | First, build a history graph in the same way that | |
492 | `--full-history` with parent rewriting does (see above). | |
493 | + | |
494 | Then simplify each commit `C` to its replacement `C'` in the final | |
495 | history according to the following rules: | |
496 | + | |
497 | -- | |
498 | * Set `C'` to `C`. | |
499 | + | |
500 | * Replace each parent `P` of `C'` with its simplification `P'`. In | |
501 | the process, drop parents that are ancestors of other parents or that are | |
502 | root commits TREESAME to an empty tree, and remove duplicates, but take care | |
503 | to never drop all parents that we are TREESAME to. | |
504 | + | |
505 | * If after this parent rewriting, `C'` is a root or merge commit (has | |
506 | zero or >1 parents), a boundary commit, or !TREESAME, it remains. | |
507 | Otherwise, it is replaced with its only parent. | |
508 | -- | |
509 | + | |
510 | The effect of this is best shown by way of comparing to | |
511 | `--full-history` with parent rewriting. The example turns into: | |
512 | + | |
513 | ----------------------------------------------------------------------- | |
514 | .-A---M---N---O | |
515 | / / / | |
516 | I B D | |
517 | \ / / | |
518 | `---------' | |
519 | ----------------------------------------------------------------------- | |
520 | + | |
521 | Note the major differences in `N`, `P`, and `Q` over `--full-history`: | |
522 | + | |
523 | -- | |
524 | * `N`'s parent list had `I` removed, because it is an ancestor of the | |
525 | other parent `M`. Still, `N` remained because it is !TREESAME. | |
526 | + | |
527 | * `P`'s parent list similarly had `I` removed. `P` was then | |
528 | removed completely, because it had one parent and is TREESAME. | |
529 | + | |
530 | * `Q`'s parent list had `Y` simplified to `X`. `X` was then removed, because it | |
531 | was a TREESAME root. `Q` was then removed completely, because it had one | |
532 | parent and is TREESAME. | |
533 | -- | |
534 | ||
535 | Finally, there is a fifth simplification mode available: | |
536 | ||
537 | --ancestry-path:: | |
538 | Limit the displayed commits to those directly on the ancestry | |
539 | chain between the ``from'' and ``to'' commits in the given commit | |
540 | range. I.e. only display commits that are ancestor of the ``to'' | |
541 | commit and descendants of the ``from'' commit. | |
542 | + | |
543 | As an example use case, consider the following commit history: | |
544 | + | |
545 | ----------------------------------------------------------------------- | |
546 | D---E-------F | |
547 | / \ \ | |
548 | B---C---G---H---I---J | |
549 | / \ | |
550 | A-------K---------------L--M | |
551 | ----------------------------------------------------------------------- | |
552 | + | |
553 | A regular 'D..M' computes the set of commits that are ancestors of `M`, | |
554 | but excludes the ones that are ancestors of `D`. This is useful to see | |
555 | what happened to the history leading to `M` since `D`, in the sense | |
556 | that ``what does `M` have that did not exist in `D`''. The result in this | |
557 | example would be all the commits, except `A` and `B` (and `D` itself, | |
558 | of course). | |
559 | + | |
560 | When we want to find out what commits in `M` are contaminated with the | |
561 | bug introduced by `D` and need fixing, however, we might want to view | |
562 | only the subset of 'D..M' that are actually descendants of `D`, i.e. | |
563 | excluding `C` and `K`. This is exactly what the `--ancestry-path` | |
564 | option does. Applied to the 'D..M' range, it results in: | |
565 | + | |
566 | ----------------------------------------------------------------------- | |
567 | E-------F | |
568 | \ \ | |
569 | G---H---I---J | |
570 | \ | |
571 | L--M | |
572 | ----------------------------------------------------------------------- | |
573 | ||
574 | The `--simplify-by-decoration` option allows you to view only the | |
575 | big picture of the topology of the history, by omitting commits | |
576 | that are not referenced by tags. Commits are marked as !TREESAME | |
577 | (in other words, kept after history simplification rules described | |
578 | above) if (1) they are referenced by tags, or (2) they change the | |
579 | contents of the paths given on the command line. All other | |
580 | commits are marked as TREESAME (subject to be simplified away). | |
581 | ||
582 | ifdef::git-rev-list[] | |
583 | Bisection Helpers | |
584 | ~~~~~~~~~~~~~~~~~ | |
585 | ||
586 | --bisect:: | |
587 | Limit output to the one commit object which is roughly halfway between | |
588 | included and excluded commits. Note that the bad bisection ref | |
589 | `refs/bisect/bad` is added to the included commits (if it | |
590 | exists) and the good bisection refs `refs/bisect/good-*` are | |
591 | added to the excluded commits (if they exist). Thus, supposing there | |
592 | are no refs in `refs/bisect/`, if | |
593 | + | |
594 | ----------------------------------------------------------------------- | |
595 | $ git rev-list --bisect foo ^bar ^baz | |
596 | ----------------------------------------------------------------------- | |
597 | + | |
598 | outputs 'midpoint', the output of the two commands | |
599 | + | |
600 | ----------------------------------------------------------------------- | |
601 | $ git rev-list foo ^midpoint | |
602 | $ git rev-list midpoint ^bar ^baz | |
603 | ----------------------------------------------------------------------- | |
604 | + | |
605 | would be of roughly the same length. Finding the change which | |
606 | introduces a regression is thus reduced to a binary search: repeatedly | |
607 | generate and test new 'midpoint's until the commit chain is of length | |
608 | one. Cannot be combined with --first-parent. | |
609 | ||
610 | --bisect-vars:: | |
611 | This calculates the same as `--bisect`, except that refs in | |
612 | `refs/bisect/` are not used, and except that this outputs | |
613 | text ready to be eval'ed by the shell. These lines will assign the | |
614 | name of the midpoint revision to the variable `bisect_rev`, and the | |
615 | expected number of commits to be tested after `bisect_rev` is tested | |
616 | to `bisect_nr`, the expected number of commits to be tested if | |
617 | `bisect_rev` turns out to be good to `bisect_good`, the expected | |
618 | number of commits to be tested if `bisect_rev` turns out to be bad to | |
619 | `bisect_bad`, and the number of commits we are bisecting right now to | |
620 | `bisect_all`. | |
621 | ||
622 | --bisect-all:: | |
623 | This outputs all the commit objects between the included and excluded | |
624 | commits, ordered by their distance to the included and excluded | |
625 | commits. Refs in `refs/bisect/` are not used. The farthest | |
626 | from them is displayed first. (This is the only one displayed by | |
627 | `--bisect`.) | |
628 | + | |
629 | This is useful because it makes it easy to choose a good commit to | |
630 | test when you want to avoid to test some of them for some reason (they | |
631 | may not compile for example). | |
632 | + | |
633 | This option can be used along with `--bisect-vars`, in this case, | |
634 | after all the sorted commit objects, there will be the same text as if | |
635 | `--bisect-vars` had been used alone. | |
636 | endif::git-rev-list[] | |
637 | ||
638 | ||
639 | Commit Ordering | |
640 | ~~~~~~~~~~~~~~~ | |
641 | ||
642 | By default, the commits are shown in reverse chronological order. | |
643 | ||
644 | --date-order:: | |
645 | Show no parents before all of its children are shown, but | |
646 | otherwise show commits in the commit timestamp order. | |
647 | ||
648 | --author-date-order:: | |
649 | Show no parents before all of its children are shown, but | |
650 | otherwise show commits in the author timestamp order. | |
651 | ||
652 | --topo-order:: | |
653 | Show no parents before all of its children are shown, and | |
654 | avoid showing commits on multiple lines of history | |
655 | intermixed. | |
656 | + | |
657 | For example, in a commit history like this: | |
658 | + | |
659 | ---------------------------------------------------------------- | |
660 | ||
661 | ---1----2----4----7 | |
662 | \ \ | |
663 | 3----5----6----8--- | |
664 | ||
665 | ---------------------------------------------------------------- | |
666 | + | |
667 | where the numbers denote the order of commit timestamps, `git | |
668 | rev-list` and friends with `--date-order` show the commits in the | |
669 | timestamp order: 8 7 6 5 4 3 2 1. | |
670 | + | |
671 | With `--topo-order`, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5 | |
672 | 3 1); some older commits are shown before newer ones in order to | |
673 | avoid showing the commits from two parallel development track mixed | |
674 | together. | |
675 | ||
676 | --reverse:: | |
677 | Output the commits chosen to be shown (see Commit Limiting | |
678 | section above) in reverse order. Cannot be combined with | |
679 | `--walk-reflogs`. | |
680 | ||
681 | Object Traversal | |
682 | ~~~~~~~~~~~~~~~~ | |
683 | ||
684 | These options are mostly targeted for packing of Git repositories. | |
685 | ||
686 | ifdef::git-rev-list[] | |
687 | --objects:: | |
688 | Print the object IDs of any object referenced by the listed | |
689 | commits. `--objects foo ^bar` thus means ``send me | |
690 | all object IDs which I need to download if I have the commit | |
691 | object _bar_ but not _foo_''. | |
692 | ||
693 | --in-commit-order:: | |
694 | Print tree and blob ids in order of the commits. The tree | |
695 | and blob ids are printed after they are first referenced | |
696 | by a commit. | |
697 | ||
698 | --objects-edge:: | |
699 | Similar to `--objects`, but also print the IDs of excluded | |
700 | commits prefixed with a ``-'' character. This is used by | |
701 | linkgit:git-pack-objects[1] to build a ``thin'' pack, which records | |
702 | objects in deltified form based on objects contained in these | |
703 | excluded commits to reduce network traffic. | |
704 | ||
705 | --objects-edge-aggressive:: | |
706 | Similar to `--objects-edge`, but it tries harder to find excluded | |
707 | commits at the cost of increased time. This is used instead of | |
708 | `--objects-edge` to build ``thin'' packs for shallow repositories. | |
709 | ||
710 | --indexed-objects:: | |
711 | Pretend as if all trees and blobs used by the index are listed | |
712 | on the command line. Note that you probably want to use | |
713 | `--objects`, too. | |
714 | ||
715 | --unpacked:: | |
716 | Only useful with `--objects`; print the object IDs that are not | |
717 | in packs. | |
718 | ||
719 | --object-names:: | |
720 | Only useful with `--objects`; print the names of the object IDs | |
721 | that are found. This is the default behavior. | |
722 | ||
723 | --no-object-names:: | |
724 | Only useful with `--objects`; does not print the names of the object | |
725 | IDs that are found. This inverts `--object-names`. This flag allows | |
726 | the output to be more easily parsed by commands such as | |
727 | linkgit:git-cat-file[1]. | |
728 | ||
729 | --filter=<filter-spec>:: | |
730 | Only useful with one of the `--objects*`; omits objects (usually | |
731 | blobs) from the list of printed objects. The '<filter-spec>' | |
732 | may be one of the following: | |
733 | + | |
734 | The form '--filter=blob:none' omits all blobs. | |
735 | + | |
736 | The form '--filter=blob:limit=<n>[kmg]' omits blobs larger than n bytes | |
737 | or units. n may be zero. The suffixes k, m, and g can be used to name | |
738 | units in KiB, MiB, or GiB. For example, 'blob:limit=1k' is the same | |
739 | as 'blob:limit=1024'. | |
740 | + | |
741 | The form '--filter=sparse:oid=<blob-ish>' uses a sparse-checkout | |
742 | specification contained in the blob (or blob-expression) '<blob-ish>' | |
743 | to omit blobs that would not be not required for a sparse checkout on | |
744 | the requested refs. | |
745 | + | |
746 | The form '--filter=tree:<depth>' omits all blobs and trees whose depth | |
747 | from the root tree is >= <depth> (minimum depth if an object is located | |
748 | at multiple depths in the commits traversed). <depth>=0 will not include | |
749 | any trees or blobs unless included explicitly in the command-line (or | |
750 | standard input when --stdin is used). <depth>=1 will include only the | |
751 | tree and blobs which are referenced directly by a commit reachable from | |
752 | <commit> or an explicitly-given object. <depth>=2 is like <depth>=1 | |
753 | while also including trees and blobs one more level removed from an | |
754 | explicitly-given commit or tree. | |
755 | + | |
756 | Note that the form '--filter=sparse:path=<path>' that wants to read | |
757 | from an arbitrary path on the filesystem has been dropped for security | |
758 | reasons. | |
759 | + | |
760 | Multiple '--filter=' flags can be specified to combine filters. Only | |
761 | objects which are accepted by every filter are included. | |
762 | + | |
763 | The form '--filter=combine:<filter1>+<filter2>+...<filterN>' can also be | |
764 | used to combined several filters, but this is harder than just repeating | |
765 | the '--filter' flag and is usually not necessary. Filters are joined by | |
766 | '{plus}' and individual filters are %-encoded (i.e. URL-encoded). | |
767 | Besides the '{plus}' and '%' characters, the following characters are | |
768 | reserved and also must be encoded: `~!@#$^&*()[]{}\;",<>?`+'`+ | |
769 | as well as all characters with ASCII code <= `0x20`, which includes | |
770 | space and newline. | |
771 | + | |
772 | Other arbitrary characters can also be encoded. For instance, | |
773 | 'combine:tree:3+blob:none' and 'combine:tree%3A3+blob%3Anone' are | |
774 | equivalent. | |
775 | ||
776 | --no-filter:: | |
777 | Turn off any previous `--filter=` argument. | |
778 | ||
779 | --filter-print-omitted:: | |
780 | Only useful with `--filter=`; prints a list of the objects omitted | |
781 | by the filter. Object IDs are prefixed with a ``~'' character. | |
782 | ||
783 | --missing=<missing-action>:: | |
784 | A debug option to help with future "partial clone" development. | |
785 | This option specifies how missing objects are handled. | |
786 | + | |
787 | The form '--missing=error' requests that rev-list stop with an error if | |
788 | a missing object is encountered. This is the default action. | |
789 | + | |
790 | The form '--missing=allow-any' will allow object traversal to continue | |
791 | if a missing object is encountered. Missing objects will silently be | |
792 | omitted from the results. | |
793 | + | |
794 | The form '--missing=allow-promisor' is like 'allow-any', but will only | |
795 | allow object traversal to continue for EXPECTED promisor missing objects. | |
796 | Unexpected missing objects will raise an error. | |
797 | + | |
798 | The form '--missing=print' is like 'allow-any', but will also print a | |
799 | list of the missing objects. Object IDs are prefixed with a ``?'' character. | |
800 | ||
801 | --exclude-promisor-objects:: | |
802 | (For internal use only.) Prefilter object traversal at | |
803 | promisor boundary. This is used with partial clone. This is | |
804 | stronger than `--missing=allow-promisor` because it limits the | |
805 | traversal, rather than just silencing errors about missing | |
806 | objects. | |
807 | endif::git-rev-list[] | |
808 | ||
809 | --no-walk[=(sorted|unsorted)]:: | |
810 | Only show the given commits, but do not traverse their ancestors. | |
811 | This has no effect if a range is specified. If the argument | |
812 | `unsorted` is given, the commits are shown in the order they were | |
813 | given on the command line. Otherwise (if `sorted` or no argument | |
814 | was given), the commits are shown in reverse chronological order | |
815 | by commit time. | |
816 | Cannot be combined with `--graph`. | |
817 | ||
818 | --do-walk:: | |
819 | Overrides a previous `--no-walk`. | |
820 | ||
821 | Commit Formatting | |
822 | ~~~~~~~~~~~~~~~~~ | |
823 | ||
824 | ifdef::git-rev-list[] | |
825 | Using these options, linkgit:git-rev-list[1] will act similar to the | |
826 | more specialized family of commit log tools: linkgit:git-log[1], | |
827 | linkgit:git-show[1], and linkgit:git-whatchanged[1] | |
828 | endif::git-rev-list[] | |
829 | ||
830 | include::pretty-options.txt[] | |
831 | ||
832 | --relative-date:: | |
833 | Synonym for `--date=relative`. | |
834 | ||
835 | --date=<format>:: | |
836 | Only takes effect for dates shown in human-readable format, such | |
837 | as when using `--pretty`. `log.date` config variable sets a default | |
838 | value for the log command's `--date` option. By default, dates | |
839 | are shown in the original time zone (either committer's or | |
840 | author's). If `-local` is appended to the format (e.g., | |
841 | `iso-local`), the user's local time zone is used instead. | |
842 | + | |
843 | -- | |
844 | `--date=relative` shows dates relative to the current time, | |
845 | e.g. ``2 hours ago''. The `-local` option has no effect for | |
846 | `--date=relative`. | |
847 | ||
848 | `--date=local` is an alias for `--date=default-local`. | |
849 | ||
850 | `--date=iso` (or `--date=iso8601`) shows timestamps in a ISO 8601-like format. | |
851 | The differences to the strict ISO 8601 format are: | |
852 | ||
853 | - a space instead of the `T` date/time delimiter | |
854 | - a space between time and time zone | |
855 | - no colon between hours and minutes of the time zone | |
856 | ||
857 | `--date=iso-strict` (or `--date=iso8601-strict`) shows timestamps in strict | |
858 | ISO 8601 format. | |
859 | ||
860 | `--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822 | |
861 | format, often found in email messages. | |
862 | ||
863 | `--date=short` shows only the date, but not the time, in `YYYY-MM-DD` format. | |
864 | ||
865 | `--date=raw` shows the date as seconds since the epoch (1970-01-01 | |
866 | 00:00:00 UTC), followed by a space, and then the timezone as an offset | |
867 | from UTC (a `+` or `-` with four digits; the first two are hours, and | |
868 | the second two are minutes). I.e., as if the timestamp were formatted | |
869 | with `strftime("%s %z")`). | |
870 | Note that the `-local` option does not affect the seconds-since-epoch | |
871 | value (which is always measured in UTC), but does switch the accompanying | |
872 | timezone value. | |
873 | ||
874 | `--date=human` shows the timezone if the timezone does not match the | |
875 | current time-zone, and doesn't print the whole date if that matches | |
876 | (ie skip printing year for dates that are "this year", but also skip | |
877 | the whole date itself if it's in the last few days and we can just say | |
878 | what weekday it was). For older dates the hour and minute is also | |
879 | omitted. | |
880 | ||
881 | `--date=unix` shows the date as a Unix epoch timestamp (seconds since | |
882 | 1970). As with `--raw`, this is always in UTC and therefore `-local` | |
883 | has no effect. | |
884 | ||
885 | `--date=format:...` feeds the format `...` to your system `strftime`, | |
886 | except for %z and %Z, which are handled internally. | |
887 | Use `--date=format:%c` to show the date in your system locale's | |
888 | preferred format. See the `strftime` manual for a complete list of | |
889 | format placeholders. When using `-local`, the correct syntax is | |
890 | `--date=format-local:...`. | |
891 | ||
892 | `--date=default` is the default format, and is similar to | |
893 | `--date=rfc2822`, with a few exceptions: | |
894 | -- | |
895 | - there is no comma after the day-of-week | |
896 | ||
897 | - the time zone is omitted when the local time zone is used | |
898 | ||
899 | ifdef::git-rev-list[] | |
900 | --header:: | |
901 | Print the contents of the commit in raw-format; each record is | |
902 | separated with a NUL character. | |
903 | endif::git-rev-list[] | |
904 | ||
905 | --parents:: | |
906 | Print also the parents of the commit (in the form "commit parent..."). | |
907 | Also enables parent rewriting, see 'History Simplification' above. | |
908 | ||
909 | --children:: | |
910 | Print also the children of the commit (in the form "commit child..."). | |
911 | Also enables parent rewriting, see 'History Simplification' above. | |
912 | ||
913 | ifdef::git-rev-list[] | |
914 | --timestamp:: | |
915 | Print the raw commit timestamp. | |
916 | endif::git-rev-list[] | |
917 | ||
918 | --left-right:: | |
919 | Mark which side of a symmetric difference a commit is reachable from. | |
920 | Commits from the left side are prefixed with `<` and those from | |
921 | the right with `>`. If combined with `--boundary`, those | |
922 | commits are prefixed with `-`. | |
923 | + | |
924 | For example, if you have this topology: | |
925 | + | |
926 | ----------------------------------------------------------------------- | |
927 | y---b---b branch B | |
928 | / \ / | |
929 | / . | |
930 | / / \ | |
931 | o---x---a---a branch A | |
932 | ----------------------------------------------------------------------- | |
933 | + | |
934 | you would get an output like this: | |
935 | + | |
936 | ----------------------------------------------------------------------- | |
937 | $ git rev-list --left-right --boundary --pretty=oneline A...B | |
938 | ||
939 | >bbbbbbb... 3rd on b | |
940 | >bbbbbbb... 2nd on b | |
941 | <aaaaaaa... 3rd on a | |
942 | <aaaaaaa... 2nd on a | |
943 | -yyyyyyy... 1st on b | |
944 | -xxxxxxx... 1st on a | |
945 | ----------------------------------------------------------------------- | |
946 | ||
947 | --graph:: | |
948 | Draw a text-based graphical representation of the commit history | |
949 | on the left hand side of the output. This may cause extra lines | |
950 | to be printed in between commits, in order for the graph history | |
951 | to be drawn properly. | |
952 | Cannot be combined with `--no-walk`. | |
953 | + | |
954 | This enables parent rewriting, see 'History Simplification' above. | |
955 | + | |
956 | This implies the `--topo-order` option by default, but the | |
957 | `--date-order` option may also be specified. | |
958 | ||
959 | --show-linear-break[=<barrier>]:: | |
960 | When --graph is not used, all history branches are flattened | |
961 | which can make it hard to see that the two consecutive commits | |
962 | do not belong to a linear branch. This option puts a barrier | |
963 | in between them in that case. If `<barrier>` is specified, it | |
964 | is the string that will be shown instead of the default one. | |
965 | ||
966 | ifdef::git-rev-list[] | |
967 | --count:: | |
968 | Print a number stating how many commits would have been | |
969 | listed, and suppress all other output. When used together | |
970 | with `--left-right`, instead print the counts for left and | |
971 | right commits, separated by a tab. When used together with | |
972 | `--cherry-mark`, omit patch equivalent commits from these | |
973 | counts and print the count for equivalent commits separated | |
974 | by a tab. | |
975 | endif::git-rev-list[] | |
976 | ||
977 | ifndef::git-rev-list[] | |
978 | Diff Formatting | |
979 | ~~~~~~~~~~~~~~~ | |
980 | ||
981 | Listed below are options that control the formatting of diff output. | |
982 | Some of them are specific to linkgit:git-rev-list[1], however other diff | |
983 | options may be given. See linkgit:git-diff-files[1] for more options. | |
984 | ||
985 | -c:: | |
986 | With this option, diff output for a merge commit | |
987 | shows the differences from each of the parents to the merge result | |
988 | simultaneously instead of showing pairwise diff between a parent | |
989 | and the result one at a time. Furthermore, it lists only files | |
990 | which were modified from all parents. | |
991 | ||
992 | --cc:: | |
993 | This flag implies the `-c` option and further compresses the | |
994 | patch output by omitting uninteresting hunks whose contents in | |
995 | the parents have only two variants and the merge result picks | |
996 | one of them without modification. | |
997 | ||
998 | --combined-all-paths:: | |
999 | This flag causes combined diffs (used for merge commits) to | |
1000 | list the name of the file from all parents. It thus only has | |
1001 | effect when -c or --cc are specified, and is likely only | |
1002 | useful if filename changes are detected (i.e. when either | |
1003 | rename or copy detection have been requested). | |
1004 | ||
1005 | -m:: | |
1006 | This flag makes the merge commits show the full diff like | |
1007 | regular commits; for each merge parent, a separate log entry | |
1008 | and diff is generated. An exception is that only diff against | |
1009 | the first parent is shown when `--first-parent` option is given; | |
1010 | in that case, the output represents the changes the merge | |
1011 | brought _into_ the then-current branch. | |
1012 | ||
1013 | -r:: | |
1014 | Show recursive diffs. | |
1015 | ||
1016 | -t:: | |
1017 | Show the tree objects in the diff output. This implies `-r`. | |
1018 | endif::git-rev-list[] |