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