#
#
# patch "cmd_ws_commit.cc"
#  from [b9f4f47dc0fb69f7cd4a12df1d6ad998519988bb]
#    to [00714654a6c2baca9166d9b999f0a41ec89e8f1b]
# 
# patch "monotone.texi"
#  from [a582d518e5e7d64f6089cc1e939023f11c4934b5]
#    to [714fe55c98765b6e29e2d66833519b203444e0fc]
#
============================================================
--- cmd_ws_commit.cc	b9f4f47dc0fb69f7cd4a12df1d6ad998519988bb
+++ cmd_ws_commit.cc	00714654a6c2baca9166d9b999f0a41ec89e8f1b
@@ -1509,8 +1509,7 @@ CMD(reset, "reset", "", CMD_REF(bisect),
   work.update_current_roster_from_filesystem(current_roster);
 
   E(parent_roster(parents.begin()) == current_roster, origin::user,
-    F("'%s' can only be used in a workspace with no pending changes") %
-    join_words(execid)());
+    F("this command can only be used in a workspace with no pending changes"));
 
   bisect::entry start = *bisect.begin();
   I(start.first == bisect::start);
@@ -1663,7 +1662,6 @@ bisect_update(app_state & app,
 
 static void
 bisect_update(app_state & app,
-              commands::command_id const & execid,
               bisect::type type)
 {
   database db(app);
@@ -1683,8 +1681,7 @@ bisect_update(app_state & app,
   work.update_current_roster_from_filesystem(current_roster);
 
   E(parent_roster(parents.begin()) == current_roster, origin::user,
-    F("'%s' can only be used in a workspace with no pending changes") %
-    join_words(execid)());
+    F("this command can only be used in a workspace with no pending changes"));
 
   set<revision_id> marked_ids;
 
@@ -1794,7 +1791,7 @@ CMD(skip, "skip", "", CMD_REF(bisect), "
 {
   if (args.size() != 0)
     throw usage(execid);
-  bisect_update(app, execid, bisect::skipped);
+  bisect_update(app, bisect::skipped);
 }
 
 CMD(bad, "bad", "", CMD_REF(bisect), "",
@@ -1804,7 +1801,7 @@ CMD(bad, "bad", "", CMD_REF(bisect), "",
 {
   if (args.size() != 0)
     throw usage(execid);
-  bisect_update(app, execid, bisect::bad);
+  bisect_update(app, bisect::bad);
 }
 
 CMD(good, "good", "", CMD_REF(bisect), "",
@@ -1814,7 +1811,7 @@ CMD(good, "good", "", CMD_REF(bisect), "
 {
   if (args.size() != 0)
     throw usage(execid);
-  bisect_update(app, execid, bisect::good);
+  bisect_update(app, bisect::good);
 }
 
 // Local Variables:
============================================================
--- monotone.texi	a582d518e5e7d64f6089cc1e939023f11c4934b5
+++ monotone.texi	714fe55c98765b6e29e2d66833519b203444e0fc
@@ -2635,6 +2635,7 @@ @chapter Advanced Uses
 * Importing from CVS::          Building a monotone database from a CVS repository.
 * Exporting to GIT::            Building a git repository from a monotone database.
 * Using packets::               Transferring data ``by hand''.
+* Bisecting::                   Finding bad revisions.
 @end menu
 
 @page
@@ -4068,7 +4069,7 @@ @section Exporting to GIT
 requirements.
 
 @page
address@hidden    Using packets,  , Exporting to GIT, Advanced Uses
address@hidden    Using packets, Bisecting, Exporting to GIT, Advanced Uses
 @section Using packets
 
 Suppose you made changes to your database, and want to send those
@@ -4259,6 +4260,64 @@ @section Using packets
 
 
 @page
address@hidden    Bisecting, , Using packets, Advanced Uses
address@hidden Bisecting
+
+Bisecting is an efficient means of finding the earliest revision that
+introduced a bug known to exist in some later revision. Given a set of
+``good'' earlier revisions that do not contain the bug and a set of
+``bad'' later revisions that do contain the bug @command{bisect}
+performs a binary search over the set of revisions between these two
+sets to identify the specific revision that introduced the bug.
+
+Bisection is started by marking revisions with the @command{bisect
+good} and @command{bisect bad} commands. Once both good and bad
+revisions have been specified the set of candidate revisions between
+the good and bad revisions is determined. The midpoint of this set is
+selected as the next revision to be tested and the workspace is
+updated to this selected revision. After the selected revision has
+been tested bisection continues when the revision is marked with
address@hidden good} or @command{bisect bad}. If the selected
+revision is marked as good, it and all of its ancestors are considered
+to be good and excluded from the remaining search set. If the selected
+revision is marked as bad, all of its descendants are considered to be
+bad and excluded from the remaining search set. After each selected
+revision is marked as good or bad the size of the remaining search set
+is halved.
+
+Revisions that are untestable for some reason (e.g. they don't
+compile) may be ignored with the @command{bisect skip} command. This
+excludes the specified revisions from the candidate set and allows the
+bisection operation to continue. Skipping revisions may cause the
+search to fail or end on the wrong revision if the revision being
+searched for is skipped.
+
+The current status of the bisection operation and the next revision to
+be tested is reported by the @command{bisect status} command. This
+command can be run at any stage of the bisection operation to see how
+many revisions remain to be tested and how many revisions have been
+ruled out.
+
+Currently @command{bisect} updates the workspace but does @emph{not}
+update the workspace @option{branch} option. This may leave the
+workspace at a revision that is @emph{not} in the branch specified by
+the workspace @option{branch} option and cause subsequent commits to
+be made to the wrong branch. Take care when committing new revisions
+during a bisection operation and be sure to use the @command{bisect
+reset} command once the bisection is complete to update the workspace
+back to the revision from which the bisection started.
+
+The bisection operation completes successfully when the last remaining
+revision is marked as ``bad''.  If the last remaining revision is
+marked as ``good'' the bisection fails without finding the initial bad
+revision.
+
+Once bisection is complete the workspace can be updated back to the
+starting revision with the @command{bisect reset} command. This
+command also removes all stored bisection information in preparation
+for future bisect operations.
+
address@hidden
 @node    CVS Phrasebook, Command Reference, Advanced Uses, Top
 @chapter CVS Phrasebook
 
@@ -5284,6 +5343,38 @@ @section Workspace
 When running @command{pivot_root}, it is sometimes possible for
 @ref{Workspace Collisions} to occur.
 
address@hidden mtn bisect good address@hidden ...]
+Mark the specified revisions as ``good'' for the current bisection
+operation. If no bisection operation is in progress a new bisection is
+initialized. If a bisection operation is in progress the next update
+target is selected and the workspace is updated to the selected
+revision.
+
address@hidden mtn bisect bad address@hidden ...]
+Mark the specified revisions as ``bad'' for the current bisection
+operation. If no bisection operation is in progress a new bisection is
+initialized. If a bisection operation is in progress the next update
+target is selected and the workspace is updated to the selected
+revision.
+
address@hidden mtn bisect skip address@hidden ...]
+Mark the specified revisions as ``skipped'' for the current bisection
+operation. If no bisection operation is in progress a new bisection is
+initialized. If a bisection operation is in progress the next update
+target is selected and the workspace is updated to the selected
+revision.
+
address@hidden mtn bisect status
+Report the status of the current bisection operation including the
+number of revisions that remain to be tested, the number of revisions
+that have been tested and the next revision that will selected for
+testing.
+
address@hidden mtn bisect reset
+Reset the current bisection operation by updating the workspace back
+to the revision from which the bisection was started and clearing the
+current bisection information.
+
 @end ftable
 
 @page