diff ja/undo.tex @ 290:b0db5adf11c1 ja_root

fork Japanese translation.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/ja/undo.tex	Wed Feb 06 17:43:11 2008 +0900
@@ -0,0 +1,763 @@
+\chapter{Finding and fixing your mistakes}
+\label{chap:undo}
+
+To err might be human, but to really handle the consequences well
+takes a top-notch revision control system.  In this chapter, we'll
+discuss some of the techniques you can use when you find that a
+problem has crept into your project.  Mercurial has some highly
+capable features that will help you to isolate the sources of
+problems, and to handle them appropriately.
+
+\section{Erasing local history}
+
+\subsection{The accidental commit}
+
+I have the occasional but persistent problem of typing rather more
+quickly than I can think, which sometimes results in me committing a
+changeset that is either incomplete or plain wrong.  In my case, the
+usual kind of incomplete changeset is one in which I've created a new
+source file, but forgotten to \hgcmd{add} it.  A ``plain wrong''
+changeset is not as common, but no less annoying.
+
+\subsection{Rolling back a transaction}
+\label{sec:undo:rollback}
+
+In section~\ref{sec:concepts:txn}, I mentioned that Mercurial treats
+each modification of a repository as a \emph{transaction}.  Every time
+you commit a changeset or pull changes from another repository,
+Mercurial remembers what you did.  You can undo, or \emph{roll back},
+exactly one of these actions using the \hgcmd{rollback} command.  (See
+section~\ref{sec:undo:rollback-after-push} for an important caveat
+about the use of this command.)
+
+Here's a mistake that I often find myself making: committing a change
+in which I've created a new file, but forgotten to \hgcmd{add} it.
+\interaction{rollback.commit}
+Looking at the output of \hgcmd{status} after the commit immediately
+confirms the error.
+\interaction{rollback.status}
+The commit captured the changes to the file \filename{a}, but not the
+new file \filename{b}.  If I were to push this changeset to a
+repository that I shared with a colleague, the chances are high that
+something in \filename{a} would refer to \filename{b}, which would not
+be present in their repository when they pulled my changes.  I would
+thus become the object of some indignation.
+
+However, luck is with me---I've caught my error before I pushed the
+changeset.  I use the \hgcmd{rollback} command, and Mercurial makes
+that last changeset vanish.
+\interaction{rollback.rollback}
+Notice that the changeset is no longer present in the repository's
+history, and the working directory once again thinks that the file
+\filename{a} is modified.  The commit and rollback have left the
+working directory exactly as it was prior to the commit; the changeset
+has been completely erased.  I can now safely \hgcmd{add} the file
+\filename{b}, and rerun my commit.
+\interaction{rollback.add}
+
+\subsection{The erroneous pull}
+
+It's common practice with Mercurial to maintain separate development
+branches of a project in different repositories.  Your development
+team might have one shared repository for your project's ``0.9''
+release, and another, containing different changes, for the ``1.0''
+release.
+
+Given this, you can imagine that the consequences could be messy if
+you had a local ``0.9'' repository, and accidentally pulled changes
+from the shared ``1.0'' repository into it.  At worst, you could be
+paying insufficient attention, and push those changes into the shared
+``0.9'' tree, confusing your entire team (but don't worry, we'll
+return to this horror scenario later).  However, it's more likely that
+you'll notice immediately, because Mercurial will display the URL it's
+pulling from, or you will see it pull a suspiciously large number of
+changes into the repository.
+
+The \hgcmd{rollback} command will work nicely to expunge all of the
+changesets that you just pulled.  Mercurial groups all changes from
+one \hgcmd{pull} into a single transaction, so one \hgcmd{rollback} is
+all you need to undo this mistake.
+
+\subsection{Rolling back is useless once you've pushed}
+\label{sec:undo:rollback-after-push}
+
+The value of the \hgcmd{rollback} command drops to zero once you've
+pushed your changes to another repository.  Rolling back a change
+makes it disappear entirely, but \emph{only} in the repository in
+which you perform the \hgcmd{rollback}.  Because a rollback eliminates
+history, there's no way for the disappearance of a change to propagate
+between repositories.
+
+If you've pushed a change to another repository---particularly if it's
+a shared repository---it has essentially ``escaped into the wild,''
+and you'll have to recover from your mistake in a different way.  What
+will happen if you push a changeset somewhere, then roll it back, then
+pull from the repository you pushed to, is that the changeset will
+reappear in your repository.
+
+(If you absolutely know for sure that the change you want to roll back
+is the most recent change in the repository that you pushed to,
+\emph{and} you know that nobody else could have pulled it from that
+repository, you can roll back the changeset there, too, but you really
+should really not rely on this working reliably.  If you do this,
+sooner or later a change really will make it into a repository that
+you don't directly control (or have forgotten about), and come back to
+bite you.)
+
+\subsection{You can only roll back once}
+
+Mercurial stores exactly one transaction in its transaction log; that
+transaction is the most recent one that occurred in the repository.
+This means that you can only roll back one transaction.  If you expect
+to be able to roll back one transaction, then its predecessor, this is
+not the behaviour you will get.
+\interaction{rollback.twice}
+Once you've rolled back one transaction in a repository, you can't
+roll back again in that repository until you perform another commit or
+pull.
+
+\section{Reverting the mistaken change}
+
+If you make a modification to a file, and decide that you really
+didn't want to change the file at all, and you haven't yet committed
+your changes, the \hgcmd{revert} command is the one you'll need.  It
+looks at the changeset that's the parent of the working directory, and
+restores the contents of the file to their state as of that changeset.
+(That's a long-winded way of saying that, in the normal case, it
+undoes your modifications.)
+
+Let's illustrate how the \hgcmd{revert} command works with yet another
+small example.  We'll begin by modifying a file that Mercurial is
+already tracking.
+\interaction{daily.revert.modify}
+If we don't want that change, we can simply \hgcmd{revert} the file.
+\interaction{daily.revert.unmodify}
+The \hgcmd{revert} command provides us with an extra degree of safety
+by saving our modified file with a \filename{.orig} extension.
+\interaction{daily.revert.status}
+
+Here is a summary of the cases that the \hgcmd{revert} command can
+deal with.  We will describe each of these in more detail in the
+section that follows.
+\begin{itemize}
+\item If you modify a file, it will restore the file to its unmodified
+  state.
+\item If you \hgcmd{add} a file, it will undo the ``added'' state of
+  the file, but leave the file itself untouched.
+\item If you delete a file without telling Mercurial, it will restore
+  the file to its unmodified contents.
+\item If you use the \hgcmd{remove} command to remove a file, it will
+  undo the ``removed'' state of the file, and restore the file to its
+  unmodified contents.
+\end{itemize}
+
+\subsection{File management errors}
+\label{sec:undo:mgmt}
+
+The \hgcmd{revert} command is useful for more than just modified
+files.  It lets you reverse the results of all of Mercurial's file
+management commands---\hgcmd{add}, \hgcmd{remove}, and so on.
+
+If you \hgcmd{add} a file, then decide that in fact you don't want
+Mercurial to track it, use \hgcmd{revert} to undo the add.  Don't
+worry; Mercurial will not modify the file in any way.  It will just
+``unmark'' the file.
+\interaction{daily.revert.add}
+
+Similarly, if you ask Mercurial to \hgcmd{remove} a file, you can use
+\hgcmd{revert} to restore it to the contents it had as of the parent
+of the working directory.
+\interaction{daily.revert.remove}
+This works just as well for a file that you deleted by hand, without
+telling Mercurial (recall that in Mercurial terminology, this kind of
+file is called ``missing'').
+\interaction{daily.revert.missing}
+
+If you revert a \hgcmd{copy}, the copied-to file remains in your
+working directory afterwards, untracked.  Since a copy doesn't affect
+the copied-from file in any way, Mercurial doesn't do anything with
+the copied-from file.
+\interaction{daily.revert.copy}
+
+\subsubsection{A slightly special case: reverting a rename}
+
+If you \hgcmd{rename} a file, there is one small detail that
+you should remember.  When you \hgcmd{revert} a rename, it's not
+enough to provide the name of the renamed-to file, as you can see
+here.
+\interaction{daily.revert.rename}
+As you can see from the output of \hgcmd{status}, the renamed-to file
+is no longer identified as added, but the renamed-\emph{from} file is
+still removed!  This is counter-intuitive (at least to me), but at
+least it's easy to deal with.
+\interaction{daily.revert.rename-orig}
+So remember, to revert a \hgcmd{rename}, you must provide \emph{both}
+the source and destination names.  
+
+(By the way, if you rename a file, then modify the renamed-to file,
+then revert both components of the rename, when Mercurial restores the
+file that was removed as part of the rename, it will be unmodified.
+If you need the modifications in the renamed-to file to show up in the
+renamed-from file, don't forget to copy them over.)
+
+These fiddly aspects of reverting a rename arguably constitute a small
+bug in Mercurial.
+
+\section{Dealing with committed changes}
+
+Consider a case where you have committed a change $a$, and another
+change $b$ on top of it; you then realise that change $a$ was
+incorrect.  Mercurial lets you ``back out'' an entire changeset
+automatically, and building blocks that let you reverse part of a
+changeset by hand.
+
+Before you read this section, here's something to keep in mind: the
+\hgcmd{backout} command undoes changes by \emph{adding} history, not
+by modifying or erasing it.  It's the right tool to use if you're
+fixing bugs, but not if you're trying to undo some change that has
+catastrophic consequences.  To deal with those, see
+section~\ref{sec:undo:aaaiiieee}.
+
+\subsection{Backing out a changeset}
+
+The \hgcmd{backout} command lets you ``undo'' the effects of an entire
+changeset in an automated fashion.  Because Mercurial's history is
+immutable, this command \emph{does not} get rid of the changeset you
+want to undo.  Instead, it creates a new changeset that
+\emph{reverses} the effect of the to-be-undone changeset.
+
+The operation of the \hgcmd{backout} command is a little intricate, so
+let's illustrate it with some examples.  First, we'll create a
+repository with some simple changes.
+\interaction{backout.init}
+
+The \hgcmd{backout} command takes a single changeset ID as its
+argument; this is the changeset to back out.  Normally,
+\hgcmd{backout} will drop you into a text editor to write a commit
+message, so you can record why you're backing the change out.  In this
+example, we provide a commit message on the command line using the
+\hgopt{backout}{-m} option.
+
+\subsection{Backing out the tip changeset}
+
+We're going to start by backing out the last changeset we committed.
+\interaction{backout.simple}
+You can see that the second line from \filename{myfile} is no longer
+present.  Taking a look at the output of \hgcmd{log} gives us an idea
+of what the \hgcmd{backout} command has done.
+\interaction{backout.simple.log}
+Notice that the new changeset that \hgcmd{backout} has created is a
+child of the changeset we backed out.  It's easier to see this in
+figure~\ref{fig:undo:backout}, which presents a graphical view of the
+change history.  As you can see, the history is nice and linear.
+
+\begin{figure}[htb]
+  \centering
+  \grafix{undo-simple}
+  \caption{Backing out a change using the \hgcmd{backout} command}
+  \label{fig:undo:backout}
+\end{figure}
+
+\subsection{Backing out a non-tip change}
+
+If you want to back out a change other than the last one you
+committed, pass the \hgopt{backout}{--merge} option to the
+\hgcmd{backout} command.
+\interaction{backout.non-tip.clone}
+This makes backing out any changeset a ``one-shot'' operation that's
+usually simple and fast.
+\interaction{backout.non-tip.backout}
+
+If you take a look at the contents of \filename{myfile} after the
+backout finishes, you'll see that the first and third changes are
+present, but not the second.
+\interaction{backout.non-tip.cat}
+
+As the graphical history in figure~\ref{fig:undo:backout-non-tip}
+illustrates, Mercurial actually commits \emph{two} changes in this
+kind of situation (the box-shaped nodes are the ones that Mercurial
+commits automatically).  Before Mercurial begins the backout process,
+it first remembers what the current parent of the working directory
+is.  It then backs out the target changeset, and commits that as a
+changeset.  Finally, it merges back to the previous parent of the
+working directory, and commits the result of the merge.
+
+\begin{figure}[htb]
+  \centering
+  \grafix{undo-non-tip}
+  \caption{Automated backout of a non-tip change using the \hgcmd{backout} command}
+  \label{fig:undo:backout-non-tip}
+\end{figure}
+
+The result is that you end up ``back where you were'', only with some
+extra history that undoes the effect of the changeset you wanted to
+back out.
+
+\subsubsection{Always use the \hgopt{backout}{--merge} option}
+
+In fact, since the \hgopt{backout}{--merge} option will do the ``right
+thing'' whether or not the changeset you're backing out is the tip
+(i.e.~it won't try to merge if it's backing out the tip, since there's
+no need), you should \emph{always} use this option when you run the
+\hgcmd{backout} command.
+
+\subsection{Gaining more control of the backout process}
+
+While I've recommended that you always use the
+\hgopt{backout}{--merge} option when backing out a change, the
+\hgcmd{backout} command lets you decide how to merge a backout
+changeset.  Taking control of the backout process by hand is something
+you will rarely need to do, but it can be useful to understand what
+the \hgcmd{backout} command is doing for you automatically.  To
+illustrate this, let's clone our first repository, but omit the
+backout change that it contains.
+
+\interaction{backout.manual.clone}
+As with our earlier example, We'll commit a third changeset, then back
+out its parent, and see what happens.
+\interaction{backout.manual.backout} 
+Our new changeset is again a descendant of the changeset we backout
+out; it's thus a new head, \emph{not} a descendant of the changeset
+that was the tip.  The \hgcmd{backout} command was quite explicit in
+telling us this.
+\interaction{backout.manual.log}
+
+Again, it's easier to see what has happened by looking at a graph of
+the revision history, in figure~\ref{fig:undo:backout-manual}.  This
+makes it clear that when we use \hgcmd{backout} to back out a change
+other than the tip, Mercurial adds a new head to the repository (the
+change it committed is box-shaped).
+
+\begin{figure}[htb]
+  \centering
+  \grafix{undo-manual}
+  \caption{Backing out a change using the \hgcmd{backout} command}
+  \label{fig:undo:backout-manual}
+\end{figure}
+
+After the \hgcmd{backout} command has completed, it leaves the new
+``backout'' changeset as the parent of the working directory.
+\interaction{backout.manual.parents}
+Now we have two isolated sets of changes.
+\interaction{backout.manual.heads}
+
+Let's think about what we expect to see as the contents of
+\filename{myfile} now.  The first change should be present, because
+we've never backed it out.  The second change should be missing, as
+that's the change we backed out.  Since the history graph shows the
+third change as a separate head, we \emph{don't} expect to see the
+third change present in \filename{myfile}.
+\interaction{backout.manual.cat}
+To get the third change back into the file, we just do a normal merge
+of our two heads.
+\interaction{backout.manual.merge}
+Afterwards, the graphical history of our repository looks like
+figure~\ref{fig:undo:backout-manual-merge}.
+
+\begin{figure}[htb]
+  \centering
+  \grafix{undo-manual-merge}
+  \caption{Manually merging a backout change}
+  \label{fig:undo:backout-manual-merge}
+\end{figure}
+
+\subsection{Why \hgcmd{backout} works as it does}
+
+Here's a brief description of how the \hgcmd{backout} command works.
+\begin{enumerate}
+\item It ensures that the working directory is ``clean'', i.e.~that
+  the output of \hgcmd{status} would be empty.
+\item It remembers the current parent of the working directory.  Let's
+  call this changeset \texttt{orig}
+\item It does the equivalent of a \hgcmd{update} to sync the working
+  directory to the changeset you want to back out.  Let's call this
+  changeset \texttt{backout}
+\item It finds the parent of that changeset.  Let's call that
+  changeset \texttt{parent}.
+\item For each file that the \texttt{backout} changeset affected, it
+  does the equivalent of a \hgcmdargs{revert}{-r parent} on that file,
+  to restore it to the contents it had before that changeset was
+  committed.
+\item It commits the result as a new changeset.  This changeset has
+  \texttt{backout} as its parent.
+\item If you specify \hgopt{backout}{--merge} on the command line, it
+  merges with \texttt{orig}, and commits the result of the merge.
+\end{enumerate}
+
+An alternative way to implement the \hgcmd{backout} command would be
+to \hgcmd{export} the to-be-backed-out changeset as a diff, then use
+the \cmdopt{patch}{--reverse} option to the \command{patch} command to
+reverse the effect of the change without fiddling with the working
+directory.  This sounds much simpler, but it would not work nearly as
+well.
+
+The reason that \hgcmd{backout} does an update, a commit, a merge, and
+another commit is to give the merge machinery the best chance to do a
+good job when dealing with all the changes \emph{between} the change
+you're backing out and the current tip.  
+
+If you're backing out a changeset that's~100 revisions back in your
+project's history, the chances that the \command{patch} command will
+be able to apply a reverse diff cleanly are not good, because
+intervening changes are likely to have ``broken the context'' that
+\command{patch} uses to determine whether it can apply a patch (if
+this sounds like gibberish, see \ref{sec:mq:patch} for a
+discussion of the \command{patch} command).  Also, Mercurial's merge
+machinery will handle files and directories being renamed, permission
+changes, and modifications to binary files, none of which
+\command{patch} can deal with.
+
+\section{Changes that should never have been}
+\label{sec:undo:aaaiiieee}
+
+Most of the time, the \hgcmd{backout} command is exactly what you need
+if you want to undo the effects of a change.  It leaves a permanent
+record of exactly what you did, both when committing the original
+changeset and when you cleaned up after it.
+
+On rare occasions, though, you may find that you've committed a change
+that really should not be present in the repository at all.  For
+example, it would be very unusual, and usually considered a mistake,
+to commit a software project's object files as well as its source
+files.  Object files have almost no intrinsic value, and they're
+\emph{big}, so they increase the size of the repository and the amount
+of time it takes to clone or pull changes.
+
+Before I discuss the options that you have if you commit a ``brown
+paper bag'' change (the kind that's so bad that you want to pull a
+brown paper bag over your head), let me first discuss some approaches
+that probably won't work.
+
+Since Mercurial treats history as accumulative---every change builds
+on top of all changes that preceded it---you generally can't just make
+disastrous changes disappear.  The one exception is when you've just
+committed a change, and it hasn't been pushed or pulled into another
+repository.  That's when you can safely use the \hgcmd{rollback}
+command, as I detailed in section~\ref{sec:undo:rollback}.
+
+After you've pushed a bad change to another repository, you
+\emph{could} still use \hgcmd{rollback} to make your local copy of the
+change disappear, but it won't have the consequences you want.  The
+change will still be present in the remote repository, so it will
+reappear in your local repository the next time you pull.
+
+If a situation like this arises, and you know which repositories your
+bad change has propagated into, you can \emph{try} to get rid of the
+changeefrom \emph{every} one of those repositories.  This is, of
+course, not a satisfactory solution: if you miss even a single
+repository while you're expunging, the change is still ``in the
+wild'', and could propagate further.
+
+If you've committed one or more changes \emph{after} the change that
+you'd like to see disappear, your options are further reduced.
+Mercurial doesn't provide a way to ``punch a hole'' in history,
+leaving changesets intact.
+
+XXX This needs filling out.  The \texttt{hg-replay} script in the
+\texttt{examples} directory works, but doesn't handle merge
+changesets.  Kind of an important omission.
+
+\subsection{Protect yourself from ``escaped'' changes}
+
+If you've committed some changes to your local repository and they've
+been pushed or pulled somewhere else, this isn't necessarily a
+disaster.  You can protect yourself ahead of time against some classes
+of bad changeset.  This is particularly easy if your team usually
+pulls changes from a central repository.
+
+By configuring some hooks on that repository to validate incoming
+changesets (see chapter~\ref{chap:hook}), you can automatically
+prevent some kinds of bad changeset from being pushed to the central
+repository at all.  With such a configuration in place, some kinds of
+bad changeset will naturally tend to ``die out'' because they can't
+propagate into the central repository.  Better yet, this happens
+without any need for explicit intervention.
+
+For instance, an incoming change hook that verifies that a changeset
+will actually compile can prevent people from inadvertantly ``breaking
+the build''.
+
+\section{Finding the source of a bug}
+\label{sec:undo:bisect}
+
+While it's all very well to be able to back out a changeset that
+introduced a bug, this requires that you know which changeset to back
+out.  Mercurial provides an invaluable command, called
+\hgcmd{bisect}, that helps you to automate this process and accomplish
+it very efficiently.
+
+The idea behind the \hgcmd{bisect} command is that a changeset has
+introduced some change of behaviour that you can identify with a
+simple binary test.  You don't know which piece of code introduced the
+change, but you know how to test for the presence of the bug.  The
+\hgcmd{bisect} command uses your test to direct its search for the
+changeset that introduced the code that caused the bug.
+
+Here are a few scenarios to help you understand how you might apply
+this command.
+\begin{itemize}
+\item The most recent version of your software has a bug that you
+  remember wasn't present a few weeks ago, but you don't know when it
+  was introduced.  Here, your binary test checks for the presence of
+  that bug.
+\item You fixed a bug in a rush, and now it's time to close the entry
+  in your team's bug database.  The bug database requires a changeset
+  ID when you close an entry, but you don't remember which changeset
+  you fixed the bug in.  Once again, your binary test checks for the
+  presence of the bug.
+\item Your software works correctly, but runs~15\% slower than the
+  last time you measured it.  You want to know which changeset
+  introduced the performance regression.  In this case, your binary
+  test measures the performance of your software, to see whether it's
+  ``fast'' or ``slow''.
+\item The sizes of the components of your project that you ship
+  exploded recently, and you suspect that something changed in the way
+  you build your project.
+\end{itemize}
+
+From these examples, it should be clear that the \hgcmd{bisect}
+command is not useful only for finding the sources of bugs.  You can
+use it to find any ``emergent property'' of a repository (anything
+that you can't find from a simple text search of the files in the
+tree) for which you can write a binary test.
+
+We'll introduce a little bit of terminology here, just to make it
+clear which parts of the search process are your responsibility, and
+which are Mercurial's.  A \emph{test} is something that \emph{you} run
+when \hgcmd{bisect} chooses a changeset.  A \emph{probe} is what
+\hgcmd{bisect} runs to tell whether a revision is good.  Finally,
+we'll use the word ``bisect'', as both a noun and a verb, to stand in
+for the phrase ``search using the \hgcmd{bisect} command.
+
+One simple way to automate the searching process would be simply to
+probe every changeset.  However, this scales poorly.  If it took ten
+minutes to test a single changeset, and you had 10,000 changesets in
+your repository, the exhaustive approach would take on average~35
+\emph{days} to find the changeset that introduced a bug.  Even if you
+knew that the bug was introduced by one of the last 500 changesets,
+and limited your search to those, you'd still be looking at over 40
+hours to find the changeset that introduced your bug.
+
+What the \hgcmd{bisect} command does is use its knowledge of the
+``shape'' of your project's revision history to perform a search in
+time proportional to the \emph{logarithm} of the number of changesets
+to check (the kind of search it performs is called a dichotomic
+search).  With this approach, searching through 10,000 changesets will
+take less than three hours, even at ten minutes per test (the search
+will require about 14 tests).  Limit your search to the last hundred
+changesets, and it will take only about an hour (roughly seven tests).
+
+The \hgcmd{bisect} command is aware of the ``branchy'' nature of a
+Mercurial project's revision history, so it has no problems dealing
+with branches, merges, or multiple heads in a repoository.  It can
+prune entire branches of history with a single probe, which is how it
+operates so efficiently.
+
+\subsection{Using the \hgcmd{bisect} command}
+
+Here's an example of \hgcmd{bisect} in action.
+
+\begin{note}
+  In versions 0.9.5 and earlier of Mercurial, \hgcmd{bisect} was not a
+  core command: it was distributed with Mercurial as an extension.
+  This section describes the built-in command, not the old extension.
+\end{note}
+
+Now let's create a repository, so that we can try out the
+\hgcmd{bisect} command in isolation.
+\interaction{bisect.init}
+We'll simulate a project that has a bug in it in a simple-minded way:
+create trivial changes in a loop, and nominate one specific change
+that will have the ``bug''.  This loop creates 35 changesets, each
+adding a single file to the repository.  We'll represent our ``bug''
+with a file that contains the text ``i have a gub''.
+\interaction{bisect.commits}
+
+The next thing that we'd like to do is figure out how to use the
+\hgcmd{bisect} command.  We can use Mercurial's normal built-in help
+mechanism for this.
+\interaction{bisect.help}
+
+The \hgcmd{bisect} command works in steps.  Each step proceeds as follows.
+\begin{enumerate}
+\item You run your binary test.
+  \begin{itemize}
+  \item If the test succeeded, you tell \hgcmd{bisect} by running the
+    \hgcmdargs{bisect}{good} command.
+  \item If it failed, run the \hgcmdargs{bisect}{--bad} command.
+  \end{itemize}
+\item The command uses your information to decide which changeset to
+  test next.
+\item It updates the working directory to that changeset, and the
+  process begins again.
+\end{enumerate}
+The process ends when \hgcmd{bisect} identifies a unique changeset
+that marks the point where your test transitioned from ``succeeding''
+to ``failing''.
+
+To start the search, we must run the \hgcmdargs{bisect}{--reset} command.
+\interaction{bisect.search.init}
+
+In our case, the binary test we use is simple: we check to see if any
+file in the repository contains the string ``i have a gub''.  If it
+does, this changeset contains the change that ``caused the bug''.  By
+convention, a changeset that has the property we're searching for is
+``bad'', while one that doesn't is ``good''.
+
+Most of the time, the revision to which the working directory is
+synced (usually the tip) already exhibits the problem introduced by
+the buggy change, so we'll mark it as ``bad''.
+\interaction{bisect.search.bad-init}
+
+Our next task is to nominate a changeset that we know \emph{doesn't}
+have the bug; the \hgcmd{bisect} command will ``bracket'' its search
+between the first pair of good and bad changesets.  In our case, we
+know that revision~10 didn't have the bug.  (I'll have more words
+about choosing the first ``good'' changeset later.)
+\interaction{bisect.search.good-init}
+
+Notice that this command printed some output.
+\begin{itemize}
+\item It told us how many changesets it must consider before it can
+  identify the one that introduced the bug, and how many tests that
+  will require.
+\item It updated the working directory to the next changeset to test,
+  and told us which changeset it's testing.
+\end{itemize}
+
+We now run our test in the working directory.  We use the
+\command{grep} command to see if our ``bad'' file is present in the
+working directory.  If it is, this revision is bad; if not, this
+revision is good.
+\interaction{bisect.search.step1}
+
+This test looks like a perfect candidate for automation, so let's turn
+it into a shell function.
+\interaction{bisect.search.mytest}
+We can now run an entire test step with a single command,
+\texttt{mytest}.
+\interaction{bisect.search.step2}
+A few more invocations of our canned test step command, and we're
+done.
+\interaction{bisect.search.rest}
+
+Even though we had~40 changesets to search through, the \hgcmd{bisect}
+command let us find the changeset that introduced our ``bug'' with
+only five tests.  Because the number of tests that the \hgcmd{bisect}
+command grows logarithmically with the number of changesets to
+search, the advantage that it has over the ``brute force'' search
+approach increases with every changeset you add.
+
+\subsection{Cleaning up after your search}
+
+When you're finished using the \hgcmd{bisect} command in a
+repository, you can use the \hgcmdargs{bisect}{reset} command to drop
+the information it was using to drive your search.  The command
+doesn't use much space, so it doesn't matter if you forget to run this
+command.  However, \hgcmd{bisect} won't let you start a new search in
+that repository until you do a \hgcmdargs{bisect}{reset}.
+\interaction{bisect.search.reset}
+
+\section{Tips for finding bugs effectively}
+
+\subsection{Give consistent input}
+
+The \hgcmd{bisect} command requires that you correctly report the
+result of every test you perform.  If you tell it that a test failed
+when it really succeeded, it \emph{might} be able to detect the
+inconsistency.  If it can identify an inconsistency in your reports,
+it will tell you that a particular changeset is both good and bad.
+However, it can't do this perfectly; it's about as likely to report
+the wrong changeset as the source of the bug.
+
+\subsection{Automate as much as possible}
+
+When I started using the \hgcmd{bisect} command, I tried a few times
+to run my tests by hand, on the command line.  This is an approach
+that I, at least, am not suited to.  After a few tries, I found that I
+was making enough mistakes that I was having to restart my searches
+several times before finally getting correct results.
+
+My initial problems with driving the \hgcmd{bisect} command by hand
+occurred even with simple searches on small repositories; if the
+problem you're looking for is more subtle, or the number of tests that
+\hgcmd{bisect} must perform increases, the likelihood of operator
+error ruining the search is much higher.  Once I started automating my
+tests, I had much better results.
+
+The key to automated testing is twofold:
+\begin{itemize}
+\item always test for the same symptom, and
+\item always feed consistent input to the \hgcmd{bisect} command.
+\end{itemize}
+In my tutorial example above, the \command{grep} command tests for the
+symptom, and the \texttt{if} statement takes the result of this check
+and ensures that we always feed the same input to the \hgcmd{bisect}
+command.  The \texttt{mytest} function marries these together in a
+reproducible way, so that every test is uniform and consistent.
+
+\subsection{Check your results}
+
+Because the output of a \hgcmd{bisect} search is only as good as the
+input you give it, don't take the changeset it reports as the
+absolute truth.  A simple way to cross-check its report is to manually
+run your test at each of the following changesets:
+\begin{itemize}
+\item The changeset that it reports as the first bad revision.  Your
+  test should still report this as bad.
+\item The parent of that changeset (either parent, if it's a merge).
+  Your test should report this changeset as good.
+\item A child of that changeset.  Your test should report this
+  changeset as bad.
+\end{itemize}
+
+\subsection{Beware interference between bugs}
+
+It's possible that your search for one bug could be disrupted by the
+presence of another.  For example, let's say your software crashes at
+revision 100, and worked correctly at revision 50.  Unknown to you,
+someone else introduced a different crashing bug at revision 60, and
+fixed it at revision 80.  This could distort your results in one of
+several ways.
+
+It is possible that this other bug completely ``masks'' yours, which
+is to say that it occurs before your bug has a chance to manifest
+itself.  If you can't avoid that other bug (for example, it prevents
+your project from building), and so can't tell whether your bug is
+present in a particular changeset, the \hgcmd{bisect} command cannot
+help you directly.  Instead, you can mark a changeset as untested by
+running \hgcmdargs{bisect}{--skip}.
+
+A different problem could arise if your test for a bug's presence is
+not specific enough.  If you check for ``my program crashes'', then
+both your crashing bug and an unrelated crashing bug that masks it
+will look like the same thing, and mislead \hgcmd{bisect}.
+
+Another useful situation in which to use \hgcmdargs{bisect}{--skip} is
+if you can't test a revision because your project was in a broken and
+hence untestable state at that revision, perhaps because someone
+checked in a change that prevented the project from building.
+
+\subsection{Bracket your search lazily}
+
+Choosing the first ``good'' and ``bad'' changesets that will mark the
+end points of your search is often easy, but it bears a little
+discussion nevertheless.  From the perspective of \hgcmd{bisect}, the
+``newest'' changeset is conventionally ``bad'', and the older
+changeset is ``good''.
+
+If you're having trouble remembering when a suitable ``good'' change
+was, so that you can tell \hgcmd{bisect}, you could do worse than
+testing changesets at random.  Just remember to eliminate contenders
+that can't possibly exhibit the bug (perhaps because the feature with
+the bug isn't present yet) and those where another problem masks the
+bug (as I discussed above).
+
+Even if you end up ``early'' by thousands of changesets or months of
+history, you will only add a handful of tests to the total number that
+\hgcmd{bisect} must perform, thanks to its logarithmic behaviour.
+
+%%% Local Variables: 
+%%% mode: latex
+%%% TeX-master: "00book"
+%%% End: