Merge git://git.kernel.org/pub/scm/gitk/gitk
[git/git.git] / Documentation / git-rev-list.txt
CommitLineData
2cf565c5
DG
1git-rev-list(1)
2===============
2cf565c5
DG
3
4NAME
5----
6git-rev-list - Lists commit objects in reverse chronological order
7
8
9SYNOPSIS
10--------
353ce815 11[verse]
69e0c256 12'git-rev-list' [ \--max-count=number ]
353ce815
JF
13 [ \--max-age=timestamp ]
14 [ \--min-age=timestamp ]
15 [ \--sparse ]
16 [ \--no-merges ]
93b74bca 17 [ \--remove-empty ]
0d2c9d67 18 [ \--not ]
353ce815 19 [ \--all ]
765ac8ec 20 [ \--topo-order ]
353ce815 21 [ \--parents ]
ec579767 22 [ [\--objects | \--objects-edge] [ \--unpacked ] ]
353ce815
JF
23 [ \--pretty | \--header ]
24 [ \--bisect ]
d249b455 25 [ \--merge ]
353ce815 26 <commit>... [ \-- <paths>... ]
2cf565c5
DG
27
28DESCRIPTION
29-----------
30Lists commit objects in reverse chronological order starting at the
adcd3512 31given commit(s), taking ancestry relationship into account. This is
2cf565c5
DG
32useful to produce human-readable log output.
33
69e0c256
JH
34Commits which are stated with a preceding '{caret}' cause listing to stop at
35that point. Their parents are implied. "git-rev-list foo bar {caret}baz" thus
adcd3512
MU
36means "list all the commits which are included in 'foo' and 'bar', but
37not in 'baz'".
38
69e0c256
JH
39A special notation <commit1>..<commit2> can be used as a
40short-hand for {caret}<commit1> <commit2>.
41
0d2c9d67
RS
42Another special notation is <commit1>...<commit2> which is useful for
43merges. The resulting set of commits is the symmetric difference
44between the two operands. The following two commands are equivalent:
45
46------------
47$ git-rev-list A B --not $(git-merge-base --all A B)
48$ git-rev-list A...B
49------------
69e0c256 50
df8baa42
JF
51OPTIONS
52-------
53--pretty::
54 Print the contents of the commit changesets in human-readable form.
55
69e0c256
JH
56--header::
57 Print the contents of the commit in raw-format; each
58 record is separated with a NUL character.
59
f443455a
ML
60--parents::
61 Print the parents of the commit.
62
df8baa42
JF
63--objects::
64 Print the object IDs of any object referenced by the listed commits.
65 'git-rev-list --objects foo ^bar' thus means "send me all object IDs
66 which I need to download if I have the commit object 'bar', but
67 not 'foo'".
68
ec579767
JH
69--objects-edge::
70 Similar to `--objects`, but also print the IDs of
addf88e4 71 excluded commits prefixed with a `-` character. This is
ec579767
JH
72 used by `git-pack-objects` to build 'thin' pack, which
73 records objects in deltified form based on objects
74 contained in these excluded commits to reduce network
75 traffic.
76
69e0c256
JH
77--unpacked::
78 Only useful with `--objects`; print the object IDs that
79 are not in packs.
80
df8baa42
JF
81--bisect::
82 Limit output to the one commit object which is roughly halfway
83 between the included and excluded commits. Thus, if 'git-rev-list
afb4ff20
JH
84 --bisect foo {caret}bar {caret}baz' outputs 'midpoint', the output
85 of 'git-rev-list foo {caret}midpoint' and 'git-rev-list midpoint
86 {caret}bar {caret}baz' would be of roughly the same length.
87 Finding the change
df8baa42
JF
88 which introduces a regression is thus reduced to a binary search:
89 repeatedly generate and test new 'midpoint's until the commit chain
90 is of length one.
91
69e0c256
JH
92--max-count::
93 Limit the number of commits output.
94
95--max-age=timestamp, --min-age=timestamp::
96 Limit the commits output to specified time range.
97
98--sparse::
99 When optional paths are given, the command outputs only
64b1f6e6
JH
100 the commits that changes at least one of them, and also
101 ignores merges that do not touch the given paths. This
102 flag makes the command output all eligible commits
103 (still subject to count and age limitation), but apply
104 merge simplification nevertheless.
69e0c256 105
93b74bca
JH
106--remove-empty::
107 Stop when a given path disappears from the tree.
108
f443455a
ML
109--no-merges::
110 Do not print commits with more than one parent.
111
0d2c9d67
RS
112--not::
113 Reverses the meaning of the '{caret}' prefix (or lack
114 thereof) for all following revision specifiers, up to
115 the next `--not`.
116
69e0c256
JH
117--all::
118 Pretend as if all the refs in `$GIT_DIR/refs/` are
119 listed on the command line as <commit>.
120
121--topo-order::
122 By default, the commits are shown in reverse
123 chronological order. This option makes them appear in
124 topological order (i.e. descendant commits are shown
125 before their parents).
126
d249b455
UZ
127--merge::
128 After a failed merge, show refs that touch files having a
129 conflict and don't exist on all heads to merge.
130
3dfb9278
JF
131--relative-date::
132 Show dates relative to the current time, e.g. "2 hours ago".
133 Only takes effect for dates shown in human-readable format,
134 such as when using "--pretty".
135
2cf565c5
DG
136Author
137------
138Written by Linus Torvalds <torvalds@osdl.org>
139
140Documentation
141--------------
142Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
143
144GIT
145---
a7154e91 146Part of the gitlink:git[7] suite
2cf565c5 147