]>
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 | 15 | |
70c2a258 NTND |
16 | -<number>:: |
17 | -n <number>:: | |
982962ce | 18 | --max-count=<number>:: |
841d8118 | 19 | Limit the number of commits to output. |
fdcf39e5 | 20 | |
982962ce | 21 | --skip=<number>:: |
fdcf39e5 MV |
22 | Skip 'number' commits before starting to show the commit output. |
23 | ||
982962ce MM |
24 | --since=<date>:: |
25 | --after=<date>:: | |
fdcf39e5 MV |
26 | Show commits more recent than a specific date. |
27 | ||
96697781 MV |
28 | --since-as-filter=<date>:: |
29 | Show all commits more recent than a specific date. This visits | |
30 | all commits in the range, rather than stopping at the first commit which | |
31 | is older than a specific date. | |
32 | ||
982962ce MM |
33 | --until=<date>:: |
34 | --before=<date>:: | |
fdcf39e5 MV |
35 | Show commits older than a specific date. |
36 | ||
56b6d01d | 37 | ifdef::git-rev-list[] |
982962ce MM |
38 | --max-age=<timestamp>:: |
39 | --min-age=<timestamp>:: | |
fdcf39e5 | 40 | Limit the commits output to specified time range. |
56b6d01d | 41 | endif::git-rev-list[] |
fdcf39e5 | 42 | |
982962ce MM |
43 | --author=<pattern>:: |
44 | --committer=<pattern>:: | |
fdcf39e5 | 45 | Limit the commits output to ones with author/committer |
a23e3138 JH |
46 | header lines that match the specified pattern (regular |
47 | expression). With more than one `--author=<pattern>`, | |
48 | commits whose author matches any of the given patterns are | |
49 | chosen (similarly for multiple `--committer=<pattern>`). | |
fdcf39e5 | 50 | |
72fd13f7 | 51 | --grep-reflog=<pattern>:: |
72fd13f7 NTND |
52 | Limit the commits output to ones with reflog entries that |
53 | match the specified pattern (regular expression). With | |
54 | more than one `--grep-reflog`, commits whose reflog message | |
baa6378f JH |
55 | matches any of the given patterns are chosen. It is an |
56 | error to use this option unless `--walk-reflogs` is in use. | |
72fd13f7 | 57 | |
982962ce | 58 | --grep=<pattern>:: |
0a4f051f | 59 | Limit the commits output to ones with a log message that |
a23e3138 JH |
60 | matches the specified pattern (regular expression). With |
61 | more than one `--grep=<pattern>`, commits whose message | |
62 | matches any of the given patterns are chosen (but see | |
63 | `--all-match`). | |
2aea7a51 | 64 | ifndef::git-rev-list[] |
38cfe915 | 65 | + |
9d45ac4c | 66 | When `--notes` is in effect, the message from the notes is |
7348cdeb | 67 | matched as if it were part of the log message. |
2aea7a51 | 68 | endif::git-rev-list[] |
fdcf39e5 | 69 | |
7756ba74 | 70 | --all-match:: |
4528aa1a | 71 | Limit the commits output to ones that match all given `--grep`, |
a23e3138 | 72 | instead of ones that match at least one. |
7756ba74 | 73 | |
22dfa8a2 | 74 | --invert-grep:: |
0a4f051f | 75 | Limit the commits output to ones with a log message that do not |
22dfa8a2 CJ |
76 | match the pattern specified with `--grep=<pattern>`. |
77 | ||
3240240f SB |
78 | -i:: |
79 | --regexp-ignore-case:: | |
19d6eb41 JSJ |
80 | Match the regular expression limiting patterns without regard to letter |
81 | case. | |
fdcf39e5 | 82 | |
727b6fc3 | 83 | --basic-regexp:: |
727b6fc3 JH |
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 | Consider the limiting patterns to be extended regular expressions |
90 | instead of the default basic regular expressions. | |
91 | ||
3240240f SB |
92 | -F:: |
93 | --fixed-strings:: | |
dc1c0fff JN |
94 | Consider the limiting patterns to be fixed strings (don't interpret |
95 | pattern as a regular expression). | |
96 | ||
7531a2dd | 97 | -P:: |
727b6fc3 | 98 | --perl-regexp:: |
d048cb13 ÆAB |
99 | Consider the limiting patterns to be Perl-compatible regular |
100 | expressions. | |
101 | + | |
102 | Support for these types of regular expressions is an optional | |
103 | compile-time dependency. If Git wasn't compiled with support for them | |
104 | providing this option will cause it to die. | |
727b6fc3 | 105 | |
fdcf39e5 | 106 | --remove-empty:: |
fdcf39e5 MV |
107 | Stop when a given path disappears from the tree. |
108 | ||
2657420d | 109 | --merges:: |
6a6ebded | 110 | Print only merge commits. This is exactly the same as `--min-parents=2`. |
2657420d | 111 | |
fdcf39e5 | 112 | --no-merges:: |
6a6ebded MG |
113 | Do not print commits with more than one parent. This is |
114 | exactly the same as `--max-parents=1`. | |
115 | ||
116 | --min-parents=<number>:: | |
117 | --max-parents=<number>:: | |
118 | --no-min-parents:: | |
119 | --no-max-parents:: | |
5104d21f | 120 | Show only commits which have at least (or at most) that many parent |
6a6ebded MG |
121 | commits. In particular, `--max-parents=1` is the same as `--no-merges`, |
122 | `--min-parents=2` is the same as `--merges`. `--max-parents=0` | |
123 | gives all root commits and `--min-parents=3` all octopus merges. | |
124 | + | |
125 | `--no-min-parents` and `--no-max-parents` reset these limits (to no limit) | |
126 | again. Equivalent forms are `--min-parents=0` (any commit has 0 or more | |
127 | parents) and `--max-parents=-1` (negative numbers denote no upper limit). | |
fdcf39e5 MV |
128 | |
129 | --first-parent:: | |
9d505b7b JZ |
130 | When finding commits to include, follow only the first |
131 | parent commit upon seeing a merge commit. This option | |
132 | can give a better overview when viewing the evolution of | |
133 | a particular topic branch, because merges into a topic | |
134 | branch tend to be only about adjusting to updated upstream | |
135 | from time to time, and this option allows you to ignore | |
136 | the individual commits brought in to your history by such | |
137 | a merge. | |
e58142ad | 138 | ifdef::git-log[] |
452d2644 MÅ |
139 | + |
140 | This option also changes default diff format for merge commits | |
141 | to `first-parent`, see `--diff-merges=first-parent` for details. | |
e58142ad SO |
142 | endif::git-log[] |
143 | ||
9d505b7b JZ |
144 | --exclude-first-parent-only:: |
145 | When finding commits to exclude (with a '{caret}'), follow only | |
146 | the first parent commit upon seeing a merge commit. | |
147 | This can be used to find the set of changes in a topic branch | |
148 | from the point where it diverged from the remote branch, given | |
149 | that arbitrary merges can be valid topic branch changes. | |
150 | ||
fdcf39e5 | 151 | --not:: |
fdcf39e5 | 152 | Reverses the meaning of the '{caret}' prefix (or lack thereof) |
4528aa1a | 153 | for all following revision specifiers, up to the next `--not`. |
f97c8b1e PS |
154 | When used on the command line before --stdin, the revisions passed |
155 | through stdin will not be affected by it. Conversely, when passed | |
156 | via standard input, the revisions passed on the command line will | |
157 | not be affected by it. | |
fdcf39e5 MV |
158 | |
159 | --all:: | |
209df269 NTND |
160 | Pretend as if all the refs in `refs/`, along with `HEAD`, are |
161 | listed on the command line as '<commit>'. | |
c2e6385d | 162 | |
62b4698e | 163 | --branches[=<pattern>]:: |
cc1b8d8b | 164 | Pretend as if all the refs in `refs/heads` are listed |
62b4698e | 165 | on the command line as '<commit>'. If '<pattern>' is given, limit |
b09fe971 | 166 | branches to ones matching given shell glob. If pattern lacks '?', |
e34bb2e7 | 167 | '{asterisk}', or '[', '/{asterisk}' at the end is implied. |
c2e6385d | 168 | |
62b4698e | 169 | --tags[=<pattern>]:: |
cc1b8d8b | 170 | Pretend as if all the refs in `refs/tags` are listed |
62b4698e | 171 | on the command line as '<commit>'. If '<pattern>' is given, limit |
e34bb2e7 CMN |
172 | tags to ones matching given shell glob. If pattern lacks '?', '{asterisk}', |
173 | or '[', '/{asterisk}' at the end is implied. | |
c2e6385d | 174 | |
62b4698e | 175 | --remotes[=<pattern>]:: |
cc1b8d8b | 176 | Pretend as if all the refs in `refs/remotes` are listed |
62b4698e | 177 | on the command line as '<commit>'. If '<pattern>' is given, limit |
0e615b25 | 178 | remote-tracking branches to ones matching given shell glob. |
e34bb2e7 | 179 | If pattern lacks '?', '{asterisk}', or '[', '/{asterisk}' at the end is implied. |
fdcf39e5 | 180 | |
62b4698e ŠN |
181 | --glob=<glob-pattern>:: |
182 | Pretend as if all the refs matching shell glob '<glob-pattern>' | |
d08bae7e | 183 | are listed on the command line as '<commit>'. Leading 'refs/', |
e34bb2e7 CMN |
184 | is automatically prepended if missing. If pattern lacks '?', '{asterisk}', |
185 | or '[', '/{asterisk}' at the end is implied. | |
d08bae7e | 186 | |
574d370b JS |
187 | --exclude=<glob-pattern>:: |
188 | ||
189 | Do not include refs matching '<glob-pattern>' that the next `--all`, | |
190 | `--branches`, `--tags`, `--remotes`, or `--glob` would otherwise | |
191 | consider. Repetitions of this option accumulate exclusion patterns | |
192 | up to the next `--all`, `--branches`, `--tags`, `--remotes`, or | |
193 | `--glob` option (other options or arguments do not clear | |
f745acb0 | 194 | accumulated patterns). |
574d370b JS |
195 | + |
196 | The patterns given should not begin with `refs/heads`, `refs/tags`, or | |
197 | `refs/remotes` when applied to `--branches`, `--tags`, or `--remotes`, | |
198 | respectively, and they must begin with `refs/` when applied to `--glob` | |
199 | or `--all`. If a trailing '/{asterisk}' is intended, it must be given | |
200 | explicitly. | |
201 | ||
c6ce27ab EW |
202 | --exclude-hidden=[fetch|receive|uploadpack]:: |
203 | Do not include refs that would be hidden by `git-fetch`, | |
204 | `git-receive-pack` or `git-upload-pack` by consulting the appropriate | |
205 | `fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs` | |
206 | configuration along with `transfer.hideRefs` (see | |
8c1bc2a7 PS |
207 | linkgit:git-config[1]). This option affects the next pseudo-ref option |
208 | `--all` or `--glob` and is cleared after processing them. | |
209 | ||
41d018d1 JK |
210 | --reflog:: |
211 | Pretend as if all objects mentioned by reflogs are listed on the | |
212 | command line as `<commit>`. | |
213 | ||
39b44ba7 JK |
214 | --alternate-refs:: |
215 | Pretend as if all objects mentioned as ref tips of alternate | |
216 | repositories were listed on the command line. An alternate | |
217 | repository is any repository whose object directory is specified | |
218 | in `objects/info/alternates`. The set of included objects may | |
219 | be modified by `core.alternateRefsCommand`, etc. See | |
220 | linkgit:git-config[1]. | |
221 | ||
32619f99 NTND |
222 | --single-worktree:: |
223 | By default, all working trees will be examined by the | |
224 | following options when there are more than one (see | |
225 | linkgit:git-worktree[1]): `--all`, `--reflog` and | |
226 | `--indexed-objects`. | |
227 | This option forces them to examine the current working tree | |
228 | only. | |
229 | ||
cc243c3c | 230 | --ignore-missing:: |
cc243c3c JH |
231 | Upon seeing an invalid object name in the input, pretend as if |
232 | the bad input was not given. | |
d08bae7e | 233 | |
af06e93a CC |
234 | ifndef::git-rev-list[] |
235 | --bisect:: | |
cc1b8d8b | 236 | Pretend as if the bad bisection ref `refs/bisect/bad` |
af06e93a | 237 | was listed and as if it was followed by `--not` and the good |
cc1b8d8b | 238 | bisection refs `refs/bisect/good-*` on the command |
0fe305a5 | 239 | line. |
af06e93a CC |
240 | endif::git-rev-list[] |
241 | ||
fdcf39e5 | 242 | --stdin:: |
c40f0b78 | 243 | In addition to getting arguments from the command line, read |
c81f1a16 | 244 | them from standard input as well. This accepts commits and |
c40f0b78 PS |
245 | pseudo-options like `--all` and `--glob=`. When a `--` separator |
246 | is seen, the following input is treated as paths and used to | |
f97c8b1e PS |
247 | limit the result. Flags like `--not` which are read via standard input |
248 | are only respected for arguments passed in the same way and will not | |
249 | influence any subsequent command line arguments. | |
fdcf39e5 | 250 | |
8b3dce56 | 251 | ifdef::git-rev-list[] |
fdcf39e5 | 252 | --quiet:: |
fdcf39e5 MV |
253 | Don't print anything to standard output. This form |
254 | is primarily meant to allow the caller to | |
255 | test the exit status to see if a range of objects is fully | |
256 | connected (or not). It is faster than redirecting stdout | |
4528aa1a | 257 | to `/dev/null` as the output does not have to be formatted. |
16950f83 JK |
258 | |
259 | --disk-usage:: | |
9096451a | 260 | --disk-usage=human:: |
16950f83 JK |
261 | Suppress normal output; instead, print the sum of the bytes used |
262 | for on-disk storage by the selected commits or objects. This is | |
263 | equivalent to piping the output into `git cat-file | |
264 | --batch-check='%(objectsize:disk)'`, except that it runs much | |
265 | faster (especially with `--use-bitmap-index`). See the `CAVEATS` | |
266 | section in linkgit:git-cat-file[1] for the limitations of what | |
267 | "on-disk storage" means. | |
9096451a LL |
268 | With the optional value `human`, on-disk storage size is shown |
269 | in human-readable string(e.g. 12.24 Kib, 3.50 Mib). | |
adf60f14 | 270 | endif::git-rev-list[] |
fdcf39e5 | 271 | |
cb56e309 | 272 | --cherry-mark:: |
cb56e309 MG |
273 | Like `--cherry-pick` (see below) but mark equivalent commits |
274 | with `=` rather than omitting them, and inequivalent ones with `+`. | |
275 | ||
fdcf39e5 | 276 | --cherry-pick:: |
fdcf39e5 | 277 | Omit any commit that introduces the same change as |
4528aa1a | 278 | another commit on the ``other side'' when the set of |
fdcf39e5 MV |
279 | commits are limited with symmetric difference. |
280 | + | |
281 | For example, if you have two branches, `A` and `B`, a usual way | |
282 | to list all commits on only one side of them is with | |
3add01bb | 283 | `--left-right` (see the example below in the description of |
19d6eb41 JSJ |
284 | the `--left-right` option). However, it shows the commits that were |
285 | cherry-picked from the other branch (for example, ``3rd on b'' may be | |
286 | cherry-picked from branch A). With this option, such pairs of commits are | |
fdcf39e5 MV |
287 | excluded from the output. |
288 | ||
59c8afdf MG |
289 | --left-only:: |
290 | --right-only:: | |
27ac8371 | 291 | List only commits on the respective side of a symmetric difference, |
59c8afdf MG |
292 | i.e. only those which would be marked `<` resp. `>` by |
293 | `--left-right`. | |
294 | + | |
295 | For example, `--cherry-pick --right-only A...B` omits those | |
296 | commits from `B` which are in `A` or are patch-equivalent to a commit in | |
6cf378f0 | 297 | `A`. In other words, this lists the `+` commits from `git cherry A B`. |
59c8afdf MG |
298 | More precisely, `--cherry-pick --right-only --no-merges` gives the exact |
299 | list. | |
300 | ||
94f605ec | 301 | --cherry:: |
94f605ec MG |
302 | A synonym for `--right-only --cherry-mark --no-merges`; useful to |
303 | limit the output to the commits on our side and mark those that | |
304 | have been applied to the other side of a forked history with | |
305 | `git log --cherry upstream...mybranch`, similar to | |
306 | `git cherry upstream mybranch`. | |
307 | ||
3240240f SB |
308 | -g:: |
309 | --walk-reflogs:: | |
fdcf39e5 MV |
310 | Instead of walking the commit ancestry chain, walk |
311 | reflog entries from the most recent one to older ones. | |
312 | When this option is used you cannot specify commits to | |
313 | exclude (that is, '{caret}commit', 'commit1..commit2', | |
a58088ab | 314 | and 'commit1\...commit2' notations cannot be used). |
fdcf39e5 | 315 | + |
1f0fc1db | 316 | With `--pretty` format other than `oneline` and `reference` (for obvious reasons), |
fdcf39e5 | 317 | this causes the output to have two extra lines of information |
83c9f95c | 318 | taken from the reflog. The reflog designator in the output may be shown |
67471bc7 JNA |
319 | as `ref@{<Nth>}` (where _<Nth>_ is the reverse-chronological index in the |
320 | reflog) or as `ref@{<timestamp>}` (with the _<timestamp>_ for that entry), | |
83c9f95c JK |
321 | depending on a few rules: |
322 | + | |
323 | -- | |
67471bc7 | 324 | 1. If the starting point is specified as `ref@{<Nth>}`, show the index |
ba170517 | 325 | format. |
83c9f95c JK |
326 | + |
327 | 2. If the starting point was specified as `ref@{now}`, show the | |
ba170517 | 328 | timestamp format. |
83c9f95c JK |
329 | + |
330 | 3. If neither was used, but `--date` was given on the command line, show | |
ba170517 | 331 | the timestamp in the format requested by `--date`. |
83c9f95c JK |
332 | + |
333 | 4. Otherwise, show the index format. | |
334 | -- | |
335 | + | |
336 | Under `--pretty=oneline`, the commit message is | |
fdcf39e5 | 337 | prefixed with this information on the same line. |
4528aa1a | 338 | This option cannot be combined with `--reverse`. |
fdcf39e5 | 339 | See also linkgit:git-reflog[1]. |
1f0fc1db DL |
340 | + |
341 | Under `--pretty=reference`, this information will not be shown at all. | |
fdcf39e5 MV |
342 | |
343 | --merge:: | |
f3fc5d9c ML |
344 | Show commits touching conflicted paths in the range `HEAD...<other>`, |
345 | where `<other>` is the first existing pseudoref in `MERGE_HEAD`, | |
346 | `CHERRY_PICK_HEAD`, `REVERT_HEAD` or `REBASE_HEAD`. Only works | |
347 | when the index has unmerged entries. This option can be used to show | |
348 | relevant commits when resolving conflicts from a 3-way merge. | |
fdcf39e5 MV |
349 | |
350 | --boundary:: | |
e32db66d KB |
351 | Output excluded boundary commits. Boundary commits are |
352 | prefixed with `-`. | |
fdcf39e5 | 353 | |
aa32939f VM |
354 | ifdef::git-rev-list[] |
355 | --use-bitmap-index:: | |
356 | ||
357 | Try to speed up the traversal using the pack bitmap index (if | |
358 | one is available). Note that when traversing with `--objects`, | |
359 | trees and blobs will not have their associated path printed. | |
434ea3cd JK |
360 | |
361 | --progress=<header>:: | |
362 | Show progress reports on stderr as objects are considered. The | |
363 | `<header>` text will be printed with each progress update. | |
aa32939f VM |
364 | endif::git-rev-list[] |
365 | ||
70d9895e TR |
366 | History Simplification |
367 | ~~~~~~~~~~~~~~~~~~~~~~ | |
368 | ||
7bc2508b SB |
369 | Sometimes you are only interested in parts of the history, for example the |
370 | commits modifying a particular <path>. But there are two parts of | |
371 | 'History Simplification', one part is selecting the commits and the other | |
372 | is how to do it, as there are various strategies to simplify the history. | |
373 | ||
374 | The following options select the commits to be shown: | |
375 | ||
376 | <paths>:: | |
7bc2508b SB |
377 | Commits modifying the given <paths> are selected. |
378 | ||
379 | --simplify-by-decoration:: | |
7bc2508b SB |
380 | Commits that are referred by some branch or tag are selected. |
381 | ||
382 | Note that extra commits can be shown to give a meaningful history. | |
383 | ||
384 | The following options affect the way the simplification is performed: | |
385 | ||
386 | Default mode:: | |
7bc2508b SB |
387 | Simplifies the history to the simplest history explaining the |
388 | final state of the tree. Simplest because it prunes some side | |
389 | branches if the end result is the same (i.e. merging branches | |
390 | with the same content) | |
391 | ||
8d049e18 DS |
392 | --show-pulls:: |
393 | Include all commits from the default mode, but also any merge | |
394 | commits that are not TREESAME to the first parent but are | |
395 | TREESAME to a later parent. This mode is helpful for showing | |
396 | the merge commits that "first introduced" a change to a branch. | |
397 | ||
7bc2508b | 398 | --full-history:: |
df6b0cad | 399 | Same as the default mode, but does not prune some history. |
7bc2508b SB |
400 | |
401 | --dense:: | |
7bc2508b SB |
402 | Only the selected commits are shown, plus some to have a |
403 | meaningful history. | |
404 | ||
405 | --sparse:: | |
7bc2508b SB |
406 | All commits in the simplified history are shown. |
407 | ||
408 | --simplify-merges:: | |
4528aa1a | 409 | Additional option to `--full-history` to remove some needless |
7bc2508b SB |
410 | merges from the resulting history, as there are no selected |
411 | commits contributing to this merge. | |
412 | ||
257418c5 | 413 | --ancestry-path[=<commit>]:: |
57456ef4 | 414 | When given a range of commits to display (e.g. 'commit1..commit2' |
257418c5 EN |
415 | or 'commit2 {caret}commit1'), only display commits in that range |
416 | that are ancestors of <commit>, descendants of <commit>, or | |
417 | <commit> itself. If no commit is specified, use 'commit1' (the | |
418 | excluded part of the range) as <commit>. Can be passed multiple | |
419 | times; if so, a commit is included if it is any of the commits | |
420 | given or if it is an ancestor or descendant of one of them. | |
57456ef4 | 421 | |
7bc2508b | 422 | A more detailed explanation follows. |
70d9895e TR |
423 | |
424 | Suppose you specified `foo` as the <paths>. We shall call commits | |
425 | that modify `foo` !TREESAME, and the rest TREESAME. (In a diff | |
426 | filtered for `foo`, they look different and equal, respectively.) | |
427 | ||
428 | In the following, we will always refer to the same example history to | |
429 | illustrate the differences between simplification settings. We assume | |
430 | that you are filtering for a file `foo` in this commit graph: | |
431 | ----------------------------------------------------------------------- | |
143f1eaf KB |
432 | .-A---M---N---O---P---Q |
433 | / / / / / / | |
434 | I B C D E Y | |
435 | \ / / / / / | |
436 | `-------------' X | |
70d9895e | 437 | ----------------------------------------------------------------------- |
143f1eaf | 438 | The horizontal line of history A---Q is taken to be the first parent of |
70d9895e TR |
439 | each merge. The commits are: |
440 | ||
441 | * `I` is the initial commit, in which `foo` exists with contents | |
4528aa1a | 442 | ``asdf'', and a file `quux` exists with contents ``quux''. Initial |
70d9895e TR |
443 | commits are compared to an empty tree, so `I` is !TREESAME. |
444 | ||
4528aa1a | 445 | * In `A`, `foo` contains just ``foo''. |
70d9895e TR |
446 | |
447 | * `B` contains the same change as `A`. Its merge `M` is trivial and | |
448 | hence TREESAME to all parents. | |
449 | ||
4528aa1a | 450 | * `C` does not change `foo`, but its merge `N` changes it to ``foobar'', |
70d9895e TR |
451 | so it is not TREESAME to any parent. |
452 | ||
4528aa1a JSJ |
453 | * `D` sets `foo` to ``baz''. Its merge `O` combines the strings from |
454 | `N` and `D` to ``foobarbaz''; i.e., it is not TREESAME to any parent. | |
70d9895e | 455 | |
4528aa1a JSJ |
456 | * `E` changes `quux` to ``xyzzy'', and its merge `P` combines the |
457 | strings to ``quux xyzzy''. `P` is TREESAME to `O`, but not to `E`. | |
70d9895e | 458 | |
17b83d71 | 459 | * `X` is an independent root commit that added a new file `side`, and `Y` |
143f1eaf KB |
460 | modified it. `Y` is TREESAME to `X`. Its merge `Q` added `side` to `P`, and |
461 | `Q` is TREESAME to `P`, but not to `Y`. | |
462 | ||
4528aa1a JSJ |
463 | `rev-list` walks backwards through history, including or excluding |
464 | commits based on whether `--full-history` and/or parent rewriting | |
465 | (via `--parents` or `--children`) are used. The following settings | |
70d9895e TR |
466 | are available. |
467 | ||
468 | Default mode:: | |
70d9895e | 469 | Commits are included if they are not TREESAME to any parent |
4528aa1a | 470 | (though this can be changed, see `--sparse` below). If the |
70d9895e TR |
471 | commit was a merge, and it was TREESAME to one parent, follow |
472 | only that parent. (Even if there are several TREESAME | |
473 | parents, follow only one of them.) Otherwise, follow all | |
474 | parents. | |
475 | + | |
476 | This results in: | |
477 | + | |
478 | ----------------------------------------------------------------------- | |
479 | .-A---N---O | |
f70d0586 | 480 | / / / |
70d9895e TR |
481 | I---------D |
482 | ----------------------------------------------------------------------- | |
483 | + | |
484 | Note how the rule to only follow the TREESAME parent, if one is | |
485 | available, removed `B` from consideration entirely. `C` was | |
486 | considered via `N`, but is TREESAME. Root commits are compared to an | |
487 | empty tree, so `I` is !TREESAME. | |
488 | + | |
4528aa1a | 489 | Parent/child relations are only visible with `--parents`, but that does |
70d9895e TR |
490 | not affect the commits selected in default mode, so we have shown the |
491 | parent lines. | |
492 | ||
493 | --full-history without parent rewriting:: | |
70d9895e TR |
494 | This mode differs from the default in one point: always follow |
495 | all parents of a merge, even if it is TREESAME to one of them. | |
496 | Even if more than one side of the merge has commits that are | |
497 | included, this does not imply that the merge itself is! In | |
498 | the example, we get | |
499 | + | |
500 | ----------------------------------------------------------------------- | |
143f1eaf | 501 | I A B N D O P Q |
70d9895e TR |
502 | ----------------------------------------------------------------------- |
503 | + | |
d0af663e | 504 | `M` was excluded because it is TREESAME to both parents. `E`, |
70d9895e TR |
505 | `C` and `B` were all walked, but only `B` was !TREESAME, so the others |
506 | do not appear. | |
507 | + | |
508 | Note that without parent rewriting, it is not really possible to talk | |
509 | about the parent/child relationships between the commits, so we show | |
510 | them disconnected. | |
511 | ||
512 | --full-history with parent rewriting:: | |
70d9895e | 513 | Ordinary commits are only included if they are !TREESAME |
4528aa1a | 514 | (though this can be changed, see `--sparse` below). |
70d9895e TR |
515 | + |
516 | Merges are always included. However, their parent list is rewritten: | |
517 | Along each parent, prune away commits that are not included | |
518 | themselves. This results in | |
519 | + | |
520 | ----------------------------------------------------------------------- | |
143f1eaf | 521 | .-A---M---N---O---P---Q |
70d9895e TR |
522 | / / / / / |
523 | I B / D / | |
524 | \ / / / / | |
525 | `-------------' | |
526 | ----------------------------------------------------------------------- | |
527 | + | |
4528aa1a | 528 | Compare to `--full-history` without rewriting above. Note that `E` |
70d9895e TR |
529 | was pruned away because it is TREESAME, but the parent list of P was |
530 | rewritten to contain `E`'s parent `I`. The same happened for `C` and | |
143f1eaf | 531 | `N`, and `X`, `Y` and `Q`. |
70d9895e TR |
532 | |
533 | In addition to the above settings, you can change whether TREESAME | |
534 | affects inclusion: | |
535 | ||
3240240f | 536 | --dense:: |
70d9895e TR |
537 | Commits that are walked are included if they are not TREESAME |
538 | to any parent. | |
539 | ||
3240240f | 540 | --sparse:: |
70d9895e TR |
541 | All commits that are walked are included. |
542 | + | |
4528aa1a | 543 | Note that without `--full-history`, this still simplifies merges: if |
70d9895e TR |
544 | one of the parents is TREESAME, we follow only that one, so the other |
545 | sides of the merge are never walked. | |
fdcf39e5 | 546 | |
d266a988 | 547 | --simplify-merges:: |
d266a988 | 548 | First, build a history graph in the same way that |
4528aa1a | 549 | `--full-history` with parent rewriting does (see above). |
d266a988 TR |
550 | + |
551 | Then simplify each commit `C` to its replacement `C'` in the final | |
552 | history according to the following rules: | |
553 | + | |
554 | -- | |
555 | * Set `C'` to `C`. | |
556 | + | |
557 | * Replace each parent `P` of `C'` with its simplification `P'`. In | |
143f1eaf KB |
558 | the process, drop parents that are ancestors of other parents or that are |
559 | root commits TREESAME to an empty tree, and remove duplicates, but take care | |
560 | to never drop all parents that we are TREESAME to. | |
d266a988 TR |
561 | + |
562 | * If after this parent rewriting, `C'` is a root or merge commit (has | |
563 | zero or >1 parents), a boundary commit, or !TREESAME, it remains. | |
564 | Otherwise, it is replaced with its only parent. | |
565 | -- | |
566 | + | |
567 | The effect of this is best shown by way of comparing to | |
4528aa1a | 568 | `--full-history` with parent rewriting. The example turns into: |
d266a988 TR |
569 | + |
570 | ----------------------------------------------------------------------- | |
571 | .-A---M---N---O | |
572 | / / / | |
573 | I B D | |
574 | \ / / | |
575 | `---------' | |
576 | ----------------------------------------------------------------------- | |
577 | + | |
19d6eb41 | 578 | Note the major differences in `N`, `P`, and `Q` over `--full-history`: |
d266a988 TR |
579 | + |
580 | -- | |
581 | * `N`'s parent list had `I` removed, because it is an ancestor of the | |
582 | other parent `M`. Still, `N` remained because it is !TREESAME. | |
583 | + | |
584 | * `P`'s parent list similarly had `I` removed. `P` was then | |
585 | removed completely, because it had one parent and is TREESAME. | |
143f1eaf KB |
586 | + |
587 | * `Q`'s parent list had `Y` simplified to `X`. `X` was then removed, because it | |
588 | was a TREESAME root. `Q` was then removed completely, because it had one | |
589 | parent and is TREESAME. | |
d266a988 | 590 | -- |
fdcf39e5 | 591 | |
8d049e18 | 592 | There is another simplification mode available: |
57456ef4 | 593 | |
257418c5 EN |
594 | --ancestry-path[=<commit>]:: |
595 | Limit the displayed commits to those which are an ancestor of | |
596 | <commit>, or which are a descendant of <commit>, or are <commit> | |
597 | itself. | |
57456ef4 JH |
598 | + |
599 | As an example use case, consider the following commit history: | |
600 | + | |
601 | ----------------------------------------------------------------------- | |
602 | D---E-------F | |
603 | / \ \ | |
604 | B---C---G---H---I---J | |
605 | / \ | |
606 | A-------K---------------L--M | |
607 | ----------------------------------------------------------------------- | |
608 | + | |
609 | A regular 'D..M' computes the set of commits that are ancestors of `M`, | |
610 | but excludes the ones that are ancestors of `D`. This is useful to see | |
611 | what happened to the history leading to `M` since `D`, in the sense | |
4528aa1a | 612 | that ``what does `M` have that did not exist in `D`''. The result in this |
57456ef4 JH |
613 | example would be all the commits, except `A` and `B` (and `D` itself, |
614 | of course). | |
615 | + | |
616 | When we want to find out what commits in `M` are contaminated with the | |
617 | bug introduced by `D` and need fixing, however, we might want to view | |
618 | only the subset of 'D..M' that are actually descendants of `D`, i.e. | |
4528aa1a | 619 | excluding `C` and `K`. This is exactly what the `--ancestry-path` |
57456ef4 JH |
620 | option does. Applied to the 'D..M' range, it results in: |
621 | + | |
622 | ----------------------------------------------------------------------- | |
623 | E-------F | |
624 | \ \ | |
625 | G---H---I---J | |
626 | \ | |
627 | L--M | |
628 | ----------------------------------------------------------------------- | |
257418c5 EN |
629 | + |
630 | We can also use `--ancestry-path=D` instead of `--ancestry-path` which | |
631 | means the same thing when applied to the 'D..M' range but is just more | |
632 | explicit. | |
633 | + | |
634 | If we instead are interested in a given topic within this range, and all | |
635 | commits affected by that topic, we may only want to view the subset of | |
636 | `D..M` which contain that topic in their ancestry path. So, using | |
637 | `--ancestry-path=H D..M` for example would result in: | |
638 | + | |
639 | ----------------------------------------------------------------------- | |
640 | E | |
641 | \ | |
642 | G---H---I---J | |
643 | \ | |
644 | L--M | |
645 | ----------------------------------------------------------------------- | |
646 | + | |
647 | Whereas `--ancestry-path=K D..M` would result in | |
648 | + | |
649 | ----------------------------------------------------------------------- | |
650 | K---------------L--M | |
651 | ----------------------------------------------------------------------- | |
57456ef4 | 652 | |
8d049e18 DS |
653 | Before discussing another option, `--show-pulls`, we need to |
654 | create a new example history. | |
32f7037a | 655 | |
8d049e18 DS |
656 | A common problem users face when looking at simplified history is that a |
657 | commit they know changed a file somehow does not appear in the file's | |
658 | simplified history. Let's demonstrate a new example and show how options | |
659 | such as `--full-history` and `--simplify-merges` works in that case: | |
32f7037a | 660 | |
8d049e18 DS |
661 | ----------------------------------------------------------------------- |
662 | .-A---M-----C--N---O---P | |
663 | / / \ \ \/ / / | |
664 | I B \ R-'`-Z' / | |
665 | \ / \/ / | |
666 | \ / /\ / | |
667 | `---X--' `---Y--' | |
668 | ----------------------------------------------------------------------- | |
32f7037a | 669 | |
8d049e18 DS |
670 | For this example, suppose `I` created `file.txt` which was modified by |
671 | `A`, `B`, and `X` in different ways. The single-parent commits `C`, `Z`, | |
672 | and `Y` do not change `file.txt`. The merge commit `M` was created by | |
673 | resolving the merge conflict to include both changes from `A` and `B` | |
674 | and hence is not TREESAME to either. The merge commit `R`, however, was | |
675 | created by ignoring the contents of `file.txt` at `M` and taking only | |
676 | the contents of `file.txt` at `X`. Hence, `R` is TREESAME to `X` but not | |
677 | `M`. Finally, the natural merge resolution to create `N` is to take the | |
678 | contents of `file.txt` at `R`, so `N` is TREESAME to `R` but not `C`. | |
679 | The merge commits `O` and `P` are TREESAME to their first parents, but | |
680 | not to their second parents, `Z` and `Y` respectively. | |
32f7037a | 681 | |
8d049e18 DS |
682 | When using the default mode, `N` and `R` both have a TREESAME parent, so |
683 | those edges are walked and the others are ignored. The resulting history | |
684 | graph is: | |
32f7037a | 685 | |
8d049e18 DS |
686 | ----------------------------------------------------------------------- |
687 | I---X | |
688 | ----------------------------------------------------------------------- | |
32f7037a | 689 | |
8d049e18 DS |
690 | When using `--full-history`, Git walks every edge. This will discover |
691 | the commits `A` and `B` and the merge `M`, but also will reveal the | |
692 | merge commits `O` and `P`. With parent rewriting, the resulting graph is: | |
32f7037a | 693 | |
8d049e18 DS |
694 | ----------------------------------------------------------------------- |
695 | .-A---M--------N---O---P | |
696 | / / \ \ \/ / / | |
697 | I B \ R-'`--' / | |
698 | \ / \/ / | |
699 | \ / /\ / | |
700 | `---X--' `------' | |
701 | ----------------------------------------------------------------------- | |
32f7037a | 702 | |
8d049e18 DS |
703 | Here, the merge commits `O` and `P` contribute extra noise, as they did |
704 | not actually contribute a change to `file.txt`. They only merged a topic | |
705 | that was based on an older version of `file.txt`. This is a common | |
706 | issue in repositories using a workflow where many contributors work in | |
11ea33ce | 707 | parallel and merge their topic branches along a single trunk: many |
8d049e18 | 708 | unrelated merges appear in the `--full-history` results. |
32f7037a | 709 | |
8d049e18 DS |
710 | When using the `--simplify-merges` option, the commits `O` and `P` |
711 | disappear from the results. This is because the rewritten second parents | |
712 | of `O` and `P` are reachable from their first parents. Those edges are | |
713 | removed and then the commits look like single-parent commits that are | |
714 | TREESAME to their parent. This also happens to the commit `N`, resulting | |
715 | in a history view as follows: | |
32f7037a | 716 | |
8d049e18 DS |
717 | ----------------------------------------------------------------------- |
718 | .-A---M--. | |
719 | / / \ | |
720 | I B R | |
721 | \ / / | |
722 | \ / / | |
723 | `---X--' | |
724 | ----------------------------------------------------------------------- | |
32f7037a | 725 | |
8d049e18 DS |
726 | In this view, we see all of the important single-parent changes from |
727 | `A`, `B`, and `X`. We also see the carefully-resolved merge `M` and the | |
728 | not-so-carefully-resolved merge `R`. This is usually enough information | |
729 | to determine why the commits `A` and `B` "disappeared" from history in | |
730 | the default view. However, there are a few issues with this approach. | |
32f7037a | 731 | |
8d049e18 DS |
732 | The first issue is performance. Unlike any previous option, the |
733 | `--simplify-merges` option requires walking the entire commit history | |
734 | before returning a single result. This can make the option difficult to | |
735 | use for very large repositories. | |
32f7037a | 736 | |
8d049e18 DS |
737 | The second issue is one of auditing. When many contributors are working |
738 | on the same repository, it is important which merge commits introduced | |
739 | a change into an important branch. The problematic merge `R` above is | |
740 | not likely to be the merge commit that was used to merge into an | |
741 | important branch. Instead, the merge `N` was used to merge `R` and `X` | |
742 | into the important branch. This commit may have information about why | |
743 | the change `X` came to override the changes from `A` and `B` in its | |
744 | commit message. | |
32f7037a MÅ |
745 | |
746 | --show-pulls:: | |
747 | In addition to the commits shown in the default history, show | |
748 | each merge commit that is not TREESAME to its first parent but | |
749 | is TREESAME to a later parent. | |
8d049e18 | 750 | + |
32f7037a | 751 | When a merge commit is included by `--show-pulls`, the merge is |
8d049e18 DS |
752 | treated as if it "pulled" the change from another branch. When using |
753 | `--show-pulls` on this example (and no other options) the resulting | |
754 | graph is: | |
755 | + | |
756 | ----------------------------------------------------------------------- | |
757 | I---X---R---N | |
758 | ----------------------------------------------------------------------- | |
759 | + | |
760 | Here, the merge commits `R` and `N` are included because they pulled | |
761 | the commits `X` and `R` into the base branch, respectively. These | |
762 | merges are the reason the commits `A` and `B` do not appear in the | |
763 | default history. | |
764 | + | |
765 | When `--show-pulls` is paired with `--simplify-merges`, the | |
766 | graph includes all of the necessary information: | |
767 | + | |
768 | ----------------------------------------------------------------------- | |
769 | .-A---M--. N | |
770 | / / \ / | |
771 | I B R | |
772 | \ / / | |
773 | \ / / | |
774 | `---X--' | |
775 | ----------------------------------------------------------------------- | |
776 | + | |
777 | Notice that since `M` is reachable from `R`, the edge from `N` to `M` | |
778 | was simplified away. However, `N` still appears in the history as an | |
779 | important commit because it "pulled" the change `R` into the main | |
780 | branch. | |
781 | ||
4528aa1a | 782 | The `--simplify-by-decoration` option allows you to view only the |
3fcfd662 NS |
783 | big picture of the topology of the history, by omitting commits |
784 | that are not referenced by tags. Commits are marked as !TREESAME | |
785 | (in other words, kept after history simplification rules described | |
786 | above) if (1) they are referenced by tags, or (2) they change the | |
787 | contents of the paths given on the command line. All other | |
788 | commits are marked as TREESAME (subject to be simplified away). | |
789 | ||
461caf3e | 790 | ifndef::git-shortlog[] |
fdcf39e5 | 791 | ifdef::git-rev-list[] |
70d9895e TR |
792 | Bisection Helpers |
793 | ~~~~~~~~~~~~~~~~~ | |
794 | ||
fdcf39e5 | 795 | --bisect:: |
4528aa1a JSJ |
796 | Limit output to the one commit object which is roughly halfway between |
797 | included and excluded commits. Note that the bad bisection ref | |
798 | `refs/bisect/bad` is added to the included commits (if it | |
799 | exists) and the good bisection refs `refs/bisect/good-*` are | |
800 | added to the excluded commits (if they exist). Thus, supposing there | |
801 | are no refs in `refs/bisect/`, if | |
802 | + | |
fdcf39e5 | 803 | ----------------------------------------------------------------------- |
6514aa36 | 804 | $ git rev-list --bisect foo ^bar ^baz |
fdcf39e5 | 805 | ----------------------------------------------------------------------- |
4528aa1a | 806 | + |
fdcf39e5 | 807 | outputs 'midpoint', the output of the two commands |
4528aa1a | 808 | + |
fdcf39e5 | 809 | ----------------------------------------------------------------------- |
6514aa36 CC |
810 | $ git rev-list foo ^midpoint |
811 | $ git rev-list midpoint ^bar ^baz | |
fdcf39e5 | 812 | ----------------------------------------------------------------------- |
4528aa1a | 813 | + |
fdcf39e5 MV |
814 | would be of roughly the same length. Finding the change which |
815 | introduces a regression is thus reduced to a binary search: repeatedly | |
816 | generate and test new 'midpoint's until the commit chain is of length | |
0fe305a5 | 817 | one. |
fdcf39e5 MV |
818 | |
819 | --bisect-vars:: | |
4528aa1a JSJ |
820 | This calculates the same as `--bisect`, except that refs in |
821 | `refs/bisect/` are not used, and except that this outputs | |
822 | text ready to be eval'ed by the shell. These lines will assign the | |
823 | name of the midpoint revision to the variable `bisect_rev`, and the | |
824 | expected number of commits to be tested after `bisect_rev` is tested | |
825 | to `bisect_nr`, the expected number of commits to be tested if | |
826 | `bisect_rev` turns out to be good to `bisect_good`, the expected | |
827 | number of commits to be tested if `bisect_rev` turns out to be bad to | |
828 | `bisect_bad`, and the number of commits we are bisecting right now to | |
829 | `bisect_all`. | |
fdcf39e5 MV |
830 | |
831 | --bisect-all:: | |
4528aa1a JSJ |
832 | This outputs all the commit objects between the included and excluded |
833 | commits, ordered by their distance to the included and excluded | |
834 | commits. Refs in `refs/bisect/` are not used. The farthest | |
835 | from them is displayed first. (This is the only one displayed by | |
836 | `--bisect`.) | |
3d2d4f96 | 837 | + |
fdcf39e5 MV |
838 | This is useful because it makes it easy to choose a good commit to |
839 | test when you want to avoid to test some of them for some reason (they | |
840 | may not compile for example). | |
3d2d4f96 | 841 | + |
fdcf39e5 MV |
842 | This option can be used along with `--bisect-vars`, in this case, |
843 | after all the sorted commit objects, there will be the same text as if | |
844 | `--bisect-vars` had been used alone. | |
845 | endif::git-rev-list[] | |
461caf3e | 846 | endif::git-shortlog[] |
fdcf39e5 | 847 | |
461caf3e | 848 | ifndef::git-shortlog[] |
fdcf39e5 MV |
849 | Commit Ordering |
850 | ~~~~~~~~~~~~~~~ | |
851 | ||
852 | By default, the commits are shown in reverse chronological order. | |
853 | ||
3f0350cc JH |
854 | --date-order:: |
855 | Show no parents before all of its children are shown, but | |
856 | otherwise show commits in the commit timestamp order. | |
fdcf39e5 | 857 | |
81c6b38b JH |
858 | --author-date-order:: |
859 | Show no parents before all of its children are shown, but | |
860 | otherwise show commits in the author timestamp order. | |
861 | ||
3f0350cc JH |
862 | --topo-order:: |
863 | Show no parents before all of its children are shown, and | |
864 | avoid showing commits on multiple lines of history | |
865 | intermixed. | |
866 | + | |
867 | For example, in a commit history like this: | |
868 | + | |
869 | ---------------------------------------------------------------- | |
fdcf39e5 | 870 | |
3f0350cc JH |
871 | ---1----2----4----7 |
872 | \ \ | |
873 | 3----5----6----8--- | |
fdcf39e5 | 874 | |
3f0350cc JH |
875 | ---------------------------------------------------------------- |
876 | + | |
877 | where the numbers denote the order of commit timestamps, `git | |
878 | rev-list` and friends with `--date-order` show the commits in the | |
879 | timestamp order: 8 7 6 5 4 3 2 1. | |
880 | + | |
881 | With `--topo-order`, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5 | |
882 | 3 1); some older commits are shown before newer ones in order to | |
883 | avoid showing the commits from two parallel development track mixed | |
884 | together. | |
fdcf39e5 MV |
885 | |
886 | --reverse:: | |
04be6947 PB |
887 | Output the commits chosen to be shown (see Commit Limiting |
888 | section above) in reverse order. Cannot be combined with | |
889 | `--walk-reflogs`. | |
461caf3e | 890 | endif::git-shortlog[] |
fdcf39e5 | 891 | |
461caf3e | 892 | ifndef::git-shortlog[] |
fdcf39e5 MV |
893 | Object Traversal |
894 | ~~~~~~~~~~~~~~~~ | |
895 | ||
2de9b711 | 896 | These options are mostly targeted for packing of Git repositories. |
fdcf39e5 | 897 | |
3cab02de | 898 | ifdef::git-rev-list[] |
fdcf39e5 | 899 | --objects:: |
fdcf39e5 | 900 | Print the object IDs of any object referenced by the listed |
4528aa1a | 901 | commits. `--objects foo ^bar` thus means ``send me |
fdcf39e5 | 902 | all object IDs which I need to download if I have the commit |
15364d2a | 903 | object _bar_ but not _foo_''. See also `--object-names` below. |
fdcf39e5 | 904 | |
ce5b6f9b SB |
905 | --in-commit-order:: |
906 | Print tree and blob ids in order of the commits. The tree | |
907 | and blob ids are printed after they are first referenced | |
908 | by a commit. | |
909 | ||
fdcf39e5 | 910 | --objects-edge:: |
4528aa1a JSJ |
911 | Similar to `--objects`, but also print the IDs of excluded |
912 | commits prefixed with a ``-'' character. This is used by | |
8297643f | 913 | linkgit:git-pack-objects[1] to build a ``thin'' pack, which records |
fdcf39e5 MV |
914 | objects in deltified form based on objects contained in these |
915 | excluded commits to reduce network traffic. | |
916 | ||
1684c1b2 | 917 | --objects-edge-aggressive:: |
918 | Similar to `--objects-edge`, but it tries harder to find excluded | |
2dacf26d | 919 | commits at the cost of increased time. This is used instead of |
920 | `--objects-edge` to build ``thin'' packs for shallow repositories. | |
1684c1b2 | 921 | |
3cab02de JH |
922 | --indexed-objects:: |
923 | Pretend as if all trees and blobs used by the index are listed | |
924 | on the command line. Note that you probably want to use | |
925 | `--objects`, too. | |
926 | ||
fdcf39e5 | 927 | --unpacked:: |
4528aa1a | 928 | Only useful with `--objects`; print the object IDs that are not |
fdcf39e5 | 929 | in packs. |
caf3827e | 930 | |
42357b4e ES |
931 | --object-names:: |
932 | Only useful with `--objects`; print the names of the object IDs | |
15364d2a JK |
933 | that are found. This is the default behavior. Note that the |
934 | "name" of each object is ambiguous, and mostly intended as a | |
935 | hint for packing objects. In particular: no distinction is made between | |
936 | the names of tags, trees, and blobs; path names may be modified | |
937 | to remove newlines; and if an object would appear multiple times | |
938 | with different names, only one name is shown. | |
42357b4e ES |
939 | |
940 | --no-object-names:: | |
941 | Only useful with `--objects`; does not print the names of the object | |
942 | IDs that are found. This inverts `--object-names`. This flag allows | |
943 | the output to be more easily parsed by commands such as | |
944 | linkgit:git-cat-file[1]. | |
945 | ||
caf3827e JH |
946 | --filter=<filter-spec>:: |
947 | Only useful with one of the `--objects*`; omits objects (usually | |
948 | blobs) from the list of printed objects. The '<filter-spec>' | |
949 | may be one of the following: | |
950 | + | |
951 | The form '--filter=blob:none' omits all blobs. | |
952 | + | |
8f50984c NE |
953 | The form '--filter=blob:limit=<n>[kmg]' omits blobs of size at least n |
954 | bytes or units. n may be zero. The suffixes k, m, and g can be used | |
955 | to name units in KiB, MiB, or GiB. For example, 'blob:limit=1k' | |
956 | is the same as 'blob:limit=1024'. | |
caf3827e | 957 | + |
b0c42a53 PS |
958 | The form '--filter=object:type=(tag|commit|tree|blob)' omits all objects |
959 | which are not of the requested type. | |
960 | + | |
f4371a88 JH |
961 | The form '--filter=sparse:oid=<blob-ish>' uses a sparse-checkout |
962 | specification contained in the blob (or blob-expression) '<blob-ish>' | |
b1d87fba | 963 | to omit blobs that would not be required for a sparse checkout on |
f4371a88 | 964 | the requested refs. |
caf3827e | 965 | + |
bc5975d2 MD |
966 | The form '--filter=tree:<depth>' omits all blobs and trees whose depth |
967 | from the root tree is >= <depth> (minimum depth if an object is located | |
c813a7c3 MD |
968 | at multiple depths in the commits traversed). <depth>=0 will not include |
969 | any trees or blobs unless included explicitly in the command-line (or | |
970 | standard input when --stdin is used). <depth>=1 will include only the | |
971 | tree and blobs which are referenced directly by a commit reachable from | |
972 | <commit> or an explicitly-given object. <depth>=2 is like <depth>=1 | |
973 | while also including trees and blobs one more level removed from an | |
974 | explicitly-given commit or tree. | |
e693237e CC |
975 | + |
976 | Note that the form '--filter=sparse:path=<path>' that wants to read | |
977 | from an arbitrary path on the filesystem has been dropped for security | |
978 | reasons. | |
489fc9ee MD |
979 | + |
980 | Multiple '--filter=' flags can be specified to combine filters. Only | |
981 | objects which are accepted by every filter are included. | |
982 | + | |
983 | The form '--filter=combine:<filter1>+<filter2>+...<filterN>' can also be | |
984 | used to combined several filters, but this is harder than just repeating | |
985 | the '--filter' flag and is usually not necessary. Filters are joined by | |
986 | '{plus}' and individual filters are %-encoded (i.e. URL-encoded). | |
987 | Besides the '{plus}' and '%' characters, the following characters are | |
988 | reserved and also must be encoded: `~!@#$^&*()[]{}\;",<>?`+'`+ | |
989 | as well as all characters with ASCII code <= `0x20`, which includes | |
990 | space and newline. | |
991 | + | |
992 | Other arbitrary characters can also be encoded. For instance, | |
993 | 'combine:tree:3+blob:none' and 'combine:tree%3A3+blob%3Anone' are | |
994 | equivalent. | |
caf3827e | 995 | |
f4371a88 JH |
996 | --no-filter:: |
997 | Turn off any previous `--filter=` argument. | |
998 | ||
9cf68b27 PS |
999 | --filter-provided-objects:: |
1000 | Filter the list of explicitly provided objects, which would otherwise | |
1001 | always be printed even if they did not match any of the filters. Only | |
1002 | useful with `--filter=`. | |
1003 | ||
caf3827e JH |
1004 | --filter-print-omitted:: |
1005 | Only useful with `--filter=`; prints a list of the objects omitted | |
8d75a1d1 | 1006 | by the filter. Object IDs are prefixed with a ``~'' character. |
caf3827e JH |
1007 | |
1008 | --missing=<missing-action>:: | |
1009 | A debug option to help with future "partial clone" development. | |
1010 | This option specifies how missing objects are handled. | |
1011 | + | |
1012 | The form '--missing=error' requests that rev-list stop with an error if | |
1013 | a missing object is encountered. This is the default action. | |
1014 | + | |
1015 | The form '--missing=allow-any' will allow object traversal to continue | |
1016 | if a missing object is encountered. Missing objects will silently be | |
1017 | omitted from the results. | |
1018 | + | |
df11e196 JT |
1019 | The form '--missing=allow-promisor' is like 'allow-any', but will only |
1020 | allow object traversal to continue for EXPECTED promisor missing objects. | |
1021 | Unexpected missing objects will raise an error. | |
1022 | + | |
caf3827e JH |
1023 | The form '--missing=print' is like 'allow-any', but will also print a |
1024 | list of the missing objects. Object IDs are prefixed with a ``?'' character. | |
7b644c8c CC |
1025 | + |
1026 | If some tips passed to the traversal are missing, they will be | |
1027 | considered as missing too, and the traversal will ignore them. In case | |
1028 | we cannot get their Object ID though, an error will be raised. | |
fdcf39e5 | 1029 | |
df11e196 JT |
1030 | --exclude-promisor-objects:: |
1031 | (For internal use only.) Prefilter object traversal at | |
1032 | promisor boundary. This is used with partial clone. This is | |
1033 | stronger than `--missing=allow-promisor` because it limits the | |
1034 | traversal, rather than just silencing errors about missing | |
1035 | objects. | |
368a8912 | 1036 | endif::git-rev-list[] |
df11e196 | 1037 | |
ca92e59e | 1038 | --no-walk[=(sorted|unsorted)]:: |
ca92e59e MZ |
1039 | Only show the given commits, but do not traverse their ancestors. |
1040 | This has no effect if a range is specified. If the argument | |
19d6eb41 | 1041 | `unsorted` is given, the commits are shown in the order they were |
4528aa1a | 1042 | given on the command line. Otherwise (if `sorted` or no argument |
19d6eb41 | 1043 | was given), the commits are shown in reverse chronological order |
ca92e59e | 1044 | by commit time. |
a7df4f52 | 1045 | Cannot be combined with `--graph`. |
fdcf39e5 MV |
1046 | |
1047 | --do-walk:: | |
4528aa1a | 1048 | Overrides a previous `--no-walk`. |
461caf3e | 1049 | endif::git-shortlog[] |
f98fd436 | 1050 | |
461caf3e | 1051 | ifndef::git-shortlog[] |
f98fd436 MG |
1052 | Commit Formatting |
1053 | ~~~~~~~~~~~~~~~~~ | |
1054 | ||
1055 | ifdef::git-rev-list[] | |
1056 | Using these options, linkgit:git-rev-list[1] will act similar to the | |
1057 | more specialized family of commit log tools: linkgit:git-log[1], | |
1058 | linkgit:git-show[1], and linkgit:git-whatchanged[1] | |
1059 | endif::git-rev-list[] | |
1060 | ||
1061 | include::pretty-options.txt[] | |
1062 | ||
1063 | --relative-date:: | |
f98fd436 MG |
1064 | Synonym for `--date=relative`. |
1065 | ||
4b1c5e1d | 1066 | --date=<format>:: |
f98fd436 | 1067 | Only takes effect for dates shown in human-readable format, such |
4528aa1a | 1068 | as when using `--pretty`. `log.date` config variable sets a default |
add00ba2 JK |
1069 | value for the log command's `--date` option. By default, dates |
1070 | are shown in the original time zone (either committer's or | |
1071 | author's). If `-local` is appended to the format (e.g., | |
1072 | `iso-local`), the user's local time zone is used instead. | |
f98fd436 | 1073 | + |
39a869b2 | 1074 | -- |
f98fd436 | 1075 | `--date=relative` shows dates relative to the current time, |
1a2a1e8e JK |
1076 | e.g. ``2 hours ago''. The `-local` option has no effect for |
1077 | `--date=relative`. | |
39a869b2 | 1078 | |
add00ba2 | 1079 | `--date=local` is an alias for `--date=default-local`. |
39a869b2 | 1080 | |
466fb674 BB |
1081 | `--date=iso` (or `--date=iso8601`) shows timestamps in a ISO 8601-like format. |
1082 | The differences to the strict ISO 8601 format are: | |
1083 | ||
1084 | - a space instead of the `T` date/time delimiter | |
1085 | - a space between time and time zone | |
1086 | - no colon between hours and minutes of the time zone | |
1087 | ||
466fb674 BB |
1088 | `--date=iso-strict` (or `--date=iso8601-strict`) shows timestamps in strict |
1089 | ISO 8601 format. | |
39a869b2 | 1090 | |
f98fd436 | 1091 | `--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822 |
19d6eb41 | 1092 | format, often found in email messages. |
39a869b2 | 1093 | |
19d6eb41 | 1094 | `--date=short` shows only the date, but not the time, in `YYYY-MM-DD` format. |
39a869b2 | 1095 | |
442f6fd3 JH |
1096 | `--date=raw` shows the date as seconds since the epoch (1970-01-01 |
1097 | 00:00:00 UTC), followed by a space, and then the timezone as an offset | |
1098 | from UTC (a `+` or `-` with four digits; the first two are hours, and | |
1099 | the second two are minutes). I.e., as if the timestamp were formatted | |
1100 | with `strftime("%s %z")`). | |
1a2a1e8e JK |
1101 | Note that the `-local` option does not affect the seconds-since-epoch |
1102 | value (which is always measured in UTC), but does switch the accompanying | |
1103 | timezone value. | |
39a869b2 | 1104 | |
038a8788 SS |
1105 | `--date=human` shows the timezone if the timezone does not match the |
1106 | current time-zone, and doesn't print the whole date if that matches | |
1107 | (ie skip printing year for dates that are "this year", but also skip | |
1108 | the whole date itself if it's in the last few days and we can just say | |
1109 | what weekday it was). For older dates the hour and minute is also | |
1110 | omitted. | |
39a869b2 | 1111 | |
642833db JK |
1112 | `--date=unix` shows the date as a Unix epoch timestamp (seconds since |
1113 | 1970). As with `--raw`, this is always in UTC and therefore `-local` | |
1114 | has no effect. | |
39a869b2 | 1115 | |
c3fbf81a | 1116 | `--date=format:...` feeds the format `...` to your system `strftime`, |
9b591b94 | 1117 | except for %s, %z, and %Z, which are handled internally. |
aa1462cc JK |
1118 | Use `--date=format:%c` to show the date in your system locale's |
1119 | preferred format. See the `strftime` manual for a complete list of | |
add00ba2 JK |
1120 | format placeholders. When using `-local`, the correct syntax is |
1121 | `--date=format-local:...`. | |
39a869b2 | 1122 | |
9deef088 JH |
1123 | `--date=default` is the default format, and is based on ctime(3) |
1124 | output. It shows a single line with three-letter day of the week, | |
1125 | three-letter month, day-of-month, hour-minute-seconds in "HH:MM:SS" | |
1126 | format, followed by 4-digit year, plus timezone information, unless | |
1127 | the local time zone is used, e.g. `Thu Jan 1 00:00:00 1970 +0000`. | |
39a869b2 | 1128 | -- |
f98fd436 MG |
1129 | |
1130 | ifdef::git-rev-list[] | |
1131 | --header:: | |
f98fd436 MG |
1132 | Print the contents of the commit in raw-format; each record is |
1133 | separated with a NUL character. | |
d1c5ae78 | 1134 | |
1135 | --no-commit-header:: | |
1136 | Suppress the header line containing "commit" and the object ID printed before | |
1137 | the specified format. This has no effect on the built-in formats; only custom | |
1138 | formats are affected. | |
1139 | ||
1140 | --commit-header:: | |
1141 | Overrides a previous `--no-commit-header`. | |
f98fd436 MG |
1142 | endif::git-rev-list[] |
1143 | ||
1144 | --parents:: | |
f98fd436 | 1145 | Print also the parents of the commit (in the form "commit parent..."). |
4f851dc8 | 1146 | Also enables parent rewriting, see 'History Simplification' above. |
f98fd436 MG |
1147 | |
1148 | --children:: | |
f98fd436 | 1149 | Print also the children of the commit (in the form "commit child..."). |
4f851dc8 | 1150 | Also enables parent rewriting, see 'History Simplification' above. |
f98fd436 MG |
1151 | |
1152 | ifdef::git-rev-list[] | |
1153 | --timestamp:: | |
1154 | Print the raw commit timestamp. | |
1155 | endif::git-rev-list[] | |
1156 | ||
1157 | --left-right:: | |
27ac8371 | 1158 | Mark which side of a symmetric difference a commit is reachable from. |
f98fd436 MG |
1159 | Commits from the left side are prefixed with `<` and those from |
1160 | the right with `>`. If combined with `--boundary`, those | |
1161 | commits are prefixed with `-`. | |
1162 | + | |
1163 | For example, if you have this topology: | |
1164 | + | |
1165 | ----------------------------------------------------------------------- | |
1166 | y---b---b branch B | |
1167 | / \ / | |
1168 | / . | |
1169 | / / \ | |
1170 | o---x---a---a branch A | |
1171 | ----------------------------------------------------------------------- | |
1172 | + | |
1173 | you would get an output like this: | |
1174 | + | |
1175 | ----------------------------------------------------------------------- | |
1176 | $ git rev-list --left-right --boundary --pretty=oneline A...B | |
1177 | ||
1178 | >bbbbbbb... 3rd on b | |
1179 | >bbbbbbb... 2nd on b | |
1180 | <aaaaaaa... 3rd on a | |
1181 | <aaaaaaa... 2nd on a | |
1182 | -yyyyyyy... 1st on b | |
1183 | -xxxxxxx... 1st on a | |
1184 | ----------------------------------------------------------------------- | |
1185 | ||
1186 | --graph:: | |
f98fd436 MG |
1187 | Draw a text-based graphical representation of the commit history |
1188 | on the left hand side of the output. This may cause extra lines | |
1189 | to be printed in between commits, in order for the graph history | |
1190 | to be drawn properly. | |
695985f4 | 1191 | Cannot be combined with `--no-walk`. |
f98fd436 | 1192 | + |
4f851dc8 | 1193 | This enables parent rewriting, see 'History Simplification' above. |
f98fd436 | 1194 | + |
4528aa1a JSJ |
1195 | This implies the `--topo-order` option by default, but the |
1196 | `--date-order` option may also be specified. | |
f98fd436 | 1197 | |
1b32dece NTND |
1198 | --show-linear-break[=<barrier>]:: |
1199 | When --graph is not used, all history branches are flattened | |
1200 | which can make it hard to see that the two consecutive commits | |
1201 | do not belong to a linear branch. This option puts a barrier | |
1202 | in between them in that case. If `<barrier>` is specified, it | |
1203 | is the string that will be shown instead of the default one. | |
1204 | ||
f98fd436 MG |
1205 | ifdef::git-rev-list[] |
1206 | --count:: | |
1207 | Print a number stating how many commits would have been | |
1208 | listed, and suppress all other output. When used together | |
4528aa1a | 1209 | with `--left-right`, instead print the counts for left and |
b388e14b | 1210 | right commits, separated by a tab. When used together with |
4528aa1a | 1211 | `--cherry-mark`, omit patch equivalent commits from these |
b388e14b MG |
1212 | counts and print the count for equivalent commits separated |
1213 | by a tab. | |
f98fd436 | 1214 | endif::git-rev-list[] |
461caf3e | 1215 | endif::git-shortlog[] |