Merge with master.kernel.org:/pub/scm/git/git.git

[git.git] / Documentation / git-rev-list.txt

diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index 35fecf3..f386a3a 100644 (file)
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -22,62 +22,69 @@ that point. Their parents are implied. "git-rev-list foo bar ^baz" thus
 means "list all the commits which are included in 'foo' and 'bar', but
 not in 'baz'".
 
 means "list all the commits which are included in 'foo' and 'bar', but
 not in 'baz'".
 

-If *--pretty* is specified, print the contents of the commit changesets
-in human-readable form.
-
-The *--objects* flag causes 'git-rev-list' to print the object IDs of
-any object referenced by the listed commits. 'git-rev-list --objects foo
-^bar' thus means "send me all object IDs which I need to download if
-I have the commit object 'bar', but not 'foo'".
-
-The *--bisect* flag limits output to the one commit object which is
-roughly halfway between the included and excluded commits. Thus,
-if "git-rev-list --bisect foo ^bar ^baz" outputs 'midpoint', the output
-of "git-rev-list foo ^midpoint" and "git-rev-list midpoint ^bar ^baz"
-would be of roughly the same length. Finding the change which introduces
-a regression is thus reduced to a binary search: repeatedly generate and
-test new 'midpoint's until the commit chain is of length one.
-
-If *--merge-order* is specified, the commit history is decomposed into a
-unique sequence of minimal, non-linear epochs and maximal, linear epochs.
-Non-linear epochs are then linearised by sorting them into merge order, which
-is described below.
-
+OPTIONS
+-------
+--pretty::
+       Print the contents of the commit changesets in human-readable form.
+
+--objects::
+       Print the object IDs of any object referenced by the listed commits.
+       'git-rev-list --objects foo ^bar' thus means "send me all object IDs
+       which I need to download if I have the commit object 'bar', but
+       not 'foo'".
+
+--bisect::
+       Limit output to the one commit object which is roughly halfway
+       between the included and excluded commits. Thus, if 'git-rev-list
+       --bisect foo ^bar ^baz' outputs 'midpoint', the output
+       of 'git-rev-list foo ^midpoint' and 'git-rev-list midpoint
+       ^bar ^baz' would be of roughly the same length. Finding the change
+       which introduces a regression is thus reduced to a binary search:
+       repeatedly generate and test new 'midpoint's until the commit chain
+       is of length one.
+
+--merge-order::
+       When specified the commit history is decomposed into a unique
+       sequence of minimal, non-linear epochs and maximal, linear epochs.
+       Non-linear epochs are then linearised by sorting them into merge
+       order, which is described below.
++

 Maximal, linear epochs correspond to periods of sequential development.
 Minimal, non-linear epochs correspond to periods of divergent development
 followed by a converging merge. The theory of epochs is described in more
 detail at
 link:http://blackcubes.dyndns.org/epoch/[http://blackcubes.dyndns.org/epoch/].
 Maximal, linear epochs correspond to periods of sequential development.
 Minimal, non-linear epochs correspond to periods of divergent development
 followed by a converging merge. The theory of epochs is described in more
 detail at
 link:http://blackcubes.dyndns.org/epoch/[http://blackcubes.dyndns.org/epoch/].

-
++

 The merge order for a non-linear epoch is defined as a linearisation for which
 the following invariants are true:
 The merge order for a non-linear epoch is defined as a linearisation for which
 the following invariants are true:

-
++

     1. if a commit P is reachable from commit N, commit P sorts after commit N
        in the linearised list.
     2. if Pi and Pj are any two parents of a merge M (with i < j), then any
        commit N, such that N is reachable from Pj but not reachable from Pi,
        sorts before all commits reachable from Pi.
     1. if a commit P is reachable from commit N, commit P sorts after commit N
        in the linearised list.
     2. if Pi and Pj are any two parents of a merge M (with i < j), then any
        commit N, such that N is reachable from Pj but not reachable from Pi,
        sorts before all commits reachable from Pi.

-
++

 Invariant 1 states that later commits appear before earlier commits they are
 derived from.
 Invariant 1 states that later commits appear before earlier commits they are
 derived from.

-
++

 Invariant 2 states that commits unique to "later" parents in a merge, appear
 before all commits from "earlier" parents of a merge.
 
 Invariant 2 states that commits unique to "later" parents in a merge, appear
 before all commits from "earlier" parents of a merge.
 

-If *--show-breaks* is specified, each item of the list is output with a
-2-character prefix consisting of one of: (|), (^), (=) followed by a space.
-
+--show-breaks::
+       Each item of the list is output with a 2-character prefix consisting
+       of one of: (|), (^), (=) followed by a space.
++

 Commits marked with (=) represent the boundaries of minimal, non-linear epochs
 and correspond either to the start of a period of divergent development or to
 the end of such a period.
 Commits marked with (=) represent the boundaries of minimal, non-linear epochs
 and correspond either to the start of a period of divergent development or to
 the end of such a period.

-
++

 Commits marked with (|) are direct parents of commits immediately preceding
 the marked commit in the list.
 Commits marked with (|) are direct parents of commits immediately preceding
 the marked commit in the list.

-
++

 Commits marked with (^) are not parents of the immediately preceding commit.
 These "breaks" represent necessary discontinuities implied by trying to
 represent an arbtirary DAG in a linear form.
 Commits marked with (^) are not parents of the immediately preceding commit.
 These "breaks" represent necessary discontinuities implied by trying to
 represent an arbtirary DAG in a linear form.

-
++

 *--show-breaks* is only valid if *--merge-order* is also specified.
 
 Author
 *--show-breaks* is only valid if *--merge-order* is also specified.
 
 Author


@@ -92,5 +99,5 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel
 
 GIT
 ---
 
 GIT
 ---

-Part of the link:git.html[git] suite
+Part of the gitlink:git[7] suite