]>
Commit | Line | Data |
---|---|---|
2cf565c5 DG |
1 | git-rev-list(1) |
2 | =============== | |
2cf565c5 DG |
3 | |
4 | NAME | |
5 | ---- | |
6 | git-rev-list - Lists commit objects in reverse chronological order | |
7 | ||
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
353ce815 | 11 | [verse] |
69e0c256 | 12 | 'git-rev-list' [ \--max-count=number ] |
d5db6c9e | 13 | [ \--skip=number ] |
353ce815 JF |
14 | [ \--max-age=timestamp ] |
15 | [ \--min-age=timestamp ] | |
16 | [ \--sparse ] | |
17 | [ \--no-merges ] | |
25db465a | 18 | [ \--first-parent ] |
93b74bca | 19 | [ \--remove-empty ] |
29a6c3f8 | 20 | [ \--full-history ] |
0d2c9d67 | 21 | [ \--not ] |
353ce815 | 22 | [ \--all ] |
42cabc34 | 23 | [ \--stdin ] |
27350891 | 24 | [ \--quiet ] |
765ac8ec | 25 | [ \--topo-order ] |
353ce815 | 26 | [ \--parents ] |
e3c1500f | 27 | [ \--timestamp ] |
b24bace5 | 28 | [ \--left-right ] |
55a643ed | 29 | [ \--cherry-pick ] |
7cbcf4d5 | 30 | [ \--encoding[=<encoding>] ] |
bd95fcd3 | 31 | [ \--(author|committer|grep)=<pattern> ] |
e5633cbb JH |
32 | [ \--regexp-ignore-case | \-i ] |
33 | [ \--extended-regexp | \-E ] | |
1701872f | 34 | [ \--date={local|relative|default|iso|rfc|short} ] |
ec579767 | 35 | [ [\--objects | \--objects-edge] [ \--unpacked ] ] |
353ce815 JF |
36 | [ \--pretty | \--header ] |
37 | [ \--bisect ] | |
457f08a0 | 38 | [ \--bisect-vars ] |
3ac9f612 | 39 | [ \--bisect-all ] |
d249b455 | 40 | [ \--merge ] |
9c5e66e9 | 41 | [ \--reverse ] |
4d12a471 | 42 | [ \--walk-reflogs ] |
8e64006e | 43 | [ \--no-walk ] [ \--do-walk ] |
353ce815 | 44 | <commit>... [ \-- <paths>... ] |
2cf565c5 DG |
45 | |
46 | DESCRIPTION | |
47 | ----------- | |
8c02eee2 | 48 | |
2cf565c5 | 49 | Lists commit objects in reverse chronological order starting at the |
adcd3512 | 50 | given commit(s), taking ancestry relationship into account. This is |
2cf565c5 DG |
51 | useful to produce human-readable log output. |
52 | ||
8c02eee2 JF |
53 | Commits which are stated with a preceding '{caret}' cause listing to |
54 | stop at that point. Their parents are implied. Thus the following | |
55 | command: | |
56 | ||
57 | ----------------------------------------------------------------------- | |
58 | $ git-rev-list foo bar ^baz | |
59 | ----------------------------------------------------------------------- | |
60 | ||
adcd3512 MU |
61 | means "list all the commits which are included in 'foo' and 'bar', but |
62 | not in 'baz'". | |
63 | ||
8c02eee2 JF |
64 | A special notation "'<commit1>'..'<commit2>'" can be used as a |
65 | short-hand for "{caret}'<commit1>' '<commit2>'". For example, either of | |
66 | the following may be used interchangeably: | |
69e0c256 | 67 | |
8c02eee2 JF |
68 | ----------------------------------------------------------------------- |
69 | $ git-rev-list origin..HEAD | |
70 | $ git-rev-list HEAD ^origin | |
71 | ----------------------------------------------------------------------- | |
72 | ||
73 | Another special notation is "'<commit1>'...'<commit2>'" which is useful | |
74 | for merges. The resulting set of commits is the symmetric difference | |
0d2c9d67 RS |
75 | between the two operands. The following two commands are equivalent: |
76 | ||
8c02eee2 JF |
77 | ----------------------------------------------------------------------- |
78 | $ git-rev-list A B --not $(git-merge-base --all A B) | |
79 | $ git-rev-list A...B | |
80 | ----------------------------------------------------------------------- | |
81 | ||
5162e697 | 82 | linkgit:git-rev-list[1] is a very essential git program, since it |
8c02eee2 JF |
83 | provides the ability to build and traverse commit ancestry graphs. For |
84 | this reason, it has a lot of different options that enables it to be | |
5162e697 DM |
85 | used by commands as different as linkgit:git-bisect[1] and |
86 | linkgit:git-repack[1]. | |
69e0c256 | 87 | |
df8baa42 JF |
88 | OPTIONS |
89 | ------- | |
8c02eee2 JF |
90 | |
91 | Commit Formatting | |
92 | ~~~~~~~~~~~~~~~~~ | |
93 | ||
5162e697 DM |
94 | Using these options, linkgit:git-rev-list[1] will act similar to the |
95 | more specialized family of commit log tools: linkgit:git-log[1], | |
96 | linkgit:git-show[1], and linkgit:git-whatchanged[1] | |
8c02eee2 | 97 | |
331b51d2 | 98 | include::pretty-options.txt[] |
8c02eee2 JF |
99 | |
100 | --relative-date:: | |
101 | ||
a7b02ccf JH |
102 | Synonym for `--date=relative`. |
103 | ||
1701872f | 104 | --date={relative,local,default,iso,rfc}:: |
a7b02ccf | 105 | |
8c02eee2 JF |
106 | Only takes effect for dates shown in human-readable format, such |
107 | as when using "--pretty". | |
a7b02ccf JH |
108 | + |
109 | `--date=relative` shows dates relative to the current time, | |
110 | e.g. "2 hours ago". | |
111 | + | |
112 | `--date=local` shows timestamps in user's local timezone. | |
113 | + | |
1701872f JH |
114 | `--date=iso` (or `--date=iso8601`) shows timestamps in ISO 8601 format. |
115 | + | |
116 | `--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822 | |
117 | format, often found in E-mail messages. | |
118 | + | |
02783075 | 119 | `--date=short` shows only date but not time, in `YYYY-MM-DD` format. |
1701872f | 120 | + |
a7b02ccf JH |
121 | `--date=default` shows timestamps in the original timezone |
122 | (either committer's or author's). | |
df8baa42 | 123 | |
69e0c256 | 124 | --header:: |
8c02eee2 JF |
125 | |
126 | Print the contents of the commit in raw-format; each record is | |
127 | separated with a NUL character. | |
69e0c256 | 128 | |
f443455a | 129 | --parents:: |
8c02eee2 | 130 | |
f443455a ML |
131 | Print the parents of the commit. |
132 | ||
e3c1500f JN |
133 | --timestamp:: |
134 | Print the raw commit timestamp. | |
135 | ||
b24bace5 BG |
136 | --left-right:: |
137 | ||
138 | Mark which side of a symmetric diff a commit is reachable from. | |
139 | Commits from the left side are prefixed with `<` and those from | |
140 | the right with `>`. If combined with `--boundary`, those | |
141 | commits are prefixed with `-`. | |
142 | + | |
143 | For example, if you have this topology: | |
144 | + | |
145 | ----------------------------------------------------------------------- | |
146 | y---b---b branch B | |
147 | / \ / | |
148 | / . | |
149 | / / \ | |
150 | o---x---a---a branch A | |
151 | ----------------------------------------------------------------------- | |
152 | + | |
153 | you would get an output line this: | |
154 | + | |
155 | ----------------------------------------------------------------------- | |
156 | $ git rev-list --left-right --boundary --pretty=oneline A...B | |
157 | ||
158 | >bbbbbbb... 3rd on b | |
159 | >bbbbbbb... 2nd on b | |
160 | <aaaaaaa... 3rd on a | |
161 | <aaaaaaa... 2nd on a | |
162 | -yyyyyyy... 1st on b | |
163 | -xxxxxxx... 1st on a | |
164 | ----------------------------------------------------------------------- | |
165 | ||
8c02eee2 JF |
166 | Diff Formatting |
167 | ~~~~~~~~~~~~~~~ | |
df8baa42 | 168 | |
8c02eee2 | 169 | Below are listed options that control the formatting of diff output. |
5162e697 DM |
170 | Some of them are specific to linkgit:git-rev-list[1], however other diff |
171 | options may be given. See linkgit:git-diff-files[1] for more options. | |
ec579767 | 172 | |
8c02eee2 JF |
173 | -c:: |
174 | ||
175 | This flag changes the way a merge commit is displayed. It shows | |
176 | the differences from each of the parents to the merge result | |
177 | simultaneously instead of showing pairwise diff between a parent | |
178 | and the result one at a time. Furthermore, it lists only files | |
179 | which were modified from all parents. | |
180 | ||
181 | --cc:: | |
182 | ||
183 | This flag implies the '-c' options and further compresses the | |
184 | patch output by omitting hunks that show differences from only | |
185 | one parent, or show the same change from all but one parent for | |
186 | an Octopus merge. | |
187 | ||
188 | -r:: | |
189 | ||
190 | Show recursive diffs. | |
191 | ||
192 | -t:: | |
193 | ||
194 | Show the tree objects in the diff output. This implies '-r'. | |
195 | ||
196 | Commit Limiting | |
197 | ~~~~~~~~~~~~~~~ | |
198 | ||
199 | Besides specifying a range of commits that should be listed using the | |
200 | special notations explained in the description, additional commit | |
201 | limiting may be applied. | |
202 | ||
203 | -- | |
204 | ||
205 | -n 'number', --max-count='number':: | |
69e0c256 | 206 | |
69e0c256 JH |
207 | Limit the number of commits output. |
208 | ||
d5db6c9e JH |
209 | --skip='number':: |
210 | ||
211 | Skip 'number' commits before starting to show the commit output. | |
212 | ||
8c02eee2 JF |
213 | --since='date', --after='date':: |
214 | ||
215 | Show commits more recent than a specific date. | |
216 | ||
217 | --until='date', --before='date':: | |
69e0c256 | 218 | |
8c02eee2 JF |
219 | Show commits older than a specific date. |
220 | ||
221 | --max-age='timestamp', --min-age='timestamp':: | |
222 | ||
223 | Limit the commits output to specified time range. | |
69e0c256 | 224 | |
bd95fcd3 JH |
225 | --author='pattern', --committer='pattern':: |
226 | ||
227 | Limit the commits output to ones with author/committer | |
a5c2d26a | 228 | header lines that match the specified pattern (regular expression). |
bd95fcd3 JH |
229 | |
230 | --grep='pattern':: | |
231 | ||
232 | Limit the commits output to ones with log message that | |
a5c2d26a | 233 | matches the specified pattern (regular expression). |
bd95fcd3 | 234 | |
e5633cbb | 235 | -i, --regexp-ignore-case:: |
93d496a5 PB |
236 | |
237 | Match the regexp limiting patterns without regard to letters case. | |
238 | ||
e5633cbb | 239 | -E, --extended-regexp:: |
93d496a5 PB |
240 | |
241 | Consider the limiting patterns to be extended regular expressions | |
242 | instead of the default basic regular expressions. | |
243 | ||
93b74bca | 244 | --remove-empty:: |
8c02eee2 | 245 | |
93b74bca JH |
246 | Stop when a given path disappears from the tree. |
247 | ||
29a6c3f8 JN |
248 | --full-history:: |
249 | ||
250 | Show also parts of history irrelevant to current state of a given | |
251 | path. This turns off history simplification, which removed merges | |
252 | which didn't change anything at all at some child. It will still actually | |
253 | simplify away merges that didn't change anything at all into either | |
254 | child. | |
255 | ||
f443455a | 256 | --no-merges:: |
8c02eee2 | 257 | |
f443455a ML |
258 | Do not print commits with more than one parent. |
259 | ||
25db465a JH |
260 | --first-parent:: |
261 | Follow only the first parent commit upon seeing a merge | |
262 | commit. This option can give a better overview when | |
263 | viewing the evolution of a particular topic branch, | |
264 | because merges into a topic branch tend to be only about | |
265 | adjusting to updated upstream from time to time, and | |
266 | this option allows you to ignore the individual commits | |
267 | brought in to your history by such a merge. | |
268 | ||
0d2c9d67 | 269 | --not:: |
8c02eee2 JF |
270 | |
271 | Reverses the meaning of the '{caret}' prefix (or lack thereof) | |
272 | for all following revision specifiers, up to the next '--not'. | |
0d2c9d67 | 273 | |
69e0c256 | 274 | --all:: |
69e0c256 | 275 | |
8c02eee2 JF |
276 | Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the |
277 | command line as '<commit>'. | |
69e0c256 | 278 | |
42cabc34 JH |
279 | --stdin:: |
280 | ||
281 | In addition to the '<commit>' listed on the command | |
282 | line, read them from the standard input. | |
55a643ed | 283 | |
27350891 SP |
284 | --quiet:: |
285 | ||
286 | Don't print anything to standard output. This form of | |
02ff6250 | 287 | git-rev-list is primarily meant to allow the caller to |
27350891 SP |
288 | test the exit status to see if a range of objects is fully |
289 | connected (or not). It is faster than redirecting stdout | |
290 | to /dev/null as the output does not have to be formatted. | |
291 | ||
55a643ed JH |
292 | --cherry-pick:: |
293 | ||
294 | Omit any commit that introduces the same change as | |
295 | another commit on the "other side" when the set of | |
296 | commits are limited with symmetric difference. | |
297 | + | |
298 | For example, if you have two branches, `A` and `B`, a usual way | |
299 | to list all commits on only one side of them is with | |
300 | `--left-right`, like the example above in the description of | |
301 | that option. It however shows the commits that were cherry-picked | |
302 | from the other branch (for example, "3rd on b" may be cherry-picked | |
303 | from branch A). With this option, such pairs of commits are | |
304 | excluded from the output. | |
42cabc34 | 305 | |
084ae0a7 | 306 | -g, --walk-reflogs:: |
911cedc9 JH |
307 | |
308 | Instead of walking the commit ancestry chain, walk | |
309 | reflog entries from the most recent one to older ones. | |
310 | When this option is used you cannot specify commits to | |
311 | exclude (that is, '{caret}commit', 'commit1..commit2', | |
312 | nor 'commit1...commit2' notations cannot be used). | |
313 | + | |
314 | With '\--pretty' format other than oneline (for obvious reasons), | |
315 | this causes the output to have two extra lines of information | |
967506bb | 316 | taken from the reflog. By default, 'commit@\{Nth}' notation is |
911cedc9 | 317 | used in the output. When the starting commit is specified as |
967506bb | 318 | 'commit@{now}', output also uses 'commit@\{timestamp}' notation |
4d12a471 JH |
319 | instead. Under '\--pretty=oneline', the commit message is |
320 | prefixed with this information on the same line. | |
620e729d QT |
321 | |
322 | Cannot be combined with '\--reverse'. | |
911cedc9 | 323 | |
d249b455 | 324 | --merge:: |
8c02eee2 | 325 | |
d249b455 UZ |
326 | After a failed merge, show refs that touch files having a |
327 | conflict and don't exist on all heads to merge. | |
328 | ||
8c02eee2 JF |
329 | --boundary:: |
330 | ||
331 | Output uninteresting commits at the boundary, which are usually | |
332 | not shown. | |
333 | ||
334 | --dense, --sparse:: | |
335 | ||
336 | When optional paths are given, the default behaviour ('--dense') is to | |
337 | only output commits that changes at least one of them, and also ignore | |
338 | merges that do not touch the given paths. | |
339 | ||
340 | Use the '--sparse' flag to makes the command output all eligible commits | |
341 | (still subject to count and age limitation), but apply merge | |
342 | simplification nevertheless. | |
343 | ||
344 | --bisect:: | |
345 | ||
346 | Limit output to the one commit object which is roughly halfway between | |
347 | the included and excluded commits. Thus, if | |
348 | ||
349 | ----------------------------------------------------------------------- | |
350 | $ git-rev-list --bisect foo ^bar ^baz | |
351 | ----------------------------------------------------------------------- | |
352 | ||
353 | outputs 'midpoint', the output of the two commands | |
354 | ||
355 | ----------------------------------------------------------------------- | |
356 | $ git-rev-list foo ^midpoint | |
357 | $ git-rev-list midpoint ^bar ^baz | |
358 | ----------------------------------------------------------------------- | |
359 | ||
360 | would be of roughly the same length. Finding the change which | |
361 | introduces a regression is thus reduced to a binary search: repeatedly | |
362 | generate and test new 'midpoint's until the commit chain is of length | |
363 | one. | |
364 | ||
457f08a0 JH |
365 | --bisect-vars:: |
366 | ||
367 | This calculates the same as `--bisect`, but outputs text ready | |
368 | to be eval'ed by the shell. These lines will assign the name of | |
369 | the midpoint revision to the variable `bisect_rev`, and the | |
370 | expected number of commits to be tested after `bisect_rev` is | |
371 | tested to `bisect_nr`, the expected number of commits to be | |
372 | tested if `bisect_rev` turns out to be good to `bisect_good`, | |
373 | the expected number of commits to be tested if `bisect_rev` | |
374 | turns out to be bad to `bisect_bad`, and the number of commits | |
375 | we are bisecting right now to `bisect_all`. | |
376 | ||
3ac9f612 CC |
377 | --bisect-all:: |
378 | ||
379 | This outputs all the commit objects between the included and excluded | |
380 | commits, ordered by their distance to the included and excluded | |
381 | commits. The farthest from them is displayed first. (This is the only | |
382 | one displayed by `--bisect`.) | |
383 | ||
384 | This is useful because it makes it easy to choose a good commit to | |
385 | test when you want to avoid to test some of them for some reason (they | |
386 | may not compile for example). | |
387 | ||
388 | This option can be used along with `--bisect-vars`, in this case, | |
389 | after all the sorted commit objects, there will be the same text as if | |
390 | `--bisect-vars` had been used alone. | |
391 | ||
8c02eee2 JF |
392 | -- |
393 | ||
394 | Commit Ordering | |
395 | ~~~~~~~~~~~~~~~ | |
396 | ||
397 | By default, the commits are shown in reverse chronological order. | |
398 | ||
399 | --topo-order:: | |
400 | ||
401 | This option makes them appear in topological order (i.e. | |
402 | descendant commits are shown before their parents). | |
403 | ||
404 | --date-order:: | |
405 | ||
406 | This option is similar to '--topo-order' in the sense that no | |
407 | parent comes before all of its children, but otherwise things | |
408 | are still ordered in the commit timestamp order. | |
409 | ||
9c5e66e9 JS |
410 | --reverse:: |
411 | ||
412 | Output the commits in reverse order. | |
620e729d | 413 | Cannot be combined with '\--walk-reflogs'. |
9c5e66e9 | 414 | |
8c02eee2 JF |
415 | Object Traversal |
416 | ~~~~~~~~~~~~~~~~ | |
417 | ||
418 | These options are mostly targeted for packing of git repositories. | |
419 | ||
420 | --objects:: | |
421 | ||
422 | Print the object IDs of any object referenced by the listed | |
423 | commits. 'git-rev-list --objects foo ^bar' thus means "send me | |
424 | all object IDs which I need to download if I have the commit | |
425 | object 'bar', but not 'foo'". | |
426 | ||
427 | --objects-edge:: | |
428 | ||
429 | Similar to '--objects', but also print the IDs of excluded | |
430 | commits prefixed with a "-" character. This is used by | |
5162e697 | 431 | linkgit:git-pack-objects[1] to build "thin" pack, which records |
8c02eee2 JF |
432 | objects in deltified form based on objects contained in these |
433 | excluded commits to reduce network traffic. | |
434 | ||
435 | --unpacked:: | |
436 | ||
437 | Only useful with '--objects'; print the object IDs that are not | |
438 | in packs. | |
3dfb9278 | 439 | |
8e64006e JS |
440 | --no-walk:: |
441 | ||
442 | Only show the given revs, but do not traverse their ancestors. | |
443 | ||
444 | --do-walk:: | |
445 | ||
446 | Overrides a previous --no-walk. | |
447 | ||
331b51d2 JN |
448 | |
449 | include::pretty-formats.txt[] | |
450 | ||
451 | ||
2cf565c5 DG |
452 | Author |
453 | ------ | |
454 | Written by Linus Torvalds <torvalds@osdl.org> | |
455 | ||
456 | Documentation | |
457 | -------------- | |
8c02eee2 JF |
458 | Documentation by David Greaves, Junio C Hamano, Jonas Fonseca |
459 | and the git-list <git@vger.kernel.org>. | |
2cf565c5 DG |
460 | |
461 | GIT | |
462 | --- | |
5162e697 | 463 | Part of the linkgit:git[7] suite |