1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/fr/ch12-mq.xml	Tue Sep 08 15:30:26 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