1.1 --- a/fr/ch12-mq.xml	Sun Aug 16 04:58:01 2009 +0200
     1.2 +++ b/fr/ch12-mq.xml	Sat Sep 12 20:53:36 2009 +0200
     1.3 @@ -1,1309 +1,1368 @@
     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 id="chap:mq">
  1.1307 +  <?dbhtml filename="managing-change-with-mercurial-queues.html"?>
  1.1308 +  <title>Managing change with Mercurial Queues</title>
  1.1309 +
  1.1310 +  <sect1 id="sec:mq:patch-mgmt">
  1.1311 +    <title>The patch management problem</title>
  1.1312 +
  1.1313 +    <para id="x_3ac">Here is a common scenario: you need to install a software
  1.1314 +      package from source, but you find a bug that you must fix in the
  1.1315 +      source before you can start using the package.  You make your
  1.1316 +      changes, forget about the package for a while, and a few months
  1.1317 +      later you need to upgrade to a newer version of the package.  If
  1.1318 +      the newer version of the package still has the bug, you must
  1.1319 +      extract your fix from the older source tree and apply it against
  1.1320 +      the newer version.  This is a tedious task, and it's easy to
  1.1321 +      make mistakes.</para>
  1.1322 +
  1.1323 +    <para id="x_3ad">This is a simple case of the <quote>patch management</quote>
  1.1324 +      problem.  You have an <quote>upstream</quote> source tree that
  1.1325 +      you can't change; you need to make some local changes on top of
  1.1326 +      the upstream tree; and you'd like to be able to keep those
  1.1327 +      changes separate, so that you can apply them to newer versions
  1.1328 +      of the upstream source.</para>
  1.1329 +
  1.1330 +    <para id="x_3ae">The patch management problem arises in many situations.
  1.1331 +      Probably the most visible is that a user of an open source
  1.1332 +      software project will contribute a bug fix or new feature to the
  1.1333 +      project's maintainers in the form of a patch.</para>
  1.1334 +
  1.1335 +    <para id="x_3af">Distributors of operating systems that include open source
  1.1336 +      software often need to make changes to the packages they
  1.1337 +      distribute so that they will build properly in their
  1.1338 +      environments.</para>
  1.1339 +
  1.1340 +    <para id="x_3b0">When you have few changes to maintain, it is easy to manage
  1.1341 +      a single patch using the standard <command>diff</command> and
  1.1342 +      <command>patch</command> programs (see <xref
  1.1343 +	linkend="sec:mq:patch"/> for a discussion of these
  1.1344 +      tools). Once the number of changes grows, it starts to make
  1.1345 +      sense to maintain patches as discrete <quote>chunks of
  1.1346 +	work,</quote> so that for example a single patch will contain
  1.1347 +      only one bug fix (the patch might modify several files, but it's
  1.1348 +      doing <quote>only one thing</quote>), and you may have a number
  1.1349 +      of such patches for different bugs you need fixed and local
  1.1350 +      changes you require.  In this situation, if you submit a bug fix
  1.1351 +      patch to the upstream maintainers of a package and they include
  1.1352 +      your fix in a subsequent release, you can simply drop that
  1.1353 +      single patch when you're updating to the newer release.</para>
  1.1354 +
  1.1355 +    <para id="x_3b1">Maintaining a single patch against an upstream tree is a
  1.1356 +      little tedious and error-prone, but not difficult.  However, the
  1.1357 +      complexity of the problem grows rapidly as the number of patches
  1.1358 +      you have to maintain increases.  With more than a tiny number of
  1.1359 +      patches in hand, understanding which ones you have applied and
  1.1360 +      maintaining them moves from messy to overwhelming.</para>
  1.1361 +
  1.1362 +    <para id="x_3b2">Fortunately, Mercurial includes a powerful extension,
  1.1363 +      Mercurial Queues (or simply <quote>MQ</quote>), that massively
  1.1364 +      simplifies the patch management problem.</para>
  1.1365 +
  1.1366 +  </sect1>
  1.1367 +  <sect1 id="sec:mq:history">
  1.1368 +    <title>The prehistory of Mercurial Queues</title>
  1.1369 +
  1.1370 +    <para id="x_3b3">During the late 1990s, several Linux kernel developers
  1.1371 +      started to maintain <quote>patch series</quote> that modified
  1.1372 +      the behavior of the Linux kernel.  Some of these series were
  1.1373 +      focused on stability, some on feature coverage, and others were
  1.1374 +      more speculative.</para>
  1.1375 +
  1.1376 +    <para id="x_3b4">The sizes of these patch series grew rapidly.  In 2002,
  1.1377 +      Andrew Morton published some shell scripts he had been using to
  1.1378 +      automate the task of managing his patch queues.  Andrew was
  1.1379 +      successfully using these scripts to manage hundreds (sometimes
  1.1380 +      thousands) of patches on top of the Linux kernel.</para>
  1.1381 +
  1.1382 +    <sect2 id="sec:mq:quilt">
  1.1383 +      <title>A patchwork quilt</title>
  1.1384 +
  1.1385 +      <para id="x_3b5">In early 2003, Andreas Gruenbacher and Martin Quinson
  1.1386 +	borrowed the approach of Andrew's scripts and published a tool
  1.1387 +	called <quote>patchwork quilt</quote>
  1.1388 +	<citation>web:quilt</citation>, or simply <quote>quilt</quote>
  1.1389 +	(see <citation>gruenbacher:2005</citation> for a paper
  1.1390 +	describing it).  Because quilt substantially automated patch
  1.1391 +	management, it rapidly gained a large following among open
  1.1392 +	source software developers.</para>
  1.1393 +
  1.1394 +      <para id="x_3b6">Quilt manages a <emphasis>stack of patches</emphasis> on
  1.1395 +	top of a directory tree. To begin, you tell quilt to manage a
  1.1396 +	directory tree, and tell it which files you want to manage; it
  1.1397 +	stores away the names and contents of those files.  To fix a
  1.1398 +	bug, you create a new patch (using a single command), edit the
  1.1399 +	files you need to fix, then <quote>refresh</quote> the
  1.1400 +	patch.</para>
  1.1401 +
  1.1402 +      <para id="x_3b7">The refresh step causes quilt to scan the directory tree;
  1.1403 +	it updates the patch with all of the changes you have made.
  1.1404 +	You can create another patch on top of the first, which will
  1.1405 +	track the changes required to modify the tree from <quote>tree
  1.1406 +	  with one patch applied</quote> to <quote>tree with two
  1.1407 +	  patches applied</quote>.</para>
  1.1408 +
  1.1409 +      <para id="x_3b8">You can <emphasis>change</emphasis> which patches are
  1.1410 +	applied to the tree.  If you <quote>pop</quote> a patch, the
  1.1411 +	changes made by that patch will vanish from the directory
  1.1412 +	tree.  Quilt remembers which patches you have popped, though,
  1.1413 +	so you can <quote>push</quote> a popped patch again, and the
  1.1414 +	directory tree will be restored to contain the modifications
  1.1415 +	in the patch.  Most importantly, you can run the
  1.1416 +	<quote>refresh</quote> command at any time, and the topmost
  1.1417 +	applied patch will be updated.  This means that you can, at
  1.1418 +	any time, change both which patches are applied and what
  1.1419 +	modifications those patches make.</para>
  1.1420 +
  1.1421 +      <para id="x_3b9">Quilt knows nothing about revision control tools, so it
  1.1422 +	works equally well on top of an unpacked tarball or a
  1.1423 +	Subversion working copy.</para>
  1.1424 +    </sect2>
  1.1425 +
  1.1426 +    <sect2 id="sec:mq:quilt-mq">
  1.1427 +      <title>From patchwork quilt to Mercurial Queues</title>
  1.1428 +
  1.1429 +      <para id="x_3ba">In mid-2005, Chris Mason took the features of quilt and
  1.1430 +	wrote an extension that he called Mercurial Queues, which
  1.1431 +	added quilt-like behavior to Mercurial.</para>
  1.1432 +
  1.1433 +      <para id="x_3bb">The key difference between quilt and MQ is that quilt
  1.1434 +	knows nothing about revision control systems, while MQ is
  1.1435 +	<emphasis>integrated</emphasis> into Mercurial.  Each patch
  1.1436 +	that you push is represented as a Mercurial changeset.  Pop a
  1.1437 +	patch, and the changeset goes away.</para>
  1.1438 +
  1.1439 +      <para id="x_3bc">Because quilt does not care about revision control tools,
  1.1440 +	it is still a tremendously useful piece of software to know
  1.1441 +	about for situations where you cannot use Mercurial and
  1.1442 +	MQ.</para>
  1.1443 +
  1.1444 +    </sect2>
  1.1445 +  </sect1>
  1.1446 +  <sect1>
  1.1447 +    <title>The huge advantage of MQ</title>
  1.1448 +
  1.1449 +    <para id="x_3bd">I cannot overstate the value that MQ offers through the
  1.1450 +      unification of patches and revision control.</para>
  1.1451 +
  1.1452 +    <para id="x_3be">A major reason that patches have persisted in the free
  1.1453 +      software and open source world&emdash;in spite of the
  1.1454 +      availability of increasingly capable revision control tools over
  1.1455 +      the years&emdash;is the <emphasis>agility</emphasis> they
  1.1456 +      offer.</para>
  1.1457 +
  1.1458 +    <para id="x_3bf">Traditional revision control tools make a permanent,
  1.1459 +      irreversible record of everything that you do.  While this has
  1.1460 +      great value, it's also somewhat stifling.  If you want to
  1.1461 +      perform a wild-eyed experiment, you have to be careful in how
  1.1462 +      you go about it, or you risk leaving unneeded&emdash;or worse,
  1.1463 +      misleading or destabilising&emdash;traces of your missteps and
  1.1464 +      errors in the permanent revision record.</para>
  1.1465 +
  1.1466 +    <para id="x_3c0">By contrast, MQ's marriage of distributed revision control
  1.1467 +      with patches makes it much easier to isolate your work.  Your
  1.1468 +      patches live on top of normal revision history, and you can make
  1.1469 +      them disappear or reappear at will.  If you don't like a patch,
  1.1470 +      you can drop it.  If a patch isn't quite as you want it to be,
  1.1471 +      simply fix it&emdash;as many times as you need to, until you
  1.1472 +      have refined it into the form you desire.</para>
  1.1473 +
  1.1474 +    <para id="x_3c1">As an example, the integration of patches with revision
  1.1475 +      control makes understanding patches and debugging their
  1.1476 +      effects&emdash;and their interplay with the code they're based
  1.1477 +      on&emdash;<emphasis>enormously</emphasis> easier. Since every
  1.1478 +      applied patch has an associated changeset, you can give <command
  1.1479 +	role="hg-cmd">hg log</command> a file name to see which
  1.1480 +      changesets and patches affected the file.  You can use the
  1.1481 +      <command role="hg-cmd">hg bisect</command> command to
  1.1482 +      binary-search through all changesets and applied patches to see
  1.1483 +      where a bug got introduced or fixed.  You can use the <command
  1.1484 +	role="hg-cmd">hg annotate</command> command to see which
  1.1485 +      changeset or patch modified a particular line of a source file.
  1.1486 +      And so on.</para>
  1.1487 +  </sect1>
  1.1488 +
  1.1489 +  <sect1 id="sec:mq:patch">
  1.1490 +    <title>Understanding patches</title>
  1.1491 +
  1.1492 +    <para id="x_3c2">Because MQ doesn't hide its patch-oriented nature, it is
  1.1493 +      helpful to understand what patches are, and a little about the
  1.1494 +      tools that work with them.</para>
  1.1495 +
  1.1496 +    <para id="x_3c3">The traditional Unix <command>diff</command> command
  1.1497 +      compares two files, and prints a list of differences between
  1.1498 +      them. The <command>patch</command> command understands these
  1.1499 +      differences as <emphasis>modifications</emphasis> to make to a
  1.1500 +      file.  Take a look below for a simple example of these commands
  1.1501 +      in action.</para>
  1.1502 +
  1.1503 +      &interaction.mq.dodiff.diff;
  1.1504 +
  1.1505 +    <para id="x_3c4">The type of file that <command>diff</command> generates (and
  1.1506 +      <command>patch</command> takes as input) is called a
  1.1507 +      <quote>patch</quote> or a <quote>diff</quote>; there is no
  1.1508 +      difference between a patch and a diff.  (We'll use the term
  1.1509 +      <quote>patch</quote>, since it's more commonly used.)</para>
  1.1510 +
  1.1511 +    <para id="x_3c5">A patch file can start with arbitrary text; the
  1.1512 +      <command>patch</command> command ignores this text, but MQ uses
  1.1513 +      it as the commit message when creating changesets.  To find the
  1.1514 +      beginning of the patch content, <command>patch</command>
  1.1515 +      searches for the first line that starts with the string
  1.1516 +      <quote><literal>diff -</literal></quote>.</para>
  1.1517 +
  1.1518 +    <para id="x_3c6">MQ works with <emphasis>unified</emphasis> diffs
  1.1519 +      (<command>patch</command> can accept several other diff formats,
  1.1520 +      but MQ doesn't).  A unified diff contains two kinds of header.
  1.1521 +      The <emphasis>file header</emphasis> describes the file being
  1.1522 +      modified; it contains the name of the file to modify.  When
  1.1523 +      <command>patch</command> sees a new file header, it looks for a
  1.1524 +      file with that name to start modifying.</para>
  1.1525 +
  1.1526 +    <para id="x_3c7">After the file header comes a series of
  1.1527 +      <emphasis>hunks</emphasis>.  Each hunk starts with a header;
  1.1528 +      this identifies the range of line numbers within the file that
  1.1529 +      the hunk should modify.  Following the header, a hunk starts and
  1.1530 +      ends with a few (usually three) lines of text from the
  1.1531 +      unmodified file; these are called the
  1.1532 +      <emphasis>context</emphasis> for the hunk.  If there's only a
  1.1533 +      small amount of context between successive hunks,
  1.1534 +      <command>diff</command> doesn't print a new hunk header; it just
  1.1535 +      runs the hunks together, with a few lines of context between
  1.1536 +      modifications.</para>
  1.1537 +
  1.1538 +    <para id="x_3c8">Each line of context begins with a space character.  Within
  1.1539 +      the hunk, a line that begins with
  1.1540 +      <quote><literal>-</literal></quote> means <quote>remove this
  1.1541 +	line,</quote> while a line that begins with
  1.1542 +      <quote><literal>+</literal></quote> means <quote>insert this
  1.1543 +	line.</quote>  For example, a line that is modified is
  1.1544 +      represented by one deletion and one insertion.</para>
  1.1545 +
  1.1546 +    <para id="x_3c9">We will return to some of the more subtle aspects of patches
  1.1547 +      later (in <xref linkend="sec:mq:adv-patch"/>), but you
  1.1548 +      should have
  1.1549 +      enough information now to use MQ.</para>
  1.1550 +  </sect1>
  1.1551 +
  1.1552 +  <sect1 id="sec:mq:start">
  1.1553 +    <title>Getting started with Mercurial Queues</title>
  1.1554 +
  1.1555 +    <para id="x_3ca">Because MQ is implemented as an extension, you must
  1.1556 +      explicitly enable before you can use it.  (You don't need to
  1.1557 +      download anything; MQ ships with the standard Mercurial
  1.1558 +      distribution.)  To enable MQ, edit your <filename
  1.1559 +	role="home">~/.hgrc</filename> file, and add the lines
  1.1560 +      below.</para>
  1.1561 +
  1.1562 +    <programlisting>[extensions]
  1.1563 +hgext.mq =</programlisting>
  1.1564 +
  1.1565 +    <para id="x_3cb">Once the extension is enabled, it will make a number of new
  1.1566 +      commands available.  To verify that the extension is working,
  1.1567 +      you can use <command role="hg-cmd">hg help</command> to see if
  1.1568 +      the <command role="hg-ext-mq">qinit</command> command is now
  1.1569 +      available.</para>
  1.1570 +
  1.1571 +    &interaction.mq.qinit-help.help;
  1.1572 +
  1.1573 +    <para id="x_3cc">You can use MQ with <emphasis>any</emphasis> Mercurial
  1.1574 +      repository, and its commands only operate within that
  1.1575 +      repository.  To get started, simply prepare the repository using
  1.1576 +      the <command role="hg-ext-mq">qinit</command> command.</para>
  1.1577 +
  1.1578 +    &interaction.mq.tutorial.qinit;
  1.1579 +
  1.1580 +    <para id="x_3cd">This command creates an empty directory called <filename
  1.1581 +	role="special" class="directory">.hg/patches</filename>, where
  1.1582 +      MQ will keep its metadata.  As with many Mercurial commands, the
  1.1583 +      <command role="hg-ext-mq">qinit</command> command prints nothing
  1.1584 +      if it succeeds.</para>
  1.1585 +
  1.1586 +    <sect2>
  1.1587 +      <title>Creating a new patch</title>
  1.1588 +
  1.1589 +      <para id="x_3ce">To begin work on a new patch, use the <command
  1.1590 +	  role="hg-ext-mq">qnew</command> command.  This command takes
  1.1591 +	one argument, the name of the patch to create.</para>
  1.1592 +
  1.1593 +      <para id="x_3cf">MQ will use this as the name of an actual file in the
  1.1594 +	<filename role="special"
  1.1595 +	  class="directory">.hg/patches</filename> directory, as you
  1.1596 +	can see below.</para>
  1.1597 +
  1.1598 +      &interaction.mq.tutorial.qnew;
  1.1599 +
  1.1600 +      <para id="x_3d0">Also newly present in the <filename role="special"
  1.1601 +	  class="directory">.hg/patches</filename> directory are two
  1.1602 +	other files, <filename role="special">series</filename> and
  1.1603 +	<filename role="special">status</filename>.  The <filename
  1.1604 +	  role="special">series</filename> file lists all of the
  1.1605 +	patches that MQ knows about for this repository, with one
  1.1606 +	patch per line.  Mercurial uses the <filename
  1.1607 +	  role="special">status</filename> file for internal
  1.1608 +	book-keeping; it tracks all of the patches that MQ has
  1.1609 +	<emphasis>applied</emphasis> in this repository.</para>
  1.1610 +
  1.1611 +      <note>
  1.1612 +	<para id="x_3d1">  You may sometimes want to edit the <filename
  1.1613 +	    role="special">series</filename> file by hand; for
  1.1614 +	  example, to change the sequence in which some patches are
  1.1615 +	  applied.  However, manually editing the <filename
  1.1616 +	    role="special">status</filename> file is almost always a
  1.1617 +	  bad idea, as it's easy to corrupt MQ's idea of what is
  1.1618 +	  happening.</para>
  1.1619 +      </note>
  1.1620 +
  1.1621 +      <para id="x_3d2">Once you have created your new patch, you can edit files
  1.1622 +	in the working directory as you usually would.  All of the
  1.1623 +	normal Mercurial commands, such as <command role="hg-cmd">hg
  1.1624 +	  diff</command> and <command role="hg-cmd">hg
  1.1625 +	  annotate</command>, work exactly as they did before.</para>
  1.1626 +    </sect2>
  1.1627 +
  1.1628 +    <sect2>
  1.1629 +      <title>Refreshing a patch</title>
  1.1630 +
  1.1631 +      <para id="x_3d3">When you reach a point where you want to save your work,
  1.1632 +	use the <command role="hg-ext-mq">qrefresh</command> command
  1.1633 +	to update the patch you are working on.</para>
  1.1634 +
  1.1635 +      &interaction.mq.tutorial.qrefresh;
  1.1636 +
  1.1637 +      <para id="x_3d4">This command folds the changes you have made in the
  1.1638 +	working directory into your patch, and updates its
  1.1639 +	corresponding changeset to contain those changes.</para>
  1.1640 +
  1.1641 +      <para id="x_3d5">You can run <command role="hg-ext-mq">qrefresh</command>
  1.1642 +	as often as you like, so it's a good way to
  1.1643 +	<quote>checkpoint</quote> your work.  Refresh your patch at an
  1.1644 +	opportune time; try an experiment; and if the experiment
  1.1645 +	doesn't work out, <command role="hg-cmd">hg revert</command>
  1.1646 +	your modifications back to the last time you refreshed.</para>
  1.1647 +
  1.1648 +      &interaction.mq.tutorial.qrefresh2;
  1.1649 +    </sect2>
  1.1650 +
  1.1651 +    <sect2>
  1.1652 +      <title>Stacking and tracking patches</title>
  1.1653 +
  1.1654 +      <para id="x_3d6">Once you have finished working on a patch, or need to work
  1.1655 +	on another, you can use the <command
  1.1656 +	  role="hg-ext-mq">qnew</command> command again to create a
  1.1657 +	new patch. Mercurial will apply this patch on top of your
  1.1658 +	existing patch.</para>
  1.1659 +
  1.1660 +      &interaction.mq.tutorial.qnew2;
  1.1661 +
  1.1662 +      <para id="x_3d7">Notice that the patch contains the changes in our prior
  1.1663 +	patch as part of its context (you can see this more clearly in
  1.1664 +	the output of <command role="hg-cmd">hg
  1.1665 +	  annotate</command>).</para>
  1.1666 +
  1.1667 +      <para id="x_3d8">So far, with the exception of <command
  1.1668 +	  role="hg-ext-mq">qnew</command> and <command
  1.1669 +	  role="hg-ext-mq">qrefresh</command>, we've been careful to
  1.1670 +	only use regular Mercurial commands.  However, MQ provides
  1.1671 +	many commands that are easier to use when you are thinking
  1.1672 +	about patches, as illustrated below.</para>
  1.1673 +
  1.1674 +      &interaction.mq.tutorial.qseries;
  1.1675 +
  1.1676 +      <itemizedlist>
  1.1677 +	<listitem><para id="x_3d9">The <command
  1.1678 +	      role="hg-ext-mq">qseries</command> command lists every
  1.1679 +	    patch that MQ knows about in this repository, from oldest
  1.1680 +	    to newest (most recently
  1.1681 +	    <emphasis>created</emphasis>).</para>
  1.1682 +	</listitem>
  1.1683 +	<listitem><para id="x_3da">The <command
  1.1684 +	      role="hg-ext-mq">qapplied</command> command lists every
  1.1685 +	    patch that MQ has <emphasis>applied</emphasis> in this
  1.1686 +	    repository, again from oldest to newest (most recently
  1.1687 +	    applied).</para>
  1.1688 +	</listitem></itemizedlist>
  1.1689 +    </sect2>
  1.1690 +
  1.1691 +    <sect2>
  1.1692 +      <title>Manipulating the patch stack</title>
  1.1693 +
  1.1694 +      <para id="x_3db">The previous discussion implied that there must be a
  1.1695 +	difference between <quote>known</quote> and
  1.1696 +	<quote>applied</quote> patches, and there is.  MQ can manage a
  1.1697 +	patch without it being applied in the repository.</para>
  1.1698 +
  1.1699 +      <para id="x_3dc">An <emphasis>applied</emphasis> patch has a corresponding
  1.1700 +	changeset in the repository, and the effects of the patch and
  1.1701 +	changeset are visible in the working directory.  You can undo
  1.1702 +	the application of a patch using the <command
  1.1703 +	  role="hg-ext-mq">qpop</command> command.  MQ still
  1.1704 +	<emphasis>knows about</emphasis>, or manages, a popped patch,
  1.1705 +	but the patch no longer has a corresponding changeset in the
  1.1706 +	repository, and the working directory does not contain the
  1.1707 +	changes made by the patch.  <xref
  1.1708 +	  linkend="fig:mq:stack"/> illustrates
  1.1709 +	the difference between applied and tracked patches.</para>
  1.1710 +
  1.1711 +      <figure id="fig:mq:stack">
  1.1712 +	<title>Applied and unapplied patches in the MQ patch
  1.1713 +	  stack</title>
  1.1714 +	<mediaobject>
  1.1715 +	  <imageobject><imagedata fileref="figs/mq-stack.png"/></imageobject>
  1.1716 +	  <textobject><phrase>XXX add text</phrase></textobject>
  1.1717 +	</mediaobject>
  1.1718 +      </figure>
  1.1719 +
  1.1720 +      <para id="x_3de">You can reapply an unapplied, or popped, patch using the
  1.1721 +	<command role="hg-ext-mq">qpush</command> command.  This
  1.1722 +	creates a new changeset to correspond to the patch, and the
  1.1723 +	patch's changes once again become present in the working
  1.1724 +	directory.  See below for examples of <command
  1.1725 +	  role="hg-ext-mq">qpop</command> and <command
  1.1726 +	  role="hg-ext-mq">qpush</command> in action.</para>
  1.1727 +
  1.1728 +      &interaction.mq.tutorial.qpop;
  1.1729 +
  1.1730 +      <para id="x_3df">Notice that once we have popped a patch or two patches,
  1.1731 +	the output of <command role="hg-ext-mq">qseries</command>
  1.1732 +	remains the same, while that of <command
  1.1733 +	  role="hg-ext-mq">qapplied</command> has changed.</para>
  1.1734 +
  1.1735 +    </sect2>
  1.1736 +
  1.1737 +    <sect2>
  1.1738 +      <title>Pushing and popping many patches</title>
  1.1739 +
  1.1740 +      <para id="x_3e0">While <command role="hg-ext-mq">qpush</command> and
  1.1741 +	<command role="hg-ext-mq">qpop</command> each operate on a
  1.1742 +	single patch at a time by default, you can push and pop many
  1.1743 +	patches in one go.  The <option
  1.1744 +	  role="hg-ext-mq-cmd-qpush-opt">hg -a</option> option to
  1.1745 +	<command role="hg-ext-mq">qpush</command> causes it to push
  1.1746 +	all unapplied patches, while the <option
  1.1747 +	  role="hg-ext-mq-cmd-qpop-opt">-a</option> option to <command
  1.1748 +	  role="hg-ext-mq">qpop</command> causes it to pop all applied
  1.1749 +	patches.  (For some more ways to push and pop many patches,
  1.1750 +	see <xref linkend="sec:mq:perf"/> below.)</para>
  1.1751 +
  1.1752 +      &interaction.mq.tutorial.qpush-a;
  1.1753 +    </sect2>
  1.1754 +
  1.1755 +    <sect2>
  1.1756 +      <title>Safety checks, and overriding them</title>
  1.1757 +
  1.1758 +      <para id="x_3e1">Several MQ commands check the working directory before
  1.1759 +	they do anything, and fail if they find any modifications.
  1.1760 +	They do this to ensure that you won't lose any changes that
  1.1761 +	you have made, but not yet incorporated into a patch.  The
  1.1762 +	example below illustrates this; the <command
  1.1763 +	  role="hg-ext-mq">qnew</command> command will not create a
  1.1764 +	new patch if there are outstanding changes, caused in this
  1.1765 +	case by the <command role="hg-cmd">hg add</command> of
  1.1766 +	<filename>file3</filename>.</para>
  1.1767 +
  1.1768 +      &interaction.mq.tutorial.add;
  1.1769 +
  1.1770 +      <para id="x_3e2">Commands that check the working directory all take an
  1.1771 +	<quote>I know what I'm doing</quote> option, which is always
  1.1772 +	named <option>-f</option>.  The exact meaning of
  1.1773 +	<option>-f</option> depends on the command.  For example,
  1.1774 +	<command role="hg-cmd">hg qnew <option
  1.1775 +	    role="hg-ext-mq-cmd-qnew-opt">hg -f</option></command>
  1.1776 +	will incorporate any outstanding changes into the new patch it
  1.1777 +	creates, but <command role="hg-cmd">hg qpop <option
  1.1778 +	    role="hg-ext-mq-cmd-qpop-opt">hg -f</option></command>
  1.1779 +	will revert modifications to any files affected by the patch
  1.1780 +	that it is popping.  Be sure to read the documentation for a
  1.1781 +	command's <option>-f</option> option before you use it!</para>
  1.1782 +    </sect2>
  1.1783 +
  1.1784 +    <sect2>
  1.1785 +      <title>Working on several patches at once</title>
  1.1786 +
  1.1787 +      <para id="x_3e3">The <command role="hg-ext-mq">qrefresh</command> command
  1.1788 +	always refreshes the <emphasis>topmost</emphasis> applied
  1.1789 +	patch.  This means that you can suspend work on one patch (by
  1.1790 +	refreshing it), pop or push to make a different patch the top,
  1.1791 +	and work on <emphasis>that</emphasis> patch for a
  1.1792 +	while.</para>
  1.1793 +
  1.1794 +      <para id="x_3e4">Here's an example that illustrates how you can use this
  1.1795 +	ability. Let's say you're developing a new feature as two
  1.1796 +	patches.  The first is a change to the core of your software,
  1.1797 +	and the second&emdash;layered on top of the
  1.1798 +	first&emdash;changes the user interface to use the code you
  1.1799 +	just added to the core.  If you notice a bug in the core while
  1.1800 +	you're working on the UI patch, it's easy to fix the core.
  1.1801 +	Simply <command role="hg-ext-mq">qrefresh</command> the UI
  1.1802 +	patch to save your in-progress changes, and <command
  1.1803 +	  role="hg-ext-mq">qpop</command> down to the core patch.  Fix
  1.1804 +	the core bug, <command role="hg-ext-mq">qrefresh</command> the
  1.1805 +	core patch, and <command role="hg-ext-mq">qpush</command> back
  1.1806 +	to the UI patch to continue where you left off.</para>
  1.1807 +    </sect2>
  1.1808 +  </sect1>
  1.1809 +
  1.1810 +  <sect1 id="sec:mq:adv-patch">
  1.1811 +    <title>More about patches</title>
  1.1812 +
  1.1813 +    <para id="x_3e5">MQ uses the GNU <command>patch</command> command to apply
  1.1814 +      patches, so it's helpful to know a few more detailed aspects of
  1.1815 +      how <command>patch</command> works, and about patches
  1.1816 +      themselves.</para>
  1.1817 +
  1.1818 +    <sect2>
  1.1819 +      <title>The strip count</title>
  1.1820 +
  1.1821 +      <para id="x_3e6">If you look at the file headers in a patch, you will
  1.1822 +	notice that the pathnames usually have an extra component on
  1.1823 +	the front that isn't present in the actual path name.  This is
  1.1824 +	a holdover from the way that people used to generate patches
  1.1825 +	(people still do this, but it's somewhat rare with modern
  1.1826 +	revision control tools).</para>
  1.1827 +
  1.1828 +      <para id="x_3e7">Alice would unpack a tarball, edit her files, then decide
  1.1829 +	that she wanted to create a patch.  So she'd rename her
  1.1830 +	working directory, unpack the tarball again (hence the need
  1.1831 +	for the rename), and use the <option
  1.1832 +	  role="cmd-opt-diff">-r</option> and <option
  1.1833 +	  role="cmd-opt-diff">-N</option> options to
  1.1834 +	<command>diff</command> to recursively generate a patch
  1.1835 +	between the unmodified directory and the modified one.  The
  1.1836 +	result would be that the name of the unmodified directory
  1.1837 +	would be at the front of the left-hand path in every file
  1.1838 +	header, and the name of the modified directory would be at the
  1.1839 +	front of the right-hand path.</para>
  1.1840 +
  1.1841 +      <para id="x_3e8">Since someone receiving a patch from the Alices of the net
  1.1842 +	would be unlikely to have unmodified and modified directories
  1.1843 +	with exactly the same names, the <command>patch</command>
  1.1844 +	command has a <option role="cmd-opt-patch">-p</option> option
  1.1845 +	that indicates the number of leading path name components to
  1.1846 +	strip when trying to apply a patch.  This number is called the
  1.1847 +	<emphasis>strip count</emphasis>.</para>
  1.1848 +
  1.1849 +      <para id="x_3e9">An option of <quote><literal>-p1</literal></quote> means
  1.1850 +	<quote>use a strip count of one</quote>.  If
  1.1851 +	<command>patch</command> sees a file name
  1.1852 +	<filename>foo/bar/baz</filename> in a file header, it will
  1.1853 +	strip <filename>foo</filename> and try to patch a file named
  1.1854 +	<filename>bar/baz</filename>.  (Strictly speaking, the strip
  1.1855 +	count refers to the number of <emphasis>path
  1.1856 +	  separators</emphasis> (and the components that go with them
  1.1857 +	) to strip.  A strip count of one will turn
  1.1858 +	<filename>foo/bar</filename> into <filename>bar</filename>,
  1.1859 +	but <filename>/foo/bar</filename> (notice the extra leading
  1.1860 +	slash) into <filename>foo/bar</filename>.)</para>
  1.1861 +
  1.1862 +      <para id="x_3ea">The <quote>standard</quote> strip count for patches is
  1.1863 +	one; almost all patches contain one leading path name
  1.1864 +	component that needs to be stripped. Mercurial's <command
  1.1865 +	  role="hg-cmd">hg diff</command> command generates path names
  1.1866 +	in this form, and the <command role="hg-cmd">hg
  1.1867 +	  import</command> command and MQ expect patches to have a
  1.1868 +	strip count of one.</para>
  1.1869 +
  1.1870 +      <para id="x_3eb">If you receive a patch from someone that you want to add
  1.1871 +	to your patch queue, and the patch needs a strip count other
  1.1872 +	than one, you cannot just <command
  1.1873 +	  role="hg-ext-mq">qimport</command> the patch, because
  1.1874 +	<command role="hg-ext-mq">qimport</command> does not yet have
  1.1875 +	a <literal>-p</literal> option (see <ulink role="hg-bug"
  1.1876 +	  url="http://www.selenic.com/mercurial/bts/issue311">issue
  1.1877 +	  311</ulink>).  Your best bet is to <command
  1.1878 +	  role="hg-ext-mq">qnew</command> a patch of your own, then
  1.1879 +	use <command>patch -pN</command> to apply their patch,
  1.1880 +	followed by <command role="hg-cmd">hg addremove</command> to
  1.1881 +	pick up any files added or removed by the patch, followed by
  1.1882 +	<command role="hg-ext-mq">hg qrefresh</command>. This
  1.1883 +	complexity may become unnecessary; see <ulink role="hg-bug"
  1.1884 +	  url="http://www.selenic.com/mercurial/bts/issue311">issue
  1.1885 +	  311</ulink> for details.
  1.1886 +      </para>
  1.1887 +    </sect2>
  1.1888 +
  1.1889 +    <sect2>
  1.1890 +      <title>Strategies for applying a patch</title>
  1.1891 +
  1.1892 +      <para id="x_3ec">When <command>patch</command> applies a hunk, it tries a
  1.1893 +	handful of successively less accurate strategies to try to
  1.1894 +	make the hunk apply. This falling-back technique often makes
  1.1895 +	it possible to take a patch that was generated against an old
  1.1896 +	version of a file, and apply it against a newer version of
  1.1897 +	that file.</para>
  1.1898 +
  1.1899 +      <para id="x_3ed">First, <command>patch</command> tries an exact match,
  1.1900 +	where the line numbers, the context, and the text to be
  1.1901 +	modified must apply exactly.  If it cannot make an exact
  1.1902 +	match, it tries to find an exact match for the context,
  1.1903 +	without honouring the line numbering information.  If this
  1.1904 +	succeeds, it prints a line of output saying that the hunk was
  1.1905 +	applied, but at some <emphasis>offset</emphasis> from the
  1.1906 +	original line number.</para>
  1.1907 +
  1.1908 +      <para id="x_3ee">If a context-only match fails, <command>patch</command>
  1.1909 +	removes the first and last lines of the context, and tries a
  1.1910 +	<emphasis>reduced</emphasis> context-only match.  If the hunk
  1.1911 +	with reduced context succeeds, it prints a message saying that
  1.1912 +	it applied the hunk with a <emphasis>fuzz factor</emphasis>
  1.1913 +	(the number after the fuzz factor indicates how many lines of
  1.1914 +	context <command>patch</command> had to trim before the patch
  1.1915 +	applied).</para>
  1.1916 +
  1.1917 +      <para id="x_3ef">When neither of these techniques works,
  1.1918 +	<command>patch</command> prints a message saying that the hunk
  1.1919 +	in question was rejected.  It saves rejected hunks (also
  1.1920 +	simply called <quote>rejects</quote>) to a file with the same
  1.1921 +	name, and an added <filename role="special">.rej</filename>
  1.1922 +	extension.  It also saves an unmodified copy of the file with
  1.1923 +	a <filename role="special">.orig</filename> extension; the
  1.1924 +	copy of the file without any extensions will contain any
  1.1925 +	changes made by hunks that <emphasis>did</emphasis> apply
  1.1926 +	cleanly.  If you have a patch that modifies
  1.1927 +	<filename>foo</filename> with six hunks, and one of them fails
  1.1928 +	to apply, you will have: an unmodified
  1.1929 +	<filename>foo.orig</filename>, a <filename>foo.rej</filename>
  1.1930 +	containing one hunk, and <filename>foo</filename>, containing
  1.1931 +	the changes made by the five successful hunks.</para>
  1.1932 +    </sect2>
  1.1933 +
  1.1934 +    <sect2>
  1.1935 +      <title>Some quirks of patch representation</title>
  1.1936 +
  1.1937 +      <para id="x_3f0">There are a few useful things to know about how
  1.1938 +	<command>patch</command> works with files.</para>
  1.1939 +      <itemizedlist>
  1.1940 +	<listitem><para id="x_3f1">This should already be obvious, but
  1.1941 +	    <command>patch</command> cannot handle binary
  1.1942 +	    files.</para>
  1.1943 +	</listitem>
  1.1944 +	<listitem><para id="x_3f2">Neither does it care about the executable bit;
  1.1945 +	    it creates new files as readable, but not
  1.1946 +	    executable.</para>
  1.1947 +	</listitem>
  1.1948 +	<listitem><para id="x_3f3"><command>patch</command> treats the removal of
  1.1949 +	    a file as a diff between the file to be removed and the
  1.1950 +	    empty file.  So your idea of <quote>I deleted this
  1.1951 +	      file</quote> looks like <quote>every line of this file
  1.1952 +	      was deleted</quote> in a patch.</para>
  1.1953 +	</listitem>
  1.1954 +	<listitem><para id="x_3f4">It treats the addition of a file as a diff
  1.1955 +	    between the empty file and the file to be added.  So in a
  1.1956 +	    patch, your idea of <quote>I added this file</quote> looks
  1.1957 +	    like <quote>every line of this file was
  1.1958 +	      added</quote>.</para>
  1.1959 +	</listitem>
  1.1960 +	<listitem><para id="x_3f5">It treats a renamed file as the removal of the
  1.1961 +	    old name, and the addition of the new name.  This means
  1.1962 +	    that renamed files have a big footprint in patches.  (Note
  1.1963 +	    also that Mercurial does not currently try to infer when
  1.1964 +	    files have been renamed or copied in a patch.)</para>
  1.1965 +	</listitem>
  1.1966 +	<listitem><para id="x_3f6"><command>patch</command> cannot represent
  1.1967 +	    empty files, so you cannot use a patch to represent the
  1.1968 +	    notion <quote>I added this empty file to the
  1.1969 +	      tree</quote>.</para>
  1.1970 +	</listitem></itemizedlist>
  1.1971 +    </sect2>
  1.1972 +
  1.1973 +    <sect2>
  1.1974 +      <title>Beware the fuzz</title>
  1.1975 +
  1.1976 +      <para id="x_3f7">While applying a hunk at an offset, or with a fuzz factor,
  1.1977 +	will often be completely successful, these inexact techniques
  1.1978 +	naturally leave open the possibility of corrupting the patched
  1.1979 +	file.  The most common cases typically involve applying a
  1.1980 +	patch twice, or at an incorrect location in the file.  If
  1.1981 +	<command>patch</command> or <command
  1.1982 +	  role="hg-ext-mq">qpush</command> ever mentions an offset or
  1.1983 +	fuzz factor, you should make sure that the modified files are
  1.1984 +	correct afterwards.</para>
  1.1985 +
  1.1986 +      <para id="x_3f8">It's often a good idea to refresh a patch that has applied
  1.1987 +	with an offset or fuzz factor; refreshing the patch generates
  1.1988 +	new context information that will make it apply cleanly.  I
  1.1989 +	say <quote>often,</quote> not <quote>always,</quote> because
  1.1990 +	sometimes refreshing a patch will make it fail to apply
  1.1991 +	against a different revision of the underlying files.  In some
  1.1992 +	cases, such as when you're maintaining a patch that must sit
  1.1993 +	on top of multiple versions of a source tree, it's acceptable
  1.1994 +	to have a patch apply with some fuzz, provided you've verified
  1.1995 +	the results of the patching process in such cases.</para>
  1.1996 +    </sect2>
  1.1997 +
  1.1998 +    <sect2>
  1.1999 +      <title>Handling rejection</title>
  1.2000 +
  1.2001 +      <para id="x_3f9">If <command role="hg-ext-mq">qpush</command> fails to
  1.2002 +	apply a patch, it will print an error message and exit.  If it
  1.2003 +	has left <filename role="special">.rej</filename> files
  1.2004 +	behind, it is usually best to fix up the rejected hunks before
  1.2005 +	you push more patches or do any further work.</para>
  1.2006 +
  1.2007 +      <para id="x_3fa">If your patch <emphasis>used to</emphasis> apply cleanly,
  1.2008 +	and no longer does because you've changed the underlying code
  1.2009 +	that your patches are based on, Mercurial Queues can help; see
  1.2010 +	<xref linkend="sec:mq:merge"/> for details.</para>
  1.2011 +
  1.2012 +      <para id="x_3fb">Unfortunately, there aren't any great techniques for
  1.2013 +	dealing with rejected hunks.  Most often, you'll need to view
  1.2014 +	the <filename role="special">.rej</filename> file and edit the
  1.2015 +	target file, applying the rejected hunks by hand.</para>
  1.2016 +
  1.2017 +      <para id="x_3fd">A Linux kernel hacker, Chris Mason (the author
  1.2018 +	of Mercurial Queues), wrote a tool called
  1.2019 +	<command>mpatch</command> (<ulink
  1.2020 +	  url="http://oss.oracle.com/~mason/mpatch/">http://oss.oracle.com/~mason/mpatch/</ulink>), 
  1.2021 +	which takes a simple approach to automating the application of
  1.2022 +	hunks rejected by <command>patch</command>.  The
  1.2023 +	<command>mpatch</command> command can help with four common
  1.2024 +	reasons that a hunk may be rejected:</para>
  1.2025 +
  1.2026 +      <itemizedlist>
  1.2027 +	<listitem><para id="x_3fe">The context in the middle of a hunk has
  1.2028 +	    changed.</para>
  1.2029 +	</listitem>
  1.2030 +	<listitem><para id="x_3ff">A hunk is missing some context at the
  1.2031 +	    beginning or end.</para>
  1.2032 +	</listitem>
  1.2033 +	<listitem><para id="x_400">A large hunk might apply better&emdash;either
  1.2034 +	    entirely or in part&emdash;if it was broken up into
  1.2035 +	    smaller hunks.</para>
  1.2036 +	</listitem>
  1.2037 +	<listitem><para id="x_401">A hunk removes lines with slightly different
  1.2038 +	    content than those currently present in the file.</para>
  1.2039 +	</listitem></itemizedlist>
  1.2040 +
  1.2041 +      <para id="x_402">If you use <command>mpatch</command>, you
  1.2042 +	should be doubly careful to check your results when you're
  1.2043 +	done.  In fact, <command>mpatch</command> enforces this method
  1.2044 +	of double-checking the tool's output, by automatically
  1.2045 +	dropping you into a merge program when it has done its job, so
  1.2046 +	that you can verify its work and finish off any remaining
  1.2047 +	merges.</para>
  1.2048 +    </sect2>
  1.2049 +  </sect1>
  1.2050 +
  1.2051 +  <sect1>
  1.2052 +    <title>More on patch management</title>
  1.2053 +
  1.2054 +    <para id="x_6db">As you grow familiar with MQ, you will find yourself wanting
  1.2055 +      to perform other kinds of patch management operations.</para>
  1.2056 +
  1.2057 +    <sect2>
  1.2058 +      <title>Deleting unwanted patches</title>
  1.2059 +
  1.2060 +      <para id="x_6dc">If you want to get rid of a patch, use the <command
  1.2061 +	  role="hg-ext-mq">hg qdelete</command> command to delete the
  1.2062 +	patch file and remove its entry from the patch series.  If you
  1.2063 +	try to delete a patch that is still applied, <command
  1.2064 +	  role="hg-ext-mq">hg qdelete</command> will refuse.</para>
  1.2065 +
  1.2066 +      &interaction.ch11-qdelete.go;
  1.2067 +    </sect2>
  1.2068 +
  1.2069 +    <sect2>
  1.2070 +      <title>Converting to and from permanent revisions</title>
  1.2071 +
  1.2072 +      <para id="x_6dd">Once you're done working on a patch and want to
  1.2073 +      turn it into a permanent changeset, use the <command
  1.2074 +      role="hg-ext-mq">hg qfinish</command> command. Pass a revision
  1.2075 +      to the command to identify the patch that you want to turn into
  1.2076 +      a regular changeset; this patch must already be applied.</para>
  1.2077 +
  1.2078 +      &interaction.ch11-qdelete.convert;
  1.2079 +
  1.2080 +      <para id="x_6e0">The <command role="hg-ext-mq">hg qfinish</command> command
  1.2081 +        accepts an <option>--all</option> or <option>-a</option>
  1.2082 +        option, which turns all applied patches into regular
  1.2083 +        changesets.</para>
  1.2084 +
  1.2085 +      <para id="x_6de">It is also possible to turn an existing changeset into a
  1.2086 +	patch, by passing the <option>-r</option> option to <command
  1.2087 +	  role="hg-ext-mq">hg qimport</command>.</para>
  1.2088 +
  1.2089 +      &interaction.ch11-qdelete.import;
  1.2090 +
  1.2091 +      <para id="x_6df">Note that it only makes sense to convert a changeset into
  1.2092 +	a patch if you have not propagated that changeset into any
  1.2093 +	other repositories.  The imported changeset's ID will change
  1.2094 +	every time you refresh the patch, which will make Mercurial
  1.2095 +	treat it as unrelated to the original changeset if you have
  1.2096 +	pushed it somewhere else.</para>
  1.2097 +    </sect2>
  1.2098 +  </sect1>
  1.2099 +
  1.2100 +  <sect1 id="sec:mq:perf">
  1.2101 +    <title>Getting the best performance out of MQ</title>
  1.2102 +
  1.2103 +    <para id="x_403">MQ is very efficient at handling a large number
  1.2104 +      of patches. I ran some performance experiments in mid-2006 for a
  1.2105 +      talk that I gave at the 2006 EuroPython conference (on modern
  1.2106 +      hardware, you should expect better performance than you'll see
  1.2107 +      below).  I used as my data set the Linux 2.6.17-mm1 patch
  1.2108 +      series, which consists of 1,738 patches. I applied these on top
  1.2109 +      of a Linux kernel repository containing all 27,472 revisions
  1.2110 +      between Linux 2.6.12-rc2 and Linux 2.6.17.</para>
  1.2111 +
  1.2112 +    <para id="x_404">On my old, slow laptop, I was able to <command
  1.2113 +	role="hg-cmd">hg qpush <option
  1.2114 +	  role="hg-ext-mq-cmd-qpush-opt">hg -a</option></command> all
  1.2115 +      1,738 patches in 3.5 minutes, and <command role="hg-cmd">hg qpop
  1.2116 +	<option role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command>
  1.2117 +      them all in 30 seconds.  (On a newer laptop, the time to push
  1.2118 +      all patches dropped to two minutes.)  I could <command
  1.2119 +	role="hg-ext-mq">qrefresh</command> one of the biggest patches
  1.2120 +      (which made 22,779 lines of changes to 287 files) in 6.6
  1.2121 +      seconds.</para>
  1.2122 +
  1.2123 +    <para id="x_405">Clearly, MQ is well suited to working in large trees, but
  1.2124 +      there are a few tricks you can use to get the best performance
  1.2125 +      of it.</para>
  1.2126 +
  1.2127 +    <para id="x_406">First of all, try to <quote>batch</quote> operations
  1.2128 +      together.  Every time you run <command
  1.2129 +	role="hg-ext-mq">qpush</command> or <command
  1.2130 +	role="hg-ext-mq">qpop</command>, these commands scan the
  1.2131 +      working directory once to make sure you haven't made some
  1.2132 +      changes and then forgotten to run <command
  1.2133 +	role="hg-ext-mq">qrefresh</command>.  On a small tree, the
  1.2134 +      time that this scan takes is unnoticeable.  However, on a
  1.2135 +      medium-sized tree (containing tens of thousands of files), it
  1.2136 +      can take a second or more.</para>
  1.2137 +
  1.2138 +    <para id="x_407">The <command role="hg-ext-mq">qpush</command> and <command
  1.2139 +	role="hg-ext-mq">qpop</command> commands allow you to push and
  1.2140 +      pop multiple patches at a time.  You can identify the
  1.2141 +      <quote>destination patch</quote> that you want to end up at.
  1.2142 +      When you <command role="hg-ext-mq">qpush</command> with a
  1.2143 +      destination specified, it will push patches until that patch is
  1.2144 +      at the top of the applied stack.  When you <command
  1.2145 +	role="hg-ext-mq">qpop</command> to a destination, MQ will pop
  1.2146 +      patches until the destination patch is at the top.</para>
  1.2147 +
  1.2148 +    <para id="x_408">You can identify a destination patch using either the name
  1.2149 +      of the patch, or by number.  If you use numeric addressing,
  1.2150 +      patches are counted from zero; this means that the first patch
  1.2151 +      is zero, the second is one, and so on.</para>
  1.2152 +  </sect1>
  1.2153 +
  1.2154 +  <sect1 id="sec:mq:merge">
  1.2155 +    <title>Updating your patches when the underlying code
  1.2156 +      changes</title>
  1.2157 +
  1.2158 +    <para id="x_409">It's common to have a stack of patches on top of an
  1.2159 +      underlying repository that you don't modify directly.  If you're
  1.2160 +      working on changes to third-party code, or on a feature that is
  1.2161 +      taking longer to develop than the rate of change of the code
  1.2162 +      beneath, you will often need to sync up with the underlying
  1.2163 +      code, and fix up any hunks in your patches that no longer apply.
  1.2164 +      This is called <emphasis>rebasing</emphasis> your patch
  1.2165 +      series.</para>
  1.2166 +
  1.2167 +    <para id="x_40a">The simplest way to do this is to <command role="hg-cmd">hg
  1.2168 +	qpop <option role="hg-ext-mq-cmd-qpop-opt">hg
  1.2169 +	  -a</option></command> your patches, then <command
  1.2170 +	role="hg-cmd">hg pull</command> changes into the underlying
  1.2171 +      repository, and finally <command role="hg-cmd">hg qpush <option
  1.2172 +	  role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> your
  1.2173 +      patches again.  MQ will stop pushing any time it runs across a
  1.2174 +      patch that fails to apply during conflicts, allowing you to fix
  1.2175 +      your conflicts, <command role="hg-ext-mq">qrefresh</command> the
  1.2176 +      affected patch, and continue pushing until you have fixed your
  1.2177 +      entire stack.</para>
  1.2178 +
  1.2179 +    <para id="x_40b">This approach is easy to use and works well if you don't
  1.2180 +      expect changes to the underlying code to affect how well your
  1.2181 +      patches apply. If your patch stack touches code that is modified
  1.2182 +      frequently or invasively in the underlying repository, however,
  1.2183 +      fixing up rejected hunks by hand quickly becomes
  1.2184 +      tiresome.</para>
  1.2185 +
  1.2186 +    <para id="x_40c">It's possible to partially automate the rebasing process.
  1.2187 +      If your patches apply cleanly against some revision of the
  1.2188 +      underlying repo, MQ can use this information to help you to
  1.2189 +      resolve conflicts between your patches and a different
  1.2190 +      revision.</para>
  1.2191 +
  1.2192 +    <para id="x_40d">The process is a little involved.</para>
  1.2193 +    <orderedlist>
  1.2194 +      <listitem><para id="x_40e">To begin, <command role="hg-cmd">hg qpush
  1.2195 +	    -a</command> all of your patches on top of the revision
  1.2196 +	  where you know that they apply cleanly.</para>
  1.2197 +      </listitem>
  1.2198 +      <listitem><para id="x_40f">Save a backup copy of your patch directory using
  1.2199 +	  <command role="hg-cmd">hg qsave <option
  1.2200 +	      role="hg-ext-mq-cmd-qsave-opt">hg -e</option> <option
  1.2201 +	      role="hg-ext-mq-cmd-qsave-opt">hg -c</option></command>.
  1.2202 +	  This prints the name of the directory that it has saved the
  1.2203 +	  patches in.  It will save the patches to a directory called
  1.2204 +	  <filename role="special"
  1.2205 +	    class="directory">.hg/patches.N</filename>, where
  1.2206 +	  <literal>N</literal> is a small integer.  It also commits a
  1.2207 +	  <quote>save changeset</quote> on top of your applied
  1.2208 +	  patches; this is for internal book-keeping, and records the
  1.2209 +	  states of the <filename role="special">series</filename> and
  1.2210 +	  <filename role="special">status</filename> files.</para>
  1.2211 +      </listitem>
  1.2212 +      <listitem><para id="x_410">Use <command role="hg-cmd">hg pull</command> to
  1.2213 +	  bring new changes into the underlying repository.  (Don't
  1.2214 +	  run <command role="hg-cmd">hg pull -u</command>; see below
  1.2215 +	  for why.)</para>
  1.2216 +      </listitem>
  1.2217 +      <listitem><para id="x_411">Update to the new tip revision, using <command
  1.2218 +	    role="hg-cmd">hg update <option
  1.2219 +	      role="hg-opt-update">-C</option></command> to override
  1.2220 +	  the patches you have pushed.</para>
  1.2221 +      </listitem>
  1.2222 +      <listitem><para id="x_412">Merge all patches using <command>hg qpush -m
  1.2223 +	    -a</command>.  The <option
  1.2224 +	    role="hg-ext-mq-cmd-qpush-opt">-m</option> option to
  1.2225 +	  <command role="hg-ext-mq">qpush</command> tells MQ to
  1.2226 +	  perform a three-way merge if the patch fails to
  1.2227 +	  apply.</para>
  1.2228 +      </listitem></orderedlist>
  1.2229 +
  1.2230 +    <para id="x_413">During the <command role="hg-cmd">hg qpush <option
  1.2231 +	  role="hg-ext-mq-cmd-qpush-opt">hg -m</option></command>,
  1.2232 +      each patch in the <filename role="special">series</filename>
  1.2233 +      file is applied normally.  If a patch applies with fuzz or
  1.2234 +      rejects, MQ looks at the queue you <command
  1.2235 +	role="hg-ext-mq">qsave</command>d, and performs a three-way
  1.2236 +      merge with the corresponding changeset.  This merge uses
  1.2237 +      Mercurial's normal merge machinery, so it may pop up a GUI merge
  1.2238 +      tool to help you to resolve problems.</para>
  1.2239 +
  1.2240 +    <para id="x_414">When you finish resolving the effects of a patch, MQ
  1.2241 +      refreshes your patch based on the result of the merge.</para>
  1.2242 +
  1.2243 +    <para id="x_415">At the end of this process, your repository will have one
  1.2244 +      extra head from the old patch queue, and a copy of the old patch
  1.2245 +      queue will be in <filename role="special"
  1.2246 +	class="directory">.hg/patches.N</filename>. You can remove the
  1.2247 +      extra head using <command role="hg-cmd">hg qpop -a -n
  1.2248 +	patches.N</command> or <command role="hg-cmd">hg
  1.2249 +	strip</command>.  You can delete <filename role="special"
  1.2250 +	class="directory">.hg/patches.N</filename> once you are sure
  1.2251 +      that you no longer need it as a backup.</para>
  1.2252 +  </sect1>
  1.2253 +
  1.2254 +  <sect1>
  1.2255 +    <title>Identifying patches</title>
  1.2256 +
  1.2257 +    <para id="x_416">MQ commands that work with patches let you refer to a patch
  1.2258 +      either by using its name or by a number.  By name is obvious
  1.2259 +      enough; pass the name <filename>foo.patch</filename> to <command
  1.2260 +	role="hg-ext-mq">qpush</command>, for example, and it will
  1.2261 +      push patches until <filename>foo.patch</filename> is
  1.2262 +      applied.</para>
  1.2263 +
  1.2264 +    <para id="x_417">As a shortcut, you can refer to a patch using both a name
  1.2265 +      and a numeric offset; <literal>foo.patch-2</literal> means
  1.2266 +      <quote>two patches before <literal>foo.patch</literal></quote>,
  1.2267 +      while <literal>bar.patch+4</literal> means <quote>four patches
  1.2268 +	after <literal>bar.patch</literal></quote>.</para>
  1.2269 +
  1.2270 +    <para id="x_418">Referring to a patch by index isn't much different.  The
  1.2271 +      first patch printed in the output of <command
  1.2272 +	role="hg-ext-mq">qseries</command> is patch zero (yes, it's
  1.2273 +      one of those start-at-zero counting systems); the second is
  1.2274 +      patch one; and so on.</para>
  1.2275 +
  1.2276 +    <para id="x_419">MQ also makes it easy to work with patches when you are
  1.2277 +      using normal Mercurial commands.  Every command that accepts a
  1.2278 +      changeset ID will also accept the name of an applied patch.  MQ
  1.2279 +      augments the tags normally in the repository with an eponymous
  1.2280 +      one for each applied patch.  In addition, the special tags
  1.2281 +      <literal role="tag">qbase</literal> and
  1.2282 +      <literal role="tag">qtip</literal> identify
  1.2283 +      the <quote>bottom-most</quote> and topmost applied patches,
  1.2284 +      respectively.</para>
  1.2285 +
  1.2286 +    <para id="x_41a">These additions to Mercurial's normal tagging capabilities
  1.2287 +      make dealing with patches even more of a breeze.</para>
  1.2288 +    <itemizedlist>
  1.2289 +      <listitem><para id="x_41b">Want to patchbomb a mailing list with your
  1.2290 +	  latest series of changes?</para>
  1.2291 +	<programlisting>hg email qbase:qtip</programlisting>
  1.2292 +	<para id="x_41c">  (Don't know what <quote>patchbombing</quote> is?  See
  1.2293 +	  <xref linkend="sec:hgext:patchbomb"/>.)</para>
  1.2294 +      </listitem>
  1.2295 +      <listitem><para id="x_41d">Need to see all of the patches since
  1.2296 +	  <literal>foo.patch</literal> that have touched files in a
  1.2297 +	  subdirectory of your tree?</para>
  1.2298 +	<programlisting>hg log -r foo.patch:qtip subdir</programlisting>
  1.2299 +      </listitem>
  1.2300 +    </itemizedlist>
  1.2301 +
  1.2302 +    <para id="x_41e">Because MQ makes the names of patches available to the rest
  1.2303 +      of Mercurial through its normal internal tag machinery, you
  1.2304 +      don't need to type in the entire name of a patch when you want
  1.2305 +      to identify it by name.</para>
  1.2306 +
  1.2307 +    <para id="x_41f">Another nice consequence of representing patch names as tags
  1.2308 +      is that when you run the <command role="hg-cmd">hg log</command>
  1.2309 +      command, it will display a patch's name as a tag, simply as part
  1.2310 +      of its normal output.  This makes it easy to visually
  1.2311 +      distinguish applied patches from underlying
  1.2312 +      <quote>normal</quote> revisions.  The following example shows a
  1.2313 +      few normal Mercurial commands in use with applied
  1.2314 +      patches.</para>
  1.2315 +
  1.2316 +    &interaction.mq.id.output;
  1.2317 +  </sect1>
  1.2318 +
  1.2319 +  <sect1>
  1.2320 +    <title>Useful things to know about</title>
  1.2321 +
  1.2322 +    <para id="x_420">There are a number of aspects of MQ usage that don't fit
  1.2323 +      tidily into sections of their own, but that are good to know.
  1.2324 +      Here they are, in one place.</para>
  1.2325 +
  1.2326 +    <itemizedlist>
  1.2327 +      <listitem><para id="x_421">Normally, when you <command
  1.2328 +	    role="hg-ext-mq">qpop</command> a patch and <command
  1.2329 +	    role="hg-ext-mq">qpush</command> it again, the changeset
  1.2330 +	  that represents the patch after the pop/push will have a
  1.2331 +	  <emphasis>different identity</emphasis> than the changeset
  1.2332 +	  that represented the hash beforehand.  See <xref
  1.2333 +	    linkend="sec:mqref:cmd:qpush"/> for
  1.2334 +	  information as to why this is.</para>
  1.2335 +      </listitem>
  1.2336 +      <listitem><para id="x_422">It's not a good idea to <command
  1.2337 +	    role="hg-cmd">hg merge</command> changes from another
  1.2338 +	  branch with a patch changeset, at least if you want to
  1.2339 +	  maintain the <quote>patchiness</quote> of that changeset and
  1.2340 +	  changesets below it on the patch stack.  If you try to do
  1.2341 +	  this, it will appear to succeed, but MQ will become
  1.2342 +	  confused.</para>
  1.2343 +      </listitem></itemizedlist>
  1.2344 +  </sect1>
  1.2345 +
  1.2346 +  <sect1 id="sec:mq:repo">
  1.2347 +    <title>Managing patches in a repository</title>
  1.2348 +
  1.2349 +    <para id="x_423">Because MQ's <filename role="special"
  1.2350 +	class="directory">.hg/patches</filename> directory resides
  1.2351 +      outside a Mercurial repository's working directory, the
  1.2352 +      <quote>underlying</quote> Mercurial repository knows nothing
  1.2353 +      about the management or presence of patches.</para>
  1.2354 +
  1.2355 +    <para id="x_424">This presents the interesting possibility of managing the
  1.2356 +      contents of the patch directory as a Mercurial repository in its
  1.2357 +      own right.  This can be a useful way to work.  For example, you
  1.2358 +      can work on a patch for a while, <command
  1.2359 +	role="hg-ext-mq">qrefresh</command> it, then <command
  1.2360 +	role="hg-cmd">hg commit</command> the current state of the
  1.2361 +      patch.  This lets you <quote>roll back</quote> to that version
  1.2362 +      of the patch later on.</para>
  1.2363 +
  1.2364 +    <para id="x_425">You can then share different versions of the same patch
  1.2365 +      stack among multiple underlying repositories.  I use this when I
  1.2366 +      am developing a Linux kernel feature.  I have a pristine copy of
  1.2367 +      my kernel sources for each of several CPU architectures, and a
  1.2368 +      cloned repository under each that contains the patches I am
  1.2369 +      working on.  When I want to test a change on a different
  1.2370 +      architecture, I push my current patches to the patch repository
  1.2371 +      associated with that kernel tree, pop and push all of my
  1.2372 +      patches, and build and test that kernel.</para>
  1.2373 +
  1.2374 +    <para id="x_426">Managing patches in a repository makes it possible for
  1.2375 +      multiple developers to work on the same patch series without
  1.2376 +      colliding with each other, all on top of an underlying source
  1.2377 +      base that they may or may not control.</para>
  1.2378 +
  1.2379 +    <sect2>
  1.2380 +      <title>MQ support for patch repositories</title>
  1.2381 +
  1.2382 +      <para id="x_427">MQ helps you to work with the <filename role="special"
  1.2383 +	  class="directory">.hg/patches</filename> directory as a
  1.2384 +	repository; when you prepare a repository for working with
  1.2385 +	patches using <command role="hg-ext-mq">qinit</command>, you
  1.2386 +	can pass the <option role="hg-ext-mq-cmd-qinit-opt">hg
  1.2387 +	  -c</option> option to create the <filename role="special"
  1.2388 +	  class="directory">.hg/patches</filename> directory as a
  1.2389 +	Mercurial repository.</para>
  1.2390 +
  1.2391 +      <note>
  1.2392 +	<para id="x_428">  If you forget to use the <option
  1.2393 +	    role="hg-ext-mq-cmd-qinit-opt">hg -c</option> option, you
  1.2394 +	  can simply go into the <filename role="special"
  1.2395 +	    class="directory">.hg/patches</filename> directory at any
  1.2396 +	  time and run <command role="hg-cmd">hg init</command>.
  1.2397 +	  Don't forget to add an entry for the <filename
  1.2398 +	    role="special">status</filename> file to the <filename
  1.2399 +	    role="special">.hgignore</filename> file, though</para>
  1.2400 +
  1.2401 +	<para id="x_429">  (<command role="hg-cmd">hg qinit <option
  1.2402 +	      role="hg-ext-mq-cmd-qinit-opt">hg -c</option></command>
  1.2403 +	  does this for you automatically); you
  1.2404 +	  <emphasis>really</emphasis> don't want to manage the
  1.2405 +	  <filename role="special">status</filename> file.</para>
  1.2406 +      </note>
  1.2407 +
  1.2408 +      <para id="x_42a">As a convenience, if MQ notices that the <filename
  1.2409 +	  class="directory">.hg/patches</filename> directory is a
  1.2410 +	repository, it will automatically <command role="hg-cmd">hg
  1.2411 +	  add</command> every patch that you create and import.</para>
  1.2412 +
  1.2413 +      <para id="x_42b">MQ provides a shortcut command, <command
  1.2414 +	  role="hg-ext-mq">qcommit</command>, that runs <command
  1.2415 +	  role="hg-cmd">hg commit</command> in the <filename
  1.2416 +	  role="special" class="directory">.hg/patches</filename>
  1.2417 +	directory.  This saves some bothersome typing.</para>
  1.2418 +
  1.2419 +      <para id="x_42c">Finally, as a convenience to manage the patch directory,
  1.2420 +	you can define the alias <command>mq</command> on Unix
  1.2421 +	systems. For example, on Linux systems using the
  1.2422 +	<command>bash</command> shell, you can include the following
  1.2423 +	snippet in your <filename
  1.2424 +	  role="home">~/.bashrc</filename>.</para>
  1.2425 +
  1.2426 +      <programlisting>alias mq=`hg -R $(hg root)/.hg/patches'</programlisting>
  1.2427 +
  1.2428 +      <para id="x_42d">You can then issue commands of the form <command>mq
  1.2429 +	  pull</command> from the main repository.</para>
  1.2430 +    </sect2>
  1.2431 +
  1.2432 +    <sect2>
  1.2433 +      <title>A few things to watch out for</title>
  1.2434 +
  1.2435 +      <para id="x_42e">MQ's support for working with a repository full of patches
  1.2436 +	is limited in a few small respects.</para>
  1.2437 +
  1.2438 +      <para id="x_42f">MQ cannot automatically detect changes that you make to
  1.2439 +	the patch directory.  If you <command role="hg-cmd">hg
  1.2440 +	  pull</command>, manually edit, or <command role="hg-cmd">hg
  1.2441 +	  update</command> changes to patches or the <filename
  1.2442 +	  role="special">series</filename> file, you will have to
  1.2443 +	<command role="hg-cmd">hg qpop <option
  1.2444 +	    role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> and
  1.2445 +	then <command role="hg-cmd">hg qpush <option
  1.2446 +	    role="hg-ext-mq-cmd-qpush-opt">hg -a</option></command> in
  1.2447 +	the underlying repository to see those changes show up there.
  1.2448 +	If you forget to do this, you can confuse MQ's idea of which
  1.2449 +	patches are applied.</para>
  1.2450 +
  1.2451 +    </sect2>
  1.2452 +  </sect1>
  1.2453 +  <sect1 id="sec:mq:tools">
  1.2454 +    <title>Third party tools for working with patches</title>
  1.2455 +
  1.2456 +    <para id="x_430">Once you've been working with patches for a while, you'll
  1.2457 +      find yourself hungry for tools that will help you to understand
  1.2458 +      and manipulate the patches you're dealing with.</para>
  1.2459 +
  1.2460 +    <para id="x_431">The <command>diffstat</command> command
  1.2461 +      <citation>web:diffstat</citation> generates a histogram of the
  1.2462 +      modifications made to each file in a patch.  It provides a good
  1.2463 +      way to <quote>get a sense of</quote> a patch&emdash;which files
  1.2464 +      it affects, and how much change it introduces to each file and
  1.2465 +      as a whole.  (I find that it's a good idea to use
  1.2466 +      <command>diffstat</command>'s <option
  1.2467 +	role="cmd-opt-diffstat">-p</option> option as a matter of
  1.2468 +      course, as otherwise it will try to do clever things with
  1.2469 +      prefixes of file names that inevitably confuse at least
  1.2470 +      me.)</para>
  1.2471 +
  1.2472 +&interaction.mq.tools.tools;
  1.2473 +
  1.2474 +    <para id="x_432">The <literal role="package">patchutils</literal> package
  1.2475 +      <citation>web:patchutils</citation> is invaluable. It provides a
  1.2476 +      set of small utilities that follow the <quote>Unix
  1.2477 +	philosophy;</quote> each does one useful thing with a patch.
  1.2478 +      The <literal role="package">patchutils</literal> command I use
  1.2479 +      most is <command>filterdiff</command>, which extracts subsets
  1.2480 +      from a patch file.  For example, given a patch that modifies
  1.2481 +      hundreds of files across dozens of directories, a single
  1.2482 +      invocation of <command>filterdiff</command> can generate a
  1.2483 +      smaller patch that only touches files whose names match a
  1.2484 +      particular glob pattern.  See <xref
  1.2485 +	linkend="mq-collab:tips:interdiff"/> for another
  1.2486 +      example.</para>
  1.2487 +
  1.2488 +  </sect1>
  1.2489 +  <sect1>
  1.2490 +    <title>Good ways to work with patches</title>
  1.2491 +
  1.2492 +    <para id="x_433">Whether you are working on a patch series to submit to a
  1.2493 +      free software or open source project, or a series that you
  1.2494 +      intend to treat as a sequence of regular changesets when you're
  1.2495 +      done, you can use some simple techniques to keep your work well
  1.2496 +      organized.</para>
  1.2497 +
  1.2498 +    <para id="x_434">Give your patches descriptive names.  A good name for a
  1.2499 +      patch might be <filename>rework-device-alloc.patch</filename>,
  1.2500 +      because it will immediately give you a hint what the purpose of
  1.2501 +      the patch is.  Long names shouldn't be a problem; you won't be
  1.2502 +      typing the names often, but you <emphasis>will</emphasis> be
  1.2503 +      running commands like <command
  1.2504 +	role="hg-ext-mq">qapplied</command> and <command
  1.2505 +	role="hg-ext-mq">qtop</command> over and over. Good naming
  1.2506 +      becomes especially important when you have a number of patches
  1.2507 +      to work with, or if you are juggling a number of different tasks
  1.2508 +      and your patches only get a fraction of your attention.</para>
  1.2509 +
  1.2510 +    <para id="x_435">Be aware of what patch you're working on.  Use the <command
  1.2511 +	role="hg-ext-mq">qtop</command> command and skim over the text
  1.2512 +      of your patches frequently&emdash;for example, using <command
  1.2513 +	role="hg-cmd">hg tip <option
  1.2514 +	  role="hg-opt-tip">-p</option></command>)&emdash;to be sure
  1.2515 +      of where you stand.  I have several times worked on and <command
  1.2516 +	role="hg-ext-mq">qrefresh</command>ed a patch other than the
  1.2517 +      one I intended, and it's often tricky to migrate changes into
  1.2518 +      the right patch after making them in the wrong one.</para>
  1.2519 +
  1.2520 +    <para id="x_436">For this reason, it is very much worth investing a little
  1.2521 +      time to learn how to use some of the third-party tools I
  1.2522 +      described in <xref linkend="sec:mq:tools"/>,
  1.2523 +      particularly
  1.2524 +      <command>diffstat</command> and <command>filterdiff</command>.
  1.2525 +      The former will give you a quick idea of what changes your patch
  1.2526 +      is making, while the latter makes it easy to splice hunks
  1.2527 +      selectively out of one patch and into another.</para>
  1.2528 +
  1.2529 +  </sect1>
  1.2530 +  <sect1>
  1.2531 +    <title>MQ cookbook</title>
  1.2532 +
  1.2533 +    <sect2>
  1.2534 +      <title>Manage <quote>trivial</quote> patches</title>
  1.2535 +
  1.2536 +      <para id="x_437">Because the overhead of dropping files into a new
  1.2537 +	Mercurial repository is so low, it makes a lot of sense to
  1.2538 +	manage patches this way even if you simply want to make a few
  1.2539 +	changes to a source tarball that you downloaded.</para>
  1.2540 +
  1.2541 +      <para id="x_438">Begin by downloading and unpacking the source tarball, and
  1.2542 +	turning it into a Mercurial repository.</para>
  1.2543 +
  1.2544 +      &interaction.mq.tarball.download;
  1.2545 +
  1.2546 +      <para id="x_439">Continue by creating a patch stack and making your
  1.2547 +	changes.</para>
  1.2548 +
  1.2549 +      &interaction.mq.tarball.qinit;
  1.2550 +
  1.2551 +      <para id="x_43a">Let's say a few weeks or months pass, and your package
  1.2552 +	author releases a new version.  First, bring their changes
  1.2553 +	into the repository.</para>
  1.2554 +
  1.2555 +      &interaction.mq.tarball.newsource;
  1.2556 +
  1.2557 +      <para id="x_43b">The pipeline starting with <command role="hg-cmd">hg
  1.2558 +	  locate</command> above deletes all files in the working
  1.2559 +	directory, so that <command role="hg-cmd">hg
  1.2560 +	  commit</command>'s <option
  1.2561 +	  role="hg-opt-commit">--addremove</option> option can
  1.2562 +	actually tell which files have really been removed in the
  1.2563 +	newer version of the source.</para>
  1.2564 +
  1.2565 +      <para id="x_43c">Finally, you can apply your patches on top of the new
  1.2566 +	tree.</para>
  1.2567 +
  1.2568 +      &interaction.mq.tarball.repush;
  1.2569 +    </sect2>
  1.2570 +
  1.2571 +    <sect2 id="sec:mq:combine">
  1.2572 +      <title>Combining entire patches</title>
  1.2573 +
  1.2574 +      <para id="x_43d">MQ provides a command, <command
  1.2575 +	  role="hg-ext-mq">qfold</command> that lets you combine
  1.2576 +	entire patches.  This <quote>folds</quote> the patches you
  1.2577 +	name, in the order you name them, into the topmost applied
  1.2578 +	patch, and concatenates their descriptions onto the end of its
  1.2579 +	description.  The patches that you fold must be unapplied
  1.2580 +	before you fold them.</para>
  1.2581 +
  1.2582 +      <para id="x_43e">The order in which you fold patches matters.  If your
  1.2583 +	topmost applied patch is <literal>foo</literal>, and you
  1.2584 +	<command role="hg-ext-mq">qfold</command>
  1.2585 +	<literal>bar</literal> and <literal>quux</literal> into it,
  1.2586 +	you will end up with a patch that has the same effect as if
  1.2587 +	you applied first <literal>foo</literal>, then
  1.2588 +	<literal>bar</literal>, followed by
  1.2589 +	<literal>quux</literal>.</para>
  1.2590 +    </sect2>
  1.2591 +
  1.2592 +    <sect2>
  1.2593 +      <title>Merging part of one patch into another</title>
  1.2594 +
  1.2595 +      <para id="x_43f">Merging <emphasis>part</emphasis> of one patch into
  1.2596 +	another is more difficult than combining entire
  1.2597 +	patches.</para>
  1.2598 +
  1.2599 +      <para id="x_440">If you want to move changes to entire files, you can use
  1.2600 +	<command>filterdiff</command>'s <option
  1.2601 +	  role="cmd-opt-filterdiff">-i</option> and <option
  1.2602 +	  role="cmd-opt-filterdiff">-x</option> options to choose the
  1.2603 +	modifications to snip out of one patch, concatenating its
  1.2604 +	output onto the end of the patch you want to merge into.  You
  1.2605 +	usually won't need to modify the patch you've merged the
  1.2606 +	changes from.  Instead, MQ will report some rejected hunks
  1.2607 +	when you <command role="hg-ext-mq">qpush</command> it (from
  1.2608 +	the hunks you moved into the other patch), and you can simply
  1.2609 +	<command role="hg-ext-mq">qrefresh</command> the patch to drop
  1.2610 +	the duplicate hunks.</para>
  1.2611 +
  1.2612 +      <para id="x_441">If you have a patch that has multiple hunks modifying a
  1.2613 +	file, and you only want to move a few of those hunks, the job
  1.2614 +	becomes more messy, but you can still partly automate it.  Use
  1.2615 +	<command>lsdiff -nvv</command> to print some metadata about
  1.2616 +	the patch.</para>
  1.2617 +
  1.2618 +      &interaction.mq.tools.lsdiff;
  1.2619 +
  1.2620 +      <para id="x_442">This command prints three different kinds of
  1.2621 +	number:</para>
  1.2622 +      <itemizedlist>
  1.2623 +	<listitem><para id="x_443">(in the first column) a <emphasis>file
  1.2624 +	      number</emphasis> to identify each file modified in the
  1.2625 +	    patch;</para>
  1.2626 +	</listitem>
  1.2627 +	<listitem><para id="x_444">(on the next line, indented) the line number
  1.2628 +	    within a modified file where a hunk starts; and</para>
  1.2629 +	</listitem>
  1.2630 +	<listitem><para id="x_445">(on the same line) a <emphasis>hunk
  1.2631 +	      number</emphasis> to identify that hunk.</para>
  1.2632 +	</listitem></itemizedlist>
  1.2633 +
  1.2634 +      <para id="x_446">You'll have to use some visual inspection, and reading of
  1.2635 +	the patch, to identify the file and hunk numbers you'll want,
  1.2636 +	but you can then pass them to to
  1.2637 +	<command>filterdiff</command>'s <option
  1.2638 +	  role="cmd-opt-filterdiff">--files</option> and <option
  1.2639 +	  role="cmd-opt-filterdiff">--hunks</option> options, to
  1.2640 +	select exactly the file and hunk you want to extract.</para>
  1.2641 +
  1.2642 +      <para id="x_447">Once you have this hunk, you can concatenate it onto the
  1.2643 +	end of your destination patch and continue with the remainder
  1.2644 +	of <xref linkend="sec:mq:combine"/>.</para>
  1.2645 +
  1.2646 +    </sect2>
  1.2647 +  </sect1>
  1.2648 +  <sect1>
  1.2649 +    <title>Differences between quilt and MQ</title>
  1.2650 +
  1.2651 +    <para id="x_448">If you are already familiar with quilt, MQ provides a
  1.2652 +      similar command set.  There are a few differences in the way
  1.2653 +      that it works.</para>
  1.2654 +
  1.2655 +    <para id="x_449">You will already have noticed that most quilt commands have
  1.2656 +      MQ counterparts that simply begin with a
  1.2657 +      <quote><literal>q</literal></quote>.  The exceptions are quilt's
  1.2658 +      <literal>add</literal> and <literal>remove</literal> commands,
  1.2659 +      the counterparts for which are the normal Mercurial <command
  1.2660 +	role="hg-cmd">hg add</command> and <command role="hg-cmd">hg
  1.2661 +	remove</command> commands.  There is no MQ equivalent of the
  1.2662 +      quilt <literal>edit</literal> command.</para>
  1.2663 +
  1.2664 +  </sect1>
  1.2665  </chapter>
  1.2666  
  1.2667  <!--
  1.2668  local variables: 
  1.2669  sgml-parent-document: ("00book.xml" "book" "chapter")
  1.2670  end:
  1.2671 --->
  1.2672 \ No newline at end of file
  1.2673 +-->