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