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

[Martin von Zweigbergk <martin.von.zweigbergk@gmail.com>]

On Mon, Aug 13, 2012 at 3:21 PM, Junio C Hamano <gitster@pobox.com> 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).

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

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?)