From: Junio C Hamano <gitster@pobox.com>
Date: Wed, 22 Aug 2012 18:53:20 +0000 (-0700)
Subject: Merge branch 'jc/maint-rev-list-topo-doc'
X-Git-Tag: v1.8.0-rc0~142
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/4def968e1438373152ff91391202da8adafb5f68?hp=-c

Merge branch 'jc/maint-rev-list-topo-doc'

It was unclear what "--topo-order" was really about in the
documentation. It is not just about "children before parent", but
also about "don't mix lineages".

* jc/maint-rev-list-topo-doc:
rev-list docs: clarify --topo-order description
---

4def968e1438373152ff91391202da8adafb5f68
diff --combined Documentation/rev-list-options.txt
index d9b2b5b2e0,9404d08673..def1340ac7
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@@ -198,7 -198,7 +198,7 @@@ excluded from the output
  +
  For example, `--cherry-pick --right-only A...B` omits those
  commits from `B` which are in `A` or are patch-equivalent to a commit in
 -`A`. In other words, this lists the `{plus}` commits from `git cherry A B`.
 +`A`. In other words, this lists the `+` commits from `git cherry A B`.
  More precisely, `--cherry-pick --right-only --no-merges` gives the exact
  list.
  
@@@ -455,7 -455,7 +455,7 @@@ The effect of this is best shown by wa
  	  `---------'
  -----------------------------------------------------------------------
  +
 -Note the major differences in `N` and `P` over '\--full-history':
 +Note the major differences in `N` and `P` over '--full-history':
  +
  --
  * `N`'s parent list had `I` removed, because it is an ancestor of the
@@@ -494,7 -494,7 +494,7 @@@ of course)
  When we want to find out what commits in `M` are contaminated with the
  bug introduced by `D` and need fixing, however, we might want to view
  only the subset of 'D..M' that are actually descendants of `D`, i.e.
 -excluding `C` and `K`. This is exactly what the '\--ancestry-path'
 +excluding `C` and `K`. This is exactly what the '--ancestry-path'
  option does. Applied to the 'D..M' range, it results in:
  +
  -----------------------------------------------------------------------
@@@ -578,16 -578,33 +578,33 @@@ Commit Orderin
  
  By default, the commits are shown in reverse chronological order.
  
- --topo-order::
+ --date-order::
+ 	Show no parents before all of its children are shown, but
+ 	otherwise show commits in the commit timestamp order.
  
- 	This option makes them appear in topological order (i.e.
- 	descendant commits are shown before their parents).
+ --topo-order::
+ 	Show no parents before all of its children are shown, and
+ 	avoid showing commits on multiple lines of history
+ 	intermixed.
+ +
+ For example, in a commit history like this:
+ +
+ ----------------------------------------------------------------
  
- --date-order::
+     ---1----2----4----7
+ 	\	       \
+ 	 3----5----6----8---
  
- 	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.
+ ----------------------------------------------------------------
+ +
+ 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); some older commits are shown before newer ones in order to
+ avoid showing the commits from two parallel development track mixed
+ together.
  
  --reverse::
  
@@@ -622,7 -639,6 +639,7 @@@ These options are mostly targeted for p
  --no-walk::
  
  	Only show the given revs, but do not traverse their ancestors.
 +	This has no effect if a range is specified.
  
  --do-walk::
  
@@@ -760,7 -776,7 +777,7 @@@ options may be given. See linkgit:git-d
  
  --cc::
  
 -	This flag implies the '-c' options and further compresses the
 +	This flag implies the '-c' option and further compresses the
  	patch output by omitting uninteresting hunks whose contents in
  	the parents have only two variants and the merge result picks
  	one of them without modification.