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