hgbook
diff en/ch12-mq.xml @ 558:8631da51309b
Slow progress on XML conversion
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Mon Feb 09 23:25:40 2009 -0800 (2009-02-09) |
parents | en/ch12-mq.tex@5cd47f721686 |
children | b90b024729f1 |
line diff
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/en/ch12-mq.xml Mon Feb 09 23:25:40 2009 -0800 1.3 @@ -0,0 +1,1324 @@ 1.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 1.5 + 1.6 +<chapter id="chap:mq"> 1.7 + <title>Managing change with Mercurial Queues</title> 1.8 + 1.9 + <sect1 id="sec:mq:patch-mgmt"> 1.10 + <title>The patch management problem</title> 1.11 + 1.12 + <para>Here is a common scenario: you need to install a software 1.13 + package from source, but you find a bug that you must fix in the 1.14 + source before you can start using the package. You make your 1.15 + changes, forget about the package for a while, and a few months 1.16 + later you need to upgrade to a newer version of the package. If 1.17 + the newer version of the package still has the bug, you must 1.18 + extract your fix from the older source tree and apply it against 1.19 + the newer version. This is a tedious task, and it's easy to 1.20 + make mistakes.</para> 1.21 + 1.22 + <para>This is a simple case of the <quote>patch management</quote> 1.23 + problem. You have an <quote>upstream</quote> source tree that 1.24 + you can't change; you need to make some local changes on top of 1.25 + the upstream tree; and you'd like to be able to keep those 1.26 + changes separate, so that you can apply them to newer versions 1.27 + of the upstream source.</para> 1.28 + 1.29 + <para>The patch management problem arises in many situations. 1.30 + Probably the most visible is that a user of an open source 1.31 + software project will contribute a bug fix or new feature to the 1.32 + project's maintainers in the form of a patch.</para> 1.33 + 1.34 + <para>Distributors of operating systems that include open source 1.35 + software often need to make changes to the packages they 1.36 + distribute so that they will build properly in their 1.37 + environments.</para> 1.38 + 1.39 + <para>When you have few changes to maintain, it is easy to manage 1.40 + a single patch using the standard <command>diff</command> and 1.41 + <command>patch</command> programs (see section <xref 1.42 + linkend="sec:mq:patch"/> for a discussion of these tools). 1.43 + Once the number of changes grows, it starts to make sense to 1.44 + maintain patches as discrete <quote>chunks of work,</quote> so 1.45 + that for example a single patch will contain only one bug fix 1.46 + (the patch might modify several files, but it's doing 1.47 + <quote>only one thing</quote>), and you may have a number of 1.48 + such patches for different bugs you need fixed and local changes 1.49 + you require. In this situation, if you submit a bug fix patch 1.50 + to the upstream maintainers of a package and they include your 1.51 + fix in a subsequent release, you can simply drop that single 1.52 + patch when you're updating to the newer release.</para> 1.53 + 1.54 + <para>Maintaining a single patch against an upstream tree is a 1.55 + little tedious and error-prone, but not difficult. However, the 1.56 + complexity of the problem grows rapidly as the number of patches 1.57 + you have to maintain increases. With more than a tiny number of 1.58 + patches in hand, understanding which ones you have applied and 1.59 + maintaining them moves from messy to overwhelming.</para> 1.60 + 1.61 + <para>Fortunately, Mercurial includes a powerful extension, 1.62 + Mercurial Queues (or simply <quote>MQ</quote>), that massively 1.63 + simplifies the patch management problem.</para> 1.64 + 1.65 + </sect1> 1.66 + <sect1 id="sec:mq:history"> 1.67 + <title>The prehistory of Mercurial Queues</title> 1.68 + 1.69 + <para>During the late 1990s, several Linux kernel developers 1.70 + started to maintain <quote>patch series</quote> that modified 1.71 + the behaviour of the Linux kernel. Some of these series were 1.72 + focused on stability, some on feature coverage, and others were 1.73 + more speculative.</para> 1.74 + 1.75 + <para>The sizes of these patch series grew rapidly. In 2002, 1.76 + Andrew Morton published some shell scripts he had been using to 1.77 + automate the task of managing his patch queues. Andrew was 1.78 + successfully using these scripts to manage hundreds (sometimes 1.79 + thousands) of patches on top of the Linux kernel.</para> 1.80 + 1.81 + <sect2 id="sec:mq:quilt"> 1.82 + <title>A patchwork quilt</title> 1.83 + 1.84 + <para>In early 2003, Andreas Gruenbacher and Martin Quinson 1.85 + borrowed the approach of Andrew's scripts and published a tool 1.86 + called <quote>patchwork quilt</quote> 1.87 + <citation>web:quilt</citation>, or simply <quote>quilt</quote> 1.88 + (see <citation>gruenbacher:2005</citation> for a paper 1.89 + describing it). Because quilt substantially automated patch 1.90 + management, it rapidly gained a large following among open 1.91 + source software developers.</para> 1.92 + 1.93 + <para>Quilt manages a <emphasis>stack of patches</emphasis> on 1.94 + top of a directory tree. To begin, you tell quilt to manage a 1.95 + directory tree, and tell it which files you want to manage; it 1.96 + stores away the names and contents of those files. To fix a 1.97 + bug, you create a new patch (using a single command), edit the 1.98 + files you need to fix, then <quote>refresh</quote> the 1.99 + patch.</para> 1.100 + 1.101 + <para>The refresh step causes quilt to scan the directory tree; 1.102 + it updates the patch with all of the changes you have made. 1.103 + You can create another patch on top of the first, which will 1.104 + track the changes required to modify the tree from <quote>tree 1.105 + with one patch applied</quote> to <quote>tree with two 1.106 + patches applied</quote>.</para> 1.107 + 1.108 + <para>You can <emphasis>change</emphasis> which patches are 1.109 + applied to the tree. If you <quote>pop</quote> a patch, the 1.110 + changes made by that patch will vanish from the directory 1.111 + tree. Quilt remembers which patches you have popped, though, 1.112 + so you can <quote>push</quote> a popped patch again, and the 1.113 + directory tree will be restored to contain the modifications 1.114 + in the patch. Most importantly, you can run the 1.115 + <quote>refresh</quote> command at any time, and the topmost 1.116 + applied patch will be updated. This means that you can, at 1.117 + any time, change both which patches are applied and what 1.118 + modifications those patches make.</para> 1.119 + 1.120 + <para>Quilt knows nothing about revision control tools, so it 1.121 + works equally well on top of an unpacked tarball or a 1.122 + Subversion working copy.</para> 1.123 + 1.124 + </sect2> 1.125 + <sect2 id="sec:mq:quilt-mq"> 1.126 + <title>From patchwork quilt to Mercurial Queues</title> 1.127 + 1.128 + <para>In mid-2005, Chris Mason took the features of quilt and 1.129 + wrote an extension that he called Mercurial Queues, which 1.130 + added quilt-like behaviour to Mercurial.</para> 1.131 + 1.132 + <para>The key difference between quilt and MQ is that quilt 1.133 + knows nothing about revision control systems, while MQ is 1.134 + <emphasis>integrated</emphasis> into Mercurial. Each patch 1.135 + that you push is represented as a Mercurial changeset. Pop a 1.136 + patch, and the changeset goes away.</para> 1.137 + 1.138 + <para>Because quilt does not care about revision control tools, 1.139 + it is still a tremendously useful piece of software to know 1.140 + about for situations where you cannot use Mercurial and 1.141 + MQ.</para> 1.142 + 1.143 + </sect2> 1.144 + </sect1> 1.145 + <sect1> 1.146 + <title>The huge advantage of MQ</title> 1.147 + 1.148 + <para>I cannot overstate the value that MQ offers through the 1.149 + unification of patches and revision control.</para> 1.150 + 1.151 + <para>A major reason that patches have persisted in the free 1.152 + software and open source world&emdash;in spite of the availability of 1.153 + increasingly capable revision control tools over the years&emdash;is 1.154 + the <emphasis>agility</emphasis> they offer.</para> 1.155 + 1.156 + <para>Traditional revision control tools make a permanent, 1.157 + irreversible record of everything that you do. While this has 1.158 + great value, it's also somewhat stifling. If you want to 1.159 + perform a wild-eyed experiment, you have to be careful in how 1.160 + you go about it, or you risk leaving unneeded&emdash;or worse, 1.161 + misleading or destabilising&emdash;traces of your missteps and errors 1.162 + in the permanent revision record.</para> 1.163 + 1.164 + <para>By contrast, MQ's marriage of distributed revision control 1.165 + with patches makes it much easier to isolate your work. Your 1.166 + patches live on top of normal revision history, and you can make 1.167 + them disappear or reappear at will. If you don't like a patch, 1.168 + you can drop it. If a patch isn't quite as you want it to be, 1.169 + simply fix it&emdash;as many times as you need to, until you have 1.170 + refined it into the form you desire.</para> 1.171 + 1.172 + <para>As an example, the integration of patches with revision 1.173 + control makes understanding patches and debugging their 1.174 + effects&emdash;and their interplay with the code they're based 1.175 + on&emdash;<emphasis>enormously</emphasis> easier. Since every applied 1.176 + patch has an associated changeset, you can use <command 1.177 + role="hg-cmd">hg log</command> to see which changesets and 1.178 + patches affected a file. You can use the <literal 1.179 + role="hg-ext">bisect</literal> command to binary-search 1.180 + through all changesets and applied patches to see where a bug 1.181 + got introduced or fixed. You can use the <command 1.182 + role="hg-cmd">hg annotate</command> command to see which 1.183 + changeset or patch modified a particular line of a source file. 1.184 + And so on.</para> 1.185 + 1.186 + </sect1> 1.187 + 1.188 + <sect1 id="sec:mq:patch"> 1.189 + <title>Understanding patches</title> 1.190 + 1.191 + <para>Because MQ doesn't hide its patch-oriented nature, it is 1.192 + helpful to understand what patches are, and a little about the 1.193 + tools that work with them.</para> 1.194 + 1.195 + <para>The traditional Unix <command>diff</command> command 1.196 + compares two files, and prints a list of differences between 1.197 + them. The <command>patch</command> command understands these 1.198 + differences as <emphasis>modifications</emphasis> to make to a 1.199 + file. Take a look below for a simple example of these commands 1.200 + in action.</para> 1.201 + 1.202 +<!-- &interaction.mq.dodiff.diff; --> 1.203 + 1.204 + <para>The type of file that <command>diff</command> generates (and 1.205 + <command>patch</command> takes as input) is called a 1.206 + <quote>patch</quote> or a <quote>diff</quote>; there is no 1.207 + difference between a patch and a diff. (We'll use the term 1.208 + <quote>patch</quote>, since it's more commonly used.)</para> 1.209 + 1.210 + <para>A patch file can start with arbitrary text; the 1.211 + <command>patch</command> command ignores this text, but MQ uses 1.212 + it as the commit message when creating changesets. To find the 1.213 + beginning of the patch content, <command>patch</command> 1.214 + searches for the first line that starts with the string 1.215 + <quote><literal>diff -</literal></quote>.</para> 1.216 + 1.217 + <para>MQ works with <emphasis>unified</emphasis> diffs 1.218 + (<command>patch</command> can accept several other diff formats, 1.219 + but MQ doesn't). A unified diff contains two kinds of header. 1.220 + The <emphasis>file header</emphasis> describes the file being 1.221 + modified; it contains the name of the file to modify. When 1.222 + <command>patch</command> sees a new file header, it looks for a 1.223 + file with that name to start modifying.</para> 1.224 + 1.225 + <para>After the file header comes a series of 1.226 + <emphasis>hunks</emphasis>. Each hunk starts with a header; 1.227 + this identifies the range of line numbers within the file that 1.228 + the hunk should modify. Following the header, a hunk starts and 1.229 + ends with a few (usually three) lines of text from the 1.230 + unmodified file; these are called the 1.231 + <emphasis>context</emphasis> for the hunk. If there's only a 1.232 + small amount of context between successive hunks, 1.233 + <command>diff</command> doesn't print a new hunk header; it just 1.234 + runs the hunks together, with a few lines of context between 1.235 + modifications.</para> 1.236 + 1.237 + <para>Each line of context begins with a space character. Within 1.238 + the hunk, a line that begins with 1.239 + <quote><literal>-</literal></quote> means <quote>remove this 1.240 + line,</quote> while a line that begins with 1.241 + <quote><literal>+</literal></quote> means <quote>insert this 1.242 + line.</quote> For example, a line that is modified is 1.243 + represented by one deletion and one insertion.</para> 1.244 + 1.245 + <para>We will return to some of the more subtle aspects of patches 1.246 + later (in section <xref linkend="sec:mq:adv-patch"/>), but you 1.247 + should have enough information now to use MQ.</para> 1.248 + 1.249 + </sect1> 1.250 + <sect1 id="sec:mq:start"> 1.251 + <title>Getting started with Mercurial Queues</title> 1.252 + 1.253 + <para>Because MQ is implemented as an extension, you must 1.254 + explicitly enable before you can use it. (You don't need to 1.255 + download anything; MQ ships with the standard Mercurial 1.256 + distribution.) To enable MQ, edit your <filename role="home"> 1.257 + /.hgrc</filename> file, and add the lines below.</para> 1.258 + 1.259 + <programlisting>[extensions] hgext.mq =</programlisting> 1.260 + 1.261 + <para>Once the extension is enabled, it will make a number of new 1.262 + commands available. To verify that the extension is working, 1.263 + you can use <command role="hg-cmd">hg help</command> to see if 1.264 + the <command role="hg-ext-mq">hg qinit</command> command is now 1.265 + available.</para> 1.266 + 1.267 +<!-- &interaction.mq.qinit-help.help; --> 1.268 + 1.269 + <para>You can use MQ with <emphasis>any</emphasis> Mercurial 1.270 + repository, and its commands only operate within that 1.271 + repository. To get started, simply prepare the repository using 1.272 + the <command role="hg-ext-mq">hg qinit</command> command. This 1.273 + command creates an empty directory called <filename 1.274 + role="special" class="directory">.hg/patches</filename>, where 1.275 + MQ will keep its metadata. As with many Mercurial commands, the 1.276 + <command role="hg-ext-mq">hg qinit</command> command prints nothing 1.277 + if it succeeds.</para> 1.278 +<!-- &interaction.mq.tutorial.qinit; --> 1.279 + 1.280 + 1.281 + <sect2> 1.282 + <title>Creating a new patch</title> 1.283 + 1.284 + <para>To begin work on a new patch, use the <command 1.285 + role="hg-ext-mq">hg qnew</command> command. This command takes 1.286 + one argument, the name of the patch to create. MQ will use 1.287 + this as the name of an actual file in the <filename 1.288 + role="special" class="directory">.hg/patches</filename> 1.289 + directory, as you can see in figure <xref 1.290 + linkend="ex:mq:qnew"/>.</para> 1.291 + 1.292 + <para>Also newly present in the <filename role="special" 1.293 + class="directory">.hg/patches</filename> directory are two 1.294 + other files, <filename role="special">series</filename> and 1.295 + <filename role="special">status</filename>. The <filename 1.296 + role="special">series</filename> file lists all of the 1.297 + patches that MQ knows about for this repository, with one 1.298 + patch per line. Mercurial uses the <filename 1.299 + role="special">status</filename> file for internal 1.300 + book-keeping; it tracks all of the patches that MQ has 1.301 + <emphasis>applied</emphasis> in this repository.</para> 1.302 + 1.303 + <note> 1.304 + <para> You may sometimes want to edit the <filename 1.305 + role="special">series</filename> file by hand; for 1.306 + example, to change the sequence in which some patches are 1.307 + applied. However, manually editing the <filename 1.308 + role="special">status</filename> file is almost always a 1.309 + bad idea, as it's easy to corrupt MQ's idea of what is 1.310 + happening.</para> 1.311 + </note> 1.312 + 1.313 + <para>Once you have created your new patch, you can edit files 1.314 + in the working directory as you usually would. All of the 1.315 + normal Mercurial commands, such as <command role="hg-cmd">hg 1.316 + diff</command> and <command role="hg-cmd">hg 1.317 + annotate</command>, work exactly as they did before.</para> 1.318 + 1.319 + </sect2> 1.320 + <sect2> 1.321 + <title>Refreshing a patch</title> 1.322 + 1.323 + <para>When you reach a point where you want to save your work, 1.324 + use the <command role="hg-ext-mq">hg qrefresh</command> 1.325 + command to update the patch you are working on. This command 1.326 + folds the changes you have made in the working directory into 1.327 + your patch, and updates its corresponding changeset to contain 1.328 + those changes.</para> 1.329 + 1.330 +<!-- &interaction.mq.tutorial.qrefresh; --> 1.331 + 1.332 + <para>You can run <command role="hg-ext-mq">hg hg 1.333 + qrefresh</command> as often as you like, so it's a good way 1.334 + to <quote>checkpoint</quote> your work. Refresh your patch at 1.335 + an opportune time; try an experiment; and if the experiment 1.336 + doesn't work out, <command role="hg-cmd">hg revert</command> 1.337 + your modifications back to the last time you refreshed.</para> 1.338 + 1.339 +<!-- &interaction.mq.tutorial.qrefresh2; --> 1.340 + 1.341 + </sect2> 1.342 + <sect2> 1.343 + <title>Stacking and tracking patches</title> 1.344 + 1.345 + <para>Once you have finished working on a patch, or need to work 1.346 + on another, you can use the <command role="hg-ext-mq">hg hg 1.347 + qnew</command> command again to create a new patch. 1.348 + Mercurial will apply this patch on top of your existing patch. 1.349 + See figure <xref linkend="ex:mq:qnew2"/> for an example. 1.350 + Notice that the patch contains the changes in our prior patch 1.351 + as part of its context (you can see this more clearly in the 1.352 + output of <command role="hg-cmd">hg 1.353 + annotate</command>).</para> 1.354 + 1.355 +<!-- &interaction.mq.tutorial.qnew2; --> 1.356 + 1.357 + <para>So far, with the exception of <command 1.358 + role="hg-ext-mq">hg qnew</command> and <command 1.359 + role="hg-ext-mq">hg qrefresh</command>, we've been careful to 1.360 + only use regular Mercurial commands. However, MQ provides 1.361 + many commands that are easier to use when you are thinking 1.362 + about patches, as illustrated in figure <xref 1.363 + linkend="ex:mq:qseries"/>:</para> 1.364 + 1.365 + <itemizedlist> 1.366 + <listitem><para>The <command 1.367 + role="hg-ext-mq">hg qseries</command> command lists every 1.368 + patch that MQ knows about in this repository, from oldest 1.369 + to newest (most recently 1.370 + <emphasis>created</emphasis>).</para></listitem> 1.371 + <listitem><para>The <command 1.372 + role="hg-ext-mq">hg qapplied</command> command lists every 1.373 + patch that MQ has <emphasis>applied</emphasis> in this 1.374 + repository, again from oldest to newest (most recently 1.375 + applied).</para></listitem></itemizedlist> 1.376 + 1.377 +<!-- &interaction.mq.tutorial.qseries; --> 1.378 + 1.379 + </sect2> 1.380 + <sect2> 1.381 + <title>Manipulating the patch stack</title> 1.382 + 1.383 + <para>The previous discussion implied that there must be a 1.384 + difference between <quote>known</quote> and 1.385 + <quote>applied</quote> patches, and there is. MQ can manage a 1.386 + patch without it being applied in the repository.</para> 1.387 + 1.388 + <para>An <emphasis>applied</emphasis> patch has a corresponding 1.389 + changeset in the repository, and the effects of the patch and 1.390 + changeset are visible in the working directory. You can undo 1.391 + the application of a patch using the <command 1.392 + role="hg-ext-mq">hg qpop</command> command. MQ still 1.393 + <emphasis>knows about</emphasis>, or manages, a popped patch, 1.394 + but the patch no longer has a corresponding changeset in the 1.395 + repository, and the working directory does not contain the 1.396 + changes made by the patch. Figure <xref 1.397 + linkend="fig:mq:stack"/> illustrates the difference between 1.398 + applied and tracked patches.</para> 1.399 + 1.400 + <informalfigure id="fig:mq:stack"> 1.401 + <mediaobject> 1.402 + <imageobject><imagedata fileref="mq-stack"/></imageobject> 1.403 + <textobject><phrase>XXX add text</phrase></textobject> 1.404 + <caption><para>Applied and unapplied patches in the MQ patch 1.405 + stack</para></caption> 1.406 + </mediaobject> 1.407 + </informalfigure> 1.408 + 1.409 + <para>You can reapply an unapplied, or popped, patch using the 1.410 + <command role="hg-ext-mq">hg qpush</command> command. This 1.411 + creates a new changeset to correspond to the patch, and the 1.412 + patch's changes once again become present in the working 1.413 + directory. See figure <xref linkend="ex:mq:qpop"/> for 1.414 + examples of <command role="hg-ext-mq">hg qpop</command> and 1.415 + <command role="hg-ext-mq">hg qpush</command> in action. Notice 1.416 + that once we have popped a patch or two patches, the output of 1.417 + <command role="hg-ext-mq">hg qseries</command> remains the same, 1.418 + while that of <command role="hg-ext-mq">hg qapplied</command> has 1.419 + changed.</para> 1.420 + 1.421 +<!-- &interaction.mq.tutorial.qpop; --> 1.422 + 1.423 + </sect2> 1.424 + <sect2> 1.425 + <title>Pushing and popping many patches</title> 1.426 + 1.427 + <para>While <command role="hg-ext-mq">hg qpush</command> and 1.428 + <command role="hg-ext-mq">hg qpop</command> each operate on a 1.429 + single patch at a time by default, you can push and pop many 1.430 + patches in one go. The <option 1.431 + role="hg-ext-mq-cmd-qpush-opt">-a</option> option to 1.432 + <command role="hg-ext-mq">hg qpush</command> causes it to push 1.433 + all unapplied patches, while the <option 1.434 + role="hg-ext-mq-cmd-qpop-opt">-a</option> option to <command 1.435 + role="hg-ext-mq">hg qpop</command> causes it to pop all applied 1.436 + patches. (For some more ways to push and pop many patches, 1.437 + see section <xref linkend="sec:mq:perf"/> below.)</para> 1.438 + 1.439 +<!-- &interaction.mq.tutorial.qpush-a; --> 1.440 + 1.441 + </sect2> 1.442 + <sect2> 1.443 + <title>Safety checks, and overriding them</title> 1.444 + 1.445 + <para>Several MQ commands check the working directory before 1.446 + they do anything, and fail if they find any modifications. 1.447 + They do this to ensure that you won't lose any changes that 1.448 + you have made, but not yet incorporated into a patch. Figure 1.449 + <xref linkend="ex:mq:add"/> illustrates this; the <command 1.450 + role="hg-ext-mq">hg qnew</command> command will not create a 1.451 + new patch if there are outstanding changes, caused in this 1.452 + case by the <command role="hg-cmd">hg add</command> of 1.453 + <filename>file3</filename>.</para> 1.454 + 1.455 +<!-- &interaction.mq.tutorial.add; --> 1.456 + 1.457 + <para>Commands that check the working directory all take an 1.458 + <quote>I know what I'm doing</quote> option, which is always 1.459 + named <option>-f</option>. The exact meaning of 1.460 + <option>-f</option> depends on the command. For example, 1.461 + <command role="hg-cmd">hg qnew <option 1.462 + role="hg-ext-mq-cmd-qnew-opt">-f</option></command> will 1.463 + incorporate any outstanding changes into the new patch it 1.464 + creates, but <command role="hg-cmd">hg qpop <option 1.465 + role="hg-ext-mq-cmd-qpop-opt">-f</option></command> will 1.466 + revert modifications to any files affected by the patch that 1.467 + it is popping. Be sure to read the documentation for a 1.468 + command's <option>-f</option> option before you use it!</para> 1.469 + 1.470 + </sect2> 1.471 + <sect2> 1.472 + <title>Working on several patches at once</title> 1.473 + 1.474 + <para>The <command role="hg-ext-mq">hg qrefresh</command> command 1.475 + always refreshes the <emphasis>topmost</emphasis> applied 1.476 + patch. This means that you can suspend work on one patch (by 1.477 + refreshing it), pop or push to make a different patch the top, 1.478 + and work on <emphasis>that</emphasis> patch for a 1.479 + while.</para> 1.480 + 1.481 + <para>Here's an example that illustrates how you can use this 1.482 + ability. Let's say you're developing a new feature as two 1.483 + patches. The first is a change to the core of your software, 1.484 + and the second&emdash;layered on top of the first&emdash;changes the 1.485 + user interface to use the code you just added to the core. If 1.486 + you notice a bug in the core while you're working on the UI 1.487 + patch, it's easy to fix the core. Simply <command 1.488 + role="hg-ext-mq">hg qrefresh</command> the UI patch to save 1.489 + your in-progress changes, and <command 1.490 + role="hg-ext-mq">hg qpop</command> down to the core patch. Fix 1.491 + the core bug, <command role="hg-ext-mq">hg qrefresh</command> the 1.492 + core patch, and <command role="hg-ext-mq">hg qpush</command> back 1.493 + to the UI patch to continue where you left off.</para> 1.494 + 1.495 + </sect2> 1.496 + </sect1> 1.497 + 1.498 + <sect1 id="sec:mq:adv-patch"> 1.499 + <title>More about patches</title> 1.500 + 1.501 + <para>MQ uses the GNU <command>patch</command> command to apply 1.502 + patches, so it's helpful to know a few more detailed aspects of 1.503 + how <command>patch</command> works, and about patches 1.504 + themselves.</para> 1.505 + 1.506 + <sect2> 1.507 + <title>The strip count</title> 1.508 + 1.509 + <para>If you look at the file headers in a patch, you will 1.510 + notice that the pathnames usually have an extra component on 1.511 + the front that isn't present in the actual path name. This is 1.512 + a holdover from the way that people used to generate patches 1.513 + (people still do this, but it's somewhat rare with modern 1.514 + revision control tools).</para> 1.515 + 1.516 + <para>Alice would unpack a tarball, edit her files, then decide 1.517 + that she wanted to create a patch. So she'd rename her 1.518 + working directory, unpack the tarball again (hence the need 1.519 + for the rename), and use the <option 1.520 + role="cmd-opt-diff">-r</option> and <option 1.521 + role="cmd-opt-diff">-N</option> options to 1.522 + <command>diff</command> to recursively generate a patch 1.523 + between the unmodified directory and the modified one. The 1.524 + result would be that the name of the unmodified directory 1.525 + would be at the front of the left-hand path in every file 1.526 + header, and the name of the modified directory would be at the 1.527 + front of the right-hand path.</para> 1.528 + 1.529 + <para>Since someone receiving a patch from the Alices of the net 1.530 + would be unlikely to have unmodified and modified directories 1.531 + with exactly the same names, the <command>patch</command> 1.532 + command has a <option role="cmd-opt-patch">-p</option> option 1.533 + that indicates the number of leading path name components to 1.534 + strip when trying to apply a patch. This number is called the 1.535 + <emphasis>strip count</emphasis>.</para> 1.536 + 1.537 + <para>An option of <quote><literal>-p1</literal></quote> means 1.538 + <quote>use a strip count of one</quote>. If 1.539 + <command>patch</command> sees a file name 1.540 + <filename>foo/bar/baz</filename> in a file header, it will 1.541 + strip <filename>foo</filename> and try to patch a file named 1.542 + <filename>bar/baz</filename>. (Strictly speaking, the strip 1.543 + count refers to the number of <emphasis>path 1.544 + separators</emphasis> (and the components that go with them 1.545 + ) to strip. A strip count of one will turn 1.546 + <filename>foo/bar</filename> into <filename>bar</filename>, 1.547 + but <filename>/foo/bar</filename> (notice the extra leading 1.548 + slash) into <filename>foo/bar</filename>.)</para> 1.549 + 1.550 + <para>The <quote>standard</quote> strip count for patches is 1.551 + one; almost all patches contain one leading path name 1.552 + component that needs to be stripped. Mercurial's <command 1.553 + role="hg-cmd">hg diff</command> command generates path names 1.554 + in this form, and the <command role="hg-cmd">hg 1.555 + import</command> command and MQ expect patches to have a 1.556 + strip count of one.</para> 1.557 + 1.558 + <para>If you receive a patch from someone that you want to add 1.559 + to your patch queue, and the patch needs a strip count other 1.560 + than one, you cannot just <command 1.561 + role="hg-ext-mq">hg qimport</command> the patch, because 1.562 + <command role="hg-ext-mq">hg qimport</command> does not yet have 1.563 + a <literal>-p</literal> option (see <ulink role="hg-bug" 1.564 + url="http://www.selenic.com/mercurial/bts/issue311">issue 1.565 + 311</ulink>). Your best bet is to <command 1.566 + role="hg-ext-mq">hg qnew</command> a patch of your own, then 1.567 + use <command>patch -pN</command> to apply their patch, 1.568 + followed by <command role="hg-cmd">hg addremove</command> to 1.569 + pick up any files added or removed by the patch, followed by 1.570 + <command role="hg-ext-mq">hg qrefresh</command>. This complexity 1.571 + may become unnecessary; see <ulink role="hg-bug" 1.572 + url="http://www.selenic.com/mercurial/bts/issue311">issue 1.573 + 311</ulink> for details.</para> 1.574 + </sect2> 1.575 + <sect2> 1.576 + <title>Strategies for applying a patch</title> 1.577 + 1.578 + <para>When <command>patch</command> applies a hunk, it tries a 1.579 + handful of successively less accurate strategies to try to 1.580 + make the hunk apply. This falling-back technique often makes 1.581 + it possible to take a patch that was generated against an old 1.582 + version of a file, and apply it against a newer version of 1.583 + that file.</para> 1.584 + 1.585 + <para>First, <command>patch</command> tries an exact match, 1.586 + where the line numbers, the context, and the text to be 1.587 + modified must apply exactly. If it cannot make an exact 1.588 + match, it tries to find an exact match for the context, 1.589 + without honouring the line numbering information. If this 1.590 + succeeds, it prints a line of output saying that the hunk was 1.591 + applied, but at some <emphasis>offset</emphasis> from the 1.592 + original line number.</para> 1.593 + 1.594 + <para>If a context-only match fails, <command>patch</command> 1.595 + removes the first and last lines of the context, and tries a 1.596 + <emphasis>reduced</emphasis> context-only match. If the hunk 1.597 + with reduced context succeeds, it prints a message saying that 1.598 + it applied the hunk with a <emphasis>fuzz factor</emphasis> 1.599 + (the number after the fuzz factor indicates how many lines of 1.600 + context <command>patch</command> had to trim before the patch 1.601 + applied).</para> 1.602 + 1.603 + <para>When neither of these techniques works, 1.604 + <command>patch</command> prints a message saying that the hunk 1.605 + in question was rejected. It saves rejected hunks (also 1.606 + simply called <quote>rejects</quote>) to a file with the same 1.607 + name, and an added <filename role="special">.rej</filename> 1.608 + extension. It also saves an unmodified copy of the file with 1.609 + a <filename role="special">.orig</filename> extension; the 1.610 + copy of the file without any extensions will contain any 1.611 + changes made by hunks that <emphasis>did</emphasis> apply 1.612 + cleanly. If you have a patch that modifies 1.613 + <filename>foo</filename> with six hunks, and one of them fails 1.614 + to apply, you will have: an unmodified 1.615 + <filename>foo.orig</filename>, a <filename>foo.rej</filename> 1.616 + containing one hunk, and <filename>foo</filename>, containing 1.617 + the changes made by the five successful hunks.</para> 1.618 + 1.619 + </sect2> 1.620 + <sect2> 1.621 + <title>Some quirks of patch representation</title> 1.622 + 1.623 + <para>There are a few useful things to know about how 1.624 + <command>patch</command> works with files.</para> 1.625 + 1.626 + <itemizedlist> 1.627 + <listitem><para>This should already be obvious, but 1.628 + <command>patch</command> cannot handle binary 1.629 + files.</para></listitem> 1.630 + 1.631 + <listitem><para>Neither does it care about the executable bit; 1.632 + it creates new files as readable, but not 1.633 + executable.</para></listitem> 1.634 + 1.635 + <listitem><para><command>patch</command> treats the removal of 1.636 + a file as a diff between the file to be removed and the 1.637 + empty file. So your idea of <quote>I deleted this 1.638 + file</quote> looks like <quote>every line of this file 1.639 + was deleted</quote> in a patch.</para></listitem> 1.640 + 1.641 + <listitem><para>It treats the addition of a file as a diff 1.642 + between the empty file and the file to be added. So in a 1.643 + patch, your idea of <quote>I added this file</quote> looks 1.644 + like <quote>every line of this file was 1.645 + added</quote>.</para></listitem> 1.646 + 1.647 + <listitem><para>It treats a renamed file as the removal of the 1.648 + old name, and the addition of the new name. This means 1.649 + that renamed files have a big footprint in patches. (Note 1.650 + also that Mercurial does not currently try to infer when 1.651 + files have been renamed or copied in a 1.652 + patch.)</para></listitem> 1.653 + 1.654 + <listitem><para><command>patch</command> cannot represent 1.655 + empty files, so you cannot use a patch to represent the 1.656 + notion <quote>I added this empty file to the 1.657 + tree</quote>.</para></listitem> 1.658 + </itemizedlist> 1.659 + </sect2> 1.660 + 1.661 + <sect2> 1.662 + <title>Beware the fuzz</title> 1.663 + 1.664 + <para>While applying a hunk at an offset, or with a fuzz factor, 1.665 + will often be completely successful, these inexact techniques 1.666 + naturally leave open the possibility of corrupting the patched 1.667 + file. The most common cases typically involve applying a 1.668 + patch twice, or at an incorrect location in the file. If 1.669 + <command>patch</command> or <command 1.670 + role="hg-ext-mq">hg qpush</command> ever mentions an offset or 1.671 + fuzz factor, you should make sure that the modified files are 1.672 + correct afterwards.</para> 1.673 + 1.674 + <para>It's often a good idea to refresh a patch that has applied 1.675 + with an offset or fuzz factor; refreshing the patch generates 1.676 + new context information that will make it apply cleanly. I 1.677 + say <quote>often,</quote> not <quote>always,</quote> because 1.678 + sometimes refreshing a patch will make it fail to apply 1.679 + against a different revision of the underlying files. In some 1.680 + cases, such as when you're maintaining a patch that must sit 1.681 + on top of multiple versions of a source tree, it's acceptable 1.682 + to have a patch apply with some fuzz, provided you've verified 1.683 + the results of the patching process in such cases.</para> 1.684 + 1.685 + </sect2> 1.686 + <sect2> 1.687 + <title>Handling rejection</title> 1.688 + 1.689 + <para>If <command role="hg-ext-mq">hg qpush</command> fails to 1.690 + apply a patch, it will print an error message and exit. If it 1.691 + has left <filename role="special">.rej</filename> files 1.692 + behind, it is usually best to fix up the rejected hunks before 1.693 + you push more patches or do any further work.</para> 1.694 + 1.695 + <para>If your patch <emphasis>used to</emphasis> apply cleanly, 1.696 + and no longer does because you've changed the underlying code 1.697 + that your patches are based on, Mercurial Queues can help; see 1.698 + section <xref linkend="sec:mq:merge"/> for details.</para> 1.699 + 1.700 + <para>Unfortunately, there aren't any great techniques for 1.701 + dealing with rejected hunks. Most often, you'll need to view 1.702 + the <filename role="special">.rej</filename> file and edit the 1.703 + target file, applying the rejected hunks by hand.</para> 1.704 + 1.705 + <para>If you're feeling adventurous, Neil Brown, a Linux kernel 1.706 + hacker, wrote a tool called <command>wiggle</command> 1.707 + <citation>web:wiggle</citation>, which is more vigorous than 1.708 + <command>patch</command> in its attempts to make a patch 1.709 + apply.</para> 1.710 + 1.711 + <para>Another Linux kernel hacker, Chris Mason (the author of 1.712 + Mercurial Queues), wrote a similar tool called 1.713 + <command>mpatch</command> <citation>web:mpatch</citation>, 1.714 + which takes a simple approach to automating the application of 1.715 + hunks rejected by <command>patch</command>. The 1.716 + <command>mpatch</command> command can help with four common 1.717 + reasons that a hunk may be rejected:</para> 1.718 + 1.719 + <itemizedlist> 1.720 + <listitem><para>The context in the middle of a hunk has 1.721 + changed.</para></listitem> 1.722 + 1.723 + <listitem><para>A hunk is missing some context at the 1.724 + beginning or end.</para></listitem> 1.725 + 1.726 + <listitem><para>A large hunk might apply better&emdash;either 1.727 + entirely or in part&emdash;if it was broken up into smaller 1.728 + hunks.</para></listitem> 1.729 + 1.730 + <listitem><para>A hunk removes lines with slightly different 1.731 + content than those currently present in the 1.732 + file.</para></listitem> 1.733 + </itemizedlist> 1.734 + 1.735 + <para>If you use <command>wiggle</command> or 1.736 + <command>mpatch</command>, you should be doubly careful to 1.737 + check your results when you're done. In fact, 1.738 + <command>mpatch</command> enforces this method of 1.739 + double-checking the tool's output, by automatically dropping 1.740 + you into a merge program when it has done its job, so that you 1.741 + can verify its work and finish off any remaining 1.742 + merges.</para> 1.743 + 1.744 + </sect2> 1.745 + </sect1> 1.746 + <sect1 id="sec:mq:perf"> 1.747 + <title>Getting the best performance out of MQ</title> 1.748 + 1.749 + <para>MQ is very efficient at handling a large number of patches. 1.750 + I ran some performance experiments in mid-2006 for a talk that I 1.751 + gave at the 2006 EuroPython conference 1.752 + <citation>web:europython</citation>. I used as my data set the 1.753 + Linux 2.6.17-mm1 patch series, which consists of 1,738 patches. 1.754 + I applied these on top of a Linux kernel repository containing 1.755 + all 27,472 revisions between Linux 2.6.12-rc2 and Linux 1.756 + 2.6.17.</para> 1.757 + 1.758 + <para>On my old, slow laptop, I was able to <command 1.759 + role="hg-cmd">hg qpush <option 1.760 + role="hg-ext-mq-cmd-qpush-opt">-a</option></command> all 1.761 + 1,738 patches in 3.5 minutes, and <command role="hg-cmd">hg qpop 1.762 + <option role="hg-ext-mq-cmd-qpop-opt">-a</option></command> 1.763 + them all in 30 seconds. (On a newer laptop, the time to push 1.764 + all patches dropped to two minutes.) I could <command 1.765 + role="hg-ext-mq">hg qrefresh</command> one of the biggest patches 1.766 + (which made 22,779 lines of changes to 287 files) in 6.6 1.767 + seconds.</para> 1.768 + 1.769 + <para>Clearly, MQ is well suited to working in large trees, but 1.770 + there are a few tricks you can use to get the best performance 1.771 + of it.</para> 1.772 + 1.773 + <para>First of all, try to <quote>batch</quote> operations 1.774 + together. Every time you run <command 1.775 + role="hg-ext-mq">hg qpush</command> or <command 1.776 + role="hg-ext-mq">hg qpop</command>, these commands scan the 1.777 + working directory once to make sure you haven't made some 1.778 + changes and then forgotten to run <command 1.779 + role="hg-ext-mq">hg qrefresh</command>. On a small tree, the 1.780 + time that this scan takes is unnoticeable. However, on a 1.781 + medium-sized tree (containing tens of thousands of files), it 1.782 + can take a second or more.</para> 1.783 + 1.784 + <para>The <command role="hg-ext-mq">hg qpush</command> and <command 1.785 + role="hg-ext-mq">hg qpop</command> commands allow you to push and 1.786 + pop multiple patches at a time. You can identify the 1.787 + <quote>destination patch</quote> that you want to end up at. 1.788 + When you <command role="hg-ext-mq">hg qpush</command> with a 1.789 + destination specified, it will push patches until that patch is 1.790 + at the top of the applied stack. When you <command 1.791 + role="hg-ext-mq">hg qpop</command> to a destination, MQ will pop 1.792 + patches until the destination patch is at the top.</para> 1.793 + 1.794 + <para>You can identify a destination patch using either the name 1.795 + of the patch, or by number. If you use numeric addressing, 1.796 + patches are counted from zero; this means that the first patch 1.797 + is zero, the second is one, and so on.</para> 1.798 + 1.799 + </sect1> 1.800 + 1.801 + <sect1 id="sec:mq:merge"> 1.802 + <title>Updating your patches when the underlying code 1.803 + changes</title> 1.804 + 1.805 + <para>It's common to have a stack of patches on top of an 1.806 + underlying repository that you don't modify directly. If you're 1.807 + working on changes to third-party code, or on a feature that is 1.808 + taking longer to develop than the rate of change of the code 1.809 + beneath, you will often need to sync up with the underlying 1.810 + code, and fix up any hunks in your patches that no longer apply. 1.811 + This is called <emphasis>rebasing</emphasis> your patch 1.812 + series.</para> 1.813 + 1.814 + <para>The simplest way to do this is to <command role="hg-cmd">hg 1.815 + qpop <option 1.816 + role="hg-ext-mq-cmd-qpop-opt">-a</option></command> your 1.817 + patches, then <command role="hg-cmd">hg pull</command> changes 1.818 + into the underlying repository, and finally <command 1.819 + role="hg-cmd">hg qpush <option 1.820 + role="hg-ext-mq-cmd-qpop-opt">-a</option></command> your 1.821 + patches again. MQ will stop pushing any time it runs across a 1.822 + patch that fails to apply during conflicts, allowing you to fix 1.823 + your conflicts, <command role="hg-ext-mq">hg qrefresh</command> the 1.824 + affected patch, and continue pushing until you have fixed your 1.825 + entire stack.</para> 1.826 + 1.827 + <para>This approach is easy to use and works well if you don't 1.828 + expect changes to the underlying code to affect how well your 1.829 + patches apply. If your patch stack touches code that is modified 1.830 + frequently or invasively in the underlying repository, however, 1.831 + fixing up rejected hunks by hand quickly becomes 1.832 + tiresome.</para> 1.833 + 1.834 + <para>It's possible to partially automate the rebasing process. If 1.835 + your patches apply cleanly against some revision of the 1.836 + underlying repo, MQ can use this information to help you to 1.837 + resolve conflicts between your patches and a different 1.838 + revision.</para> 1.839 + 1.840 + <para>The process is a little involved.</para> 1.841 + <orderedlist> 1.842 + <listitem><para>To begin, <command role="hg-cmd">hg qpush 1.843 + -a</command> all of your patches on top of the revision 1.844 + where you know that they apply cleanly.</para></listitem> 1.845 + 1.846 + <listitem><para>Save a backup copy of your patch directory using 1.847 + <command role="hg-cmd">hg qsave <option 1.848 + role="hg-ext-mq-cmd-qsave-opt">-e</option> <option 1.849 + role="hg-ext-mq-cmd-qsave-opt">-c</option></command>. 1.850 + This prints the name of the directory that it has saved the 1.851 + patches in. It will save the patches to a directory called 1.852 + <filename role="special" 1.853 + class="directory">.hg/patches.N</filename>, where 1.854 + <literal>N</literal> is a small integer. It also commits a 1.855 + <quote>save changeset</quote> on top of your applied 1.856 + patches; this is for internal book-keeping, and records the 1.857 + states of the <filename role="special">series</filename> and 1.858 + <filename role="special">status</filename> 1.859 + files.</para></listitem> 1.860 + 1.861 + <listitem> 1.862 + <para>Use <command role="hg-cmd">hg pull</command> to bring 1.863 + new changes into the underlying repository. (Don't run 1.864 + <command role="hg-cmd">hg pull -u</command>; see below for 1.865 + why.)</para></listitem> 1.866 + 1.867 + <listitem><para>Update to the new tip revision, using <command 1.868 + role="hg-cmd">hg update <option 1.869 + role="hg-opt-update">-C</option></command> to override 1.870 + the patches you have pushed.</para></listitem> 1.871 + 1.872 + <listitem><para>Merge all patches using 1.873 + \hgcmdargs{qpush}{<option 1.874 + role="hg-ext-mq-cmd-qpush-opt">-m</option> <option 1.875 + role="hg-ext-mq-cmd-qpush-opt">-a</option>}. The <option 1.876 + role="hg-ext-mq-cmd-qpush-opt">-m</option> option to 1.877 + <command role="hg-ext-mq">hg qpush</command> tells MQ to 1.878 + perform a three-way merge if the patch fails to 1.879 + apply.</para></listitem> 1.880 + </orderedlist> 1.881 + 1.882 + <para>During the <command role="hg-cmd">hg qpush <option 1.883 + role="hg-ext-mq-cmd-qpush-opt">-m</option></command>, each 1.884 + patch in the <filename role="special">series</filename> file is 1.885 + applied normally. If a patch applies with fuzz or rejects, MQ 1.886 + looks at the queue you <command 1.887 + role="hg-ext-mq">hg qsave</command>d, and performs a three-way 1.888 + merge with the corresponding changeset. This merge uses 1.889 + Mercurial's normal merge machinery, so it may pop up a GUI merge 1.890 + tool to help you to resolve problems.</para> 1.891 + 1.892 + <para>When you finish resolving the effects of a patch, MQ 1.893 + refreshes your patch based on the result of the merge.</para> 1.894 + 1.895 + <para>At the end of this process, your repository will have one 1.896 + extra head from the old patch queue, and a copy of the old patch 1.897 + queue will be in <filename role="special" 1.898 + class="directory">.hg/patches.N</filename>. You can remove the 1.899 + extra head using <command role="hg-cmd">hg qpop <option 1.900 + role="hg-ext-mq-cmd-qpop-opt">-a</option> <option 1.901 + role="hg-ext-mq-cmd-qpop-opt">-n</option> 1.902 + patches.N</command> or <command role="hg-cmd">hg 1.903 + strip</command>. You can delete <filename role="special" 1.904 + class="directory">.hg/patches.N</filename> once you are sure 1.905 + that you no longer need it as a backup.</para> 1.906 + 1.907 + </sect1> 1.908 + <sect1> 1.909 + <title>Identifying patches</title> 1.910 + 1.911 + <para>MQ commands that work with patches let you refer to a patch 1.912 + either by using its name or by a number. By name is obvious 1.913 + enough; pass the name <filename>foo.patch</filename> to <command 1.914 + role="hg-ext-mq">hg qpush</command>, for example, and it will 1.915 + push patches until <filename>foo.patch</filename> is 1.916 + applied.</para> 1.917 + 1.918 + <para>As a shortcut, you can refer to a patch using both a name 1.919 + and a numeric offset; <literal>foo.patch-2</literal> means 1.920 + <quote>two patches before <literal>foo.patch</literal></quote>, 1.921 + while <literal>bar.patch+4</literal> means <quote>four patches 1.922 + after <literal>bar.patch</literal></quote>.</para> 1.923 + 1.924 + <para>Referring to a patch by index isn't much different. The 1.925 + first patch printed in the output of <command 1.926 + role="hg-ext-mq">hg qseries</command> is patch zero (yes, it's 1.927 + one of those start-at-zero counting systems); the second is 1.928 + patch one; and so on.</para> 1.929 + 1.930 + <para>MQ also makes it easy to work with patches when you are 1.931 + using normal Mercurial commands. Every command that accepts a 1.932 + changeset ID will also accept the name of an applied patch. MQ 1.933 + augments the tags normally in the repository with an eponymous 1.934 + one for each applied patch. In addition, the special tags 1.935 + \index{tags!special tag 1.936 + names!<literal>qbase</literal>}<literal>qbase</literal> and 1.937 + \index{tags!special tag 1.938 + names!<literal>qtip</literal>}<literal>qtip</literal> identify 1.939 + the <quote>bottom-most</quote> and topmost applied patches, 1.940 + respectively.</para> 1.941 + 1.942 + <para>These additions to Mercurial's normal tagging capabilities 1.943 + make dealing with patches even more of a breeze.</para> 1.944 + <itemizedlist> 1.945 + <listitem><para>Want to patchbomb a mailing list with your 1.946 + latest series of changes?</para> 1.947 + <programlisting> 1.948 + hg email qbase:qtip 1.949 + </programlisting></listitem> 1.950 + <listitem><para> (Don't know what <quote>patchbombing</quote> 1.951 + is? See section <xref 1.952 + linkend="sec:hgext:patchbomb"/>.)</para></listitem> 1.953 + 1.954 + <listitem><para>Need to see all of the patches since 1.955 + <literal>foo.patch</literal> that have touched files in a 1.956 + subdirectory of your tree?</para> 1.957 + <programlisting> 1.958 + hg log -r foo.patch:qtip <emphasis>subdir</emphasis> 1.959 + </programlisting></listitem> 1.960 + </itemizedlist> 1.961 + 1.962 + <para>Because MQ makes the names of patches available to the rest 1.963 + of Mercurial through its normal internal tag machinery, you 1.964 + don't need to type in the entire name of a patch when you want 1.965 + to identify it by name.</para> 1.966 + 1.967 +<!-- &interaction.mq.id.output; --> 1.968 + 1.969 + <para>Another nice consequence of representing patch names as tags 1.970 + is that when you run the <command role="hg-cmd">hg log</command> 1.971 + command, it will display a patch's name as a tag, simply as part 1.972 + of its normal output. This makes it easy to visually 1.973 + distinguish applied patches from underlying 1.974 + <quote>normal</quote> revisions. Figure <xref 1.975 + linkend="ex:mq:id"/> shows a few normal Mercurial commands in 1.976 + use with applied patches.</para> 1.977 + 1.978 + </sect1> 1.979 + <sect1> 1.980 + <title>Useful things to know about</title> 1.981 + 1.982 + <para>There are a number of aspects of MQ usage that don't fit 1.983 + tidily into sections of their own, but that are good to know. 1.984 + Here they are, in one place.</para> 1.985 + 1.986 + <itemizedlist> 1.987 + <listitem><para>Normally, when you <command 1.988 + role="hg-ext-mq">hg qpop</command> a patch and <command 1.989 + role="hg-ext-mq">hg qpush</command> it again, the changeset 1.990 + that represents the patch after the pop/push will have a 1.991 + <emphasis>different identity</emphasis> than the changeset 1.992 + that represented the hash beforehand. See section <xref 1.993 + linkend="sec:mqref:cmd:qpush"/> for information as to why 1.994 + this is.</para></listitem> 1.995 + 1.996 + <listitem><para>It's not a good idea to <command 1.997 + role="hg-cmd">hg merge</command> changes from another 1.998 + branch with a patch changeset, at least if you want to 1.999 + maintain the <quote>patchiness</quote> of that changeset and 1.1000 + changesets below it on the patch stack. If you try to do 1.1001 + this, it will appear to succeed, but MQ will become 1.1002 + confused.</para></listitem> 1.1003 + </itemizedlist> 1.1004 + 1.1005 + </sect1> 1.1006 + 1.1007 + <sect1 id="sec:mq:repo"> 1.1008 + <title>Managing patches in a repository</title> 1.1009 + 1.1010 + <para>Because MQ's <filename role="special" 1.1011 + class="directory">.hg/patches</filename> directory resides 1.1012 + outside a Mercurial repository's working directory, the 1.1013 + <quote>underlying</quote> Mercurial repository knows nothing 1.1014 + about the management or presence of patches.</para> 1.1015 + 1.1016 + <para>This presents the interesting possibility of managing the 1.1017 + contents of the patch directory as a Mercurial repository in its 1.1018 + own right. This can be a useful way to work. For example, you 1.1019 + can work on a patch for a while, <command 1.1020 + role="hg-ext-mq">hg qrefresh</command> it, then <command 1.1021 + role="hg-cmd">hg commit</command> the current state of the 1.1022 + patch. This lets you <quote>roll back</quote> to that version 1.1023 + of the patch later on.</para> 1.1024 + 1.1025 + <para>You can then share different versions of the same patch 1.1026 + stack among multiple underlying repositories. I use this when I 1.1027 + am developing a Linux kernel feature. I have a pristine copy of 1.1028 + my kernel sources for each of several CPU architectures, and a 1.1029 + cloned repository under each that contains the patches I am 1.1030 + working on. When I want to test a change on a different 1.1031 + architecture, I push my current patches to the patch repository 1.1032 + associated with that kernel tree, pop and push all of my 1.1033 + patches, and build and test that kernel.</para> 1.1034 + 1.1035 + <para>Managing patches in a repository makes it possible for 1.1036 + multiple developers to work on the same patch series without 1.1037 + colliding with each other, all on top of an underlying source 1.1038 + base that they may or may not control.</para> 1.1039 + 1.1040 + <sect2> 1.1041 + <title>MQ support for patch repositories</title> 1.1042 + 1.1043 + <para>MQ helps you to work with the <filename role="special" 1.1044 + class="directory">.hg/patches</filename> directory as a 1.1045 + repository; when you prepare a repository for working with 1.1046 + patches using <command role="hg-ext-mq">hg qinit</command>, you 1.1047 + can pass the <option 1.1048 + role="hg-ext-mq-cmd-qinit-opt">-c</option> option to create 1.1049 + the <filename role="special" 1.1050 + class="directory">.hg/patches</filename> directory as a 1.1051 + Mercurial repository.</para> 1.1052 + 1.1053 + <note> 1.1054 + <para> If you forget to use the <option 1.1055 + role="hg-ext-mq-cmd-qinit-opt">-c</option> option, you can 1.1056 + simply go into the <filename role="special" 1.1057 + class="directory">.hg/patches</filename> directory at any 1.1058 + time and run <command role="hg-cmd">hg init</command>. Don't 1.1059 + forget to add an entry for the <filename 1.1060 + role="special">status</filename> file to the <filename 1.1061 + role="special">.hgignore</filename> file, though</para> 1.1062 + 1.1063 + <para> (<command role="hg-cmd">hg qinit <option 1.1064 + role="hg-ext-mq-cmd-qinit-opt">-c</option></command> 1.1065 + does this for you automatically); you 1.1066 + <emphasis>really</emphasis> don't want to manage the 1.1067 + <filename role="special">status</filename> file.</para> 1.1068 + </note> 1.1069 + 1.1070 + <para>As a convenience, if MQ notices that the <filename 1.1071 + class="directory">.hg/patches</filename> directory is a 1.1072 + repository, it will automatically <command role="hg-cmd">hg 1.1073 + add</command> every patch that you create and import.</para> 1.1074 + 1.1075 + <para>MQ provides a shortcut command, <command 1.1076 + role="hg-ext-mq">hg qcommit</command>, that runs <command 1.1077 + role="hg-cmd">hg commit</command> in the <filename 1.1078 + role="special" class="directory">.hg/patches</filename> 1.1079 + directory. This saves some bothersome typing.</para> 1.1080 + 1.1081 + <para>Finally, as a convenience to manage the patch directory, 1.1082 + you can define the alias <command>mq</command> on Unix 1.1083 + systems. For example, on Linux systems using the 1.1084 + <command>bash</command> shell, you can include the following 1.1085 + snippet in your <filename role="home"> 1.1086 + /.bashrc</filename>.</para> 1.1087 + 1.1088 + <programlisting> 1.1089 + alias mq=`hg -R $(hg root)/.hg/patches' 1.1090 + </programlisting> 1.1091 + 1.1092 + <para>You can then issue commands of the form <command>mq 1.1093 + pull</command> from the main repository.</para> 1.1094 + 1.1095 + </sect2> 1.1096 + <sect2> 1.1097 + <title>A few things to watch out for</title> 1.1098 + 1.1099 + <para>MQ's support for working with a repository full of patches 1.1100 + is limited in a few small respects.</para> 1.1101 + 1.1102 + <para>MQ cannot automatically detect changes that you make to 1.1103 + the patch directory. If you <command role="hg-cmd">hg 1.1104 + pull</command>, manually edit, or <command role="hg-cmd">hg 1.1105 + update</command> changes to patches or the <filename 1.1106 + role="special">series</filename> file, you will have to 1.1107 + <command role="hg-cmd">hg qpop <option 1.1108 + role="hg-ext-mq-cmd-qpop-opt">-a</option></command> and 1.1109 + then <command role="hg-cmd">hg qpush <option 1.1110 + role="hg-ext-mq-cmd-qpush-opt">-a</option></command> in 1.1111 + the underlying repository to see those changes show up there. 1.1112 + If you forget to do this, you can confuse MQ's idea of which 1.1113 + patches are applied.</para> 1.1114 + 1.1115 + </sect2> 1.1116 + </sect1> 1.1117 + <sect1 id="sec:mq:tools"> 1.1118 + <title>Third party tools for working with patches</title> 1.1119 + 1.1120 + <para>Once you've been working with patches for a while, you'll 1.1121 + find yourself hungry for tools that will help you to understand 1.1122 + and manipulate the patches you're dealing with.</para> 1.1123 + 1.1124 + <para>The <command>diffstat</command> command 1.1125 + <citation>web:diffstat</citation> generates a histogram of the 1.1126 + modifications made to each file in a patch. It provides a good 1.1127 + way to <quote>get a sense of</quote> a patch&emdash;which files it 1.1128 + affects, and how much change it introduces to each file and as a 1.1129 + whole. (I find that it's a good idea to use 1.1130 + <command>diffstat</command>'s <option 1.1131 + role="cmd-opt-diffstat">-p</option> option as a matter of 1.1132 + course, as otherwise it will try to do clever things with 1.1133 + prefixes of file names that inevitably confuse at least 1.1134 + me.)</para> 1.1135 + 1.1136 +<!-- &interaction.mq.tools.tools; --> 1.1137 + 1.1138 + <para>The <literal role="package">patchutils</literal> package 1.1139 + <citation>web:patchutils</citation> is invaluable. It provides a 1.1140 + set of small utilities that follow the <quote>Unix 1.1141 + philosophy;</quote> each does one useful thing with a patch. 1.1142 + The <literal role="package">patchutils</literal> command I use 1.1143 + most is <command>filterdiff</command>, which extracts subsets 1.1144 + from a patch file. For example, given a patch that modifies 1.1145 + hundreds of files across dozens of directories, a single 1.1146 + invocation of <command>filterdiff</command> can generate a 1.1147 + smaller patch that only touches files whose names match a 1.1148 + particular glob pattern. See section <xref 1.1149 + linkend="mq-collab:tips:interdiff"/> for another 1.1150 + example.</para> 1.1151 + 1.1152 + </sect1> 1.1153 + <sect1> 1.1154 + <title>Good ways to work with patches</title> 1.1155 + 1.1156 + <para>Whether you are working on a patch series to submit to a 1.1157 + free software or open source project, or a series that you 1.1158 + intend to treat as a sequence of regular changesets when you're 1.1159 + done, you can use some simple techniques to keep your work well 1.1160 + organised.</para> 1.1161 + 1.1162 + <para>Give your patches descriptive names. A good name for a 1.1163 + patch might be <filename>rework-device-alloc.patch</filename>, 1.1164 + because it will immediately give you a hint what the purpose of 1.1165 + the patch is. Long names shouldn't be a problem; you won't be 1.1166 + typing the names often, but you <emphasis>will</emphasis> be 1.1167 + running commands like <command 1.1168 + role="hg-ext-mq">hg qapplied</command> and <command 1.1169 + role="hg-ext-mq">hg qtop</command> over and over. Good naming 1.1170 + becomes especially important when you have a number of patches 1.1171 + to work with, or if you are juggling a number of different tasks 1.1172 + and your patches only get a fraction of your attention.</para> 1.1173 + 1.1174 + <para>Be aware of what patch you're working on. Use the <command 1.1175 + role="hg-ext-mq">hg qtop</command> command and skim over the text 1.1176 + of your patches frequently&emdash;for example, using <command 1.1177 + role="hg-cmd">hg tip <option 1.1178 + role="hg-opt-tip">-p</option></command>)&emdash;to be sure of 1.1179 + where you stand. I have several times worked on and <command 1.1180 + role="hg-ext-mq">hg qrefresh</command>ed a patch other than the 1.1181 + one I intended, and it's often tricky to migrate changes into 1.1182 + the right patch after making them in the wrong one.</para> 1.1183 + 1.1184 + <para>For this reason, it is very much worth investing a little 1.1185 + time to learn how to use some of the third-party tools I 1.1186 + described in section <xref linkend="sec:mq:tools"/>, 1.1187 + particularly <command>diffstat</command> and 1.1188 + <command>filterdiff</command>. The former will give you a quick 1.1189 + idea of what changes your patch is making, while the latter 1.1190 + makes it easy to splice hunks selectively out of one patch and 1.1191 + into another.</para> 1.1192 + 1.1193 + </sect1> 1.1194 + <sect1> 1.1195 + <title>MQ cookbook</title> 1.1196 + 1.1197 + <sect2> 1.1198 + <title>Manage <quote>trivial</quote> patches</title> 1.1199 + 1.1200 + <para>Because the overhead of dropping files into a new 1.1201 + Mercurial repository is so low, it makes a lot of sense to 1.1202 + manage patches this way even if you simply want to make a few 1.1203 + changes to a source tarball that you downloaded.</para> 1.1204 + 1.1205 + <para>Begin by downloading and unpacking the source tarball, and 1.1206 + turning it into a Mercurial repository. <!-- 1.1207 + &interaction.mq.tarball.download; --></para> 1.1208 + 1.1209 + <para>Continue by creating a patch stack and making your 1.1210 + changes. <!-- &interaction.mq.tarball.qinit; --></para> 1.1211 + 1.1212 + <para>Let's say a few weeks or months pass, and your package 1.1213 + author releases a new version. First, bring their changes 1.1214 + into the repository. <!-- &interaction.mq.tarball.newsource; 1.1215 + --> The pipeline starting with <command role="hg-cmd">hg 1.1216 + locate</command> above deletes all files in the working 1.1217 + directory, so that <command role="hg-cmd">hg 1.1218 + commit</command>'s <option 1.1219 + role="hg-opt-commit">--addremove</option> option can 1.1220 + actually tell which files have really been removed in the 1.1221 + newer version of the source.</para> 1.1222 + 1.1223 + <para>Finally, you can apply your patches on top of the new 1.1224 + tree. <!-- &interaction.mq.tarball.repush; --></para> 1.1225 + 1.1226 + </sect2> 1.1227 + <sect2 id="sec:mq:combine"> 1.1228 + <title>Combining entire patches</title> 1.1229 + 1.1230 + <para>MQ provides a command, <command 1.1231 + role="hg-ext-mq">hg qfold</command> that lets you combine 1.1232 + entire patches. This <quote>folds</quote> the patches you 1.1233 + name, in the order you name them, into the topmost applied 1.1234 + patch, and concatenates their descriptions onto the end of its 1.1235 + description. The patches that you fold must be unapplied 1.1236 + before you fold them.</para> 1.1237 + 1.1238 + <para>The order in which you fold patches matters. If your 1.1239 + topmost applied patch is <literal>foo</literal>, and you 1.1240 + <command role="hg-ext-mq">hg qfold</command> 1.1241 + <literal>bar</literal> and <literal>quux</literal> into it, 1.1242 + you will end up with a patch that has the same effect as if 1.1243 + you applied first <literal>foo</literal>, then 1.1244 + <literal>bar</literal>, followed by 1.1245 + <literal>quux</literal>.</para> 1.1246 + 1.1247 + </sect2> 1.1248 + <sect2> 1.1249 + <title>Merging part of one patch into another</title> 1.1250 + 1.1251 + <para>Merging <emphasis>part</emphasis> of one patch into 1.1252 + another is more difficult than combining entire 1.1253 + patches.</para> 1.1254 + 1.1255 + <para>If you want to move changes to entire files, you can use 1.1256 + <command>filterdiff</command>'s <option 1.1257 + role="cmd-opt-filterdiff">-i</option> and <option 1.1258 + role="cmd-opt-filterdiff">-x</option> options to choose the 1.1259 + modifications to snip out of one patch, concatenating its 1.1260 + output onto the end of the patch you want to merge into. You 1.1261 + usually won't need to modify the patch you've merged the 1.1262 + changes from. Instead, MQ will report some rejected hunks 1.1263 + when you <command role="hg-ext-mq">hg qpush</command> it (from 1.1264 + the hunks you moved into the other patch), and you can simply 1.1265 + <command role="hg-ext-mq">hg qrefresh</command> the patch to drop 1.1266 + the duplicate hunks.</para> 1.1267 + 1.1268 + <para>If you have a patch that has multiple hunks modifying a 1.1269 + file, and you only want to move a few of those hunks, the job 1.1270 + becomes more messy, but you can still partly automate it. Use 1.1271 + <command>lsdiff -nvv</command> to print some metadata about 1.1272 + the patch. <!-- &interaction.mq.tools.lsdiff; --></para> 1.1273 + 1.1274 + <para>This command prints three different kinds of 1.1275 + number:</para> 1.1276 + <itemizedlist> 1.1277 + <listitem><para>(in the first column) a <emphasis>file 1.1278 + number</emphasis> to identify each file modified in the 1.1279 + patch;</para></listitem> 1.1280 + 1.1281 + <listitem><para>(on the next line, indented) the line number 1.1282 + within a modified file where a hunk starts; 1.1283 + and</para></listitem> 1.1284 + 1.1285 + <listitem><para>(on the same line) a <emphasis>hunk 1.1286 + number</emphasis> to identify that 1.1287 + hunk.</para></listitem> 1.1288 + </itemizedlist> 1.1289 + 1.1290 + <para>You'll have to use some visual inspection, and reading of 1.1291 + the patch, to identify the file and hunk numbers you'll want, 1.1292 + but you can then pass them to to 1.1293 + <command>filterdiff</command>'s <option 1.1294 + role="cmd-opt-filterdiff">--files</option> and <option 1.1295 + role="cmd-opt-filterdiff">--hunks</option> options, to 1.1296 + select exactly the file and hunk you want to extract.</para> 1.1297 + 1.1298 + <para>Once you have this hunk, you can concatenate it onto the 1.1299 + end of your destination patch and continue with the remainder 1.1300 + of section <xref linkend="sec:mq:combine"/>.</para> 1.1301 + 1.1302 + </sect2> 1.1303 + </sect1> 1.1304 + <sect1> 1.1305 + <title>Differences between quilt and MQ</title> 1.1306 + 1.1307 + <para>If you are already familiar with quilt, MQ provides a 1.1308 + similar command set. There are a few differences in the way 1.1309 + that it works.</para> 1.1310 + 1.1311 + <para>You will already have noticed that most quilt commands have 1.1312 + MQ counterparts that simply begin with a 1.1313 + <quote><literal>q</literal></quote>. The exceptions are quilt's 1.1314 + <literal>add</literal> and <literal>remove</literal> commands, 1.1315 + the counterparts for which are the normal Mercurial <command 1.1316 + role="hg-cmd">hg add</command> and <command role="hg-cmd">hg 1.1317 + remove</command> commands. There is no MQ equivalent of the 1.1318 + quilt <literal>edit</literal> command.</para> 1.1319 + 1.1320 + </sect1> 1.1321 +</chapter> 1.1322 + 1.1323 +<!-- 1.1324 +local variables: 1.1325 +sgml-parent-document: ("00book.xml" "book" "chapter") 1.1326 +end: 1.1327 +-->