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

[Michael Haggerty <mhagger@alum.mit.edu>]

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 <gitster@pobox.com>

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

> ---
>
>   * 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.

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/