Mercurial > hgbook
annotate en/ch09-undo.xml @ 658:b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Wed, 18 Feb 2009 00:22:09 -0800 |
parents | |
children | 8fcd44708f41 |
rev | line source |
---|---|
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
2 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
3 <chapter id="chap:undo"> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
4 <title>Finding and fixing your mistakes</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
5 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
6 <para>To err might be human, but to really handle the consequences |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
7 well takes a top-notch revision control system. In this chapter, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
8 we'll discuss some of the techniques you can use when you find |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
9 that a problem has crept into your project. Mercurial has some |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
10 highly capable features that will help you to isolate the sources |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
11 of problems, and to handle them appropriately.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
12 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
13 <sect1> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
14 <title>Erasing local history</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
15 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
16 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
17 <title>The accidental commit</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
18 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
19 <para>I have the occasional but persistent problem of typing |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
20 rather more quickly than I can think, which sometimes results |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
21 in me committing a changeset that is either incomplete or |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
22 plain wrong. In my case, the usual kind of incomplete |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
23 changeset is one in which I've created a new source file, but |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
24 forgotten to <command role="hg-cmd">hg add</command> it. A |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
25 <quote>plain wrong</quote> changeset is not as common, but no |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
26 less annoying.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
27 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
28 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
29 <sect2 id="sec:undo:rollback"> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
30 <title>Rolling back a transaction</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
31 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
32 <para>In section <xref linkend="sec:concepts:txn"/>, I mentioned |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
33 that Mercurial treats each modification of a repository as a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
34 <emphasis>transaction</emphasis>. Every time you commit a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
35 changeset or pull changes from another repository, Mercurial |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
36 remembers what you did. You can undo, or <emphasis>roll |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
37 back</emphasis>, exactly one of these actions using the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
38 <command role="hg-cmd">hg rollback</command> command. (See |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
39 section <xref linkend="sec:undo:rollback-after-push"/> for an |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
40 important caveat about the use of this command.)</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
41 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
42 <para>Here's a mistake that I often find myself making: |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
43 committing a change in which I've created a new file, but |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
44 forgotten to <command role="hg-cmd">hg add</command> it. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
45 &interaction.rollback.commit; --> Looking at the output of |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
46 <command role="hg-cmd">hg status</command> after the commit |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
47 immediately confirms the error. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
48 &interaction.rollback.status; --> The commit captured the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
49 changes to the file <filename>a</filename>, but not the new |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
50 file <filename>b</filename>. If I were to push this changeset |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
51 to a repository that I shared with a colleague, the chances |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
52 are high that something in <filename>a</filename> would refer |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
53 to <filename>b</filename>, which would not be present in their |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
54 repository when they pulled my changes. I would thus become |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
55 the object of some indignation.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
56 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
57 <para>However, luck is with me&emdash;I've caught my error |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
58 before I pushed the changeset. I use the <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
59 role="hg-cmd">hg rollback</command> command, and Mercurial |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
60 makes that last changeset vanish. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
61 &interaction.rollback.rollback; --> Notice that the changeset |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
62 is no longer present in the repository's history, and the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
63 working directory once again thinks that the file |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
64 <filename>a</filename> is modified. The commit and rollback |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
65 have left the working directory exactly as it was prior to the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
66 commit; the changeset has been completely erased. I can now |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
67 safely <command role="hg-cmd">hg add</command> the file |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
68 <filename>b</filename>, and rerun my commit. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
69 &interaction.rollback.add; --></para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
70 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
71 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
72 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
73 <title>The erroneous pull</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
74 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
75 <para>It's common practice with Mercurial to maintain separate |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
76 development branches of a project in different repositories. |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
77 Your development team might have one shared repository for |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
78 your project's <quote>0.9</quote> release, and another, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
79 containing different changes, for the <quote>1.0</quote> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
80 release.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
81 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
82 <para>Given this, you can imagine that the consequences could be |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
83 messy if you had a local <quote>0.9</quote> repository, and |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
84 accidentally pulled changes from the shared <quote>1.0</quote> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
85 repository into it. At worst, you could be paying |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
86 insufficient attention, and push those changes into the shared |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
87 <quote>0.9</quote> tree, confusing your entire team (but don't |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
88 worry, we'll return to this horror scenario later). However, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
89 it's more likely that you'll notice immediately, because |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
90 Mercurial will display the URL it's pulling from, or you will |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
91 see it pull a suspiciously large number of changes into the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
92 repository.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
93 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
94 <para>The <command role="hg-cmd">hg rollback</command> command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
95 will work nicely to expunge all of the changesets that you |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
96 just pulled. Mercurial groups all changes from one <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
97 role="hg-cmd">hg pull</command> into a single transaction, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
98 so one <command role="hg-cmd">hg rollback</command> is all you |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
99 need to undo this mistake.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
100 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
101 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
102 <sect2 id="sec:undo:rollback-after-push"> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
103 <title>Rolling back is useless once you've pushed</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
104 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
105 <para>The value of the <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
106 rollback</command> command drops to zero once you've pushed |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
107 your changes to another repository. Rolling back a change |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
108 makes it disappear entirely, but <emphasis>only</emphasis> in |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
109 the repository in which you perform the <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
110 role="hg-cmd">hg rollback</command>. Because a rollback |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
111 eliminates history, there's no way for the disappearance of a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
112 change to propagate between repositories.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
113 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
114 <para>If you've pushed a change to another |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
115 repository&emdash;particularly if it's a shared |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
116 repository&emdash;it has essentially <quote>escaped into the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
117 wild,</quote> and you'll have to recover from your mistake |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
118 in a different way. What will happen if you push a changeset |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
119 somewhere, then roll it back, then pull from the repository |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
120 you pushed to, is that the changeset will reappear in your |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
121 repository.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
122 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
123 <para>(If you absolutely know for sure that the change you want |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
124 to roll back is the most recent change in the repository that |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
125 you pushed to, <emphasis>and</emphasis> you know that nobody |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
126 else could have pulled it from that repository, you can roll |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
127 back the changeset there, too, but you really should really |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
128 not rely on this working reliably. If you do this, sooner or |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
129 later a change really will make it into a repository that you |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
130 don't directly control (or have forgotten about), and come |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
131 back to bite you.)</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
132 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
133 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
134 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
135 <title>You can only roll back once</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
136 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
137 <para>Mercurial stores exactly one transaction in its |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
138 transaction log; that transaction is the most recent one that |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
139 occurred in the repository. This means that you can only roll |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
140 back one transaction. If you expect to be able to roll back |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
141 one transaction, then its predecessor, this is not the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
142 behaviour you will get. <!-- &interaction.rollback.twice; --> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
143 Once you've rolled back one transaction in a repository, you |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
144 can't roll back again in that repository until you perform |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
145 another commit or pull.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
146 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
147 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
148 </sect1> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
149 <sect1> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
150 <title>Reverting the mistaken change</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
151 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
152 <para>If you make a modification to a file, and decide that you |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
153 really didn't want to change the file at all, and you haven't |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
154 yet committed your changes, the <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
155 revert</command> command is the one you'll need. It looks at |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
156 the changeset that's the parent of the working directory, and |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
157 restores the contents of the file to their state as of that |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
158 changeset. (That's a long-winded way of saying that, in the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
159 normal case, it undoes your modifications.)</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
160 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
161 <para>Let's illustrate how the <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
162 revert</command> command works with yet another small example. |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
163 We'll begin by modifying a file that Mercurial is already |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
164 tracking. <!-- &interaction.daily.revert.modify; --> If we don't |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
165 want that change, we can simply <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
166 revert</command> the file. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
167 &interaction.daily.revert.unmodify; --> The <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
168 role="hg-cmd">hg revert</command> command provides us with an |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
169 extra degree of safety by saving our modified file with a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
170 <filename>.orig</filename> extension. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
171 &interaction.daily.revert.status; --></para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
172 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
173 <para>Here is a summary of the cases that the <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
174 role="hg-cmd">hg revert</command> command can deal with. We |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
175 will describe each of these in more detail in the section that |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
176 follows.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
177 <itemizedlist> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
178 <listitem><para>If you modify a file, it will restore the file |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
179 to its unmodified state.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
180 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
181 <listitem><para>If you <command role="hg-cmd">hg add</command> a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
182 file, it will undo the <quote>added</quote> state of the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
183 file, but leave the file itself untouched.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
184 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
185 <listitem><para>If you delete a file without telling Mercurial, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
186 it will restore the file to its unmodified contents.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
187 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
188 <listitem><para>If you use the <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
189 remove</command> command to remove a file, it will undo |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
190 the <quote>removed</quote> state of the file, and restore |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
191 the file to its unmodified contents.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
192 </listitem></itemizedlist> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
193 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
194 <sect2 id="sec:undo:mgmt"> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
195 <title>File management errors</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
196 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
197 <para>The <command role="hg-cmd">hg revert</command> command is |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
198 useful for more than just modified files. It lets you reverse |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
199 the results of all of Mercurial's file management |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
200 commands&emdash;<command role="hg-cmd">hg add</command>, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
201 <command role="hg-cmd">hg remove</command>, and so on.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
202 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
203 <para>If you <command role="hg-cmd">hg add</command> a file, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
204 then decide that in fact you don't want Mercurial to track it, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
205 use <command role="hg-cmd">hg revert</command> to undo the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
206 add. Don't worry; Mercurial will not modify the file in any |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
207 way. It will just <quote>unmark</quote> the file. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
208 &interaction.daily.revert.add; --></para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
209 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
210 <para>Similarly, if you ask Mercurial to <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
211 role="hg-cmd">hg remove</command> a file, you can use |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
212 <command role="hg-cmd">hg revert</command> to restore it to |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
213 the contents it had as of the parent of the working directory. |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
214 <!-- &interaction.daily.revert.remove; --> This works just as |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
215 well for a file that you deleted by hand, without telling |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
216 Mercurial (recall that in Mercurial terminology, this kind of |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
217 file is called <quote>missing</quote>). <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
218 &interaction.daily.revert.missing; --></para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
219 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
220 <para>If you revert a <command role="hg-cmd">hg copy</command>, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
221 the copied-to file remains in your working directory |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
222 afterwards, untracked. Since a copy doesn't affect the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
223 copied-from file in any way, Mercurial doesn't do anything |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
224 with the copied-from file. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
225 &interaction.daily.revert.copy; --></para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
226 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
227 <sect3> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
228 <title>A slightly special case: reverting a rename</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
229 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
230 <para>If you <command role="hg-cmd">hg rename</command> a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
231 file, there is one small detail that you should remember. |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
232 When you <command role="hg-cmd">hg revert</command> a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
233 rename, it's not enough to provide the name of the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
234 renamed-to file, as you can see here. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
235 &interaction.daily.revert.rename; --> As you can see from |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
236 the output of <command role="hg-cmd">hg status</command>, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
237 the renamed-to file is no longer identified as added, but |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
238 the renamed-<emphasis>from</emphasis> file is still removed! |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
239 This is counter-intuitive (at least to me), but at least |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
240 it's easy to deal with. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
241 &interaction.daily.revert.rename-orig; --> So remember, to |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
242 revert a <command role="hg-cmd">hg rename</command>, you |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
243 must provide <emphasis>both</emphasis> the source and |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
244 destination names.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
245 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
246 <para>% TODO: the output doesn't look like it will be |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
247 removed!</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
248 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
249 <para>(By the way, if you rename a file, then modify the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
250 renamed-to file, then revert both components of the rename, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
251 when Mercurial restores the file that was removed as part of |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
252 the rename, it will be unmodified. If you need the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
253 modifications in the renamed-to file to show up in the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
254 renamed-from file, don't forget to copy them over.)</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
255 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
256 <para>These fiddly aspects of reverting a rename arguably |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
257 constitute a small bug in Mercurial.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
258 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
259 </sect3> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
260 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
261 </sect1> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
262 <sect1> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
263 <title>Dealing with committed changes</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
264 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
265 <para>Consider a case where you have committed a change $a$, and |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
266 another change $b$ on top of it; you then realise that change |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
267 $a$ was incorrect. Mercurial lets you <quote>back out</quote> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
268 an entire changeset automatically, and building blocks that let |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
269 you reverse part of a changeset by hand.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
270 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
271 <para>Before you read this section, here's something to keep in |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
272 mind: the <command role="hg-cmd">hg backout</command> command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
273 undoes changes by <emphasis>adding</emphasis> history, not by |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
274 modifying or erasing it. It's the right tool to use if you're |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
275 fixing bugs, but not if you're trying to undo some change that |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
276 has catastrophic consequences. To deal with those, see section |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
277 <xref linkend="sec:undo:aaaiiieee"/>.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
278 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
279 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
280 <title>Backing out a changeset</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
281 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
282 <para>The <command role="hg-cmd">hg backout</command> command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
283 lets you <quote>undo</quote> the effects of an entire |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
284 changeset in an automated fashion. Because Mercurial's |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
285 history is immutable, this command <emphasis>does |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
286 not</emphasis> get rid of the changeset you want to undo. |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
287 Instead, it creates a new changeset that |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
288 <emphasis>reverses</emphasis> the effect of the to-be-undone |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
289 changeset.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
290 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
291 <para>The operation of the <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
292 backout</command> command is a little intricate, so let's |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
293 illustrate it with some examples. First, we'll create a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
294 repository with some simple changes. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
295 &interaction.backout.init; --></para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
296 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
297 <para>The <command role="hg-cmd">hg backout</command> command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
298 takes a single changeset ID as its argument; this is the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
299 changeset to back out. Normally, <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
300 backout</command> will drop you into a text editor to write |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
301 a commit message, so you can record why you're backing the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
302 change out. In this example, we provide a commit message on |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
303 the command line using the <option |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
304 role="hg-opt-backout">-m</option> option.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
305 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
306 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
307 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
308 <title>Backing out the tip changeset</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
309 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
310 <para>We're going to start by backing out the last changeset we |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
311 committed. <!-- &interaction.backout.simple; --> You can see |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
312 that the second line from <filename>myfile</filename> is no |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
313 longer present. Taking a look at the output of <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
314 role="hg-cmd">hg log</command> gives us an idea of what the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
315 <command role="hg-cmd">hg backout</command> command has done. |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
316 <!-- &interaction.backout.simple.log; --> Notice that the new |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
317 changeset that <command role="hg-cmd">hg backout</command> has |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
318 created is a child of the changeset we backed out. It's |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
319 easier to see this in figure <xref |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
320 linkend="fig:undo:backout"/>, which presents a graphical |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
321 view of the change history. As you can see, the history is |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
322 nice and linear.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
323 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
324 <informalfigure id="fig:undo:backout"> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
325 <mediaobject><imageobject><imagedata |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
326 fileref="undo-simple"/></imageobject><textobject><phrase>XXX |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
327 add text</phrase></textobject><caption><para>Backing out |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
328 a change using the <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
329 backout</command> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
330 command</para></caption></mediaobject> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
331 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
332 </informalfigure> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
333 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
334 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
335 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
336 <title>Backing out a non-tip change</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
337 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
338 <para>If you want to back out a change other than the last one |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
339 you committed, pass the <option |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
340 role="hg-opt-backout">--merge</option> option to the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
341 <command role="hg-cmd">hg backout</command> command. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
342 &interaction.backout.non-tip.clone; --> This makes backing out |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
343 any changeset a <quote>one-shot</quote> operation that's |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
344 usually simple and fast. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
345 &interaction.backout.non-tip.backout; --></para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
346 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
347 <para>If you take a look at the contents of |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
348 <filename>myfile</filename> after the backout finishes, you'll |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
349 see that the first and third changes are present, but not the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
350 second. <!-- &interaction.backout.non-tip.cat; --></para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
351 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
352 <para>As the graphical history in figure <xref |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
353 linkend="fig:undo:backout-non-tip"/> illustrates, Mercurial |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
354 actually commits <emphasis>two</emphasis> changes in this kind |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
355 of situation (the box-shaped nodes are the ones that Mercurial |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
356 commits automatically). Before Mercurial begins the backout |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
357 process, it first remembers what the current parent of the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
358 working directory is. It then backs out the target changeset, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
359 and commits that as a changeset. Finally, it merges back to |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
360 the previous parent of the working directory, and commits the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
361 result of the merge.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
362 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
363 <para>% TODO: to me it looks like mercurial doesn't commit the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
364 second merge automatically!</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
365 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
366 <informalfigure id="fig:undo:backout-non-tip"> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
367 <mediaobject><imageobject><imagedata |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
368 fileref="undo-non-tip"/></imageobject><textobject><phrase>XXX |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
369 add text</phrase></textobject><caption><para>Automated |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
370 backout of a non-tip change using the <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
371 role="hg-cmd">hg backout</command> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
372 command</para></caption></mediaobject> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
373 </informalfigure> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
374 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
375 <para>The result is that you end up <quote>back where you |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
376 were</quote>, only with some extra history that undoes the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
377 effect of the changeset you wanted to back out.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
378 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
379 <sect3> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
380 <title>Always use the <option |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
381 role="hg-opt-backout">--merge</option> option</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
382 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
383 <para>In fact, since the <option |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
384 role="hg-opt-backout">--merge</option> option will do the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
385 <quote>right thing</quote> whether or not the changeset |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
386 you're backing out is the tip (i.e. it won't try to merge if |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
387 it's backing out the tip, since there's no need), you should |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
388 <emphasis>always</emphasis> use this option when you run the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
389 <command role="hg-cmd">hg backout</command> command.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
390 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
391 </sect3> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
392 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
393 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
394 <title>Gaining more control of the backout process</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
395 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
396 <para>While I've recommended that you always use the <option |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
397 role="hg-opt-backout">--merge</option> option when backing |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
398 out a change, the <command role="hg-cmd">hg backout</command> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
399 command lets you decide how to merge a backout changeset. |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
400 Taking control of the backout process by hand is something you |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
401 will rarely need to do, but it can be useful to understand |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
402 what the <command role="hg-cmd">hg backout</command> command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
403 is doing for you automatically. To illustrate this, let's |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
404 clone our first repository, but omit the backout change that |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
405 it contains.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
406 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
407 <para><!-- &interaction.backout.manual.clone; --> As with our |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
408 earlier example, We'll commit a third changeset, then back out |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
409 its parent, and see what happens. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
410 &interaction.backout.manual.backout; --> Our new changeset is |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
411 again a descendant of the changeset we backout out; it's thus |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
412 a new head, <emphasis>not</emphasis> a descendant of the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
413 changeset that was the tip. The <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
414 backout</command> command was quite explicit in telling us |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
415 this. <!-- &interaction.backout.manual.log; --></para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
416 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
417 <para>Again, it's easier to see what has happened by looking at |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
418 a graph of the revision history, in figure <xref |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
419 linkend="fig:undo:backout-manual"/>. This makes it clear |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
420 that when we use <command role="hg-cmd">hg backout</command> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
421 to back out a change other than the tip, Mercurial adds a new |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
422 head to the repository (the change it committed is |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
423 box-shaped).</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
424 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
425 <informalfigure id="fig:undo:backout-manual"> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
426 <mediaobject><imageobject><imagedata |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
427 fileref="undo-manual"/></imageobject><textobject><phrase>XXX |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
428 add text</phrase></textobject><caption><para>Backing out |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
429 a change using the <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
430 backout</command> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
431 command</para></caption></mediaobject> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
432 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
433 </informalfigure> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
434 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
435 <para>After the <command role="hg-cmd">hg backout</command> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
436 command has completed, it leaves the new |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
437 <quote>backout</quote> changeset as the parent of the working |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
438 directory. <!-- &interaction.backout.manual.parents; --> Now |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
439 we have two isolated sets of changes. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
440 &interaction.backout.manual.heads; --></para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
441 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
442 <para>Let's think about what we expect to see as the contents of |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
443 <filename>myfile</filename> now. The first change should be |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
444 present, because we've never backed it out. The second change |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
445 should be missing, as that's the change we backed out. Since |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
446 the history graph shows the third change as a separate head, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
447 we <emphasis>don't</emphasis> expect to see the third change |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
448 present in <filename>myfile</filename>. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
449 &interaction.backout.manual.cat; --> To get the third change |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
450 back into the file, we just do a normal merge of our two |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
451 heads. <!-- &interaction.backout.manual.merge; --> Afterwards, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
452 the graphical history of our repository looks like figure |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
453 <xref linkend="fig:undo:backout-manual-merge"/>.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
454 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
455 <informalfigure id="fig:undo:backout-manual-merge"> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
456 <mediaobject><imageobject><imagedata |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
457 fileref="undo-manual-merge"/></imageobject><textobject><phrase>XXX |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
458 add text</phrase></textobject><caption><para>Manually |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
459 merging a backout change</para></caption></mediaobject> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
460 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
461 </informalfigure> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
462 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
463 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
464 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
465 <title>Why <command role="hg-cmd">hg backout</command> works as |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
466 it does</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
467 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
468 <para>Here's a brief description of how the <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
469 role="hg-cmd">hg backout</command> command works.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
470 <orderedlist> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
471 <listitem><para>It ensures that the working directory is |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
472 <quote>clean</quote>, i.e. that the output of <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
473 role="hg-cmd">hg status</command> would be empty.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
474 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
475 <listitem><para>It remembers the current parent of the working |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
476 directory. Let's call this changeset |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
477 <literal>orig</literal></para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
478 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
479 <listitem><para>It does the equivalent of a <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
480 role="hg-cmd">hg update</command> to sync the working |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
481 directory to the changeset you want to back out. Let's |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
482 call this changeset <literal>backout</literal></para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
483 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
484 <listitem><para>It finds the parent of that changeset. Let's |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
485 call that changeset <literal>parent</literal>.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
486 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
487 <listitem><para>For each file that the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
488 <literal>backout</literal> changeset affected, it does the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
489 equivalent of a <command role="hg-cmd">hg revert -r |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
490 parent</command> on that file, to restore it to the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
491 contents it had before that changeset was |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
492 committed.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
493 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
494 <listitem><para>It commits the result as a new changeset. |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
495 This changeset has <literal>backout</literal> as its |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
496 parent.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
497 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
498 <listitem><para>If you specify <option |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
499 role="hg-opt-backout">--merge</option> on the command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
500 line, it merges with <literal>orig</literal>, and commits |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
501 the result of the merge.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
502 </listitem></orderedlist> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
503 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
504 <para>An alternative way to implement the <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
505 role="hg-cmd">hg backout</command> command would be to |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
506 <command role="hg-cmd">hg export</command> the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
507 to-be-backed-out changeset as a diff, then use the <option |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
508 role="cmd-opt-patch">--reverse</option> option to the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
509 <command>patch</command> command to reverse the effect of the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
510 change without fiddling with the working directory. This |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
511 sounds much simpler, but it would not work nearly as |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
512 well.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
513 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
514 <para>The reason that <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
515 backout</command> does an update, a commit, a merge, and |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
516 another commit is to give the merge machinery the best chance |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
517 to do a good job when dealing with all the changes |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
518 <emphasis>between</emphasis> the change you're backing out and |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
519 the current tip.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
520 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
521 <para>If you're backing out a changeset that's 100 revisions |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
522 back in your project's history, the chances that the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
523 <command>patch</command> command will be able to apply a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
524 reverse diff cleanly are not good, because intervening changes |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
525 are likely to have <quote>broken the context</quote> that |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
526 <command>patch</command> uses to determine whether it can |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
527 apply a patch (if this sounds like gibberish, see <xref |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
528 linkend="sec:mq:patch"/> for a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
529 discussion of the <command>patch</command> command). Also, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
530 Mercurial's merge machinery will handle files and directories |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
531 being renamed, permission changes, and modifications to binary |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
532 files, none of which <command>patch</command> can deal |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
533 with.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
534 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
535 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
536 </sect1> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
537 <sect1 id="sec:undo:aaaiiieee"> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
538 <title>Changes that should never have been</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
539 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
540 <para>Most of the time, the <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
541 backout</command> command is exactly what you need if you want |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
542 to undo the effects of a change. It leaves a permanent record |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
543 of exactly what you did, both when committing the original |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
544 changeset and when you cleaned up after it.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
545 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
546 <para>On rare occasions, though, you may find that you've |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
547 committed a change that really should not be present in the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
548 repository at all. For example, it would be very unusual, and |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
549 usually considered a mistake, to commit a software project's |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
550 object files as well as its source files. Object files have |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
551 almost no intrinsic value, and they're <emphasis>big</emphasis>, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
552 so they increase the size of the repository and the amount of |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
553 time it takes to clone or pull changes.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
554 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
555 <para>Before I discuss the options that you have if you commit a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
556 <quote>brown paper bag</quote> change (the kind that's so bad |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
557 that you want to pull a brown paper bag over your head), let me |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
558 first discuss some approaches that probably won't work.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
559 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
560 <para>Since Mercurial treats history as accumulative&emdash;every |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
561 change builds on top of all changes that preceded it&emdash;you |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
562 generally can't just make disastrous changes disappear. The one |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
563 exception is when you've just committed a change, and it hasn't |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
564 been pushed or pulled into another repository. That's when you |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
565 can safely use the <command role="hg-cmd">hg rollback</command> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
566 command, as I detailed in section <xref |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
567 linkend="sec:undo:rollback"/>.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
568 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
569 <para>After you've pushed a bad change to another repository, you |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
570 <emphasis>could</emphasis> still use <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
571 rollback</command> to make your local copy of the change |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
572 disappear, but it won't have the consequences you want. The |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
573 change will still be present in the remote repository, so it |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
574 will reappear in your local repository the next time you |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
575 pull.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
576 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
577 <para>If a situation like this arises, and you know which |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
578 repositories your bad change has propagated into, you can |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
579 <emphasis>try</emphasis> to get rid of the changeefrom |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
580 <emphasis>every</emphasis> one of those repositories. This is, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
581 of course, not a satisfactory solution: if you miss even a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
582 single repository while you're expunging, the change is still |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
583 <quote>in the wild</quote>, and could propagate further.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
584 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
585 <para>If you've committed one or more changes |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
586 <emphasis>after</emphasis> the change that you'd like to see |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
587 disappear, your options are further reduced. Mercurial doesn't |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
588 provide a way to <quote>punch a hole</quote> in history, leaving |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
589 changesets intact.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
590 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
591 <para>XXX This needs filling out. The |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
592 <literal>hg-replay</literal> script in the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
593 <literal>examples</literal> directory works, but doesn't handle |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
594 merge changesets. Kind of an important omission.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
595 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
596 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
597 <title>Protect yourself from <quote>escaped</quote> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
598 changes</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
599 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
600 <para>If you've committed some changes to your local repository |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
601 and they've been pushed or pulled somewhere else, this isn't |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
602 necessarily a disaster. You can protect yourself ahead of |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
603 time against some classes of bad changeset. This is |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
604 particularly easy if your team usually pulls changes from a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
605 central repository.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
606 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
607 <para>By configuring some hooks on that repository to validate |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
608 incoming changesets (see chapter <xref linkend="chap:hook"/>), |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
609 you can |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
610 automatically prevent some kinds of bad changeset from being |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
611 pushed to the central repository at all. With such a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
612 configuration in place, some kinds of bad changeset will |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
613 naturally tend to <quote>die out</quote> because they can't |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
614 propagate into the central repository. Better yet, this |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
615 happens without any need for explicit intervention.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
616 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
617 <para>For instance, an incoming change hook that verifies that a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
618 changeset will actually compile can prevent people from |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
619 inadvertantly <quote>breaking the build</quote>.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
620 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
621 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
622 </sect1> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
623 <sect1 id="sec:undo:bisect"> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
624 <title>Finding the source of a bug</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
625 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
626 <para>While it's all very well to be able to back out a changeset |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
627 that introduced a bug, this requires that you know which |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
628 changeset to back out. Mercurial provides an invaluable |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
629 command, called <command role="hg-cmd">hg bisect</command>, that |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
630 helps you to automate this process and accomplish it very |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
631 efficiently.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
632 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
633 <para>The idea behind the <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
634 bisect</command> command is that a changeset has introduced |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
635 some change of behaviour that you can identify with a simple |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
636 binary test. You don't know which piece of code introduced the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
637 change, but you know how to test for the presence of the bug. |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
638 The <command role="hg-cmd">hg bisect</command> command uses your |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
639 test to direct its search for the changeset that introduced the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
640 code that caused the bug.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
641 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
642 <para>Here are a few scenarios to help you understand how you |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
643 might apply this command.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
644 <itemizedlist> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
645 <listitem><para>The most recent version of your software has a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
646 bug that you remember wasn't present a few weeks ago, but |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
647 you don't know when it was introduced. Here, your binary |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
648 test checks for the presence of that bug.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
649 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
650 <listitem><para>You fixed a bug in a rush, and now it's time to |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
651 close the entry in your team's bug database. The bug |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
652 database requires a changeset ID when you close an entry, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
653 but you don't remember which changeset you fixed the bug in. |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
654 Once again, your binary test checks for the presence of the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
655 bug.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
656 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
657 <listitem><para>Your software works correctly, but runs 15% |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
658 slower than the last time you measured it. You want to know |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
659 which changeset introduced the performance regression. In |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
660 this case, your binary test measures the performance of your |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
661 software, to see whether it's <quote>fast</quote> or |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
662 <quote>slow</quote>.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
663 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
664 <listitem><para>The sizes of the components of your project that |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
665 you ship exploded recently, and you suspect that something |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
666 changed in the way you build your project.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
667 </listitem></itemizedlist> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
668 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
669 <para>From these examples, it should be clear that the <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
670 role="hg-cmd">hg bisect</command> command is not useful only |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
671 for finding the sources of bugs. You can use it to find any |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
672 <quote>emergent property</quote> of a repository (anything that |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
673 you can't find from a simple text search of the files in the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
674 tree) for which you can write a binary test.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
675 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
676 <para>We'll introduce a little bit of terminology here, just to |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
677 make it clear which parts of the search process are your |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
678 responsibility, and which are Mercurial's. A |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
679 <emphasis>test</emphasis> is something that |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
680 <emphasis>you</emphasis> run when <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
681 bisect</command> chooses a changeset. A |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
682 <emphasis>probe</emphasis> is what <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
683 bisect</command> runs to tell whether a revision is good. |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
684 Finally, we'll use the word <quote>bisect</quote>, as both a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
685 noun and a verb, to stand in for the phrase <quote>search using |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
686 the <command role="hg-cmd">hg bisect</command> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
687 command</quote>.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
688 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
689 <para>One simple way to automate the searching process would be |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
690 simply to probe every changeset. However, this scales poorly. |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
691 If it took ten minutes to test a single changeset, and you had |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
692 10,000 changesets in your repository, the exhaustive approach |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
693 would take on average 35 <emphasis>days</emphasis> to find the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
694 changeset that introduced a bug. Even if you knew that the bug |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
695 was introduced by one of the last 500 changesets, and limited |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
696 your search to those, you'd still be looking at over 40 hours to |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
697 find the changeset that introduced your bug.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
698 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
699 <para>What the <command role="hg-cmd">hg bisect</command> command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
700 does is use its knowledge of the <quote>shape</quote> of your |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
701 project's revision history to perform a search in time |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
702 proportional to the <emphasis>logarithm</emphasis> of the number |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
703 of changesets to check (the kind of search it performs is called |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
704 a dichotomic search). With this approach, searching through |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
705 10,000 changesets will take less than three hours, even at ten |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
706 minutes per test (the search will require about 14 tests). |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
707 Limit your search to the last hundred changesets, and it will |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
708 take only about an hour (roughly seven tests).</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
709 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
710 <para>The <command role="hg-cmd">hg bisect</command> command is |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
711 aware of the <quote>branchy</quote> nature of a Mercurial |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
712 project's revision history, so it has no problems dealing with |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
713 branches, merges, or multiple heads in a repository. It can |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
714 prune entire branches of history with a single probe, which is |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
715 how it operates so efficiently.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
716 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
717 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
718 <title>Using the <command role="hg-cmd">hg bisect</command> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
719 command</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
720 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
721 <para>Here's an example of <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
722 bisect</command> in action.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
723 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
724 <note> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
725 <para> In versions 0.9.5 and earlier of Mercurial, <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
726 role="hg-cmd">hg bisect</command> was not a core command: |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
727 it was distributed with Mercurial as an extension. This |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
728 section describes the built-in command, not the old |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
729 extension.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
730 </note> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
731 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
732 <para>Now let's create a repository, so that we can try out the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
733 <command role="hg-cmd">hg bisect</command> command in |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
734 isolation. <!-- &interaction.bisect.init; --> We'll simulate a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
735 project that has a bug in it in a simple-minded way: create |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
736 trivial changes in a loop, and nominate one specific change |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
737 that will have the <quote>bug</quote>. This loop creates 35 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
738 changesets, each adding a single file to the repository. |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
739 We'll represent our <quote>bug</quote> with a file that |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
740 contains the text <quote>i have a gub</quote>. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
741 &interaction.bisect.commits; --></para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
742 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
743 <para>The next thing that we'd like to do is figure out how to |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
744 use the <command role="hg-cmd">hg bisect</command> command. |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
745 We can use Mercurial's normal built-in help mechanism for |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
746 this. <!-- &interaction.bisect.help; --></para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
747 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
748 <para>The <command role="hg-cmd">hg bisect</command> command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
749 works in steps. Each step proceeds as follows.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
750 <orderedlist> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
751 <listitem><para>You run your binary test.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
752 <itemizedlist> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
753 <listitem><para>If the test succeeded, you tell <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
754 role="hg-cmd">hg bisect</command> by running the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
755 <command role="hg-cmd">hg bisect good</command> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
756 command.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
757 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
758 <listitem><para>If it failed, run the <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
759 role="hg-cmd">hg bisect bad</command> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
760 command.</para></listitem></itemizedlist> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
761 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
762 <listitem><para>The command uses your information to decide |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
763 which changeset to test next.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
764 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
765 <listitem><para>It updates the working directory to that |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
766 changeset, and the process begins again.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
767 </listitem></orderedlist> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
768 <para>The process ends when <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
769 bisect</command> identifies a unique changeset that marks |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
770 the point where your test transitioned from |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
771 <quote>succeeding</quote> to <quote>failing</quote>.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
772 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
773 <para>To start the search, we must run the <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
774 role="hg-cmd">hg bisect --reset</command> command. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
775 &interaction.bisect.search.init; --></para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
776 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
777 <para>In our case, the binary test we use is simple: we check to |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
778 see if any file in the repository contains the string <quote>i |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
779 have a gub</quote>. If it does, this changeset contains the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
780 change that <quote>caused the bug</quote>. By convention, a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
781 changeset that has the property we're searching for is |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
782 <quote>bad</quote>, while one that doesn't is |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
783 <quote>good</quote>.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
784 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
785 <para>Most of the time, the revision to which the working |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
786 directory is synced (usually the tip) already exhibits the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
787 problem introduced by the buggy change, so we'll mark it as |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
788 <quote>bad</quote>. <!-- &interaction.bisect.search.bad-init; |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
789 --></para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
790 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
791 <para>Our next task is to nominate a changeset that we know |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
792 <emphasis>doesn't</emphasis> have the bug; the <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
793 role="hg-cmd">hg bisect</command> command will |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
794 <quote>bracket</quote> its search between the first pair of |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
795 good and bad changesets. In our case, we know that revision |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
796 10 didn't have the bug. (I'll have more words about choosing |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
797 the first <quote>good</quote> changeset later.) <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
798 &interaction.bisect.search.good-init; --></para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
799 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
800 <para>Notice that this command printed some output.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
801 <itemizedlist> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
802 <listitem><para>It told us how many changesets it must |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
803 consider before it can identify the one that introduced |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
804 the bug, and how many tests that will require.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
805 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
806 <listitem><para>It updated the working directory to the next |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
807 changeset to test, and told us which changeset it's |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
808 testing.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
809 </listitem></itemizedlist> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
810 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
811 <para>We now run our test in the working directory. We use the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
812 <command>grep</command> command to see if our |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
813 <quote>bad</quote> file is present in the working directory. |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
814 If it is, this revision is bad; if not, this revision is good. |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
815 <!-- &interaction.bisect.search.step1; --></para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
816 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
817 <para>This test looks like a perfect candidate for automation, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
818 so let's turn it into a shell function. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
819 &interaction.bisect.search.mytest; --> We can now run an |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
820 entire test step with a single command, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
821 <literal>mytest</literal>. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
822 &interaction.bisect.search.step2; --> A few more invocations |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
823 of our canned test step command, and we're done. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
824 &interaction.bisect.search.rest; --></para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
825 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
826 <para>Even though we had 40 changesets to search through, the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
827 <command role="hg-cmd">hg bisect</command> command let us find |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
828 the changeset that introduced our <quote>bug</quote> with only |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
829 five tests. Because the number of tests that the <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
830 role="hg-cmd">hg bisect</command> command performs grows |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
831 logarithmically with the number of changesets to search, the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
832 advantage that it has over the <quote>brute force</quote> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
833 search approach increases with every changeset you add.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
834 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
835 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
836 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
837 <title>Cleaning up after your search</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
838 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
839 <para>When you're finished using the <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
840 bisect</command> command in a repository, you can use the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
841 <command role="hg-cmd">hg bisect reset</command> command to |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
842 drop the information it was using to drive your search. The |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
843 command doesn't use much space, so it doesn't matter if you |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
844 forget to run this command. However, <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
845 role="hg-cmd">hg bisect</command> won't let you start a new |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
846 search in that repository until you do a <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
847 role="hg-cmd">hg bisect reset</command>. <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
848 &interaction.bisect.search.reset; --></para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
849 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
850 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
851 </sect1> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
852 <sect1> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
853 <title>Tips for finding bugs effectively</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
854 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
855 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
856 <title>Give consistent input</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
857 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
858 <para>The <command role="hg-cmd">hg bisect</command> command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
859 requires that you correctly report the result of every test |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
860 you perform. If you tell it that a test failed when it really |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
861 succeeded, it <emphasis>might</emphasis> be able to detect the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
862 inconsistency. If it can identify an inconsistency in your |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
863 reports, it will tell you that a particular changeset is both |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
864 good and bad. However, it can't do this perfectly; it's about |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
865 as likely to report the wrong changeset as the source of the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
866 bug.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
867 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
868 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
869 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
870 <title>Automate as much as possible</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
871 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
872 <para>When I started using the <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
873 bisect</command> command, I tried a few times to run my |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
874 tests by hand, on the command line. This is an approach that |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
875 I, at least, am not suited to. After a few tries, I found |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
876 that I was making enough mistakes that I was having to restart |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
877 my searches several times before finally getting correct |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
878 results.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
879 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
880 <para>My initial problems with driving the <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
881 role="hg-cmd">hg bisect</command> command by hand occurred |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
882 even with simple searches on small repositories; if the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
883 problem you're looking for is more subtle, or the number of |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
884 tests that <command role="hg-cmd">hg bisect</command> must |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
885 perform increases, the likelihood of operator error ruining |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
886 the search is much higher. Once I started automating my |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
887 tests, I had much better results.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
888 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
889 <para>The key to automated testing is twofold:</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
890 <itemizedlist> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
891 <listitem><para>always test for the same symptom, and</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
892 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
893 <listitem><para>always feed consistent input to the <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
894 role="hg-cmd">hg bisect</command> command.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
895 </listitem></itemizedlist> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
896 <para>In my tutorial example above, the <command>grep</command> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
897 command tests for the symptom, and the <literal>if</literal> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
898 statement takes the result of this check and ensures that we |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
899 always feed the same input to the <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
900 bisect</command> command. The <literal>mytest</literal> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
901 function marries these together in a reproducible way, so that |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
902 every test is uniform and consistent.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
903 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
904 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
905 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
906 <title>Check your results</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
907 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
908 <para>Because the output of a <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
909 bisect</command> search is only as good as the input you |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
910 give it, don't take the changeset it reports as the absolute |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
911 truth. A simple way to cross-check its report is to manually |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
912 run your test at each of the following changesets:</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
913 <itemizedlist> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
914 <listitem><para>The changeset that it reports as the first bad |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
915 revision. Your test should still report this as |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
916 bad.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
917 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
918 <listitem><para>The parent of that changeset (either parent, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
919 if it's a merge). Your test should report this changeset |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
920 as good.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
921 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
922 <listitem><para>A child of that changeset. Your test should |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
923 report this changeset as bad.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
924 </listitem></itemizedlist> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
925 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
926 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
927 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
928 <title>Beware interference between bugs</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
929 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
930 <para>It's possible that your search for one bug could be |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
931 disrupted by the presence of another. For example, let's say |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
932 your software crashes at revision 100, and worked correctly at |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
933 revision 50. Unknown to you, someone else introduced a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
934 different crashing bug at revision 60, and fixed it at |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
935 revision 80. This could distort your results in one of |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
936 several ways.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
937 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
938 <para>It is possible that this other bug completely |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
939 <quote>masks</quote> yours, which is to say that it occurs |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
940 before your bug has a chance to manifest itself. If you can't |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
941 avoid that other bug (for example, it prevents your project |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
942 from building), and so can't tell whether your bug is present |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
943 in a particular changeset, the <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
944 bisect</command> command cannot help you directly. Instead, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
945 you can mark a changeset as untested by running <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
946 role="hg-cmd">hg bisect --skip</command>.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
947 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
948 <para>A different problem could arise if your test for a bug's |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
949 presence is not specific enough. If you check for <quote>my |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
950 program crashes</quote>, then both your crashing bug and an |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
951 unrelated crashing bug that masks it will look like the same |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
952 thing, and mislead <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
953 bisect</command>.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
954 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
955 <para>Another useful situation in which to use <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
956 role="hg-cmd">hg bisect --skip</command> is if you can't |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
957 test a revision because your project was in a broken and hence |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
958 untestable state at that revision, perhaps because someone |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
959 checked in a change that prevented the project from |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
960 building.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
961 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
962 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
963 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
964 <title>Bracket your search lazily</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
965 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
966 <para>Choosing the first <quote>good</quote> and |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
967 <quote>bad</quote> changesets that will mark the end points of |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
968 your search is often easy, but it bears a little discussion |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
969 nevertheless. From the perspective of <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
970 role="hg-cmd">hg bisect</command>, the <quote>newest</quote> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
971 changeset is conventionally <quote>bad</quote>, and the older |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
972 changeset is <quote>good</quote>.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
973 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
974 <para>If you're having trouble remembering when a suitable |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
975 <quote>good</quote> change was, so that you can tell <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
976 role="hg-cmd">hg bisect</command>, you could do worse than |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
977 testing changesets at random. Just remember to eliminate |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
978 contenders that can't possibly exhibit the bug (perhaps |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
979 because the feature with the bug isn't present yet) and those |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
980 where another problem masks the bug (as I discussed |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
981 above).</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
982 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
983 <para>Even if you end up <quote>early</quote> by thousands of |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
984 changesets or months of history, you will only add a handful |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
985 of tests to the total number that <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
986 bisect</command> must perform, thanks to its logarithmic |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
987 behaviour.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
988 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
989 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
990 </sect1> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
991 </chapter> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
992 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
993 <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
994 local variables: |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
995 sgml-parent-document: ("00book.xml" "book" "chapter") |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
996 end: |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
997 --> |