]>
Commit | Line | Data |
---|---|---|
fdcf39e5 MV |
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 | |
a23e3138 JH |
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`. | |
fdcf39e5 MV |
15 | |
16 | -- | |
17 | ||
70c2a258 NTND |
18 | -<number>:: |
19 | -n <number>:: | |
982962ce | 20 | --max-count=<number>:: |
fdcf39e5 | 21 | |
841d8118 | 22 | Limit the number of commits to output. |
fdcf39e5 | 23 | |
982962ce | 24 | --skip=<number>:: |
fdcf39e5 MV |
25 | |
26 | Skip 'number' commits before starting to show the commit output. | |
27 | ||
982962ce MM |
28 | --since=<date>:: |
29 | --after=<date>:: | |
fdcf39e5 MV |
30 | |
31 | Show commits more recent than a specific date. | |
32 | ||
982962ce MM |
33 | --until=<date>:: |
34 | --before=<date>:: | |
fdcf39e5 MV |
35 | |
36 | Show commits older than a specific date. | |
37 | ||
56b6d01d | 38 | ifdef::git-rev-list[] |
982962ce MM |
39 | --max-age=<timestamp>:: |
40 | --min-age=<timestamp>:: | |
fdcf39e5 MV |
41 | |
42 | Limit the commits output to specified time range. | |
56b6d01d | 43 | endif::git-rev-list[] |
fdcf39e5 | 44 | |
982962ce MM |
45 | --author=<pattern>:: |
46 | --committer=<pattern>:: | |
fdcf39e5 MV |
47 | |
48 | Limit the commits output to ones with author/committer | |
a23e3138 JH |
49 | header lines that match the specified pattern (regular |
50 | expression). With more than one `--author=<pattern>`, | |
51 | commits whose author matches any of the given patterns are | |
52 | chosen (similarly for multiple `--committer=<pattern>`). | |
fdcf39e5 | 53 | |
72fd13f7 NTND |
54 | --grep-reflog=<pattern>:: |
55 | ||
56 | Limit the commits output to ones with reflog entries that | |
57 | match the specified pattern (regular expression). With | |
58 | more than one `--grep-reflog`, commits whose reflog message | |
baa6378f JH |
59 | matches any of the given patterns are chosen. It is an |
60 | error to use this option unless `--walk-reflogs` is in use. | |
72fd13f7 | 61 | |
982962ce | 62 | --grep=<pattern>:: |
fdcf39e5 MV |
63 | |
64 | Limit the commits output to ones with log message that | |
a23e3138 JH |
65 | matches the specified pattern (regular expression). With |
66 | more than one `--grep=<pattern>`, commits whose message | |
67 | matches any of the given patterns are chosen (but see | |
68 | `--all-match`). | |
38cfe915 NTND |
69 | + |
70 | When `--show-notes` is in effect, the message from the notes as | |
71 | if it is part of the log message. | |
fdcf39e5 | 72 | |
7756ba74 MM |
73 | --all-match:: |
74 | Limit the commits output to ones that match all given --grep, | |
a23e3138 | 75 | instead of ones that match at least one. |
7756ba74 | 76 | |
3240240f SB |
77 | -i:: |
78 | --regexp-ignore-case:: | |
fdcf39e5 MV |
79 | |
80 | Match the regexp limiting patterns without regard to letters case. | |
81 | ||
727b6fc3 JH |
82 | --basic-regexp:: |
83 | ||
84 | Consider the limiting patterns to be basic regular expressions; | |
85 | this is the default. | |
86 | ||
3240240f SB |
87 | -E:: |
88 | --extended-regexp:: | |
fdcf39e5 MV |
89 | |
90 | Consider the limiting patterns to be extended regular expressions | |
91 | instead of the default basic regular expressions. | |
92 | ||
3240240f SB |
93 | -F:: |
94 | --fixed-strings:: | |
dc1c0fff JN |
95 | |
96 | Consider the limiting patterns to be fixed strings (don't interpret | |
97 | pattern as a regular expression). | |
98 | ||
727b6fc3 JH |
99 | --perl-regexp:: |
100 | ||
101 | Consider the limiting patterns to be Perl-compatible regexp. | |
102 | Requires libpcre to be compiled in. | |
103 | ||
fdcf39e5 MV |
104 | --remove-empty:: |
105 | ||
106 | Stop when a given path disappears from the tree. | |
107 | ||
2657420d SG |
108 | --merges:: |
109 | ||
6a6ebded | 110 | Print only merge commits. This is exactly the same as `--min-parents=2`. |
2657420d | 111 | |
fdcf39e5 MV |
112 | --no-merges:: |
113 | ||
6a6ebded MG |
114 | Do not print commits with more than one parent. This is |
115 | exactly the same as `--max-parents=1`. | |
116 | ||
117 | --min-parents=<number>:: | |
118 | --max-parents=<number>:: | |
119 | --no-min-parents:: | |
120 | --no-max-parents:: | |
121 | ||
5104d21f | 122 | Show only commits which have at least (or at most) that many parent |
6a6ebded MG |
123 | commits. In particular, `--max-parents=1` is the same as `--no-merges`, |
124 | `--min-parents=2` is the same as `--merges`. `--max-parents=0` | |
125 | gives all root commits and `--min-parents=3` all octopus merges. | |
126 | + | |
127 | `--no-min-parents` and `--no-max-parents` reset these limits (to no limit) | |
128 | again. Equivalent forms are `--min-parents=0` (any commit has 0 or more | |
129 | parents) and `--max-parents=-1` (negative numbers denote no upper limit). | |
fdcf39e5 MV |
130 | |
131 | --first-parent:: | |
132 | Follow only the first parent commit upon seeing a merge | |
133 | commit. This option can give a better overview when | |
134 | viewing the evolution of a particular topic branch, | |
135 | because merges into a topic branch tend to be only about | |
136 | adjusting to updated upstream from time to time, and | |
137 | this option allows you to ignore the individual commits | |
138 | brought in to your history by such a merge. | |
139 | ||
140 | --not:: | |
141 | ||
142 | Reverses the meaning of the '{caret}' prefix (or lack thereof) | |
143 | for all following revision specifiers, up to the next '--not'. | |
144 | ||
145 | --all:: | |
146 | ||
cc1b8d8b | 147 | Pretend as if all the refs in `refs/` are listed on the |
fdcf39e5 | 148 | command line as '<commit>'. |
c2e6385d | 149 | |
62b4698e | 150 | --branches[=<pattern>]:: |
c2e6385d | 151 | |
cc1b8d8b | 152 | Pretend as if all the refs in `refs/heads` are listed |
62b4698e | 153 | on the command line as '<commit>'. If '<pattern>' is given, limit |
b09fe971 | 154 | branches to ones matching given shell glob. If pattern lacks '?', |
e34bb2e7 | 155 | '{asterisk}', or '[', '/{asterisk}' at the end is implied. |
c2e6385d | 156 | |
62b4698e | 157 | --tags[=<pattern>]:: |
c2e6385d | 158 | |
cc1b8d8b | 159 | Pretend as if all the refs in `refs/tags` are listed |
62b4698e | 160 | on the command line as '<commit>'. If '<pattern>' is given, limit |
e34bb2e7 CMN |
161 | tags to ones matching given shell glob. If pattern lacks '?', '{asterisk}', |
162 | or '[', '/{asterisk}' at the end is implied. | |
c2e6385d | 163 | |
62b4698e | 164 | --remotes[=<pattern>]:: |
c2e6385d | 165 | |
cc1b8d8b | 166 | Pretend as if all the refs in `refs/remotes` are listed |
62b4698e | 167 | on the command line as '<commit>'. If '<pattern>' is given, limit |
0e615b25 | 168 | remote-tracking branches to ones matching given shell glob. |
e34bb2e7 | 169 | If pattern lacks '?', '{asterisk}', or '[', '/{asterisk}' at the end is implied. |
fdcf39e5 | 170 | |
62b4698e ŠN |
171 | --glob=<glob-pattern>:: |
172 | Pretend as if all the refs matching shell glob '<glob-pattern>' | |
d08bae7e | 173 | are listed on the command line as '<commit>'. Leading 'refs/', |
e34bb2e7 CMN |
174 | is automatically prepended if missing. If pattern lacks '?', '{asterisk}', |
175 | or '[', '/{asterisk}' at the end is implied. | |
d08bae7e | 176 | |
cc243c3c JH |
177 | --ignore-missing:: |
178 | ||
179 | Upon seeing an invalid object name in the input, pretend as if | |
180 | the bad input was not given. | |
d08bae7e | 181 | |
af06e93a CC |
182 | ifndef::git-rev-list[] |
183 | --bisect:: | |
184 | ||
cc1b8d8b | 185 | Pretend as if the bad bisection ref `refs/bisect/bad` |
af06e93a | 186 | was listed and as if it was followed by `--not` and the good |
cc1b8d8b | 187 | bisection refs `refs/bisect/good-*` on the command |
af06e93a CC |
188 | line. |
189 | endif::git-rev-list[] | |
190 | ||
fdcf39e5 MV |
191 | --stdin:: |
192 | ||
193 | In addition to the '<commit>' listed on the command | |
60da8b15 JH |
194 | line, read them from the standard input. If a '--' separator is |
195 | seen, stop reading commits and start reading paths to limit the | |
196 | result. | |
fdcf39e5 | 197 | |
8b3dce56 | 198 | ifdef::git-rev-list[] |
fdcf39e5 MV |
199 | --quiet:: |
200 | ||
201 | Don't print anything to standard output. This form | |
202 | is primarily meant to allow the caller to | |
203 | test the exit status to see if a range of objects is fully | |
204 | connected (or not). It is faster than redirecting stdout | |
205 | to /dev/null as the output does not have to be formatted. | |
adf60f14 | 206 | endif::git-rev-list[] |
fdcf39e5 | 207 | |
cb56e309 MG |
208 | --cherry-mark:: |
209 | ||
210 | Like `--cherry-pick` (see below) but mark equivalent commits | |
211 | with `=` rather than omitting them, and inequivalent ones with `+`. | |
212 | ||
fdcf39e5 MV |
213 | --cherry-pick:: |
214 | ||
215 | Omit any commit that introduces the same change as | |
216 | another commit on the "other side" when the set of | |
217 | commits are limited with symmetric difference. | |
218 | + | |
219 | For example, if you have two branches, `A` and `B`, a usual way | |
220 | to list all commits on only one side of them is with | |
3add01bb JH |
221 | `--left-right` (see the example below in the description of |
222 | the `--left-right` option). It however shows the commits that were cherry-picked | |
fdcf39e5 MV |
223 | from the other branch (for example, "3rd on b" may be cherry-picked |
224 | from branch A). With this option, such pairs of commits are | |
225 | excluded from the output. | |
226 | ||
59c8afdf MG |
227 | --left-only:: |
228 | --right-only:: | |
229 | ||
230 | List only commits on the respective side of a symmetric range, | |
231 | i.e. only those which would be marked `<` resp. `>` by | |
232 | `--left-right`. | |
233 | + | |
234 | For example, `--cherry-pick --right-only A...B` omits those | |
235 | commits from `B` which are in `A` or are patch-equivalent to a commit in | |
6cf378f0 | 236 | `A`. In other words, this lists the `+` commits from `git cherry A B`. |
59c8afdf MG |
237 | More precisely, `--cherry-pick --right-only --no-merges` gives the exact |
238 | list. | |
239 | ||
94f605ec MG |
240 | --cherry:: |
241 | ||
242 | A synonym for `--right-only --cherry-mark --no-merges`; useful to | |
243 | limit the output to the commits on our side and mark those that | |
244 | have been applied to the other side of a forked history with | |
245 | `git log --cherry upstream...mybranch`, similar to | |
246 | `git cherry upstream mybranch`. | |
247 | ||
3240240f SB |
248 | -g:: |
249 | --walk-reflogs:: | |
fdcf39e5 MV |
250 | |
251 | Instead of walking the commit ancestry chain, walk | |
252 | reflog entries from the most recent one to older ones. | |
253 | When this option is used you cannot specify commits to | |
254 | exclude (that is, '{caret}commit', 'commit1..commit2', | |
b9190e79 | 255 | nor 'commit1\...commit2' notations cannot be used). |
fdcf39e5 MV |
256 | + |
257 | With '\--pretty' format other than oneline (for obvious reasons), | |
258 | this causes the output to have two extra lines of information | |
259 | taken from the reflog. By default, 'commit@\{Nth}' notation is | |
260 | used in the output. When the starting commit is specified as | |
18a2197e | 261 | 'commit@\{now}', output also uses 'commit@\{timestamp}' notation |
fdcf39e5 MV |
262 | instead. Under '\--pretty=oneline', the commit message is |
263 | prefixed with this information on the same line. | |
e534735a | 264 | This option cannot be combined with '\--reverse'. |
fdcf39e5 MV |
265 | See also linkgit:git-reflog[1]. |
266 | ||
267 | --merge:: | |
268 | ||
269 | After a failed merge, show refs that touch files having a | |
270 | conflict and don't exist on all heads to merge. | |
271 | ||
272 | --boundary:: | |
273 | ||
e32db66d KB |
274 | Output excluded boundary commits. Boundary commits are |
275 | prefixed with `-`. | |
fdcf39e5 | 276 | |
70d9895e TR |
277 | -- |
278 | ||
279 | History Simplification | |
280 | ~~~~~~~~~~~~~~~~~~~~~~ | |
281 | ||
7bc2508b SB |
282 | Sometimes you are only interested in parts of the history, for example the |
283 | commits modifying a particular <path>. But there are two parts of | |
284 | 'History Simplification', one part is selecting the commits and the other | |
285 | is how to do it, as there are various strategies to simplify the history. | |
286 | ||
287 | The following options select the commits to be shown: | |
288 | ||
289 | <paths>:: | |
290 | ||
291 | Commits modifying the given <paths> are selected. | |
292 | ||
293 | --simplify-by-decoration:: | |
294 | ||
295 | Commits that are referred by some branch or tag are selected. | |
296 | ||
297 | Note that extra commits can be shown to give a meaningful history. | |
298 | ||
299 | The following options affect the way the simplification is performed: | |
300 | ||
301 | Default mode:: | |
302 | ||
303 | Simplifies the history to the simplest history explaining the | |
304 | final state of the tree. Simplest because it prunes some side | |
305 | branches if the end result is the same (i.e. merging branches | |
306 | with the same content) | |
307 | ||
308 | --full-history:: | |
309 | ||
df6b0cad | 310 | Same as the default mode, but does not prune some history. |
7bc2508b SB |
311 | |
312 | --dense:: | |
313 | ||
314 | Only the selected commits are shown, plus some to have a | |
315 | meaningful history. | |
316 | ||
317 | --sparse:: | |
318 | ||
319 | All commits in the simplified history are shown. | |
320 | ||
321 | --simplify-merges:: | |
322 | ||
323 | Additional option to '--full-history' to remove some needless | |
324 | merges from the resulting history, as there are no selected | |
325 | commits contributing to this merge. | |
326 | ||
57456ef4 JH |
327 | --ancestry-path:: |
328 | ||
329 | When given a range of commits to display (e.g. 'commit1..commit2' | |
330 | or 'commit2 {caret}commit1'), only display commits that exist | |
331 | directly on the ancestry chain between the 'commit1' and | |
332 | 'commit2', i.e. commits that are both descendants of 'commit1', | |
333 | and ancestors of 'commit2'. | |
334 | ||
7bc2508b | 335 | A more detailed explanation follows. |
70d9895e TR |
336 | |
337 | Suppose you specified `foo` as the <paths>. We shall call commits | |
338 | that modify `foo` !TREESAME, and the rest TREESAME. (In a diff | |
339 | filtered for `foo`, they look different and equal, respectively.) | |
340 | ||
341 | In the following, we will always refer to the same example history to | |
342 | illustrate the differences between simplification settings. We assume | |
343 | that you are filtering for a file `foo` in this commit graph: | |
344 | ----------------------------------------------------------------------- | |
143f1eaf KB |
345 | .-A---M---N---O---P---Q |
346 | / / / / / / | |
347 | I B C D E Y | |
348 | \ / / / / / | |
349 | `-------------' X | |
70d9895e | 350 | ----------------------------------------------------------------------- |
143f1eaf | 351 | The horizontal line of history A---Q is taken to be the first parent of |
70d9895e TR |
352 | each merge. The commits are: |
353 | ||
354 | * `I` is the initial commit, in which `foo` exists with contents | |
355 | "asdf", and a file `quux` exists with contents "quux". Initial | |
356 | commits are compared to an empty tree, so `I` is !TREESAME. | |
357 | ||
358 | * In `A`, `foo` contains just "foo". | |
359 | ||
360 | * `B` contains the same change as `A`. Its merge `M` is trivial and | |
361 | hence TREESAME to all parents. | |
362 | ||
363 | * `C` does not change `foo`, but its merge `N` changes it to "foobar", | |
364 | so it is not TREESAME to any parent. | |
365 | ||
366 | * `D` sets `foo` to "baz". Its merge `O` combines the strings from | |
367 | `N` and `D` to "foobarbaz"; i.e., it is not TREESAME to any parent. | |
368 | ||
369 | * `E` changes `quux` to "xyzzy", and its merge `P` combines the | |
617f50cb | 370 | strings to "quux xyzzy". `P` is TREESAME to `O`, but not to `E`. |
70d9895e | 371 | |
17b83d71 | 372 | * `X` is an independent root commit that added a new file `side`, and `Y` |
143f1eaf KB |
373 | modified it. `Y` is TREESAME to `X`. Its merge `Q` added `side` to `P`, and |
374 | `Q` is TREESAME to `P`, but not to `Y`. | |
375 | ||
70d9895e TR |
376 | 'rev-list' walks backwards through history, including or excluding |
377 | commits based on whether '\--full-history' and/or parent rewriting | |
378 | (via '\--parents' or '\--children') are used. The following settings | |
379 | are available. | |
380 | ||
381 | Default mode:: | |
382 | ||
383 | Commits are included if they are not TREESAME to any parent | |
384 | (though this can be changed, see '\--sparse' below). If the | |
385 | commit was a merge, and it was TREESAME to one parent, follow | |
386 | only that parent. (Even if there are several TREESAME | |
387 | parents, follow only one of them.) Otherwise, follow all | |
388 | parents. | |
389 | + | |
390 | This results in: | |
391 | + | |
392 | ----------------------------------------------------------------------- | |
393 | .-A---N---O | |
f70d0586 | 394 | / / / |
70d9895e TR |
395 | I---------D |
396 | ----------------------------------------------------------------------- | |
397 | + | |
398 | Note how the rule to only follow the TREESAME parent, if one is | |
399 | available, removed `B` from consideration entirely. `C` was | |
400 | considered via `N`, but is TREESAME. Root commits are compared to an | |
401 | empty tree, so `I` is !TREESAME. | |
402 | + | |
403 | Parent/child relations are only visible with --parents, but that does | |
404 | not affect the commits selected in default mode, so we have shown the | |
405 | parent lines. | |
406 | ||
407 | --full-history without parent rewriting:: | |
408 | ||
409 | This mode differs from the default in one point: always follow | |
410 | all parents of a merge, even if it is TREESAME to one of them. | |
411 | Even if more than one side of the merge has commits that are | |
412 | included, this does not imply that the merge itself is! In | |
413 | the example, we get | |
414 | + | |
415 | ----------------------------------------------------------------------- | |
143f1eaf | 416 | I A B N D O P Q |
70d9895e TR |
417 | ----------------------------------------------------------------------- |
418 | + | |
d0af663e | 419 | `M` was excluded because it is TREESAME to both parents. `E`, |
70d9895e TR |
420 | `C` and `B` were all walked, but only `B` was !TREESAME, so the others |
421 | do not appear. | |
422 | + | |
423 | Note that without parent rewriting, it is not really possible to talk | |
424 | about the parent/child relationships between the commits, so we show | |
425 | them disconnected. | |
426 | ||
427 | --full-history with parent rewriting:: | |
428 | ||
429 | Ordinary commits are only included if they are !TREESAME | |
430 | (though this can be changed, see '\--sparse' below). | |
431 | + | |
432 | Merges are always included. However, their parent list is rewritten: | |
433 | Along each parent, prune away commits that are not included | |
434 | themselves. This results in | |
435 | + | |
436 | ----------------------------------------------------------------------- | |
143f1eaf | 437 | .-A---M---N---O---P---Q |
70d9895e TR |
438 | / / / / / |
439 | I B / D / | |
440 | \ / / / / | |
441 | `-------------' | |
442 | ----------------------------------------------------------------------- | |
443 | + | |
444 | Compare to '\--full-history' without rewriting above. Note that `E` | |
445 | was pruned away because it is TREESAME, but the parent list of P was | |
446 | rewritten to contain `E`'s parent `I`. The same happened for `C` and | |
143f1eaf | 447 | `N`, and `X`, `Y` and `Q`. |
70d9895e TR |
448 | |
449 | In addition to the above settings, you can change whether TREESAME | |
450 | affects inclusion: | |
451 | ||
3240240f | 452 | --dense:: |
70d9895e TR |
453 | |
454 | Commits that are walked are included if they are not TREESAME | |
455 | to any parent. | |
456 | ||
3240240f | 457 | --sparse:: |
fdcf39e5 | 458 | |
70d9895e TR |
459 | All commits that are walked are included. |
460 | + | |
461 | Note that without '\--full-history', this still simplifies merges: if | |
462 | one of the parents is TREESAME, we follow only that one, so the other | |
463 | sides of the merge are never walked. | |
fdcf39e5 | 464 | |
d266a988 TR |
465 | --simplify-merges:: |
466 | ||
467 | First, build a history graph in the same way that | |
468 | '\--full-history' with parent rewriting does (see above). | |
469 | + | |
470 | Then simplify each commit `C` to its replacement `C'` in the final | |
471 | history according to the following rules: | |
472 | + | |
473 | -- | |
474 | * Set `C'` to `C`. | |
475 | + | |
476 | * Replace each parent `P` of `C'` with its simplification `P'`. In | |
143f1eaf KB |
477 | the process, drop parents that are ancestors of other parents or that are |
478 | root commits TREESAME to an empty tree, and remove duplicates, but take care | |
479 | to never drop all parents that we are TREESAME to. | |
d266a988 TR |
480 | + |
481 | * If after this parent rewriting, `C'` is a root or merge commit (has | |
482 | zero or >1 parents), a boundary commit, or !TREESAME, it remains. | |
483 | Otherwise, it is replaced with its only parent. | |
484 | -- | |
485 | + | |
486 | The effect of this is best shown by way of comparing to | |
487 | '\--full-history' with parent rewriting. The example turns into: | |
488 | + | |
489 | ----------------------------------------------------------------------- | |
490 | .-A---M---N---O | |
491 | / / / | |
492 | I B D | |
493 | \ / / | |
494 | `---------' | |
495 | ----------------------------------------------------------------------- | |
496 | + | |
143f1eaf | 497 | Note the major differences in `N`, `P` and `Q` over '--full-history': |
d266a988 TR |
498 | + |
499 | -- | |
500 | * `N`'s parent list had `I` removed, because it is an ancestor of the | |
501 | other parent `M`. Still, `N` remained because it is !TREESAME. | |
502 | + | |
503 | * `P`'s parent list similarly had `I` removed. `P` was then | |
504 | removed completely, because it had one parent and is TREESAME. | |
143f1eaf KB |
505 | + |
506 | * `Q`'s parent list had `Y` simplified to `X`. `X` was then removed, because it | |
507 | was a TREESAME root. `Q` was then removed completely, because it had one | |
508 | parent and is TREESAME. | |
d266a988 | 509 | -- |
fdcf39e5 | 510 | |
57456ef4 JH |
511 | Finally, there is a fifth simplification mode available: |
512 | ||
513 | --ancestry-path:: | |
514 | ||
515 | Limit the displayed commits to those directly on the ancestry | |
516 | chain between the "from" and "to" commits in the given commit | |
517 | range. I.e. only display commits that are ancestor of the "to" | |
518 | commit, and descendants of the "from" commit. | |
519 | + | |
520 | As an example use case, consider the following commit history: | |
521 | + | |
522 | ----------------------------------------------------------------------- | |
523 | D---E-------F | |
524 | / \ \ | |
525 | B---C---G---H---I---J | |
526 | / \ | |
527 | A-------K---------------L--M | |
528 | ----------------------------------------------------------------------- | |
529 | + | |
530 | A regular 'D..M' computes the set of commits that are ancestors of `M`, | |
531 | but excludes the ones that are ancestors of `D`. This is useful to see | |
532 | what happened to the history leading to `M` since `D`, in the sense | |
533 | that "what does `M` have that did not exist in `D`". The result in this | |
534 | example would be all the commits, except `A` and `B` (and `D` itself, | |
535 | of course). | |
536 | + | |
537 | When we want to find out what commits in `M` are contaminated with the | |
538 | bug introduced by `D` and need fixing, however, we might want to view | |
539 | only the subset of 'D..M' that are actually descendants of `D`, i.e. | |
6cf378f0 | 540 | excluding `C` and `K`. This is exactly what the '--ancestry-path' |
57456ef4 JH |
541 | option does. Applied to the 'D..M' range, it results in: |
542 | + | |
543 | ----------------------------------------------------------------------- | |
544 | E-------F | |
545 | \ \ | |
546 | G---H---I---J | |
547 | \ | |
548 | L--M | |
549 | ----------------------------------------------------------------------- | |
550 | ||
3fcfd662 NS |
551 | The '\--simplify-by-decoration' option allows you to view only the |
552 | big picture of the topology of the history, by omitting commits | |
553 | that are not referenced by tags. Commits are marked as !TREESAME | |
554 | (in other words, kept after history simplification rules described | |
555 | above) if (1) they are referenced by tags, or (2) they change the | |
556 | contents of the paths given on the command line. All other | |
557 | commits are marked as TREESAME (subject to be simplified away). | |
558 | ||
fdcf39e5 | 559 | ifdef::git-rev-list[] |
70d9895e TR |
560 | Bisection Helpers |
561 | ~~~~~~~~~~~~~~~~~ | |
562 | ||
fdcf39e5 MV |
563 | --bisect:: |
564 | ||
565 | Limit output to the one commit object which is roughly halfway between | |
af06e93a | 566 | included and excluded commits. Note that the bad bisection ref |
cc1b8d8b JK |
567 | `refs/bisect/bad` is added to the included commits (if it |
568 | exists) and the good bisection refs `refs/bisect/good-*` are | |
af06e93a | 569 | added to the excluded commits (if they exist). Thus, supposing there |
cc1b8d8b | 570 | are no refs in `refs/bisect/`, if |
fdcf39e5 MV |
571 | |
572 | ----------------------------------------------------------------------- | |
6514aa36 | 573 | $ git rev-list --bisect foo ^bar ^baz |
fdcf39e5 MV |
574 | ----------------------------------------------------------------------- |
575 | ||
576 | outputs 'midpoint', the output of the two commands | |
577 | ||
578 | ----------------------------------------------------------------------- | |
6514aa36 CC |
579 | $ git rev-list foo ^midpoint |
580 | $ git rev-list midpoint ^bar ^baz | |
fdcf39e5 MV |
581 | ----------------------------------------------------------------------- |
582 | ||
583 | would be of roughly the same length. Finding the change which | |
584 | introduces a regression is thus reduced to a binary search: repeatedly | |
585 | generate and test new 'midpoint's until the commit chain is of length | |
586 | one. | |
587 | ||
588 | --bisect-vars:: | |
589 | ||
af06e93a | 590 | This calculates the same as `--bisect`, except that refs in |
cc1b8d8b | 591 | `refs/bisect/` are not used, and except that this outputs |
af06e93a CC |
592 | text ready to be eval'ed by the shell. These lines will assign the |
593 | name of the midpoint revision to the variable `bisect_rev`, and the | |
594 | expected number of commits to be tested after `bisect_rev` is tested | |
595 | to `bisect_nr`, the expected number of commits to be tested if | |
596 | `bisect_rev` turns out to be good to `bisect_good`, the expected | |
597 | number of commits to be tested if `bisect_rev` turns out to be bad to | |
598 | `bisect_bad`, and the number of commits we are bisecting right now to | |
599 | `bisect_all`. | |
fdcf39e5 MV |
600 | |
601 | --bisect-all:: | |
602 | ||
603 | This outputs all the commit objects between the included and excluded | |
604 | commits, ordered by their distance to the included and excluded | |
cc1b8d8b | 605 | commits. Refs in `refs/bisect/` are not used. The farthest |
af06e93a CC |
606 | from them is displayed first. (This is the only one displayed by |
607 | `--bisect`.) | |
3d2d4f96 | 608 | + |
fdcf39e5 MV |
609 | This is useful because it makes it easy to choose a good commit to |
610 | test when you want to avoid to test some of them for some reason (they | |
611 | may not compile for example). | |
3d2d4f96 | 612 | + |
fdcf39e5 MV |
613 | This option can be used along with `--bisect-vars`, in this case, |
614 | after all the sorted commit objects, there will be the same text as if | |
615 | `--bisect-vars` had been used alone. | |
616 | endif::git-rev-list[] | |
617 | ||
fdcf39e5 MV |
618 | |
619 | Commit Ordering | |
620 | ~~~~~~~~~~~~~~~ | |
621 | ||
622 | By default, the commits are shown in reverse chronological order. | |
623 | ||
3f0350cc JH |
624 | --date-order:: |
625 | Show no parents before all of its children are shown, but | |
626 | otherwise show commits in the commit timestamp order. | |
fdcf39e5 | 627 | |
81c6b38b JH |
628 | --author-date-order:: |
629 | Show no parents before all of its children are shown, but | |
630 | otherwise show commits in the author timestamp order. | |
631 | ||
3f0350cc JH |
632 | --topo-order:: |
633 | Show no parents before all of its children are shown, and | |
634 | avoid showing commits on multiple lines of history | |
635 | intermixed. | |
636 | + | |
637 | For example, in a commit history like this: | |
638 | + | |
639 | ---------------------------------------------------------------- | |
fdcf39e5 | 640 | |
3f0350cc JH |
641 | ---1----2----4----7 |
642 | \ \ | |
643 | 3----5----6----8--- | |
fdcf39e5 | 644 | |
3f0350cc JH |
645 | ---------------------------------------------------------------- |
646 | + | |
647 | where the numbers denote the order of commit timestamps, `git | |
648 | rev-list` and friends with `--date-order` show the commits in the | |
649 | timestamp order: 8 7 6 5 4 3 2 1. | |
650 | + | |
651 | With `--topo-order`, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5 | |
652 | 3 1); some older commits are shown before newer ones in order to | |
653 | avoid showing the commits from two parallel development track mixed | |
654 | together. | |
fdcf39e5 MV |
655 | |
656 | --reverse:: | |
657 | ||
658 | Output the commits in reverse order. | |
659 | Cannot be combined with '\--walk-reflogs'. | |
660 | ||
661 | Object Traversal | |
662 | ~~~~~~~~~~~~~~~~ | |
663 | ||
2de9b711 | 664 | These options are mostly targeted for packing of Git repositories. |
fdcf39e5 MV |
665 | |
666 | --objects:: | |
667 | ||
668 | Print the object IDs of any object referenced by the listed | |
669 | commits. '--objects foo ^bar' thus means "send me | |
670 | all object IDs which I need to download if I have the commit | |
671 | object 'bar', but not 'foo'". | |
672 | ||
673 | --objects-edge:: | |
674 | ||
675 | Similar to '--objects', but also print the IDs of excluded | |
676 | commits prefixed with a "-" character. This is used by | |
677 | linkgit:git-pack-objects[1] to build "thin" pack, which records | |
678 | objects in deltified form based on objects contained in these | |
679 | excluded commits to reduce network traffic. | |
680 | ||
681 | --unpacked:: | |
682 | ||
683 | Only useful with '--objects'; print the object IDs that are not | |
684 | in packs. | |
685 | ||
ca92e59e MZ |
686 | --no-walk[=(sorted|unsorted)]:: |
687 | ||
688 | Only show the given commits, but do not traverse their ancestors. | |
689 | This has no effect if a range is specified. If the argument | |
690 | "unsorted" is given, the commits are show in the order they were | |
691 | given on the command line. Otherwise (if "sorted" or no argument | |
692 | was given), the commits are show in reverse chronological order | |
693 | by commit time. | |
fdcf39e5 MV |
694 | |
695 | --do-walk:: | |
696 | ||
697 | Overrides a previous --no-walk. | |
f98fd436 MG |
698 | |
699 | Commit Formatting | |
700 | ~~~~~~~~~~~~~~~~~ | |
701 | ||
702 | ifdef::git-rev-list[] | |
703 | Using these options, linkgit:git-rev-list[1] will act similar to the | |
704 | more specialized family of commit log tools: linkgit:git-log[1], | |
705 | linkgit:git-show[1], and linkgit:git-whatchanged[1] | |
706 | endif::git-rev-list[] | |
707 | ||
708 | include::pretty-options.txt[] | |
709 | ||
710 | --relative-date:: | |
711 | ||
712 | Synonym for `--date=relative`. | |
713 | ||
714 | --date=(relative|local|default|iso|rfc|short|raw):: | |
715 | ||
716 | Only takes effect for dates shown in human-readable format, such | |
717 | as when using "--pretty". `log.date` config variable sets a default | |
718 | value for log command's --date option. | |
719 | + | |
720 | `--date=relative` shows dates relative to the current time, | |
721 | e.g. "2 hours ago". | |
722 | + | |
723 | `--date=local` shows timestamps in user's local timezone. | |
724 | + | |
725 | `--date=iso` (or `--date=iso8601`) shows timestamps in ISO 8601 format. | |
726 | + | |
727 | `--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822 | |
728 | format, often found in E-mail messages. | |
729 | + | |
730 | `--date=short` shows only date but not time, in `YYYY-MM-DD` format. | |
731 | + | |
2de9b711 | 732 | `--date=raw` shows the date in the internal raw Git format `%s %z` format. |
f98fd436 MG |
733 | + |
734 | `--date=default` shows timestamps in the original timezone | |
735 | (either committer's or author's). | |
736 | ||
737 | ifdef::git-rev-list[] | |
738 | --header:: | |
739 | ||
740 | Print the contents of the commit in raw-format; each record is | |
741 | separated with a NUL character. | |
742 | endif::git-rev-list[] | |
743 | ||
744 | --parents:: | |
745 | ||
746 | Print also the parents of the commit (in the form "commit parent..."). | |
747 | Also enables parent rewriting, see 'History Simplification' below. | |
748 | ||
749 | --children:: | |
750 | ||
751 | Print also the children of the commit (in the form "commit child..."). | |
752 | Also enables parent rewriting, see 'History Simplification' below. | |
753 | ||
754 | ifdef::git-rev-list[] | |
755 | --timestamp:: | |
756 | Print the raw commit timestamp. | |
757 | endif::git-rev-list[] | |
758 | ||
759 | --left-right:: | |
760 | ||
761 | Mark which side of a symmetric diff a commit is reachable from. | |
762 | Commits from the left side are prefixed with `<` and those from | |
763 | the right with `>`. If combined with `--boundary`, those | |
764 | commits are prefixed with `-`. | |
765 | + | |
766 | For example, if you have this topology: | |
767 | + | |
768 | ----------------------------------------------------------------------- | |
769 | y---b---b branch B | |
770 | / \ / | |
771 | / . | |
772 | / / \ | |
773 | o---x---a---a branch A | |
774 | ----------------------------------------------------------------------- | |
775 | + | |
776 | you would get an output like this: | |
777 | + | |
778 | ----------------------------------------------------------------------- | |
779 | $ git rev-list --left-right --boundary --pretty=oneline A...B | |
780 | ||
781 | >bbbbbbb... 3rd on b | |
782 | >bbbbbbb... 2nd on b | |
783 | <aaaaaaa... 3rd on a | |
784 | <aaaaaaa... 2nd on a | |
785 | -yyyyyyy... 1st on b | |
786 | -xxxxxxx... 1st on a | |
787 | ----------------------------------------------------------------------- | |
788 | ||
789 | --graph:: | |
790 | ||
791 | Draw a text-based graphical representation of the commit history | |
792 | on the left hand side of the output. This may cause extra lines | |
793 | to be printed in between commits, in order for the graph history | |
794 | to be drawn properly. | |
795 | + | |
796 | This enables parent rewriting, see 'History Simplification' below. | |
797 | + | |
798 | This implies the '--topo-order' option by default, but the | |
799 | '--date-order' option may also be specified. | |
800 | ||
801 | ifdef::git-rev-list[] | |
802 | --count:: | |
803 | Print a number stating how many commits would have been | |
804 | listed, and suppress all other output. When used together | |
805 | with '--left-right', instead print the counts for left and | |
b388e14b MG |
806 | right commits, separated by a tab. When used together with |
807 | '--cherry-mark', omit patch equivalent commits from these | |
808 | counts and print the count for equivalent commits separated | |
809 | by a tab. | |
f98fd436 MG |
810 | endif::git-rev-list[] |
811 | ||
812 | ||
813 | ifndef::git-rev-list[] | |
814 | Diff Formatting | |
815 | ~~~~~~~~~~~~~~~ | |
816 | ||
817 | Below are listed options that control the formatting of diff output. | |
818 | Some of them are specific to linkgit:git-rev-list[1], however other diff | |
819 | options may be given. See linkgit:git-diff-files[1] for more options. | |
820 | ||
821 | -c:: | |
822 | ||
823 | With this option, diff output for a merge commit | |
824 | shows the differences from each of the parents to the merge result | |
825 | simultaneously instead of showing pairwise diff between a parent | |
826 | and the result one at a time. Furthermore, it lists only files | |
827 | which were modified from all parents. | |
828 | ||
829 | --cc:: | |
830 | ||
edfbbf7e | 831 | This flag implies the '-c' option and further compresses the |
f98fd436 MG |
832 | patch output by omitting uninteresting hunks whose contents in |
833 | the parents have only two variants and the merge result picks | |
834 | one of them without modification. | |
835 | ||
836 | -m:: | |
837 | ||
838 | This flag makes the merge commits show the full diff like | |
839 | regular commits; for each merge parent, a separate log entry | |
840 | and diff is generated. An exception is that only diff against | |
841 | the first parent is shown when '--first-parent' option is given; | |
842 | in that case, the output represents the changes the merge | |
843 | brought _into_ the then-current branch. | |
844 | ||
845 | -r:: | |
846 | ||
847 | Show recursive diffs. | |
848 | ||
849 | -t:: | |
850 | ||
851 | Show the tree objects in the diff output. This implies '-r'. | |
f98fd436 | 852 | endif::git-rev-list[] |