[PATCH 8 of 9] bisect: add some bisection examples, and some log revset.bisect() examples

[Yann E. MORIN]

 mercurial/commands.py |  59 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 59 insertions(+), 0 deletions(-)


# HG changeset patch
# User "Yann E. MORIN" <yann.morin.1998 at anciens.enib.fr>
# Date 1316383069 -7200
# Node ID 75ce7156d428b9a2bf6050ee9c118a638c2aeacd
# Parent  9f87db4abda16053574f4c96b41a31a154c47685
bisect: add some bisection examples, and some log revset.bisect() examples

Add a few examples on how to use bisect:
 - a few bisection examples
 - a few log examples to see the bisection status

Signed-off-by: "Yann E. MORIN" <yann.morin.1998 at anciens.enib.fr>

diff --git a/mercurial/commands.py b/mercurial/commands.py
--- a/mercurial/commands.py
+++ b/mercurial/commands.py
@@ -501,6 +501,52 @@
     (command not found) will abort the bisection, and any other
     non-zero exit status means the revision is bad.
 
+    .. container:: verbose
+
+      Some examples:
+
+      - start a bisection with known bad revision 12, and good revision 34::
+
+          hg bisect --bad 34
+          hg bisect --good 12
+
+      - advance the current bisection by marking current revision as good or
+        bad::
+
+          hg bisect --good
+          hg bisect --bad
+
+      - mark the current revision, or a known revision, to be skipped (eg. if
+        that revision is not usable because of another issue)::
+
+          hg bisect --skip
+          hg bisect --skip 23
+
+      - forget the current bisection::
+
+          hg bisect --reset
+
+      - use 'make && make tests' to automatically find the first broken
+        revision::
+
+          hg bisect --reset
+          hg bisect --bad 34
+          hg bisect --good 12
+          hg bisect --command 'make && make tests'
+
+      - see all changesets whose states are already known in the current
+        bisection::
+
+          hg log -r "bisect(pruned)"
+
+      - see all changesets that took part in the current bisection::
+
+          hg log -r "bisect(range)"
+
+      - with the graphlog extension, you can even get a nice graph::
+
+          hg log --graph -r "bisect(range)"
+
     Returns 0 on success.
     """
     def extendbisectrange(nodes, good):
@@ -3533,6 +3579,19 @@
 
           hg log -r "last(tagged())::" --template "{desc|firstline}\\n"
 
+      - see all changesets whose states are already known in the current
+        bisection::
+
+          hg log -r "bisect(pruned)"
+
+      - see all changesets that took part in the current bisection::
+
+          hg log -r "bisect(range)"
+
+      - with the graphlog extension, you can even get a nice graph::
+
+          hg log --graph -r "bisect(range)"
+
     See :hg:`help dates` for a list of formats valid for -d/--date.
 
     See :hg:`help revisions` and :hg:`help revsets` for more about