1git-rev-list(1) 2=============== 3 4NAME 5---- 6git-rev-list - Lists commit objects in reverse chronological order 7 8 9SYNOPSIS 10-------- 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>... ] 23 24DESCRIPTION 25----------- 26Lists commit objects in reverse chronological order starting at the 27given commit(s), taking ancestry relationship into account. This is 28useful to produce human-readable log output. 29 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 32means "list all the commits which are included in 'foo' and 'bar', but 33not in 'baz'". 34 35A special notation <commit1>..<commit2> can be used as a 36short-hand for {caret}<commit1> <commit2>. 37 38 39OPTIONS 40------- 41--pretty:: 42 Print the contents of the commit changesets in human-readable form. 43 44--header:: 45 Print the contents of the commit in raw-format; each 46 record is separated with a NUL character. 47 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 54--unpacked:: 55 Only useful with `--objects`; print the object IDs that 56 are not in packs. 57 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 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 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. 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 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+ 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/]. 103+ 104The merge order for a non-linear epoch is defined as a linearisation for which 105the following invariants are true: 106+ 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. 112+ 113Invariant 1 states that later commits appear before earlier commits they are 114derived from. 115+ 116Invariant 2 states that commits unique to "later" parents in a merge, appear 117before all commits from "earlier" parents of a merge. 118 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+ 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. 126+ 127Commits marked with (|) are direct parents of commits immediately preceding 128the marked commit in the list. 129+ 130Commits marked with (^) are not parents of the immediately preceding commit. 131These "breaks" represent necessary discontinuities implied by trying to 132represent an arbtirary DAG in a linear form. 133+ 134`--show-breaks` is only valid if `--merge-order` is also specified. 135 136 137Author 138------ 139Written by Linus Torvalds <torvalds@osdl.org> 140 141Original *--merge-order* logic by Jon Seymour <jon.seymour@gmail.com> 142 143Documentation 144-------------- 145Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. 146 147GIT 148--- 149Part of the gitlink:git[7] suite 150