Error message from get_sha1() on ambiguous short SHA1.
[git/git.git] / Documentation / git-rev-list.txt
CommitLineData
2cf565c5
DG
1git-rev-list(1)
2===============
3v0.1, May 2005
4
5NAME
6----
7git-rev-list - Lists commit objects in reverse chronological order
8
9
10SYNOPSIS
11--------
adcd3512 12'git-rev-list' [ *--max-count*=number ] [ *--max-age*=timestamp ] [ *--min-age*=timestamp ] [ *--bisect* ] [ *--pretty* ] [ *--objects* ] [ *--merge-order* [ *--show-breaks* ] ] <commit> [ <commit> ...] [ ^<commit> ...]
2cf565c5
DG
13
14DESCRIPTION
15-----------
16Lists commit objects in reverse chronological order starting at the
adcd3512 17given commit(s), taking ancestry relationship into account. This is
2cf565c5
DG
18useful to produce human-readable log output.
19
adcd3512
MU
20Commits which are stated with a preceding '^' cause listing to stop at
21that point. Their parents are implied. "git-rev-list foo bar ^baz" thus
22means "list all the commits which are included in 'foo' and 'bar', but
23not in 'baz'".
24
25If *--pretty* is specified, print the contents of the commit changesets
26in human-readable form.
27
28The *--objects* flag causes 'git-rev-list' to print the object IDs of
29any object referenced by the listed commits. 'git-rev-list --objects foo
30^bar' thus means "send me all object IDs which I need to download if
31I have the commit object 'bar', but not 'foo'".
32
33The *--bisect* flag limits output to the one commit object which is
34roughly halfway between the included and excluded commits. Thus,
ed0a8488
PH
35if 'git-rev-list --bisect foo ^bar
36^baz' outputs 'midpoint', the output
37of 'git-rev-list foo ^midpoint' and 'git-rev-list midpoint
38^bar
39^baz'
adcd3512
MU
40would be of roughly the same length. Finding the change which introduces
41a regression is thus reduced to a binary search: repeatedly generate and
42test new 'midpoint's until the commit chain is of length one.
43
17ebe977
PB
44If *--merge-order* is specified, the commit history is decomposed into a
45unique sequence of minimal, non-linear epochs and maximal, linear epochs.
46Non-linear epochs are then linearised by sorting them into merge order, which
a3437b8c
JS
47is described below.
48
17ebe977
PB
49Maximal, linear epochs correspond to periods of sequential development.
50Minimal, non-linear epochs correspond to periods of divergent development
51followed by a converging merge. The theory of epochs is described in more
52detail at
53link:http://blackcubes.dyndns.org/epoch/[http://blackcubes.dyndns.org/epoch/].
a3437b8c 54
17ebe977
PB
55The merge order for a non-linear epoch is defined as a linearisation for which
56the following invariants are true:
a3437b8c 57
17ebe977
PB
58 1. if a commit P is reachable from commit N, commit P sorts after commit N
59 in the linearised list.
60 2. if Pi and Pj are any two parents of a merge M (with i < j), then any
61 commit N, such that N is reachable from Pj but not reachable from Pi,
62 sorts before all commits reachable from Pi.
a3437b8c 63
17ebe977
PB
64Invariant 1 states that later commits appear before earlier commits they are
65derived from.
a3437b8c 66
17ebe977
PB
67Invariant 2 states that commits unique to "later" parents in a merge, appear
68before all commits from "earlier" parents of a merge.
69
70If *--show-breaks* is specified, each item of the list is output with a
712-character prefix consisting of one of: (|), (^), (=) followed by a space.
72
73Commits marked with (=) represent the boundaries of minimal, non-linear epochs
74and correspond either to the start of a period of divergent development or to
75the end of such a period.
76
77Commits marked with (|) are direct parents of commits immediately preceding
78the marked commit in the list.
79
80Commits marked with (^) are not parents of the immediately preceding commit.
81These "breaks" represent necessary discontinuities implied by trying to
82represent an arbtirary DAG in a linear form.
a3437b8c
JS
83
84*--show-breaks* is only valid if *--merge-order* is also specified.
2cf565c5
DG
85
86Author
87------
88Written by Linus Torvalds <torvalds@osdl.org>
89
a3437b8c
JS
90Original *--merge-order* logic by Jon Seymour <jon.seymour@gmail.com>
91
2cf565c5
DG
92Documentation
93--------------
94Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
95
96GIT
97---
a7154e91 98Part of the gitlink:git[7] suite
2cf565c5 99