[PATCH] rev-list docs: clarify --topo-order description

We said "--date-order" still does not violate the topology, but it
was still not clear enough.

Reword the description for both "--date-order" and "--topo-order",
and add an illustration to it.

Signed-off-by: Junio C Hamano <redacted>
---

 * Let's do this before I forget...; came up in discussion $gmane/203370

 Documentation/rev-list-options.txt | 29 +++++++++++++++++++++++------
 1 file changed, 23 insertions(+), 6 deletions(-)

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 6a4b635..dc501ee 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt

@@ -579,15 +579,32 @@ Commit Ordering
 By default, the commits are shown in reverse chronological order.
 
 --topo-order::
-
-	This option makes them appear in topological order (i.e.
-	descendant commits are shown before their parents).
+	This option makes them appear in topological order.  Even
+	without this option, descendant commits are shown before
+	their parents, but this tries to avoid showing commits on
+	multiple lines of history intermixed.
 
 --date-order::
 
-	This option is similar to '--topo-order' in the sense that no
-	parent comes before all of its children, but otherwise things
-	are still ordered in the commit timestamp order.
+	Show no parents before all of its children, but otherwise
+	show commits in the commit timestamp order.
++
+For example, in a commit history like this:
++
+----------------------------------------------------------------
+
+    ---1----2----4----7
+	\	       \
+	 3----5----6----8---
+
+----------------------------------------------------------------
++
+where the numbers denote the order of commit timestamps, `git
+rev-list` and friends with `--date-order` show the commits in the
+timestamp order: 8 7 6 5 4 3 2 1.
++
+With `--topo-order`, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5
+3 1), to avoid commits from two branches mixed together.
 
 --reverse::
 

-- 
1.7.12.rc2.85.g1de7134

On Mon, Aug 13, 2012 at 3:21 PM, Junio C Hamano [off-list ref] wrote:

 * Let's do this before I forget...; came up in discussion $gmane/203370

Thanks! That definitely confused me (and I suppose I stupidly didn't
test with a proper range).

It seems likely that those reading the above sentence will continue on
to read about --topo-order, but still, do you think the "descendant
commits are shown before parents" part belong here instead?

 --topo-order::
-
-       This option makes them appear in topological order (i.e.
-       descendant commits are shown before their parents).
+       This option makes them appear in topological order.  Even
+       without this option, descendant commits are shown before
+       their parents, but this tries to avoid showing commits on
+       multiple lines of history intermixed.

 --date-order::

-       This option is similar to '--topo-order' in the sense that no
-       parent comes before all of its children, but otherwise things
-       are still ordered in the commit timestamp order.
+       Show no parents before all of its children, but otherwise
+       show commits in the commit timestamp order.
++
+For example, in a commit history like this:
++
+----------------------------------------------------------------
+
+    ---1----2----4----7
+       \              \
+        3----5----6----8---
+
+----------------------------------------------------------------
++
+where the numbers denote the order of commit timestamps, `git
+rev-list` and friends with `--date-order` show the commits in the
+timestamp order: 8 7 6 5 4 3 2 1.
++
+With `--topo-order`, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5
+3 1), to avoid commits from two branches mixed together.

It would help at least me to also know what the output would be
without either of --date-order or --topo-order. (Does the default
order have a name, by the way?)

On 08/14/2012 12:21 AM, Junio C Hamano wrote:

We said "--date-order" still does not violate the topology, but it
was still not clear enough.

Reword the description for both "--date-order" and "--topo-order",
and add an illustration to it.

Signed-off-by: Junio C Hamano <redacted>

Thanks for this change.  I was recently trying to figure out the meaning 
of these ordering options myself, and found the old text confusing.

Is it possible to predict which of the two orders would be taken here? 
It would be nice for the results to be deterministic.  For example, 
topology "ties" could be broken by choosing the commit with the most 
recent timestamp.

  --reverse::

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu
http://softwareswirl.blogspot.com/