1.1 --- a/en/examples/bisect	Mon Dec 17 23:16:59 2007 -0500
     1.2 +++ b/en/examples/bisect	Mon Dec 31 20:06:58 2007 -0800
     1.3 @@ -30,19 +30,18 @@
     1.4  #$ name: help
     1.5  
     1.6  hg help bisect
     1.7 -hg bisect help
     1.8  
     1.9  #$ name: search.init
    1.10  
    1.11 -hg bisect init
    1.12 +hg bisect --init
    1.13  
    1.14  #$ name: search.bad-init
    1.15  
    1.16 -hg bisect bad
    1.17 +hg bisect --bad
    1.18  
    1.19  #$ name: search.good-init
    1.20  
    1.21 -hg bisect good 10
    1.22 +hg bisect --good 10
    1.23  
    1.24  #$ name: search.step1
    1.25  
    1.26 @@ -54,7 +53,7 @@
    1.27  fi
    1.28  
    1.29  echo this revision is $result
    1.30 -hg bisect $result
    1.31 +hg bisect --$result
    1.32  
    1.33  #$ name: search.mytest
    1.34  
    1.35 @@ -67,7 +66,7 @@
    1.36    fi
    1.37  
    1.38    echo this revision is $result
    1.39 -  hg bisect $result
    1.40 +  hg bisect --$result
    1.41  }
    1.42    
    1.43  #$ name: search.step2
    1.44 @@ -82,7 +81,7 @@
    1.45  
    1.46  #$ name: search.reset
    1.47  
    1.48 -hg bisect reset
    1.49 +hg bisect --reset
    1.50  
    1.51  #$ name:
    1.52  

     2.1 --- a/en/examples/bisect.commits.out	Mon Dec 17 23:16:59 2007 -0500
     2.2 +++ b/en/examples/bisect.commits.out	Mon Dec 31 20:06:58 2007 -0800
     2.3 @@ -8,3 +8,38 @@
     2.4  
     2.5  
     2.6  
     2.7 +
     2.8 +
     2.9 +
    2.10 +
    2.11 +
    2.12 +
    2.13 +
    2.14 +
    2.15 +
    2.16 +
    2.17 +
    2.18 +
    2.19 +
    2.20 +
    2.21 +
    2.22 +
    2.23 +
    2.24 +
    2.25 +
    2.26 +
    2.27 +
    2.28 +
    2.29 +
    2.30 +
    2.31 +
    2.32 +
    2.33 +
    2.34 +
    2.35 +
    2.36 +
    2.37 +
    2.38 +
    2.39 +
    2.40 +
    2.41 +

     3.1 --- a/en/examples/bisect.help.out	Mon Dec 17 23:16:59 2007 -0500
     3.2 +++ b/en/examples/bisect.help.out	Mon Dec 31 20:06:58 2007 -0800
     3.3 @@ -24,6 +24,3 @@
     3.4  
     3.5  
     3.6  
     3.7 -
     3.8 -
     3.9 -

     4.1 --- a/en/examples/bisect.init.out	Mon Dec 17 23:16:59 2007 -0500
     4.2 +++ b/en/examples/bisect.init.out	Mon Dec 31 20:06:58 2007 -0800
     4.3 @@ -1,2 +1,3 @@
     4.4  
     4.5  
     4.6 +

     5.1 --- a/en/examples/bisect.search.bad-init.out	Mon Dec 17 23:16:59 2007 -0500
     5.2 +++ b/en/examples/bisect.search.bad-init.out	Mon Dec 31 20:06:58 2007 -0800
     5.3 @@ -1,1 +1,2 @@
     5.4  
     5.5 +

     6.1 --- a/en/examples/bisect.search.good-init.out	Mon Dec 17 23:16:59 2007 -0500
     6.2 +++ b/en/examples/bisect.search.good-init.out	Mon Dec 31 20:06:58 2007 -0800
     6.3 @@ -1,3 +1,4 @@
     6.4  
     6.5  
     6.6  
     6.7 +

     7.1 --- a/en/examples/bisect.search.init.out	Mon Dec 17 23:16:59 2007 -0500
     7.2 +++ b/en/examples/bisect.search.init.out	Mon Dec 31 20:06:58 2007 -0800
     7.3 @@ -1,3 +1,27 @@
     7.4  
     7.5  
     7.6  
     7.7 +
     7.8 +
     7.9 +
    7.10 +
    7.11 +
    7.12 +
    7.13 +
    7.14 +
    7.15 +
    7.16 +
    7.17 +
    7.18 +
    7.19 +
    7.20 +
    7.21 +
    7.22 +
    7.23 +
    7.24 +
    7.25 +
    7.26 +
    7.27 +
    7.28 +
    7.29 +
    7.30 +

     8.1 --- a/en/examples/bisect.search.reset.out	Mon Dec 17 23:16:59 2007 -0500
     8.2 +++ b/en/examples/bisect.search.reset.out	Mon Dec 31 20:06:58 2007 -0800
     8.3 @@ -1,1 +1,2 @@
     8.4  
     8.5 +

     9.1 --- a/en/examples/bisect.search.rest.out	Mon Dec 17 23:16:59 2007 -0500
     9.2 +++ b/en/examples/bisect.search.rest.out	Mon Dec 31 20:06:58 2007 -0800
     9.3 @@ -14,3 +14,6 @@
     9.4  
     9.5  
     9.6  
     9.7 +
     9.8 +
     9.9 +

    10.1 --- a/en/examples/bisect.search.step1.out	Mon Dec 17 23:16:59 2007 -0500
    10.2 +++ b/en/examples/bisect.search.step1.out	Mon Dec 31 20:06:58 2007 -0800
    10.3 @@ -9,3 +9,4 @@
    10.4  
    10.5  
    10.6  
    10.7 +

    11.1 --- a/en/examples/bisect.search.step2.out	Mon Dec 17 23:16:59 2007 -0500
    11.2 +++ b/en/examples/bisect.search.step2.out	Mon Dec 31 20:06:58 2007 -0800
    11.3 @@ -2,3 +2,4 @@
    11.4  
    11.5  
    11.6  
    11.7 +

    12.1 --- a/en/hgext.tex	Mon Dec 17 23:16:59 2007 -0500
    12.2 +++ b/en/hgext.tex	Mon Dec 31 20:06:58 2007 -0800
    12.3 @@ -14,9 +14,6 @@
    12.4  \item Section~\ref{sec:tour-merge:fetch} covers the \hgext{fetch}
    12.5    extension; this combines pulling new changes and merging them with
    12.6    local changes into a single command, \hgxcmd{fetch}{fetch}.
    12.7 -\item The \hgext{bisect} extension adds an efficient pruning search
    12.8 -  for changes that introduced bugs, and we documented it in
    12.9 -  chapter~\ref{sec:undo:bisect}.
   12.10  \item In chapter~\ref{chap:hook}, we covered several extensions that
   12.11    are useful for hook-related functionality: \hgext{acl} adds access
   12.12    control lists; \hgext{bugzilla} adds integration with the Bugzilla

    13.1 --- a/en/mq.tex	Mon Dec 17 23:16:59 2007 -0500
    13.2 +++ b/en/mq.tex	Mon Dec 31 20:06:58 2007 -0800
    13.3 @@ -146,7 +146,7 @@
    13.4  interplay with the code they're based on---\emph{enormously} easier.
    13.5  Since every applied patch has an associated changeset, you can use
    13.6  \hgcmdargs{log}{\emph{filename}} to see which changesets and patches
    13.7 -affected a file.  You can use the \hgext{bisect} extension to
    13.8 +affected a file.  You can use the \hgext{bisect} command to
    13.9  binary-search through all changesets and applied patches to see where
   13.10  a bug got introduced or fixed.  You can use the \hgcmd{annotate}
   13.11  command to see which changeset or patch modified a particular line of

    14.1 --- a/en/undo.tex	Mon Dec 17 23:16:59 2007 -0500
    14.2 +++ b/en/undo.tex	Mon Dec 31 20:06:58 2007 -0800
    14.3 @@ -482,19 +482,19 @@
    14.4  
    14.5  While it's all very well to be able to back out a changeset that
    14.6  introduced a bug, this requires that you know which changeset to back
    14.7 -out.  Mercurial provides an invaluable extension, called
    14.8 -\hgext{bisect}, that helps you to automate this process and accomplish
    14.9 +out.  Mercurial provides an invaluable command, called
   14.10 +\hgcmd{bisect}, that helps you to automate this process and accomplish
   14.11  it very efficiently.
   14.12  
   14.13 -The idea behind the \hgext{bisect} extension is that a changeset has
   14.14 +The idea behind the \hgcmd{bisect} command is that a changeset has
   14.15  introduced some change of behaviour that you can identify with a
   14.16  simple binary test.  You don't know which piece of code introduced the
   14.17  change, but you know how to test for the presence of the bug.  The
   14.18 -\hgext{bisect} extension uses your test to direct its search for the
   14.19 +\hgcmd{bisect} command uses your test to direct its search for the
   14.20  changeset that introduced the code that caused the bug.
   14.21  
   14.22 -Here are a few scenarios to help you understand how you might apply this
   14.23 -extension.
   14.24 +Here are a few scenarios to help you understand how you might apply
   14.25 +this command.
   14.26  \begin{itemize}
   14.27  \item The most recent version of your software has a bug that you
   14.28    remember wasn't present a few weeks ago, but you don't know when it
   14.29 @@ -515,8 +515,8 @@
   14.30    you build your project.
   14.31  \end{itemize}
   14.32  
   14.33 -From these examples, it should be clear that the \hgext{bisect}
   14.34 -extension is not useful only for finding the sources of bugs.  You can
   14.35 +From these examples, it should be clear that the \hgcmd{bisect}
   14.36 +command is not useful only for finding the sources of bugs.  You can
   14.37  use it to find any ``emergent property'' of a repository (anything
   14.38  that you can't find from a simple text search of the files in the
   14.39  tree) for which you can write a binary test.
   14.40 @@ -524,10 +524,10 @@
   14.41  We'll introduce a little bit of terminology here, just to make it
   14.42  clear which parts of the search process are your responsibility, and
   14.43  which are Mercurial's.  A \emph{test} is something that \emph{you} run
   14.44 -when \hgext{bisect} chooses a changeset.  A \emph{probe} is what
   14.45 -\hgext{bisect} runs to tell whether a revision is good.  Finally,
   14.46 +when \hgcmd{bisect} chooses a changeset.  A \emph{probe} is what
   14.47 +\hgcmd{bisect} runs to tell whether a revision is good.  Finally,
   14.48  we'll use the word ``bisect'', as both a noun and a verb, to stand in
   14.49 -for the phrase ``search using the \hgext{bisect} extension''.
   14.50 +for the phrase ``search using the \hgcmd{bisect} command.
   14.51  
   14.52  One simple way to automate the searching process would be simply to
   14.53  probe every changeset.  However, this scales poorly.  If it took ten
   14.54 @@ -538,47 +538,33 @@
   14.55  and limited your search to those, you'd still be looking at over 40
   14.56  hours to find the changeset that introduced your bug.
   14.57  
   14.58 -What the \emph{bisect} extension does is use its knowledge of the
   14.59 +What the \hgcmd{bisect} command does is use its knowledge of the
   14.60  ``shape'' of your project's revision history to perform a search in
   14.61  time proportional to the \emph{logarithm} of the number of changesets
   14.62  to check (the kind of search it performs is called a dichotomic
   14.63  search).  With this approach, searching through 10,000 changesets will
   14.64 -take less than two hours, even at ten minutes per test.  Limit your
   14.65 -search to the last 500 changesets, and it will take less than an hour.
   14.66 -
   14.67 -The \hgext{bisect} extension is aware of the ``branchy'' nature of a
   14.68 +take less than three hours, even at ten minutes per test (the search
   14.69 +will require about 14 tests).  Limit your search to the last hundred
   14.70 +changesets, and it will take only about an hour (roughly seven tests).
   14.71 +
   14.72 +The \hgcmd{bisect} command is aware of the ``branchy'' nature of a
   14.73  Mercurial project's revision history, so it has no problems dealing
   14.74  with branches, merges, or multiple heads in a repoository.  It can
   14.75  prune entire branches of history with a single probe, which is how it
   14.76  operates so efficiently.
   14.77  
   14.78 -\subsection{Using the \hgext{bisect} extension}
   14.79 -
   14.80 -Here's an example of \hgext{bisect} in action.  To keep the core of
   14.81 -Mercurial simple, \hgext{bisect} is packaged as an extension; this
   14.82 -means that it won't be present unless you explicitly enable it.  To do
   14.83 -this, edit your \hgrc\ and add the following section header (if it's
   14.84 -not already present):
   14.85 -\begin{codesample2}
   14.86 -  [extensions]
   14.87 -\end{codesample2}
   14.88 -Then add a line to this section to enable the extension:
   14.89 -\begin{codesample2}
   14.90 -  hbisect =
   14.91 -\end{codesample2}
   14.92 +\subsection{Using the \hgcmd{bisect} command}
   14.93 +
   14.94 +Here's an example of \hgcmd{bisect} in action.
   14.95 +
   14.96  \begin{note}
   14.97 -  That's right, there's a ``\texttt{h}'' at the front of the name of
   14.98 -  the \hgext{bisect} extension.  The reason is that Mercurial is
   14.99 -  written in Python, and uses a standard Python package called
  14.100 -  \texttt{bisect}.  If you omit the ``\texttt{h}'' from the name
  14.101 -  ``\texttt{hbisect}'', Mercurial will erroneously find the standard
  14.102 -  Python \texttt{bisect} package, and try to use it as a Mercurial
  14.103 -  extension.  This won't work, and Mercurial will crash repeatedly
  14.104 -  until you fix the spelling in your \hgrc.  Ugh.
  14.105 +  In versions 0.9.5 and earlier of Mercurial, \hgcmd{bisect} was not a
  14.106 +  core command: it was distributed with Mercurial as an extension.
  14.107 +  This section describes the built-in command, not the old extension.
  14.108  \end{note}
  14.109  
  14.110  Now let's create a repository, so that we can try out the
  14.111 -\hgext{bisect} extension in isolation.
  14.112 +\hgcmd{bisect} command in isolation.
  14.113  \interaction{bisect.init}
  14.114  We'll simulate a project that has a bug in it in a simple-minded way:
  14.115  create trivial changes in a loop, and nominate one specific change
  14.116 @@ -588,29 +574,28 @@
  14.117  \interaction{bisect.commits}
  14.118  
  14.119  The next thing that we'd like to do is figure out how to use the
  14.120 -\hgext{bisect} extension.  We can use Mercurial's normal built-in help
  14.121 +\hgcmd{bisect} command.  We can use Mercurial's normal built-in help
  14.122  mechanism for this.
  14.123  \interaction{bisect.help}
  14.124  
  14.125 -The \hgext{bisect} extension works in steps.  Each step proceeds as follows.
  14.126 +The \hgcmd{bisect} command works in steps.  Each step proceeds as follows.
  14.127  \begin{enumerate}
  14.128  \item You run your binary test.
  14.129    \begin{itemize}
  14.130 -  \item If the test succeeded, you tell \hgext{bisect} by running the
  14.131 +  \item If the test succeeded, you tell \hgcmd{bisect} by running the
  14.132      \hgcmdargs{bisect}{good} command.
  14.133 -  \item If it failed, use the \hgcmdargs{bisect}{bad} command to let
  14.134 -    the \hgext{bisect} extension know.
  14.135 +  \item If it failed, run the \hgcmdargs{bisect}{--bad} command.
  14.136    \end{itemize}
  14.137 -\item The extension uses your information to decide which changeset to
  14.138 +\item The command uses your information to decide which changeset to
  14.139    test next.
  14.140  \item It updates the working directory to that changeset, and the
  14.141    process begins again.
  14.142  \end{enumerate}
  14.143 -The process ends when \hgext{bisect} identifies a unique changeset
  14.144 +The process ends when \hgcmd{bisect} identifies a unique changeset
  14.145  that marks the point where your test transitioned from ``succeeding''
  14.146  to ``failing''.
  14.147  
  14.148 -To start the search, we must run the \hgcmdargs{bisect}{init} command.
  14.149 +To start the search, we must run the \hgcmdargs{bisect}{--reset} command.
  14.150  \interaction{bisect.search.init}
  14.151  
  14.152  In our case, the binary test we use is simple: we check to see if any
  14.153 @@ -625,7 +610,7 @@
  14.154  \interaction{bisect.search.bad-init}
  14.155  
  14.156  Our next task is to nominate a changeset that we know \emph{doesn't}
  14.157 -have the bug; the \hgext{bisect} extension will ``bracket'' its search
  14.158 +have the bug; the \hgcmd{bisect} command will ``bracket'' its search
  14.159  between the first pair of good and bad changesets.  In our case, we
  14.160  know that revision~10 didn't have the bug.  (I'll have more words
  14.161  about choosing the first ``good'' changeset later.)
  14.162 @@ -656,20 +641,20 @@
  14.163  done.
  14.164  \interaction{bisect.search.rest}
  14.165  
  14.166 -Even though we had~40 changesets to search through, the \hgext{bisect}
  14.167 -extension let us find the changeset that introduced our ``bug'' with
  14.168 -only five tests.  Because the number of tests that the \hgext{bisect}
  14.169 -extension grows logarithmically with the number of changesets to
  14.170 +Even though we had~40 changesets to search through, the \hgcmd{bisect}
  14.171 +command let us find the changeset that introduced our ``bug'' with
  14.172 +only five tests.  Because the number of tests that the \hgcmd{bisect}
  14.173 +command grows logarithmically with the number of changesets to
  14.174  search, the advantage that it has over the ``brute force'' search
  14.175  approach increases with every changeset you add.
  14.176  
  14.177  \subsection{Cleaning up after your search}
  14.178  
  14.179 -When you're finished using the \hgext{bisect} extension in a
  14.180 +When you're finished using the \hgcmd{bisect} command in a
  14.181  repository, you can use the \hgcmdargs{bisect}{reset} command to drop
  14.182 -the information it was using to drive your search.  The extension
  14.183 +the information it was using to drive your search.  The command
  14.184  doesn't use much space, so it doesn't matter if you forget to run this
  14.185 -command.  However, \hgext{bisect} won't let you start a new search in
  14.186 +command.  However, \hgcmd{bisect} won't let you start a new search in
  14.187  that repository until you do a \hgcmdargs{bisect}{reset}.
  14.188  \interaction{bisect.search.reset}
  14.189  
  14.190 @@ -677,7 +662,7 @@
  14.191  
  14.192  \subsection{Give consistent input}
  14.193  
  14.194 -The \hgext{bisect} extension requires that you correctly report the
  14.195 +The \hgcmd{bisect} command requires that you correctly report the
  14.196  result of every test you perform.  If you tell it that a test failed
  14.197  when it really succeeded, it \emph{might} be able to detect the
  14.198  inconsistency.  If it can identify an inconsistency in your reports,
  14.199 @@ -687,16 +672,16 @@
  14.200  
  14.201  \subsection{Automate as much as possible}
  14.202  
  14.203 -When I started using the \hgext{bisect} extension, I tried a few times
  14.204 +When I started using the \hgcmd{bisect} command, I tried a few times
  14.205  to run my tests by hand, on the command line.  This is an approach
  14.206  that I, at least, am not suited to.  After a few tries, I found that I
  14.207  was making enough mistakes that I was having to restart my searches
  14.208 -several times before finally getting correct results.  
  14.209 -
  14.210 -My initial problems with driving the \hgext{bisect} extension by hand
  14.211 +several times before finally getting correct results.
  14.212 +
  14.213 +My initial problems with driving the \hgcmd{bisect} command by hand
  14.214  occurred even with simple searches on small repositories; if the
  14.215  problem you're looking for is more subtle, or the number of tests that
  14.216 -\hgext{bisect} must perform increases, the likelihood of operator
  14.217 +\hgcmd{bisect} must perform increases, the likelihood of operator
  14.218  error ruining the search is much higher.  Once I started automating my
  14.219  tests, I had much better results.
  14.220  
  14.221 @@ -713,7 +698,7 @@
  14.222  
  14.223  \subsection{Check your results}
  14.224  
  14.225 -Because the output of a \hgext{bisect} search is only as good as the
  14.226 +Because the output of a \hgcmd{bisect} search is only as good as the
  14.227  input you give it, don't take the changeset it reports as the
  14.228  absolute truth.  A simple way to cross-check its report is to manually
  14.229  run your test at each of the following changesets:
  14.230 @@ -739,26 +724,30 @@
  14.231  is to say that it occurs before your bug has a chance to manifest
  14.232  itself.  If you can't avoid that other bug (for example, it prevents
  14.233  your project from building), and so can't tell whether your bug is
  14.234 -present in a particular changeset, the \hgext{bisect} extension cannot
  14.235 -help you directly.  Instead, you'll need to manually avoid the
  14.236 -changesets where that bug is present, and do separate searches
  14.237 -``around'' it.
  14.238 +present in a particular changeset, the \hgcmd{bisect} command cannot
  14.239 +help you directly.  Instead, you can mark a changeset as untested by
  14.240 +running \hgcmdargs{bisect}{--skip}.
  14.241  
  14.242  A different problem could arise if your test for a bug's presence is
  14.243  not specific enough.  If you check for ``my program crashes'', then
  14.244  both your crashing bug and an unrelated crashing bug that masks it
  14.245 -will look like the same thing, and mislead \hgext{bisect}.
  14.246 +will look like the same thing, and mislead \hgcmd{bisect}.
  14.247 +
  14.248 +Another useful situation in which to use \hgcmdargs{bisect}{--skip} is
  14.249 +if you can't test a revision because your project was in a broken and
  14.250 +hence untestable state at that revision, perhaps because someone
  14.251 +checked in a change that prevented the project from building.
  14.252  
  14.253  \subsection{Bracket your search lazily}
  14.254  
  14.255  Choosing the first ``good'' and ``bad'' changesets that will mark the
  14.256  end points of your search is often easy, but it bears a little
  14.257 -discussion nevertheless.  From the perspective of \hgext{bisect}, the
  14.258 +discussion nevertheless.  From the perspective of \hgcmd{bisect}, the
  14.259  ``newest'' changeset is conventionally ``bad'', and the older
  14.260  changeset is ``good''.
  14.261  
  14.262  If you're having trouble remembering when a suitable ``good'' change
  14.263 -was, so that you can tell \hgext{bisect}, you could do worse than
  14.264 +was, so that you can tell \hgcmd{bisect}, you could do worse than
  14.265  testing changesets at random.  Just remember to eliminate contenders
  14.266  that can't possibly exhibit the bug (perhaps because the feature with
  14.267  the bug isn't present yet) and those where another problem masks the
  14.268 @@ -766,7 +755,7 @@
  14.269  
  14.270  Even if you end up ``early'' by thousands of changesets or months of
  14.271  history, you will only add a handful of tests to the total number that
  14.272 -\hgext{bisect} must perform, thanks to its logarithmic behaviour.
  14.273 +\hgcmd{bisect} must perform, thanks to its logarithmic behaviour.
  14.274  
  14.275  %%% Local Variables: 
  14.276  %%% mode: latex