use GIT_DIR instead of /var/tmp
[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--------
69e0c256
JH
11'git-rev-list' [ \--max-count=number ]
12 [ \--max-age=timestamp ]
13 [ \--min-age=timestamp ]
14 [ \--sparse ]
15 [ \--no-merges ]
16 [ \--all ]
17 [ [ \--merge-order [ \--show-breaks ] ] | [ \--topo-order ] | ]
18 [ \--parents ]
19 [ \--objects [ \--unpacked ] ]
20 [ \--pretty | \--header | ]
21 [ \--bisect ]
22 <commit>... [ \-- <paths>... ]
2cf565c5
DG
23
24DESCRIPTION
25-----------
26Lists commit objects in reverse chronological order starting at the
adcd3512 27given commit(s), taking ancestry relationship into account. This is
2cf565c5
DG
28useful to produce human-readable log output.
29
69e0c256
JH
30Commits which are stated with a preceding '{caret}' cause listing to stop at
31that point. Their parents are implied. "git-rev-list foo bar {caret}baz" thus
adcd3512
MU
32means "list all the commits which are included in 'foo' and 'bar', but
33not in 'baz'".
34
69e0c256
JH
35A special notation <commit1>..<commit2> can be used as a
36short-hand for {caret}<commit1> <commit2>.
37
38
df8baa42
JF
39OPTIONS
40-------
41--pretty::
42 Print the contents of the commit changesets in human-readable form.
43
69e0c256
JH
44--header::
45 Print the contents of the commit in raw-format; each
46 record is separated with a NUL character.
47
df8baa42
JF
48--objects::
49 Print the object IDs of any object referenced by the listed commits.
50 'git-rev-list --objects foo ^bar' thus means "send me all object IDs
51 which I need to download if I have the commit object 'bar', but
52 not 'foo'".
53
69e0c256
JH
54--unpacked::
55 Only useful with `--objects`; print the object IDs that
56 are not in packs.
57
df8baa42
JF
58--bisect::
59 Limit output to the one commit object which is roughly halfway
60 between the included and excluded commits. Thus, if 'git-rev-list
61 --bisect foo ^bar ^baz' outputs 'midpoint', the output
62 of 'git-rev-list foo ^midpoint' and 'git-rev-list midpoint
63 ^bar ^baz' would be of roughly the same length. Finding the change
64 which introduces a regression is thus reduced to a binary search:
65 repeatedly generate and test new 'midpoint's until the commit chain
66 is of length one.
67
69e0c256
JH
68--max-count::
69 Limit the number of commits output.
70
71--max-age=timestamp, --min-age=timestamp::
72 Limit the commits output to specified time range.
73
74--sparse::
75 When optional paths are given, the command outputs only
64b1f6e6
JH
76 the commits that changes at least one of them, and also
77 ignores merges that do not touch the given paths. This
78 flag makes the command output all eligible commits
79 (still subject to count and age limitation), but apply
80 merge simplification nevertheless.
69e0c256
JH
81
82--all::
83 Pretend as if all the refs in `$GIT_DIR/refs/` are
84 listed on the command line as <commit>.
85
86--topo-order::
87 By default, the commits are shown in reverse
88 chronological order. This option makes them appear in
89 topological order (i.e. descendant commits are shown
90 before their parents).
91
df8baa42
JF
92--merge-order::
93 When specified the commit history is decomposed into a unique
94 sequence of minimal, non-linear epochs and maximal, linear epochs.
95 Non-linear epochs are then linearised by sorting them into merge
96 order, which is described below.
97+
17ebe977
PB
98Maximal, linear epochs correspond to periods of sequential development.
99Minimal, non-linear epochs correspond to periods of divergent development
100followed by a converging merge. The theory of epochs is described in more
101detail at
102link:http://blackcubes.dyndns.org/epoch/[http://blackcubes.dyndns.org/epoch/].
df8baa42 103+
17ebe977
PB
104The merge order for a non-linear epoch is defined as a linearisation for which
105the following invariants are true:
df8baa42 106+
17ebe977
PB
107 1. if a commit P is reachable from commit N, commit P sorts after commit N
108 in the linearised list.
109 2. if Pi and Pj are any two parents of a merge M (with i < j), then any
110 commit N, such that N is reachable from Pj but not reachable from Pi,
111 sorts before all commits reachable from Pi.
df8baa42 112+
17ebe977
PB
113Invariant 1 states that later commits appear before earlier commits they are
114derived from.
df8baa42 115+
17ebe977
PB
116Invariant 2 states that commits unique to "later" parents in a merge, appear
117before all commits from "earlier" parents of a merge.
118
df8baa42
JF
119--show-breaks::
120 Each item of the list is output with a 2-character prefix consisting
121 of one of: (|), (^), (=) followed by a space.
122+
17ebe977
PB
123Commits marked with (=) represent the boundaries of minimal, non-linear epochs
124and correspond either to the start of a period of divergent development or to
125the end of such a period.
df8baa42 126+
17ebe977
PB
127Commits marked with (|) are direct parents of commits immediately preceding
128the marked commit in the list.
df8baa42 129+
17ebe977
PB
130Commits marked with (^) are not parents of the immediately preceding commit.
131These "breaks" represent necessary discontinuities implied by trying to
89438677 132represent an arbitrary DAG in a linear form.
df8baa42 133+
69e0c256
JH
134`--show-breaks` is only valid if `--merge-order` is also specified.
135
2cf565c5
DG
136
137Author
138------
139Written by Linus Torvalds <torvalds@osdl.org>
140
a3437b8c
JS
141Original *--merge-order* logic by Jon Seymour <jon.seymour@gmail.com>
142
2cf565c5
DG
143Documentation
144--------------
145Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
146
147GIT
148---
a7154e91 149Part of the gitlink:git[7] suite
2cf565c5 150