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. This 77 flag makes the command ignore the paths, outputting all 78 eligible commits (still subject to count and age 79 limitation). 80 81--all:: 82 Pretend as if all the refs in `$GIT_DIR/refs/` are 83 listed on the command line as <commit>. 84 85--topo-order:: 86 By default, the commits are shown in reverse 87 chronological order. This option makes them appear in 88 topological order (i.e. descendant commits are shown 89 before their parents). 90 91--merge-order:: 92 When specified the commit history is decomposed into a unique 93 sequence of minimal, non-linear epochs and maximal, linear epochs. 94 Non-linear epochs are then linearised by sorting them into merge 95 order, which is described below. 96+ 97Maximal, linear epochs correspond to periods of sequential development. 98Minimal, non-linear epochs correspond to periods of divergent development 99followed by a converging merge. The theory of epochs is described in more 100detail at 101link:http://blackcubes.dyndns.org/epoch/[http://blackcubes.dyndns.org/epoch/]. 102+ 103The merge order for a non-linear epoch is defined as a linearisation for which 104the following invariants are true: 105+ 106 1. if a commit P is reachable from commit N, commit P sorts after commit N 107 in the linearised list. 108 2. if Pi and Pj are any two parents of a merge M (with i < j), then any 109 commit N, such that N is reachable from Pj but not reachable from Pi, 110 sorts before all commits reachable from Pi. 111+ 112Invariant 1 states that later commits appear before earlier commits they are 113derived from. 114+ 115Invariant 2 states that commits unique to "later" parents in a merge, appear 116before all commits from "earlier" parents of a merge. 117 118--show-breaks:: 119 Each item of the list is output with a 2-character prefix consisting 120 of one of: (|), (^), (=) followed by a space. 121+ 122Commits marked with (=) represent the boundaries of minimal, non-linear epochs 123and correspond either to the start of a period of divergent development or to 124the end of such a period. 125+ 126Commits marked with (|) are direct parents of commits immediately preceding 127the marked commit in the list. 128+ 129Commits marked with (^) are not parents of the immediately preceding commit. 130These "breaks" represent necessary discontinuities implied by trying to 131represent an arbtirary DAG in a linear form. 132+ 133`--show-breaks` is only valid if `--merge-order` is also specified. 134 135 136Author 137------ 138Written by Linus Torvalds <torvalds@osdl.org> 139 140Original *--merge-order* logic by Jon Seymour <jon.seymour@gmail.com> 141 142Documentation 143-------------- 144Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. 145 146GIT 147--- 148Part of the gitlink:git[7] suite 149