1.1 --- a/en/ch09-undo.xml	Wed Feb 18 00:22:09 2009 -0800
     1.2 +++ b/en/ch09-undo.xml	Mon Mar 09 23:22:09 2009 -0700
     1.3 @@ -41,32 +41,43 @@
     1.4  
     1.5        <para>Here's a mistake that I often find myself making:
     1.6  	committing a change in which I've created a new file, but
     1.7 -	forgotten to <command role="hg-cmd">hg add</command> it. <!--
     1.8 -	&interaction.rollback.commit; --> Looking at the output of
     1.9 -	<command role="hg-cmd">hg status</command> after the commit
    1.10 -	immediately confirms the error. <!--
    1.11 -	&interaction.rollback.status; --> The commit captured the
    1.12 -	changes to the file <filename>a</filename>, but not the new
    1.13 -	file <filename>b</filename>.  If I were to push this changeset
    1.14 -	to a repository that I shared with a colleague, the chances
    1.15 -	are high that something in <filename>a</filename> would refer
    1.16 -	to <filename>b</filename>, which would not be present in their
    1.17 +	forgotten to <command role="hg-cmd">hg add</command>
    1.18 +	it.</para>
    1.19 +
    1.20 +      &interaction.rollback.commit;
    1.21 +
    1.22 +      <para>Looking at the output of <command role="hg-cmd">hg
    1.23 +	  status</command> after the commit immediately confirms the
    1.24 +	error.</para>
    1.25 +
    1.26 +      &interaction.rollback.status;
    1.27 +
    1.28 +      <para>The commit captured the changes to the file
    1.29 +	<filename>a</filename>, but not the new file
    1.30 +	<filename>b</filename>.  If I were to push this changeset to a
    1.31 +	repository that I shared with a colleague, the chances are
    1.32 +	high that something in <filename>a</filename> would refer to
    1.33 +	<filename>b</filename>, which would not be present in their
    1.34  	repository when they pulled my changes.  I would thus become
    1.35  	the object of some indignation.</para>
    1.36  
    1.37        <para>However, luck is with me&emdash;I've caught my error
    1.38  	before I pushed the changeset.  I use the <command
    1.39  	  role="hg-cmd">hg rollback</command> command, and Mercurial
    1.40 -	makes that last changeset vanish. <!--
    1.41 -	&interaction.rollback.rollback; --> Notice that the changeset
    1.42 -	is no longer present in the repository's history, and the
    1.43 -	working directory once again thinks that the file
    1.44 -	<filename>a</filename> is modified.  The commit and rollback
    1.45 -	have left the working directory exactly as it was prior to the
    1.46 -	commit; the changeset has been completely erased.  I can now
    1.47 -	safely <command role="hg-cmd">hg add</command> the file
    1.48 -	<filename>b</filename>, and rerun my commit. <!--
    1.49 -	&interaction.rollback.add; --></para>
    1.50 +	makes that last changeset vanish.</para>
    1.51 +
    1.52 +      &interaction.rollback.rollback;
    1.53 +
    1.54 +      <para>Notice that the changeset is no longer present in the
    1.55 +	repository's history, and the working directory once again
    1.56 +	thinks that the file <filename>a</filename> is modified.  The
    1.57 +	commit and rollback have left the working directory exactly as
    1.58 +	it was prior to the commit; the changeset has been completely
    1.59 +	erased.  I can now safely <command role="hg-cmd">hg
    1.60 +	  add</command> the file <filename>b</filename>, and rerun my
    1.61 +	commit.</para>
    1.62 +
    1.63 +      &interaction.rollback.add;
    1.64  
    1.65      </sect2>
    1.66      <sect2>
    1.67 @@ -139,9 +150,12 @@
    1.68  	occurred in the repository. This means that you can only roll
    1.69  	back one transaction.  If you expect to be able to roll back
    1.70  	one transaction, then its predecessor, this is not the
    1.71 -	behaviour you will get. <!-- &interaction.rollback.twice; -->
    1.72 -	Once you've rolled back one transaction in a repository, you
    1.73 -	can't roll back again in that repository until you perform
    1.74 +	behaviour you will get.</para>
    1.75 +
    1.76 +      &interaction.rollback.twice;
    1.77 +
    1.78 +      <para>Once you've rolled back one transaction in a repository,
    1.79 +	you can't roll back again in that repository until you perform
    1.80  	another commit or pull.</para>
    1.81  
    1.82      </sect2>
    1.83 @@ -161,14 +175,22 @@
    1.84      <para>Let's illustrate how the <command role="hg-cmd">hg
    1.85  	revert</command> command works with yet another small example.
    1.86        We'll begin by modifying a file that Mercurial is already
    1.87 -      tracking. <!-- &interaction.daily.revert.modify; --> If we don't
    1.88 +      tracking.</para>
    1.89 +
    1.90 +    &interaction.daily.revert.modify;
    1.91 +
    1.92 +    <para>If we don't
    1.93        want that change, we can simply <command role="hg-cmd">hg
    1.94 -	revert</command> the file. <!--
    1.95 -      &interaction.daily.revert.unmodify; --> The <command
    1.96 -	role="hg-cmd">hg revert</command> command provides us with an
    1.97 -      extra degree of safety by saving our modified file with a
    1.98 -      <filename>.orig</filename> extension. <!--
    1.99 -      &interaction.daily.revert.status; --></para>
   1.100 +	revert</command> the file.</para>
   1.101 +
   1.102 +      &interaction.daily.revert.unmodify;
   1.103 +
   1.104 +    <para>The <command role="hg-cmd">hg revert</command> command
   1.105 +      provides us with an extra degree of safety by saving our
   1.106 +      modified file with a <filename>.orig</filename>
   1.107 +      extension.</para>
   1.108 +
   1.109 +    &interaction.daily.revert.status;
   1.110  
   1.111      <para>Here is a summary of the cases that the <command
   1.112  	role="hg-cmd">hg revert</command> command can deal with.  We
   1.113 @@ -204,25 +226,28 @@
   1.114  	then decide that in fact you don't want Mercurial to track it,
   1.115  	use <command role="hg-cmd">hg revert</command> to undo the
   1.116  	add.  Don't worry; Mercurial will not modify the file in any
   1.117 -	way.  It will just <quote>unmark</quote> the file. <!--
   1.118 -	&interaction.daily.revert.add; --></para>
   1.119 +	way.  It will just <quote>unmark</quote> the file.</para>
   1.120 +
   1.121 +      &interaction.daily.revert.add;
   1.122  
   1.123        <para>Similarly, if you ask Mercurial to <command
   1.124  	  role="hg-cmd">hg remove</command> a file, you can use
   1.125  	<command role="hg-cmd">hg revert</command> to restore it to
   1.126  	the contents it had as of the parent of the working directory.
   1.127 -	<!-- &interaction.daily.revert.remove; --> This works just as
   1.128 +	&interaction.daily.revert.remove; This works just as
   1.129  	well for a file that you deleted by hand, without telling
   1.130  	Mercurial (recall that in Mercurial terminology, this kind of
   1.131 -	file is called <quote>missing</quote>). <!--
   1.132 -	&interaction.daily.revert.missing; --></para>
   1.133 +	file is called <quote>missing</quote>).</para>
   1.134 +
   1.135 +      &interaction.daily.revert.missing;
   1.136  
   1.137        <para>If you revert a <command role="hg-cmd">hg copy</command>,
   1.138  	the copied-to file remains in your working directory
   1.139  	afterwards, untracked.  Since a copy doesn't affect the
   1.140  	copied-from file in any way, Mercurial doesn't do anything
   1.141 -	with the copied-from file. <!--
   1.142 -	&interaction.daily.revert.copy; --></para>
   1.143 +	with the copied-from file.</para>
   1.144 +
   1.145 +      &interaction.daily.revert.copy;
   1.146  
   1.147        <sect3>
   1.148  	<title>A slightly special case: reverting a rename</title>
   1.149 @@ -231,17 +256,23 @@
   1.150  	  file, there is one small detail that you should remember.
   1.151  	  When you <command role="hg-cmd">hg revert</command> a
   1.152  	  rename, it's not enough to provide the name of the
   1.153 -	  renamed-to file, as you can see here. <!--
   1.154 -	  &interaction.daily.revert.rename; --> As you can see from
   1.155 -	  the output of <command role="hg-cmd">hg status</command>,
   1.156 -	  the renamed-to file is no longer identified as added, but
   1.157 -	  the renamed-<emphasis>from</emphasis> file is still removed!
   1.158 +	  renamed-to file, as you can see here.</para>
   1.159 +
   1.160 +	&interaction.daily.revert.rename;
   1.161 +
   1.162 +	<para>As you can see from the output of <command
   1.163 +	    role="hg-cmd">hg status</command>, the renamed-to file is
   1.164 +	  no longer identified as added, but the
   1.165 +	  renamed-<emphasis>from</emphasis> file is still removed!
   1.166  	  This is counter-intuitive (at least to me), but at least
   1.167 -	  it's easy to deal with. <!--
   1.168 -	  &interaction.daily.revert.rename-orig; --> So remember, to
   1.169 -	  revert a <command role="hg-cmd">hg rename</command>, you
   1.170 -	  must provide <emphasis>both</emphasis> the source and
   1.171 -	  destination names.</para>
   1.172 +	  it's easy to deal with.</para>
   1.173 +
   1.174 +	&interaction.daily.revert.rename-orig;
   1.175 +
   1.176 +	<para>So remember, to revert a <command role="hg-cmd">hg
   1.177 +	    rename</command>, you must provide
   1.178 +	  <emphasis>both</emphasis> the source and destination
   1.179 +	  names.</para>
   1.180  
   1.181  	<para>% TODO: the output doesn't look like it will be
   1.182  	  removed!</para>
   1.183 @@ -291,8 +322,9 @@
   1.184        <para>The operation of the <command role="hg-cmd">hg
   1.185  	  backout</command> command is a little intricate, so let's
   1.186  	illustrate it with some examples.  First, we'll create a
   1.187 -	repository with some simple changes. <!--
   1.188 -	&interaction.backout.init; --></para>
   1.189 +	repository with some simple changes.</para>
   1.190 +
   1.191 +      &interaction.backout.init;
   1.192  
   1.193        <para>The <command role="hg-cmd">hg backout</command> command
   1.194  	takes a single changeset ID as its argument; this is the
   1.195 @@ -308,15 +340,19 @@
   1.196        <title>Backing out the tip changeset</title>
   1.197  
   1.198        <para>We're going to start by backing out the last changeset we
   1.199 -	committed. <!-- &interaction.backout.simple; --> You can see
   1.200 -	that the second line from <filename>myfile</filename> is no
   1.201 -	longer present.  Taking a look at the output of <command
   1.202 -	  role="hg-cmd">hg log</command> gives us an idea of what the
   1.203 -	<command role="hg-cmd">hg backout</command> command has done.
   1.204 -	<!-- &interaction.backout.simple.log; --> Notice that the new
   1.205 -	changeset that <command role="hg-cmd">hg backout</command> has
   1.206 -	created is a child of the changeset we backed out.  It's
   1.207 -	easier to see this in figure <xref
   1.208 +	committed.</para>
   1.209 +
   1.210 +      &interaction.backout.simple;
   1.211 +
   1.212 +      <para>You can see that the second line from
   1.213 +	<filename>myfile</filename> is no longer present.  Taking a
   1.214 +	look at the output of <command role="hg-cmd">hg log</command>
   1.215 +	gives us an idea of what the <command role="hg-cmd">hg
   1.216 +	  backout</command> command has done.
   1.217 +	&interaction.backout.simple.log; Notice that the new changeset
   1.218 +	that <command role="hg-cmd">hg backout</command> has created
   1.219 +	is a child of the changeset we backed out.  It's easier to see
   1.220 +	this in figure <xref
   1.221  	  linkend="fig:undo:backout"/>, which presents a graphical
   1.222  	view of the change history.  As you can see, the history is
   1.223  	nice and linear.</para>
   1.224 @@ -338,16 +374,22 @@
   1.225        <para>If you want to back out a change other than the last one
   1.226  	you committed, pass the <option
   1.227  	  role="hg-opt-backout">--merge</option> option to the
   1.228 -	<command role="hg-cmd">hg backout</command> command. <!--
   1.229 -	&interaction.backout.non-tip.clone; --> This makes backing out
   1.230 -	any changeset a <quote>one-shot</quote> operation that's
   1.231 -	usually simple and fast. <!--
   1.232 -	&interaction.backout.non-tip.backout; --></para>
   1.233 +	<command role="hg-cmd">hg backout</command> command.</para>
   1.234 +
   1.235 +      &interaction.backout.non-tip.clone;
   1.236 +
   1.237 +      <para>This makes backing out any changeset a
   1.238 +	<quote>one-shot</quote> operation that's usually simple and
   1.239 +	fast.</para>
   1.240 +
   1.241 +      &interaction.backout.non-tip.backout;
   1.242  
   1.243        <para>If you take a look at the contents of
   1.244  	<filename>myfile</filename> after the backout finishes, you'll
   1.245  	see that the first and third changes are present, but not the
   1.246 -	second. <!-- &interaction.backout.non-tip.cat; --></para>
   1.247 +	second.</para>
   1.248 +
   1.249 +      &interaction.backout.non-tip.cat;
   1.250  
   1.251        <para>As the graphical history in figure <xref
   1.252  	  linkend="fig:undo:backout-non-tip"/> illustrates, Mercurial
   1.253 @@ -404,15 +446,21 @@
   1.254  	clone our first repository, but omit the backout change that
   1.255  	it contains.</para>
   1.256  
   1.257 -      <para><!-- &interaction.backout.manual.clone; --> As with our
   1.258 +      &interaction.backout.manual.clone;
   1.259 +
   1.260 +      <para>As with our
   1.261  	earlier example, We'll commit a third changeset, then back out
   1.262 -	its parent, and see what happens. <!--
   1.263 -	&interaction.backout.manual.backout; --> Our new changeset is
   1.264 -	again a descendant of the changeset we backout out; it's thus
   1.265 -	a new head, <emphasis>not</emphasis> a descendant of the
   1.266 -	changeset that was the tip.  The <command role="hg-cmd">hg
   1.267 -	  backout</command> command was quite explicit in telling us
   1.268 -	this. <!-- &interaction.backout.manual.log; --></para>
   1.269 +	its parent, and see what happens.</para>
   1.270 +
   1.271 +      &interaction.backout.manual.backout;
   1.272 +
   1.273 +      <para>Our new changeset is again a descendant of the changeset
   1.274 +	we backout out; it's thus a new head, <emphasis>not</emphasis>
   1.275 +	a descendant of the changeset that was the tip.  The <command
   1.276 +	  role="hg-cmd">hg backout</command> command was quite
   1.277 +	explicit in telling us this.</para>
   1.278 +
   1.279 +      &interaction.backout.manual.log;
   1.280  
   1.281        <para>Again, it's easier to see what has happened by looking at
   1.282  	a graph of the revision history, in figure <xref
   1.283 @@ -435,9 +483,13 @@
   1.284        <para>After the <command role="hg-cmd">hg backout</command>
   1.285  	command has completed, it leaves the new
   1.286  	<quote>backout</quote> changeset as the parent of the working
   1.287 -	directory. <!-- &interaction.backout.manual.parents; --> Now
   1.288 -	we have two isolated sets of changes. <!--
   1.289 -	&interaction.backout.manual.heads; --></para>
   1.290 +	directory.</para>
   1.291 +
   1.292 +      &interaction.backout.manual.parents;
   1.293 +
   1.294 +      <para>Now we have two isolated sets of changes.</para>
   1.295 +
   1.296 +      &interaction.backout.manual.heads;
   1.297  
   1.298        <para>Let's think about what we expect to see as the contents of
   1.299  	<filename>myfile</filename> now.  The first change should be
   1.300 @@ -445,11 +497,17 @@
   1.301  	should be missing, as that's the change we backed out.  Since
   1.302  	the history graph shows the third change as a separate head,
   1.303  	we <emphasis>don't</emphasis> expect to see the third change
   1.304 -	present in <filename>myfile</filename>. <!--
   1.305 -	&interaction.backout.manual.cat; --> To get the third change
   1.306 -	back into the file, we just do a normal merge of our two
   1.307 -	heads. <!-- &interaction.backout.manual.merge; --> Afterwards,
   1.308 -	the graphical history of our repository looks like figure
   1.309 +	present in <filename>myfile</filename>.</para>
   1.310 +
   1.311 +      &interaction.backout.manual.cat;
   1.312 +
   1.313 +      <para>To get the third change back into the file, we just do a
   1.314 +	normal merge of our two heads.</para>
   1.315 +
   1.316 +      &interaction.backout.manual.merge;
   1.317 +
   1.318 +      <para>Afterwards, the graphical history of our repository looks
   1.319 +	like figure
   1.320  	<xref linkend="fig:undo:backout-manual-merge"/>.</para>
   1.321  
   1.322        <informalfigure id="fig:undo:backout-manual-merge">
   1.323 @@ -731,19 +789,26 @@
   1.324  
   1.325        <para>Now let's create a repository, so that we can try out the
   1.326  	<command role="hg-cmd">hg bisect</command> command in
   1.327 -	isolation. <!-- &interaction.bisect.init; --> We'll simulate a
   1.328 -	project that has a bug in it in a simple-minded way: create
   1.329 -	trivial changes in a loop, and nominate one specific change
   1.330 -	that will have the <quote>bug</quote>.  This loop creates 35
   1.331 -	changesets, each adding a single file to the repository.
   1.332 -	We'll represent our <quote>bug</quote> with a file that
   1.333 -	contains the text <quote>i have a gub</quote>. <!--
   1.334 -	&interaction.bisect.commits; --></para>
   1.335 +	isolation.</para>
   1.336 +
   1.337 +      &interaction.bisect.init;
   1.338 +
   1.339 +      <para>We'll simulate a project that has a bug in it in a
   1.340 +	simple-minded way: create trivial changes in a loop, and
   1.341 +	nominate one specific change that will have the
   1.342 +	<quote>bug</quote>.  This loop creates 35 changesets, each
   1.343 +	adding a single file to the repository. We'll represent our
   1.344 +	<quote>bug</quote> with a file that contains the text <quote>i
   1.345 +	  have a gub</quote>.</para>
   1.346 +
   1.347 +      &interaction.bisect.commits;
   1.348  
   1.349        <para>The next thing that we'd like to do is figure out how to
   1.350  	use the <command role="hg-cmd">hg bisect</command> command.
   1.351  	We can use Mercurial's normal built-in help mechanism for
   1.352 -	this. <!-- &interaction.bisect.help; --></para>
   1.353 +	this.</para>
   1.354 +
   1.355 +      &interaction.bisect.help;
   1.356  
   1.357        <para>The <command role="hg-cmd">hg bisect</command> command
   1.358  	works in steps.  Each step proceeds as follows.</para>
   1.359 @@ -771,8 +836,9 @@
   1.360  	<quote>succeeding</quote> to <quote>failing</quote>.</para>
   1.361  
   1.362        <para>To start the search, we must run the <command
   1.363 -	  role="hg-cmd">hg bisect --reset</command> command. <!--
   1.364 -	&interaction.bisect.search.init; --></para>
   1.365 +	  role="hg-cmd">hg bisect --reset</command> command.</para>
   1.366 +
   1.367 +      &interaction.bisect.search.init;
   1.368  
   1.369        <para>In our case, the binary test we use is simple: we check to
   1.370  	see if any file in the repository contains the string <quote>i
   1.371 @@ -785,8 +851,9 @@
   1.372        <para>Most of the time, the revision to which the working
   1.373  	directory is synced (usually the tip) already exhibits the
   1.374  	problem introduced by the buggy change, so we'll mark it as
   1.375 -	<quote>bad</quote>. <!-- &interaction.bisect.search.bad-init;
   1.376 -	--></para>
   1.377 +	<quote>bad</quote>.</para>
   1.378 +
   1.379 +      &interaction.bisect.search.bad-init;
   1.380  
   1.381        <para>Our next task is to nominate a changeset that we know
   1.382  	<emphasis>doesn't</emphasis> have the bug; the <command
   1.383 @@ -794,8 +861,9 @@
   1.384  	<quote>bracket</quote> its search between the first pair of
   1.385  	good and bad changesets.  In our case, we know that revision
   1.386  	10 didn't have the bug.  (I'll have more words about choosing
   1.387 -	the first <quote>good</quote> changeset later.) <!--
   1.388 -	&interaction.bisect.search.good-init; --></para>
   1.389 +	the first <quote>good</quote> changeset later.)</para>
   1.390 +
   1.391 +      &interaction.bisect.search.good-init;
   1.392  
   1.393        <para>Notice that this command printed some output.</para>
   1.394        <itemizedlist>
   1.395 @@ -812,16 +880,21 @@
   1.396  	<command>grep</command> command to see if our
   1.397  	<quote>bad</quote> file is present in the working directory.
   1.398  	If it is, this revision is bad; if not, this revision is good.
   1.399 -	<!-- &interaction.bisect.search.step1; --></para>
   1.400 +	&interaction.bisect.search.step1;</para>
   1.401  
   1.402        <para>This test looks like a perfect candidate for automation,
   1.403 -	so let's turn it into a shell function. <!--
   1.404 -	&interaction.bisect.search.mytest; --> We can now run an
   1.405 -	entire test step with a single command,
   1.406 -	<literal>mytest</literal>. <!--
   1.407 -	&interaction.bisect.search.step2; --> A few more invocations
   1.408 -	of our canned test step command, and we're done. <!--
   1.409 -	&interaction.bisect.search.rest; --></para>
   1.410 +	so let's turn it into a shell function.</para>
   1.411 +      &interaction.bisect.search.mytest;
   1.412 +
   1.413 +      <para>We can now run an entire test step with a single command,
   1.414 +	<literal>mytest</literal>.</para>
   1.415 +
   1.416 +      &interaction.bisect.search.step2;
   1.417 +
   1.418 +      <para>A few more invocations of our canned test step command,
   1.419 +	and we're done.</para>
   1.420 +
   1.421 +      &interaction.bisect.search.rest;
   1.422  
   1.423        <para>Even though we had 40 changesets to search through, the
   1.424  	<command role="hg-cmd">hg bisect</command> command let us find
   1.425 @@ -844,8 +917,9 @@
   1.426  	forget to run this command.  However, <command
   1.427  	  role="hg-cmd">hg bisect</command> won't let you start a new
   1.428  	search in that repository until you do a <command
   1.429 -	  role="hg-cmd">hg bisect reset</command>. <!--
   1.430 -	&interaction.bisect.search.reset; --></para>
   1.431 +	  role="hg-cmd">hg bisect reset</command>.</para>
   1.432 +
   1.433 +      &interaction.bisect.search.reset;
   1.434  
   1.435      </sect2>
   1.436    </sect1>