]>
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 | -------- | |
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 | |
24 | DESCRIPTION | |
25 | ----------- | |
26 | Lists commit objects in reverse chronological order starting at the | |
adcd3512 | 27 | given commit(s), taking ancestry relationship into account. This is |
2cf565c5 DG |
28 | useful to produce human-readable log output. |
29 | ||
69e0c256 JH |
30 | Commits which are stated with a preceding '{caret}' cause listing to stop at |
31 | that point. Their parents are implied. "git-rev-list foo bar {caret}baz" thus | |
adcd3512 MU |
32 | means "list all the commits which are included in 'foo' and 'bar', but |
33 | not in 'baz'". | |
34 | ||
69e0c256 JH |
35 | A special notation <commit1>..<commit2> can be used as a |
36 | short-hand for {caret}<commit1> <commit2>. | |
37 | ||
38 | ||
df8baa42 JF |
39 | OPTIONS |
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 |
98 | Maximal, linear epochs correspond to periods of sequential development. |
99 | Minimal, non-linear epochs correspond to periods of divergent development | |
100 | followed by a converging merge. The theory of epochs is described in more | |
101 | detail at | |
102 | link:http://blackcubes.dyndns.org/epoch/[http://blackcubes.dyndns.org/epoch/]. | |
df8baa42 | 103 | + |
17ebe977 PB |
104 | The merge order for a non-linear epoch is defined as a linearisation for which |
105 | the 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 |
113 | Invariant 1 states that later commits appear before earlier commits they are |
114 | derived from. | |
df8baa42 | 115 | + |
17ebe977 PB |
116 | Invariant 2 states that commits unique to "later" parents in a merge, appear |
117 | before 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 |
123 | Commits marked with (=) represent the boundaries of minimal, non-linear epochs |
124 | and correspond either to the start of a period of divergent development or to | |
125 | the end of such a period. | |
df8baa42 | 126 | + |
17ebe977 PB |
127 | Commits marked with (|) are direct parents of commits immediately preceding |
128 | the marked commit in the list. | |
df8baa42 | 129 | + |
17ebe977 PB |
130 | Commits marked with (^) are not parents of the immediately preceding commit. |
131 | These "breaks" represent necessary discontinuities implied by trying to | |
132 | represent an arbtirary 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 | |
137 | Author | |
138 | ------ | |
139 | Written by Linus Torvalds <torvalds@osdl.org> | |
140 | ||
a3437b8c JS |
141 | Original *--merge-order* logic by Jon Seymour <jon.seymour@gmail.com> |
142 | ||
2cf565c5 DG |
143 | Documentation |
144 | -------------- | |
145 | Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. | |
146 | ||
147 | GIT | |
148 | --- | |
a7154e91 | 149 | Part of the gitlink:git[7] suite |
2cf565c5 | 150 |