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