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