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