hgbook
diff en/ch08-undo.xml @ 654:1c13ed2130a7
Merge with http://hg.serpentine.com/mercurial/book
| author | Dongsheng Song <dongsheng.song@gmail.com> |
|---|---|
| date | Mon Mar 30 16:23:33 2009 +0800 (2009-03-30) |
| parents | 7e7c47481e4f 0b45854f0b7b |
| children | b338f5490029 |
line diff
1.1 --- a/en/ch08-undo.xml Fri Mar 20 16:43:35 2009 +0800 1.2 +++ b/en/ch08-undo.xml Mon Mar 30 16:23:33 2009 +0800 1.3 @@ -1,10 +1,10 @@ 1.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 1.5 1.6 -<chapter id="chap.undo"> 1.7 +<chapter id="chap:undo"> 1.8 <?dbhtml filename="finding-and-fixing-mistakes.html"?> 1.9 <title>Finding and fixing mistakes</title> 1.10 1.11 - <para>To err might be human, but to really handle the consequences 1.12 + <para id="x_d2">To err might be human, but to really handle the consequences 1.13 well takes a top-notch revision control system. In this chapter, 1.14 we'll discuss some of the techniques you can use when you find 1.15 that a problem has crept into your project. Mercurial has some 1.16 @@ -17,7 +17,7 @@ 1.17 <sect2> 1.18 <title>The accidental commit</title> 1.19 1.20 - <para>I have the occasional but persistent problem of typing 1.21 + <para id="x_d3">I have the occasional but persistent problem of typing 1.22 rather more quickly than I can think, which sometimes results 1.23 in me committing a changeset that is either incomplete or 1.24 plain wrong. In my case, the usual kind of incomplete 1.25 @@ -27,33 +27,33 @@ 1.26 less annoying.</para> 1.27 1.28 </sect2> 1.29 - <sect2 id="sec.undo.rollback"> 1.30 + <sect2 id="sec:undo:rollback"> 1.31 <title>Rolling back a transaction</title> 1.32 1.33 - <para>In section <xref linkend="sec.concepts.txn"/>, I mentioned 1.34 - that Mercurial treats each modification of a repository as a 1.35 - <emphasis>transaction</emphasis>. Every time you commit a 1.36 - changeset or pull changes from another repository, Mercurial 1.37 - remembers what you did. You can undo, or <emphasis>roll 1.38 - back</emphasis>, exactly one of these actions using the 1.39 - <command role="hg-cmd">hg rollback</command> command. (See 1.40 - section <xref linkend="sec.undo.rollback-after-push"/> for an 1.41 - important caveat about the use of this command.)</para> 1.42 - 1.43 - <para>Here's a mistake that I often find myself making: 1.44 + <para id="x_d4">In <xref linkend="sec:concepts:txn"/>, I 1.45 + mentioned that Mercurial treats each modification of a 1.46 + repository as a <emphasis>transaction</emphasis>. Every time 1.47 + you commit a changeset or pull changes from another 1.48 + repository, Mercurial remembers what you did. You can undo, 1.49 + or <emphasis>roll back</emphasis>, exactly one of these 1.50 + actions using the <command role="hg-cmd">hg rollback</command> 1.51 + command. (See <xref linkend="sec:undo:rollback-after-push"/> 1.52 + for an important caveat about the use of this command.)</para> 1.53 + 1.54 + <para id="x_d5">Here's a mistake that I often find myself making: 1.55 committing a change in which I've created a new file, but 1.56 forgotten to <command role="hg-cmd">hg add</command> 1.57 it.</para> 1.58 1.59 &interaction.rollback.commit; 1.60 1.61 - <para>Looking at the output of <command role="hg-cmd">hg 1.62 + <para id="x_d6">Looking at the output of <command role="hg-cmd">hg 1.63 status</command> after the commit immediately confirms the 1.64 error.</para> 1.65 1.66 &interaction.rollback.status; 1.67 1.68 - <para>The commit captured the changes to the file 1.69 + <para id="x_d7">The commit captured the changes to the file 1.70 <filename>a</filename>, but not the new file 1.71 <filename>b</filename>. If I were to push this changeset to a 1.72 repository that I shared with a colleague, the chances are 1.73 @@ -62,14 +62,14 @@ 1.74 repository when they pulled my changes. I would thus become 1.75 the object of some indignation.</para> 1.76 1.77 - <para>However, luck is with me&emdash;I've caught my error 1.78 + <para id="x_d8">However, luck is with me&emdash;I've caught my error 1.79 before I pushed the changeset. I use the <command 1.80 role="hg-cmd">hg rollback</command> command, and Mercurial 1.81 makes that last changeset vanish.</para> 1.82 1.83 &interaction.rollback.rollback; 1.84 1.85 - <para>Notice that the changeset is no longer present in the 1.86 + <para id="x_d9">Notice that the changeset is no longer present in the 1.87 repository's history, and the working directory once again 1.88 thinks that the file <filename>a</filename> is modified. The 1.89 commit and rollback have left the working directory exactly as 1.90 @@ -84,14 +84,14 @@ 1.91 <sect2> 1.92 <title>The erroneous pull</title> 1.93 1.94 - <para>It's common practice with Mercurial to maintain separate 1.95 + <para id="x_da">It's common practice with Mercurial to maintain separate 1.96 development branches of a project in different repositories. 1.97 Your development team might have one shared repository for 1.98 your project's <quote>0.9</quote> release, and another, 1.99 containing different changes, for the <quote>1.0</quote> 1.100 release.</para> 1.101 1.102 - <para>Given this, you can imagine that the consequences could be 1.103 + <para id="x_db">Given this, you can imagine that the consequences could be 1.104 messy if you had a local <quote>0.9</quote> repository, and 1.105 accidentally pulled changes from the shared <quote>1.0</quote> 1.106 repository into it. At worst, you could be paying 1.107 @@ -103,7 +103,7 @@ 1.108 see it pull a suspiciously large number of changes into the 1.109 repository.</para> 1.110 1.111 - <para>The <command role="hg-cmd">hg rollback</command> command 1.112 + <para id="x_dc">The <command role="hg-cmd">hg rollback</command> command 1.113 will work nicely to expunge all of the changesets that you 1.114 just pulled. Mercurial groups all changes from one <command 1.115 role="hg-cmd">hg pull</command> into a single transaction, 1.116 @@ -111,10 +111,10 @@ 1.117 need to undo this mistake.</para> 1.118 1.119 </sect2> 1.120 - <sect2 id="sec.undo.rollback-after-push"> 1.121 + <sect2 id="sec:undo:rollback-after-push"> 1.122 <title>Rolling back is useless once you've pushed</title> 1.123 1.124 - <para>The value of the <command role="hg-cmd">hg 1.125 + <para id="x_dd">The value of the <command role="hg-cmd">hg 1.126 rollback</command> command drops to zero once you've pushed 1.127 your changes to another repository. Rolling back a change 1.128 makes it disappear entirely, but <emphasis>only</emphasis> in 1.129 @@ -123,7 +123,7 @@ 1.130 eliminates history, there's no way for the disappearance of a 1.131 change to propagate between repositories.</para> 1.132 1.133 - <para>If you've pushed a change to another 1.134 + <para id="x_de">If you've pushed a change to another 1.135 repository&emdash;particularly if it's a shared 1.136 repository&emdash;it has essentially <quote>escaped into the 1.137 wild,</quote> and you'll have to recover from your mistake 1.138 @@ -132,7 +132,7 @@ 1.139 you pushed to, is that the changeset will reappear in your 1.140 repository.</para> 1.141 1.142 - <para>(If you absolutely know for sure that the change you want 1.143 + <para id="x_df">(If you absolutely know for sure that the change you want 1.144 to roll back is the most recent change in the repository that 1.145 you pushed to, <emphasis>and</emphasis> you know that nobody 1.146 else could have pulled it from that repository, you can roll 1.147 @@ -146,7 +146,7 @@ 1.148 <sect2> 1.149 <title>You can only roll back once</title> 1.150 1.151 - <para>Mercurial stores exactly one transaction in its 1.152 + <para id="x_e0">Mercurial stores exactly one transaction in its 1.153 transaction log; that transaction is the most recent one that 1.154 occurred in the repository. This means that you can only roll 1.155 back one transaction. If you expect to be able to roll back 1.156 @@ -155,7 +155,7 @@ 1.157 1.158 &interaction.rollback.twice; 1.159 1.160 - <para>Once you've rolled back one transaction in a repository, 1.161 + <para id="x_e1">Once you've rolled back one transaction in a repository, 1.162 you can't roll back again in that repository until you perform 1.163 another commit or pull.</para> 1.164 1.165 @@ -164,7 +164,7 @@ 1.166 <sect1> 1.167 <title>Reverting the mistaken change</title> 1.168 1.169 - <para>If you make a modification to a file, and decide that you 1.170 + <para id="x_e2">If you make a modification to a file, and decide that you 1.171 really didn't want to change the file at all, and you haven't 1.172 yet committed your changes, the <command role="hg-cmd">hg 1.173 revert</command> command is the one you'll need. It looks at 1.174 @@ -173,57 +173,57 @@ 1.175 changeset. (That's a long-winded way of saying that, in the 1.176 normal case, it undoes your modifications.)</para> 1.177 1.178 - <para>Let's illustrate how the <command role="hg-cmd">hg 1.179 + <para id="x_e3">Let's illustrate how the <command role="hg-cmd">hg 1.180 revert</command> command works with yet another small example. 1.181 We'll begin by modifying a file that Mercurial is already 1.182 tracking.</para> 1.183 1.184 &interaction.daily.revert.modify; 1.185 1.186 - <para>If we don't 1.187 + <para id="x_e4">If we don't 1.188 want that change, we can simply <command role="hg-cmd">hg 1.189 revert</command> the file.</para> 1.190 1.191 &interaction.daily.revert.unmodify; 1.192 1.193 - <para>The <command role="hg-cmd">hg revert</command> command 1.194 + <para id="x_e5">The <command role="hg-cmd">hg revert</command> command 1.195 provides us with an extra degree of safety by saving our 1.196 modified file with a <filename>.orig</filename> 1.197 extension.</para> 1.198 1.199 &interaction.daily.revert.status; 1.200 1.201 - <para>Here is a summary of the cases that the <command 1.202 + <para id="x_e6">Here is a summary of the cases that the <command 1.203 role="hg-cmd">hg revert</command> command can deal with. We 1.204 will describe each of these in more detail in the section that 1.205 follows.</para> 1.206 <itemizedlist> 1.207 - <listitem><para>If you modify a file, it will restore the file 1.208 + <listitem><para id="x_e7">If you modify a file, it will restore the file 1.209 to its unmodified state.</para> 1.210 </listitem> 1.211 - <listitem><para>If you <command role="hg-cmd">hg add</command> a 1.212 + <listitem><para id="x_e8">If you <command role="hg-cmd">hg add</command> a 1.213 file, it will undo the <quote>added</quote> state of the 1.214 file, but leave the file itself untouched.</para> 1.215 </listitem> 1.216 - <listitem><para>If you delete a file without telling Mercurial, 1.217 + <listitem><para id="x_e9">If you delete a file without telling Mercurial, 1.218 it will restore the file to its unmodified contents.</para> 1.219 </listitem> 1.220 - <listitem><para>If you use the <command role="hg-cmd">hg 1.221 + <listitem><para id="x_ea">If you use the <command role="hg-cmd">hg 1.222 remove</command> command to remove a file, it will undo 1.223 the <quote>removed</quote> state of the file, and restore 1.224 the file to its unmodified contents.</para> 1.225 </listitem></itemizedlist> 1.226 1.227 - <sect2 id="sec.undo.mgmt"> 1.228 + <sect2 id="sec:undo:mgmt"> 1.229 <title>File management errors</title> 1.230 1.231 - <para>The <command role="hg-cmd">hg revert</command> command is 1.232 + <para id="x_eb">The <command role="hg-cmd">hg revert</command> command is 1.233 useful for more than just modified files. It lets you reverse 1.234 the results of all of Mercurial's file management 1.235 commands&emdash;<command role="hg-cmd">hg add</command>, 1.236 <command role="hg-cmd">hg remove</command>, and so on.</para> 1.237 1.238 - <para>If you <command role="hg-cmd">hg add</command> a file, 1.239 + <para id="x_ec">If you <command role="hg-cmd">hg add</command> a file, 1.240 then decide that in fact you don't want Mercurial to track it, 1.241 use <command role="hg-cmd">hg revert</command> to undo the 1.242 add. Don't worry; Mercurial will not modify the file in any 1.243 @@ -231,7 +231,7 @@ 1.244 1.245 &interaction.daily.revert.add; 1.246 1.247 - <para>Similarly, if you ask Mercurial to <command 1.248 + <para id="x_ed">Similarly, if you ask Mercurial to <command 1.249 role="hg-cmd">hg remove</command> a file, you can use 1.250 <command role="hg-cmd">hg revert</command> to restore it to 1.251 the contents it had as of the parent of the working directory. 1.252 @@ -242,7 +242,7 @@ 1.253 1.254 &interaction.daily.revert.missing; 1.255 1.256 - <para>If you revert a <command role="hg-cmd">hg copy</command>, 1.257 + <para id="x_ee">If you revert a <command role="hg-cmd">hg copy</command>, 1.258 the copied-to file remains in your working directory 1.259 afterwards, untracked. Since a copy doesn't affect the 1.260 copied-from file in any way, Mercurial doesn't do anything 1.261 @@ -253,7 +253,7 @@ 1.262 <sect3> 1.263 <title>A slightly special case: reverting a rename</title> 1.264 1.265 - <para>If you <command role="hg-cmd">hg rename</command> a 1.266 + <para id="x_ef">If you <command role="hg-cmd">hg rename</command> a 1.267 file, there is one small detail that you should remember. 1.268 When you <command role="hg-cmd">hg revert</command> a 1.269 rename, it's not enough to provide the name of the 1.270 @@ -261,7 +261,7 @@ 1.271 1.272 &interaction.daily.revert.rename; 1.273 1.274 - <para>As you can see from the output of <command 1.275 + <para id="x_f0">As you can see from the output of <command 1.276 role="hg-cmd">hg status</command>, the renamed-to file is 1.277 no longer identified as added, but the 1.278 renamed-<emphasis>from</emphasis> file is still removed! 1.279 @@ -270,22 +270,22 @@ 1.280 1.281 &interaction.daily.revert.rename-orig; 1.282 1.283 - <para>So remember, to revert a <command role="hg-cmd">hg 1.284 + <para id="x_f1">So remember, to revert a <command role="hg-cmd">hg 1.285 rename</command>, you must provide 1.286 <emphasis>both</emphasis> the source and destination 1.287 names.</para> 1.288 1.289 - <para>% TODO: the output doesn't look like it will be 1.290 + <para id="x_f2">% TODO: the output doesn't look like it will be 1.291 removed!</para> 1.292 1.293 - <para>(By the way, if you rename a file, then modify the 1.294 + <para id="x_f3">(By the way, if you rename a file, then modify the 1.295 renamed-to file, then revert both components of the rename, 1.296 when Mercurial restores the file that was removed as part of 1.297 the rename, it will be unmodified. If you need the 1.298 modifications in the renamed-to file to show up in the 1.299 renamed-from file, don't forget to copy them over.)</para> 1.300 1.301 - <para>These fiddly aspects of reverting a rename arguably 1.302 + <para id="x_f4">These fiddly aspects of reverting a rename arguably 1.303 constitute a small bug in Mercurial.</para> 1.304 1.305 </sect3> 1.306 @@ -294,24 +294,24 @@ 1.307 <sect1> 1.308 <title>Dealing with committed changes</title> 1.309 1.310 - <para>Consider a case where you have committed a change $a$, and 1.311 + <para id="x_f5">Consider a case where you have committed a change $a$, and 1.312 another change $b$ on top of it; you then realise that change 1.313 $a$ was incorrect. Mercurial lets you <quote>back out</quote> 1.314 an entire changeset automatically, and building blocks that let 1.315 you reverse part of a changeset by hand.</para> 1.316 1.317 - <para>Before you read this section, here's something to keep in 1.318 - mind: the <command role="hg-cmd">hg backout</command> command 1.319 - undoes changes by <emphasis>adding</emphasis> history, not by 1.320 - modifying or erasing it. It's the right tool to use if you're 1.321 - fixing bugs, but not if you're trying to undo some change that 1.322 - has catastrophic consequences. To deal with those, see section 1.323 - <xref linkend="sec.undo.aaaiiieee"/>.</para> 1.324 + <para id="x_f6">Before you read this section, here's something to 1.325 + keep in mind: the <command role="hg-cmd">hg backout</command> 1.326 + command undoes changes by <emphasis>adding</emphasis> history, 1.327 + not by modifying or erasing it. It's the right tool to use if 1.328 + you're fixing bugs, but not if you're trying to undo some change 1.329 + that has catastrophic consequences. To deal with those, see 1.330 + <xref linkend="sec:undo:aaaiiieee"/>.</para> 1.331 1.332 <sect2> 1.333 <title>Backing out a changeset</title> 1.334 1.335 - <para>The <command role="hg-cmd">hg backout</command> command 1.336 + <para id="x_f7">The <command role="hg-cmd">hg backout</command> command 1.337 lets you <quote>undo</quote> the effects of an entire 1.338 changeset in an automated fashion. Because Mercurial's 1.339 history is immutable, this command <emphasis>does 1.340 @@ -320,14 +320,14 @@ 1.341 <emphasis>reverses</emphasis> the effect of the to-be-undone 1.342 changeset.</para> 1.343 1.344 - <para>The operation of the <command role="hg-cmd">hg 1.345 + <para id="x_f8">The operation of the <command role="hg-cmd">hg 1.346 backout</command> command is a little intricate, so let's 1.347 illustrate it with some examples. First, we'll create a 1.348 repository with some simple changes.</para> 1.349 1.350 &interaction.backout.init; 1.351 1.352 - <para>The <command role="hg-cmd">hg backout</command> command 1.353 + <para id="x_f9">The <command role="hg-cmd">hg backout</command> command 1.354 takes a single changeset ID as its argument; this is the 1.355 changeset to back out. Normally, <command role="hg-cmd">hg 1.356 backout</command> will drop you into a text editor to write 1.357 @@ -340,12 +340,12 @@ 1.358 <sect2> 1.359 <title>Backing out the tip changeset</title> 1.360 1.361 - <para>We're going to start by backing out the last changeset we 1.362 + <para id="x_fa">We're going to start by backing out the last changeset we 1.363 committed.</para> 1.364 1.365 &interaction.backout.simple; 1.366 1.367 - <para>You can see that the second line from 1.368 + <para id="x_fb">You can see that the second line from 1.369 <filename>myfile</filename> is no longer present. Taking a 1.370 look at the output of <command role="hg-cmd">hg log</command> 1.371 gives us an idea of what the <command role="hg-cmd">hg 1.372 @@ -353,51 +353,45 @@ 1.373 &interaction.backout.simple.log; Notice that the new changeset 1.374 that <command role="hg-cmd">hg backout</command> has created 1.375 is a child of the changeset we backed out. It's easier to see 1.376 - this in figure <xref 1.377 - endterm="fig.undo.backout.caption" linkend="fig.undo.backout"/>, 1.378 - which presents a graphical 1.379 - view of the change history. As you can see, the history is 1.380 - nice and linear.</para> 1.381 - 1.382 - <informalfigure id="fig.undo.backout"> 1.383 - <mediaobject> 1.384 - <imageobject><imagedata fileref="images/undo-simple.png"/> 1.385 - </imageobject> 1.386 - <textobject><phrase>XXX add text</phrase></textobject> 1.387 - <caption><para id="fig.undo.backout.caption">Backing out 1.388 - a change using the 1.389 - <command role="hg-cmd">hg backout</command> 1.390 - command</para></caption> 1.391 - </mediaobject> 1.392 - </informalfigure> 1.393 + this in <xref linkend="fig:undo:backout"/>, which presents a 1.394 + graphical view of the change history. As you can see, the 1.395 + history is nice and linear.</para> 1.396 + 1.397 + <figure id="fig:undo:backout"> 1.398 + <title>Backing out a change using the <command 1.399 + role="hg-cmd">hg backout</command> command</title> 1.400 + <mediaobject> 1.401 + <imageobject><imagedata fileref="figs/undo-simple.png"/></imageobject> 1.402 + <textobject><phrase>XXX add text</phrase></textobject> 1.403 + </mediaobject> 1.404 + </figure> 1.405 1.406 </sect2> 1.407 <sect2> 1.408 <title>Backing out a non-tip change</title> 1.409 1.410 - <para>If you want to back out a change other than the last one 1.411 + <para id="x_fd">If you want to back out a change other than the last one 1.412 you committed, pass the <option 1.413 role="hg-opt-backout">--merge</option> option to the 1.414 <command role="hg-cmd">hg backout</command> command.</para> 1.415 1.416 &interaction.backout.non-tip.clone; 1.417 1.418 - <para>This makes backing out any changeset a 1.419 + <para id="x_fe">This makes backing out any changeset a 1.420 <quote>one-shot</quote> operation that's usually simple and 1.421 fast.</para> 1.422 1.423 &interaction.backout.non-tip.backout; 1.424 1.425 - <para>If you take a look at the contents of 1.426 + <para id="x_ff">If you take a look at the contents of 1.427 <filename>myfile</filename> after the backout finishes, you'll 1.428 see that the first and third changes are present, but not the 1.429 second.</para> 1.430 1.431 &interaction.backout.non-tip.cat; 1.432 1.433 - <para>As the graphical history in figure <xref 1.434 - endterm="fig.undo.backout-non-tip.caption" 1.435 - linkend="fig.undo.backout-non-tip"/> illustrates, Mercurial 1.436 + <para id="x_100">As the graphical history in <xref 1.437 + linkend="fig:undo:backout-non-tip"/> illustrates, Mercurial 1.438 actually commits <emphasis>two</emphasis> changes in this kind 1.439 of situation (the box-shaped nodes are the ones that Mercurial 1.440 commits automatically). Before Mercurial begins the backout 1.441 @@ -407,21 +401,19 @@ 1.442 the previous parent of the working directory, and commits the 1.443 result of the merge.</para> 1.444 1.445 - <para>% TODO: to me it looks like mercurial doesn't commit the 1.446 + <para id="x_101">% TODO: to me it looks like mercurial doesn't commit the 1.447 second merge automatically!</para> 1.448 1.449 - <informalfigure id="fig.undo.backout-non-tip"> 1.450 - <mediaobject> 1.451 - <imageobject><imagedata fileref="images/undo-non-tip.png"/> 1.452 - </imageobject> 1.453 - <textobject><phrase>XXX add text</phrase></textobject> 1.454 - <caption><para id="fig.undo.backout-non-tip.caption">Automated 1.455 - backout of a non-tip change using the 1.456 - <command role="hg-cmd">hg backout</command> command</para></caption> 1.457 - </mediaobject> 1.458 - </informalfigure> 1.459 - 1.460 - <para>The result is that you end up <quote>back where you 1.461 + <figure id="fig:undo:backout-non-tip"> 1.462 + <title>Automated backout of a non-tip change using the 1.463 + <command role="hg-cmd">hg backout</command> command</title> 1.464 + <mediaobject> 1.465 + <imageobject><imagedata fileref="figs/undo-non-tip.png"/></imageobject> 1.466 + <textobject><phrase>XXX add text</phrase></textobject> 1.467 + </mediaobject> 1.468 + </figure> 1.469 + 1.470 + <para id="x_103">The result is that you end up <quote>back where you 1.471 were</quote>, only with some extra history that undoes the 1.472 effect of the changeset you wanted to back out.</para> 1.473 1.474 @@ -429,7 +421,7 @@ 1.475 <title>Always use the <option 1.476 role="hg-opt-backout">--merge</option> option</title> 1.477 1.478 - <para>In fact, since the <option 1.479 + <para id="x_104">In fact, since the <option 1.480 role="hg-opt-backout">--merge</option> option will do the 1.481 <quote>right thing</quote> whether or not the changeset 1.482 you're backing out is the tip (i.e. it won't try to merge if 1.483 @@ -442,7 +434,7 @@ 1.484 <sect2> 1.485 <title>Gaining more control of the backout process</title> 1.486 1.487 - <para>While I've recommended that you always use the <option 1.488 + <para id="x_105">While I've recommended that you always use the <option 1.489 role="hg-opt-backout">--merge</option> option when backing 1.490 out a change, the <command role="hg-cmd">hg backout</command> 1.491 command lets you decide how to merge a backout changeset. 1.492 @@ -455,13 +447,13 @@ 1.493 1.494 &interaction.backout.manual.clone; 1.495 1.496 - <para>As with our 1.497 + <para id="x_106">As with our 1.498 earlier example, We'll commit a third changeset, then back out 1.499 its parent, and see what happens.</para> 1.500 1.501 &interaction.backout.manual.backout; 1.502 1.503 - <para>Our new changeset is again a descendant of the changeset 1.504 + <para id="x_107">Our new changeset is again a descendant of the changeset 1.505 we backout out; it's thus a new head, <emphasis>not</emphasis> 1.506 a descendant of the changeset that was the tip. The <command 1.507 role="hg-cmd">hg backout</command> command was quite 1.508 @@ -469,38 +461,35 @@ 1.509 1.510 &interaction.backout.manual.log; 1.511 1.512 - <para>Again, it's easier to see what has happened by looking at 1.513 - a graph of the revision history, in figure <xref 1.514 - endterm="fig.undo.backout-manual.caption" 1.515 - linkend="fig.undo.backout-manual"/>. This makes it clear 1.516 + <para id="x_108">Again, it's easier to see what has happened by looking at 1.517 + a graph of the revision history, in <xref 1.518 + linkend="fig:undo:backout-manual"/>. This makes it clear 1.519 that when we use <command role="hg-cmd">hg backout</command> 1.520 to back out a change other than the tip, Mercurial adds a new 1.521 head to the repository (the change it committed is 1.522 box-shaped).</para> 1.523 1.524 - <informalfigure id="fig.undo.backout-manual"> 1.525 - <mediaobject> 1.526 - <imageobject><imagedata fileref="images/undo-manual.png"/> 1.527 - </imageobject> 1.528 - <textobject><phrase>XXX add text</phrase></textobject> 1.529 - <caption><para id="fig.undo.backout-manual.caption">Backing out a 1.530 - change using the <command role="hg-cmd">hg backout</command> 1.531 - command</para></caption> 1.532 - </mediaobject> 1.533 - </informalfigure> 1.534 - 1.535 - <para>After the <command role="hg-cmd">hg backout</command> 1.536 + <figure id="fig:undo:backout-manual"> 1.537 + <title>Backing out a change using the <command 1.538 + role="hg-cmd">hg backout</command> command</title> 1.539 + <mediaobject> 1.540 + <imageobject><imagedata fileref="figs/undo-manual.png"/></imageobject> 1.541 + <textobject><phrase>XXX add text</phrase></textobject> 1.542 + </mediaobject> 1.543 + </figure> 1.544 + 1.545 + <para id="x_10a">After the <command role="hg-cmd">hg backout</command> 1.546 command has completed, it leaves the new 1.547 <quote>backout</quote> changeset as the parent of the working 1.548 directory.</para> 1.549 1.550 &interaction.backout.manual.parents; 1.551 1.552 - <para>Now we have two isolated sets of changes.</para> 1.553 + <para id="x_10b">Now we have two isolated sets of changes.</para> 1.554 1.555 &interaction.backout.manual.heads; 1.556 1.557 - <para>Let's think about what we expect to see as the contents of 1.558 + <para id="x_10c">Let's think about what we expect to see as the contents of 1.559 <filename>myfile</filename> now. The first change should be 1.560 present, because we've never backed it out. The second change 1.561 should be missing, as that's the change we backed out. Since 1.562 @@ -510,68 +499,65 @@ 1.563 1.564 &interaction.backout.manual.cat; 1.565 1.566 - <para>To get the third change back into the file, we just do a 1.567 + <para id="x_10d">To get the third change back into the file, we just do a 1.568 normal merge of our two heads.</para> 1.569 1.570 &interaction.backout.manual.merge; 1.571 1.572 - <para>Afterwards, the graphical history of our repository looks 1.573 - like figure 1.574 - <xref endterm="fig.undo.backout-manual-merge.caption" 1.575 - linkend="fig.undo.backout-manual-merge"/>.</para> 1.576 - 1.577 - <informalfigure id="fig.undo.backout-manual-merge"> 1.578 - <mediaobject> 1.579 - <imageobject><imagedata fileref="images/undo-manual-merge.png"/> 1.580 - </imageobject> 1.581 - <textobject><phrase>XXX add text</phrase></textobject> 1.582 - <caption><para id="fig.undo.backout-manual-merge.caption">Manually 1.583 - merging a backout change</para></caption> 1.584 - </mediaobject> 1.585 - </informalfigure> 1.586 + <para id="x_10e">Afterwards, the graphical history of our 1.587 + repository looks like 1.588 + <xref linkend="fig:undo:backout-manual-merge"/>.</para> 1.589 + 1.590 + <figure id="fig:undo:backout-manual-merge"> 1.591 + <title>Manually merging a backout change</title> 1.592 + <mediaobject> 1.593 + <imageobject><imagedata fileref="figs/undo-manual-merge.png"/></imageobject> 1.594 + <textobject><phrase>XXX add text</phrase></textobject> 1.595 + </mediaobject> 1.596 + </figure> 1.597 1.598 </sect2> 1.599 <sect2> 1.600 <title>Why <command role="hg-cmd">hg backout</command> works as 1.601 it does</title> 1.602 1.603 - <para>Here's a brief description of how the <command 1.604 + <para id="x_110">Here's a brief description of how the <command 1.605 role="hg-cmd">hg backout</command> command works.</para> 1.606 <orderedlist> 1.607 - <listitem><para>It ensures that the working directory is 1.608 + <listitem><para id="x_111">It ensures that the working directory is 1.609 <quote>clean</quote>, i.e. that the output of <command 1.610 role="hg-cmd">hg status</command> would be empty.</para> 1.611 </listitem> 1.612 - <listitem><para>It remembers the current parent of the working 1.613 + <listitem><para id="x_112">It remembers the current parent of the working 1.614 directory. Let's call this changeset 1.615 <literal>orig</literal></para> 1.616 </listitem> 1.617 - <listitem><para>It does the equivalent of a <command 1.618 + <listitem><para id="x_113">It does the equivalent of a <command 1.619 role="hg-cmd">hg update</command> to sync the working 1.620 directory to the changeset you want to back out. Let's 1.621 call this changeset <literal>backout</literal></para> 1.622 </listitem> 1.623 - <listitem><para>It finds the parent of that changeset. Let's 1.624 + <listitem><para id="x_114">It finds the parent of that changeset. Let's 1.625 call that changeset <literal>parent</literal>.</para> 1.626 </listitem> 1.627 - <listitem><para>For each file that the 1.628 + <listitem><para id="x_115">For each file that the 1.629 <literal>backout</literal> changeset affected, it does the 1.630 equivalent of a <command role="hg-cmd">hg revert -r 1.631 parent</command> on that file, to restore it to the 1.632 contents it had before that changeset was 1.633 committed.</para> 1.634 </listitem> 1.635 - <listitem><para>It commits the result as a new changeset. 1.636 + <listitem><para id="x_116">It commits the result as a new changeset. 1.637 This changeset has <literal>backout</literal> as its 1.638 parent.</para> 1.639 </listitem> 1.640 - <listitem><para>If you specify <option 1.641 + <listitem><para id="x_117">If you specify <option 1.642 role="hg-opt-backout">--merge</option> on the command 1.643 line, it merges with <literal>orig</literal>, and commits 1.644 the result of the merge.</para> 1.645 </listitem></orderedlist> 1.646 1.647 - <para>An alternative way to implement the <command 1.648 + <para id="x_118">An alternative way to implement the <command 1.649 role="hg-cmd">hg backout</command> command would be to 1.650 <command role="hg-cmd">hg export</command> the 1.651 to-be-backed-out changeset as a diff, then use the <option 1.652 @@ -581,21 +567,21 @@ 1.653 sounds much simpler, but it would not work nearly as 1.654 well.</para> 1.655 1.656 - <para>The reason that <command role="hg-cmd">hg 1.657 + <para id="x_119">The reason that <command role="hg-cmd">hg 1.658 backout</command> does an update, a commit, a merge, and 1.659 another commit is to give the merge machinery the best chance 1.660 to do a good job when dealing with all the changes 1.661 <emphasis>between</emphasis> the change you're backing out and 1.662 the current tip.</para> 1.663 1.664 - <para>If you're backing out a changeset that's 100 revisions 1.665 + <para id="x_11a">If you're backing out a changeset that's 100 revisions 1.666 back in your project's history, the chances that the 1.667 <command>patch</command> command will be able to apply a 1.668 reverse diff cleanly are not good, because intervening changes 1.669 are likely to have <quote>broken the context</quote> that 1.670 <command>patch</command> uses to determine whether it can 1.671 apply a patch (if this sounds like gibberish, see <xref 1.672 - linkend="sec.mq.patch"/> for a 1.673 + linkend="sec:mq:patch"/> for a 1.674 discussion of the <command>patch</command> command). Also, 1.675 Mercurial's merge machinery will handle files and directories 1.676 being renamed, permission changes, and modifications to binary 1.677 @@ -604,16 +590,16 @@ 1.678 1.679 </sect2> 1.680 </sect1> 1.681 - <sect1 id="sec.undo.aaaiiieee"> 1.682 + <sect1 id="sec:undo:aaaiiieee"> 1.683 <title>Changes that should never have been</title> 1.684 1.685 - <para>Most of the time, the <command role="hg-cmd">hg 1.686 + <para id="x_11b">Most of the time, the <command role="hg-cmd">hg 1.687 backout</command> command is exactly what you need if you want 1.688 to undo the effects of a change. It leaves a permanent record 1.689 of exactly what you did, both when committing the original 1.690 changeset and when you cleaned up after it.</para> 1.691 1.692 - <para>On rare occasions, though, you may find that you've 1.693 + <para id="x_11c">On rare occasions, though, you may find that you've 1.694 committed a change that really should not be present in the 1.695 repository at all. For example, it would be very unusual, and 1.696 usually considered a mistake, to commit a software project's 1.697 @@ -622,21 +608,21 @@ 1.698 so they increase the size of the repository and the amount of 1.699 time it takes to clone or pull changes.</para> 1.700 1.701 - <para>Before I discuss the options that you have if you commit a 1.702 + <para id="x_11d">Before I discuss the options that you have if you commit a 1.703 <quote>brown paper bag</quote> change (the kind that's so bad 1.704 that you want to pull a brown paper bag over your head), let me 1.705 first discuss some approaches that probably won't work.</para> 1.706 1.707 - <para>Since Mercurial treats history as accumulative&emdash;every 1.708 - change builds on top of all changes that preceded it&emdash;you 1.709 - generally can't just make disastrous changes disappear. The one 1.710 - exception is when you've just committed a change, and it hasn't 1.711 - been pushed or pulled into another repository. That's when you 1.712 - can safely use the <command role="hg-cmd">hg rollback</command> 1.713 - command, as I detailed in section <xref 1.714 - linkend="sec.undo.rollback"/>.</para> 1.715 - 1.716 - <para>After you've pushed a bad change to another repository, you 1.717 + <para id="x_11e">Since Mercurial treats history as 1.718 + accumulative&emdash;every change builds on top of all changes 1.719 + that preceded it&emdash;you generally can't just make disastrous 1.720 + changes disappear. The one exception is when you've just 1.721 + committed a change, and it hasn't been pushed or pulled into 1.722 + another repository. That's when you can safely use the <command 1.723 + role="hg-cmd">hg rollback</command> command, as I detailed in 1.724 + <xref linkend="sec:undo:rollback"/>.</para> 1.725 + 1.726 + <para id="x_11f">After you've pushed a bad change to another repository, you 1.727 <emphasis>could</emphasis> still use <command role="hg-cmd">hg 1.728 rollback</command> to make your local copy of the change 1.729 disappear, but it won't have the consequences you want. The 1.730 @@ -644,7 +630,7 @@ 1.731 will reappear in your local repository the next time you 1.732 pull.</para> 1.733 1.734 - <para>If a situation like this arises, and you know which 1.735 + <para id="x_120">If a situation like this arises, and you know which 1.736 repositories your bad change has propagated into, you can 1.737 <emphasis>try</emphasis> to get rid of the changeefrom 1.738 <emphasis>every</emphasis> one of those repositories. This is, 1.739 @@ -652,13 +638,13 @@ 1.740 single repository while you're expunging, the change is still 1.741 <quote>in the wild</quote>, and could propagate further.</para> 1.742 1.743 - <para>If you've committed one or more changes 1.744 + <para id="x_121">If you've committed one or more changes 1.745 <emphasis>after</emphasis> the change that you'd like to see 1.746 disappear, your options are further reduced. Mercurial doesn't 1.747 provide a way to <quote>punch a hole</quote> in history, leaving 1.748 changesets intact.</para> 1.749 1.750 - <para>XXX This needs filling out. The 1.751 + <para id="x_122">XXX This needs filling out. The 1.752 <literal>hg-replay</literal> script in the 1.753 <literal>examples</literal> directory works, but doesn't handle 1.754 merge changesets. Kind of an important omission.</para> 1.755 @@ -667,15 +653,15 @@ 1.756 <title>Protect yourself from <quote>escaped</quote> 1.757 changes</title> 1.758 1.759 - <para>If you've committed some changes to your local repository 1.760 + <para id="x_123">If you've committed some changes to your local repository 1.761 and they've been pushed or pulled somewhere else, this isn't 1.762 necessarily a disaster. You can protect yourself ahead of 1.763 time against some classes of bad changeset. This is 1.764 particularly easy if your team usually pulls changes from a 1.765 central repository.</para> 1.766 1.767 - <para>By configuring some hooks on that repository to validate 1.768 - incoming changesets (see chapter <xref linkend="chap.hook"/>), 1.769 + <para id="x_124">By configuring some hooks on that repository to validate 1.770 + incoming changesets (see chapter <xref linkend="chap:hook"/>), 1.771 you can 1.772 automatically prevent some kinds of bad changeset from being 1.773 pushed to the central repository at all. With such a 1.774 @@ -684,23 +670,23 @@ 1.775 propagate into the central repository. Better yet, this 1.776 happens without any need for explicit intervention.</para> 1.777 1.778 - <para>For instance, an incoming change hook that verifies that a 1.779 + <para id="x_125">For instance, an incoming change hook that verifies that a 1.780 changeset will actually compile can prevent people from 1.781 inadvertantly <quote>breaking the build</quote>.</para> 1.782 1.783 </sect2> 1.784 </sect1> 1.785 - <sect1 id="sec.undo.bisect"> 1.786 + <sect1 id="sec:undo:bisect"> 1.787 <title>Finding the source of a bug</title> 1.788 1.789 - <para>While it's all very well to be able to back out a changeset 1.790 + <para id="x_126">While it's all very well to be able to back out a changeset 1.791 that introduced a bug, this requires that you know which 1.792 changeset to back out. Mercurial provides an invaluable 1.793 command, called <command role="hg-cmd">hg bisect</command>, that 1.794 helps you to automate this process and accomplish it very 1.795 efficiently.</para> 1.796 1.797 - <para>The idea behind the <command role="hg-cmd">hg 1.798 + <para id="x_127">The idea behind the <command role="hg-cmd">hg 1.799 bisect</command> command is that a changeset has introduced 1.800 some change of behaviour that you can identify with a simple 1.801 binary test. You don't know which piece of code introduced the 1.802 @@ -709,41 +695,41 @@ 1.803 test to direct its search for the changeset that introduced the 1.804 code that caused the bug.</para> 1.805 1.806 - <para>Here are a few scenarios to help you understand how you 1.807 + <para id="x_128">Here are a few scenarios to help you understand how you 1.808 might apply this command.</para> 1.809 <itemizedlist> 1.810 - <listitem><para>The most recent version of your software has a 1.811 + <listitem><para id="x_129">The most recent version of your software has a 1.812 bug that you remember wasn't present a few weeks ago, but 1.813 you don't know when it was introduced. Here, your binary 1.814 test checks for the presence of that bug.</para> 1.815 </listitem> 1.816 - <listitem><para>You fixed a bug in a rush, and now it's time to 1.817 + <listitem><para id="x_12a">You fixed a bug in a rush, and now it's time to 1.818 close the entry in your team's bug database. The bug 1.819 database requires a changeset ID when you close an entry, 1.820 but you don't remember which changeset you fixed the bug in. 1.821 Once again, your binary test checks for the presence of the 1.822 bug.</para> 1.823 </listitem> 1.824 - <listitem><para>Your software works correctly, but runs 15% 1.825 + <listitem><para id="x_12b">Your software works correctly, but runs 15% 1.826 slower than the last time you measured it. You want to know 1.827 which changeset introduced the performance regression. In 1.828 this case, your binary test measures the performance of your 1.829 software, to see whether it's <quote>fast</quote> or 1.830 <quote>slow</quote>.</para> 1.831 </listitem> 1.832 - <listitem><para>The sizes of the components of your project that 1.833 + <listitem><para id="x_12c">The sizes of the components of your project that 1.834 you ship exploded recently, and you suspect that something 1.835 changed in the way you build your project.</para> 1.836 </listitem></itemizedlist> 1.837 1.838 - <para>From these examples, it should be clear that the <command 1.839 + <para id="x_12d">From these examples, it should be clear that the <command 1.840 role="hg-cmd">hg bisect</command> command is not useful only 1.841 for finding the sources of bugs. You can use it to find any 1.842 <quote>emergent property</quote> of a repository (anything that 1.843 you can't find from a simple text search of the files in the 1.844 tree) for which you can write a binary test.</para> 1.845 1.846 - <para>We'll introduce a little bit of terminology here, just to 1.847 + <para id="x_12e">We'll introduce a little bit of terminology here, just to 1.848 make it clear which parts of the search process are your 1.849 responsibility, and which are Mercurial's. A 1.850 <emphasis>test</emphasis> is something that 1.851 @@ -756,7 +742,7 @@ 1.852 the <command role="hg-cmd">hg bisect</command> 1.853 command</quote>.</para> 1.854 1.855 - <para>One simple way to automate the searching process would be 1.856 + <para id="x_12f">One simple way to automate the searching process would be 1.857 simply to probe every changeset. However, this scales poorly. 1.858 If it took ten minutes to test a single changeset, and you had 1.859 10,000 changesets in your repository, the exhaustive approach 1.860 @@ -766,7 +752,7 @@ 1.861 your search to those, you'd still be looking at over 40 hours to 1.862 find the changeset that introduced your bug.</para> 1.863 1.864 - <para>What the <command role="hg-cmd">hg bisect</command> command 1.865 + <para id="x_130">What the <command role="hg-cmd">hg bisect</command> command 1.866 does is use its knowledge of the <quote>shape</quote> of your 1.867 project's revision history to perform a search in time 1.868 proportional to the <emphasis>logarithm</emphasis> of the number 1.869 @@ -777,7 +763,7 @@ 1.870 Limit your search to the last hundred changesets, and it will 1.871 take only about an hour (roughly seven tests).</para> 1.872 1.873 - <para>The <command role="hg-cmd">hg bisect</command> command is 1.874 + <para id="x_131">The <command role="hg-cmd">hg bisect</command> command is 1.875 aware of the <quote>branchy</quote> nature of a Mercurial 1.876 project's revision history, so it has no problems dealing with 1.877 branches, merges, or multiple heads in a repository. It can 1.878 @@ -788,24 +774,24 @@ 1.879 <title>Using the <command role="hg-cmd">hg bisect</command> 1.880 command</title> 1.881 1.882 - <para>Here's an example of <command role="hg-cmd">hg 1.883 + <para id="x_132">Here's an example of <command role="hg-cmd">hg 1.884 bisect</command> in action.</para> 1.885 1.886 <note> 1.887 - <para> In versions 0.9.5 and earlier of Mercurial, <command 1.888 + <para id="x_133"> In versions 0.9.5 and earlier of Mercurial, <command 1.889 role="hg-cmd">hg bisect</command> was not a core command: 1.890 it was distributed with Mercurial as an extension. This 1.891 section describes the built-in command, not the old 1.892 extension.</para> 1.893 </note> 1.894 1.895 - <para>Now let's create a repository, so that we can try out the 1.896 + <para id="x_134">Now let's create a repository, so that we can try out the 1.897 <command role="hg-cmd">hg bisect</command> command in 1.898 isolation.</para> 1.899 1.900 &interaction.bisect.init; 1.901 1.902 - <para>We'll simulate a project that has a bug in it in a 1.903 + <para id="x_135">We'll simulate a project that has a bug in it in a 1.904 simple-minded way: create trivial changes in a loop, and 1.905 nominate one specific change that will have the 1.906 <quote>bug</quote>. This loop creates 35 changesets, each 1.907 @@ -815,44 +801,44 @@ 1.908 1.909 &interaction.bisect.commits; 1.910 1.911 - <para>The next thing that we'd like to do is figure out how to 1.912 + <para id="x_136">The next thing that we'd like to do is figure out how to 1.913 use the <command role="hg-cmd">hg bisect</command> command. 1.914 We can use Mercurial's normal built-in help mechanism for 1.915 this.</para> 1.916 1.917 &interaction.bisect.help; 1.918 1.919 - <para>The <command role="hg-cmd">hg bisect</command> command 1.920 + <para id="x_137">The <command role="hg-cmd">hg bisect</command> command 1.921 works in steps. Each step proceeds as follows.</para> 1.922 <orderedlist> 1.923 - <listitem><para>You run your binary test.</para> 1.924 + <listitem><para id="x_138">You run your binary test.</para> 1.925 <itemizedlist> 1.926 - <listitem><para>If the test succeeded, you tell <command 1.927 + <listitem><para id="x_139">If the test succeeded, you tell <command 1.928 role="hg-cmd">hg bisect</command> by running the 1.929 <command role="hg-cmd">hg bisect good</command> 1.930 command.</para> 1.931 </listitem> 1.932 - <listitem><para>If it failed, run the <command 1.933 + <listitem><para id="x_13a">If it failed, run the <command 1.934 role="hg-cmd">hg bisect bad</command> 1.935 command.</para></listitem></itemizedlist> 1.936 </listitem> 1.937 - <listitem><para>The command uses your information to decide 1.938 + <listitem><para id="x_13b">The command uses your information to decide 1.939 which changeset to test next.</para> 1.940 </listitem> 1.941 - <listitem><para>It updates the working directory to that 1.942 + <listitem><para id="x_13c">It updates the working directory to that 1.943 changeset, and the process begins again.</para> 1.944 </listitem></orderedlist> 1.945 - <para>The process ends when <command role="hg-cmd">hg 1.946 + <para id="x_13d">The process ends when <command role="hg-cmd">hg 1.947 bisect</command> identifies a unique changeset that marks 1.948 the point where your test transitioned from 1.949 <quote>succeeding</quote> to <quote>failing</quote>.</para> 1.950 1.951 - <para>To start the search, we must run the <command 1.952 + <para id="x_13e">To start the search, we must run the <command 1.953 role="hg-cmd">hg bisect --reset</command> command.</para> 1.954 1.955 &interaction.bisect.search.init; 1.956 1.957 - <para>In our case, the binary test we use is simple: we check to 1.958 + <para id="x_13f">In our case, the binary test we use is simple: we check to 1.959 see if any file in the repository contains the string <quote>i 1.960 have a gub</quote>. If it does, this changeset contains the 1.961 change that <quote>caused the bug</quote>. By convention, a 1.962 @@ -860,14 +846,14 @@ 1.963 <quote>bad</quote>, while one that doesn't is 1.964 <quote>good</quote>.</para> 1.965 1.966 - <para>Most of the time, the revision to which the working 1.967 + <para id="x_140">Most of the time, the revision to which the working 1.968 directory is synced (usually the tip) already exhibits the 1.969 problem introduced by the buggy change, so we'll mark it as 1.970 <quote>bad</quote>.</para> 1.971 1.972 &interaction.bisect.search.bad-init; 1.973 1.974 - <para>Our next task is to nominate a changeset that we know 1.975 + <para id="x_141">Our next task is to nominate a changeset that we know 1.976 <emphasis>doesn't</emphasis> have the bug; the <command 1.977 role="hg-cmd">hg bisect</command> command will 1.978 <quote>bracket</quote> its search between the first pair of 1.979 @@ -877,38 +863,38 @@ 1.980 1.981 &interaction.bisect.search.good-init; 1.982 1.983 - <para>Notice that this command printed some output.</para> 1.984 + <para id="x_142">Notice that this command printed some output.</para> 1.985 <itemizedlist> 1.986 - <listitem><para>It told us how many changesets it must 1.987 + <listitem><para id="x_143">It told us how many changesets it must 1.988 consider before it can identify the one that introduced 1.989 the bug, and how many tests that will require.</para> 1.990 </listitem> 1.991 - <listitem><para>It updated the working directory to the next 1.992 + <listitem><para id="x_144">It updated the working directory to the next 1.993 changeset to test, and told us which changeset it's 1.994 testing.</para> 1.995 </listitem></itemizedlist> 1.996 1.997 - <para>We now run our test in the working directory. We use the 1.998 + <para id="x_145">We now run our test in the working directory. We use the 1.999 <command>grep</command> command to see if our 1.1000 <quote>bad</quote> file is present in the working directory. 1.1001 If it is, this revision is bad; if not, this revision is good. 1.1002 &interaction.bisect.search.step1;</para> 1.1003 1.1004 - <para>This test looks like a perfect candidate for automation, 1.1005 + <para id="x_146">This test looks like a perfect candidate for automation, 1.1006 so let's turn it into a shell function.</para> 1.1007 &interaction.bisect.search.mytest; 1.1008 1.1009 - <para>We can now run an entire test step with a single command, 1.1010 + <para id="x_147">We can now run an entire test step with a single command, 1.1011 <literal>mytest</literal>.</para> 1.1012 1.1013 &interaction.bisect.search.step2; 1.1014 1.1015 - <para>A few more invocations of our canned test step command, 1.1016 + <para id="x_148">A few more invocations of our canned test step command, 1.1017 and we're done.</para> 1.1018 1.1019 &interaction.bisect.search.rest; 1.1020 1.1021 - <para>Even though we had 40 changesets to search through, the 1.1022 + <para id="x_149">Even though we had 40 changesets to search through, the 1.1023 <command role="hg-cmd">hg bisect</command> command let us find 1.1024 the changeset that introduced our <quote>bug</quote> with only 1.1025 five tests. Because the number of tests that the <command 1.1026 @@ -921,7 +907,7 @@ 1.1027 <sect2> 1.1028 <title>Cleaning up after your search</title> 1.1029 1.1030 - <para>When you're finished using the <command role="hg-cmd">hg 1.1031 + <para id="x_14a">When you're finished using the <command role="hg-cmd">hg 1.1032 bisect</command> command in a repository, you can use the 1.1033 <command role="hg-cmd">hg bisect reset</command> command to 1.1034 drop the information it was using to drive your search. The 1.1035 @@ -941,7 +927,7 @@ 1.1036 <sect2> 1.1037 <title>Give consistent input</title> 1.1038 1.1039 - <para>The <command role="hg-cmd">hg bisect</command> command 1.1040 + <para id="x_14b">The <command role="hg-cmd">hg bisect</command> command 1.1041 requires that you correctly report the result of every test 1.1042 you perform. If you tell it that a test failed when it really 1.1043 succeeded, it <emphasis>might</emphasis> be able to detect the 1.1044 @@ -955,7 +941,7 @@ 1.1045 <sect2> 1.1046 <title>Automate as much as possible</title> 1.1047 1.1048 - <para>When I started using the <command role="hg-cmd">hg 1.1049 + <para id="x_14c">When I started using the <command role="hg-cmd">hg 1.1050 bisect</command> command, I tried a few times to run my 1.1051 tests by hand, on the command line. This is an approach that 1.1052 I, at least, am not suited to. After a few tries, I found 1.1053 @@ -963,7 +949,7 @@ 1.1054 my searches several times before finally getting correct 1.1055 results.</para> 1.1056 1.1057 - <para>My initial problems with driving the <command 1.1058 + <para id="x_14d">My initial problems with driving the <command 1.1059 role="hg-cmd">hg bisect</command> command by hand occurred 1.1060 even with simple searches on small repositories; if the 1.1061 problem you're looking for is more subtle, or the number of 1.1062 @@ -972,14 +958,14 @@ 1.1063 the search is much higher. Once I started automating my 1.1064 tests, I had much better results.</para> 1.1065 1.1066 - <para>The key to automated testing is twofold:</para> 1.1067 + <para id="x_14e">The key to automated testing is twofold:</para> 1.1068 <itemizedlist> 1.1069 - <listitem><para>always test for the same symptom, and</para> 1.1070 - </listitem> 1.1071 - <listitem><para>always feed consistent input to the <command 1.1072 + <listitem><para id="x_14f">always test for the same symptom, and</para> 1.1073 + </listitem> 1.1074 + <listitem><para id="x_150">always feed consistent input to the <command 1.1075 role="hg-cmd">hg bisect</command> command.</para> 1.1076 </listitem></itemizedlist> 1.1077 - <para>In my tutorial example above, the <command>grep</command> 1.1078 + <para id="x_151">In my tutorial example above, the <command>grep</command> 1.1079 command tests for the symptom, and the <literal>if</literal> 1.1080 statement takes the result of this check and ensures that we 1.1081 always feed the same input to the <command role="hg-cmd">hg 1.1082 @@ -991,21 +977,21 @@ 1.1083 <sect2> 1.1084 <title>Check your results</title> 1.1085 1.1086 - <para>Because the output of a <command role="hg-cmd">hg 1.1087 + <para id="x_152">Because the output of a <command role="hg-cmd">hg 1.1088 bisect</command> search is only as good as the input you 1.1089 give it, don't take the changeset it reports as the absolute 1.1090 truth. A simple way to cross-check its report is to manually 1.1091 run your test at each of the following changesets:</para> 1.1092 <itemizedlist> 1.1093 - <listitem><para>The changeset that it reports as the first bad 1.1094 + <listitem><para id="x_153">The changeset that it reports as the first bad 1.1095 revision. Your test should still report this as 1.1096 bad.</para> 1.1097 </listitem> 1.1098 - <listitem><para>The parent of that changeset (either parent, 1.1099 + <listitem><para id="x_154">The parent of that changeset (either parent, 1.1100 if it's a merge). Your test should report this changeset 1.1101 as good.</para> 1.1102 </listitem> 1.1103 - <listitem><para>A child of that changeset. Your test should 1.1104 + <listitem><para id="x_155">A child of that changeset. Your test should 1.1105 report this changeset as bad.</para> 1.1106 </listitem></itemizedlist> 1.1107 1.1108 @@ -1013,7 +999,7 @@ 1.1109 <sect2> 1.1110 <title>Beware interference between bugs</title> 1.1111 1.1112 - <para>It's possible that your search for one bug could be 1.1113 + <para id="x_156">It's possible that your search for one bug could be 1.1114 disrupted by the presence of another. For example, let's say 1.1115 your software crashes at revision 100, and worked correctly at 1.1116 revision 50. Unknown to you, someone else introduced a 1.1117 @@ -1021,7 +1007,7 @@ 1.1118 revision 80. This could distort your results in one of 1.1119 several ways.</para> 1.1120 1.1121 - <para>It is possible that this other bug completely 1.1122 + <para id="x_157">It is possible that this other bug completely 1.1123 <quote>masks</quote> yours, which is to say that it occurs 1.1124 before your bug has a chance to manifest itself. If you can't 1.1125 avoid that other bug (for example, it prevents your project 1.1126 @@ -1031,14 +1017,14 @@ 1.1127 you can mark a changeset as untested by running <command 1.1128 role="hg-cmd">hg bisect --skip</command>.</para> 1.1129 1.1130 - <para>A different problem could arise if your test for a bug's 1.1131 + <para id="x_158">A different problem could arise if your test for a bug's 1.1132 presence is not specific enough. If you check for <quote>my 1.1133 program crashes</quote>, then both your crashing bug and an 1.1134 unrelated crashing bug that masks it will look like the same 1.1135 thing, and mislead <command role="hg-cmd">hg 1.1136 bisect</command>.</para> 1.1137 1.1138 - <para>Another useful situation in which to use <command 1.1139 + <para id="x_159">Another useful situation in which to use <command 1.1140 role="hg-cmd">hg bisect --skip</command> is if you can't 1.1141 test a revision because your project was in a broken and hence 1.1142 untestable state at that revision, perhaps because someone 1.1143 @@ -1049,7 +1035,7 @@ 1.1144 <sect2> 1.1145 <title>Bracket your search lazily</title> 1.1146 1.1147 - <para>Choosing the first <quote>good</quote> and 1.1148 + <para id="x_15a">Choosing the first <quote>good</quote> and 1.1149 <quote>bad</quote> changesets that will mark the end points of 1.1150 your search is often easy, but it bears a little discussion 1.1151 nevertheless. From the perspective of <command 1.1152 @@ -1057,7 +1043,7 @@ 1.1153 changeset is conventionally <quote>bad</quote>, and the older 1.1154 changeset is <quote>good</quote>.</para> 1.1155 1.1156 - <para>If you're having trouble remembering when a suitable 1.1157 + <para id="x_15b">If you're having trouble remembering when a suitable 1.1158 <quote>good</quote> change was, so that you can tell <command 1.1159 role="hg-cmd">hg bisect</command>, you could do worse than 1.1160 testing changesets at random. Just remember to eliminate 1.1161 @@ -1066,7 +1052,7 @@ 1.1162 where another problem masks the bug (as I discussed 1.1163 above).</para> 1.1164 1.1165 - <para>Even if you end up <quote>early</quote> by thousands of 1.1166 + <para id="x_15c">Even if you end up <quote>early</quote> by thousands of 1.1167 changesets or months of history, you will only add a handful 1.1168 of tests to the total number that <command role="hg-cmd">hg 1.1169 bisect</command> must perform, thanks to its logarithmic