1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/en/ch11-mq.xml	Fri Mar 20 16:43:35 2009 +0800
     1.3 @@ -0,0 +1,1323 @@
     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>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>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>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>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>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 section <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>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>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>During the late 1990s, several Linux kernel developers
    1.71 +      started to maintain <quote>patch series</quote> that modified
    1.72 +      the behaviour 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>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>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>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>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>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>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 +
   1.125 +    </sect2>
   1.126 +    <sect2 id="sec.mq.quilt-mq">
   1.127 +      <title>From patchwork quilt to Mercurial Queues</title>
   1.128 +
   1.129 +      <para>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 behaviour to Mercurial.</para>
   1.132 +
   1.133 +      <para>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>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>I cannot overstate the value that MQ offers through the
   1.150 +      unification of patches and revision control.</para>
   1.151 +
   1.152 +    <para>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>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>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>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 +
   1.188 +  </sect1>
   1.189 +  <sect1 id="sec.mq.patch">
   1.190 +    <title>Understanding patches</title>
   1.191 +
   1.192 +    <para>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>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>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>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>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>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>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>We will return to some of the more subtle aspects of patches
   1.247 +      later (in section <xref linkend="sec.mq.adv-patch"/>), but you
   1.248 +      should have
   1.249 +      enough information now to use MQ.</para>
   1.250 +
   1.251 +  </sect1>
   1.252 +  <sect1 id="sec.mq.start">
   1.253 +    <title>Getting started with Mercurial Queues</title>
   1.254 +
   1.255 +    <para>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>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>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>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>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>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>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>  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>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 +
   1.327 +    </sect2>
   1.328 +    <sect2>
   1.329 +      <title>Refreshing a patch</title>
   1.330 +
   1.331 +      <para>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>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>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 +
   1.350 +    </sect2>
   1.351 +    <sect2>
   1.352 +      <title>Stacking and tracking patches</title>
   1.353 +
   1.354 +      <para>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 +      <para>Notice that the patch contains the changes in our prior
   1.362 +	patch as part of its context (you can see this more clearly in
   1.363 +	the output of <command role="hg-cmd">hg
   1.364 +	  annotate</command>).</para>
   1.365 +
   1.366 +      <para>So far, with the exception of <command
   1.367 +	  role="hg-ext-mq">qnew</command> and <command
   1.368 +	  role="hg-ext-mq">qrefresh</command>, we've been careful to
   1.369 +	only use regular Mercurial commands.  However, MQ provides
   1.370 +	many commands that are easier to use when you are thinking
   1.371 +	about patches, as illustrated below.</para>
   1.372 +
   1.373 +&interaction.mq.tutorial.qseries;
   1.374 +
   1.375 +      <itemizedlist>
   1.376 +	<listitem><para>The <command
   1.377 +	      role="hg-ext-mq">qseries</command> command lists every
   1.378 +	    patch that MQ knows about in this repository, from oldest
   1.379 +	    to newest (most recently
   1.380 +	    <emphasis>created</emphasis>).</para>
   1.381 +	</listitem>
   1.382 +	<listitem><para>The <command
   1.383 +	      role="hg-ext-mq">qapplied</command> command lists every
   1.384 +	    patch that MQ has <emphasis>applied</emphasis> in this
   1.385 +	    repository, again from oldest to newest (most recently
   1.386 +	    applied).</para>
   1.387 +	</listitem></itemizedlist>
   1.388 +
   1.389 +    </sect2>
   1.390 +    <sect2>
   1.391 +      <title>Manipulating the patch stack</title>
   1.392 +
   1.393 +      <para>The previous discussion implied that there must be a
   1.394 +	difference between <quote>known</quote> and
   1.395 +	<quote>applied</quote> patches, and there is.  MQ can manage a
   1.396 +	patch without it being applied in the repository.</para>
   1.397 +
   1.398 +      <para>An <emphasis>applied</emphasis> patch has a corresponding
   1.399 +	changeset in the repository, and the effects of the patch and
   1.400 +	changeset are visible in the working directory.  You can undo
   1.401 +	the application of a patch using the <command
   1.402 +	  role="hg-ext-mq">qpop</command> command.  MQ still
   1.403 +	<emphasis>knows about</emphasis>, or manages, a popped patch,
   1.404 +	but the patch no longer has a corresponding changeset in the
   1.405 +	repository, and the working directory does not contain the
   1.406 +	changes made by the patch.  Figure <xref
   1.407 +	  endterm="fig.mq.stack.caption" linkend="fig.mq.stack"/> illustrates
   1.408 +	the difference between applied and tracked patches.</para>
   1.409 +
   1.410 +      <informalfigure id="fig.mq.stack">
   1.411 +        <mediaobject>
   1.412 +          <imageobject><imagedata fileref="images/mq-stack.png"/></imageobject>
   1.413 +          <textobject><phrase>XXX add text</phrase></textobject>
   1.414 +          <caption><para id="fig.mq.stack.caption">Applied and unapplied patches
   1.415 +            in the MQ patch stack</para></caption>
   1.416 +          </mediaobject>
   1.417 +      </informalfigure>
   1.418 +
   1.419 +      <para>You can reapply an unapplied, or popped, patch using the
   1.420 +	<command role="hg-ext-mq">qpush</command> command.  This
   1.421 +	creates a new changeset to correspond to the patch, and the
   1.422 +	patch's changes once again become present in the working
   1.423 +	directory.  See below for examples of <command
   1.424 +	  role="hg-ext-mq">qpop</command> and <command
   1.425 +	  role="hg-ext-mq">qpush</command> in action.</para>
   1.426 +&interaction.mq.tutorial.qpop;
   1.427 +
   1.428 +      <para>Notice that once we have popped a patch or two patches,
   1.429 +	the output of <command role="hg-ext-mq">qseries</command>
   1.430 +	remains the same, while that of <command
   1.431 +	  role="hg-ext-mq">qapplied</command> has changed.</para>
   1.432 +
   1.433 +
   1.434 +    </sect2>
   1.435 +    <sect2>
   1.436 +      <title>Pushing and popping many patches</title>
   1.437 +
   1.438 +      <para>While <command role="hg-ext-mq">qpush</command> and
   1.439 +	<command role="hg-ext-mq">qpop</command> each operate on a
   1.440 +	single patch at a time by default, you can push and pop many
   1.441 +	patches in one go.  The <option
   1.442 +	  role="hg-ext-mq-cmd-qpush-opt">hg -a</option> option to
   1.443 +	<command role="hg-ext-mq">qpush</command> causes it to push
   1.444 +	all unapplied patches, while the <option
   1.445 +	  role="hg-ext-mq-cmd-qpop-opt">-a</option> option to <command
   1.446 +	  role="hg-ext-mq">qpop</command> causes it to pop all applied
   1.447 +	patches.  (For some more ways to push and pop many patches,
   1.448 +	see section <xref linkend="sec.mq.perf"/>
   1.449 +	below.)</para>
   1.450 +
   1.451 +&interaction.mq.tutorial.qpush-a;
   1.452 +
   1.453 +    </sect2>
   1.454 +    <sect2>
   1.455 +      <title>Safety checks, and overriding them</title>
   1.456 +
   1.457 +      <para>Several MQ commands check the working directory before
   1.458 +	they do anything, and fail if they find any modifications.
   1.459 +	They do this to ensure that you won't lose any changes that
   1.460 +	you have made, but not yet incorporated into a patch.  The
   1.461 +	example below illustrates this; the <command
   1.462 +	  role="hg-ext-mq">qnew</command> command will not create a
   1.463 +	new patch if there are outstanding changes, caused in this
   1.464 +	case by the <command role="hg-cmd">hg add</command> of
   1.465 +	<filename>file3</filename>.</para>
   1.466 +
   1.467 +&interaction.mq.tutorial.add;
   1.468 +
   1.469 +      <para>Commands that check the working directory all take an
   1.470 +	<quote>I know what I'm doing</quote> option, which is always
   1.471 +	named <option>-f</option>.  The exact meaning of
   1.472 +	<option>-f</option> depends on the command.  For example,
   1.473 +	<command role="hg-cmd">hg qnew <option
   1.474 +	    role="hg-ext-mq-cmd-qnew-opt">hg -f</option></command>
   1.475 +	will incorporate any outstanding changes into the new patch it
   1.476 +	creates, but <command role="hg-cmd">hg qpop <option
   1.477 +	    role="hg-ext-mq-cmd-qpop-opt">hg -f</option></command>
   1.478 +	will revert modifications to any files affected by the patch
   1.479 +	that it is popping.  Be sure to read the documentation for a
   1.480 +	command's <option>-f</option> option before you use it!</para>
   1.481 +
   1.482 +    </sect2>
   1.483 +    <sect2>
   1.484 +      <title>Working on several patches at once</title>
   1.485 +
   1.486 +      <para>The <command role="hg-ext-mq">qrefresh</command> command
   1.487 +	always refreshes the <emphasis>topmost</emphasis> applied
   1.488 +	patch.  This means that you can suspend work on one patch (by
   1.489 +	refreshing it), pop or push to make a different patch the top,
   1.490 +	and work on <emphasis>that</emphasis> patch for a
   1.491 +	while.</para>
   1.492 +
   1.493 +      <para>Here's an example that illustrates how you can use this
   1.494 +	ability. Let's say you're developing a new feature as two
   1.495 +	patches.  The first is a change to the core of your software,
   1.496 +	and the second&emdash;layered on top of the
   1.497 +	first&emdash;changes the user interface to use the code you
   1.498 +	just added to the core.  If you notice a bug in the core while
   1.499 +	you're working on the UI patch, it's easy to fix the core.
   1.500 +	Simply <command role="hg-ext-mq">qrefresh</command> the UI
   1.501 +	patch to save your in-progress changes, and <command
   1.502 +	  role="hg-ext-mq">qpop</command> down to the core patch.  Fix
   1.503 +	the core bug, <command role="hg-ext-mq">qrefresh</command> the
   1.504 +	core patch, and <command role="hg-ext-mq">qpush</command> back
   1.505 +	to the UI patch to continue where you left off.</para>
   1.506 +
   1.507 +    </sect2>
   1.508 +  </sect1>
   1.509 +  <sect1 id="sec.mq.adv-patch">
   1.510 +    <title>More about patches</title>
   1.511 +
   1.512 +    <para>MQ uses the GNU <command>patch</command> command to apply
   1.513 +      patches, so it's helpful to know a few more detailed aspects of
   1.514 +      how <command>patch</command> works, and about patches
   1.515 +      themselves.</para>
   1.516 +
   1.517 +    <sect2>
   1.518 +      <title>The strip count</title>
   1.519 +
   1.520 +      <para>If you look at the file headers in a patch, you will
   1.521 +	notice that the pathnames usually have an extra component on
   1.522 +	the front that isn't present in the actual path name.  This is
   1.523 +	a holdover from the way that people used to generate patches
   1.524 +	(people still do this, but it's somewhat rare with modern
   1.525 +	revision control tools).</para>
   1.526 +
   1.527 +      <para>Alice would unpack a tarball, edit her files, then decide
   1.528 +	that she wanted to create a patch.  So she'd rename her
   1.529 +	working directory, unpack the tarball again (hence the need
   1.530 +	for the rename), and use the <option
   1.531 +	  role="cmd-opt-diff">-r</option> and <option
   1.532 +	  role="cmd-opt-diff">-N</option> options to
   1.533 +	<command>diff</command> to recursively generate a patch
   1.534 +	between the unmodified directory and the modified one.  The
   1.535 +	result would be that the name of the unmodified directory
   1.536 +	would be at the front of the left-hand path in every file
   1.537 +	header, and the name of the modified directory would be at the
   1.538 +	front of the right-hand path.</para>
   1.539 +
   1.540 +      <para>Since someone receiving a patch from the Alices of the net
   1.541 +	would be unlikely to have unmodified and modified directories
   1.542 +	with exactly the same names, the <command>patch</command>
   1.543 +	command has a <option role="cmd-opt-patch">-p</option> option
   1.544 +	that indicates the number of leading path name components to
   1.545 +	strip when trying to apply a patch.  This number is called the
   1.546 +	<emphasis>strip count</emphasis>.</para>
   1.547 +
   1.548 +      <para>An option of <quote><literal>-p1</literal></quote> means
   1.549 +	<quote>use a strip count of one</quote>.  If
   1.550 +	<command>patch</command> sees a file name
   1.551 +	<filename>foo/bar/baz</filename> in a file header, it will
   1.552 +	strip <filename>foo</filename> and try to patch a file named
   1.553 +	<filename>bar/baz</filename>.  (Strictly speaking, the strip
   1.554 +	count refers to the number of <emphasis>path
   1.555 +	  separators</emphasis> (and the components that go with them
   1.556 +	) to strip.  A strip count of one will turn
   1.557 +	<filename>foo/bar</filename> into <filename>bar</filename>,
   1.558 +	but <filename>/foo/bar</filename> (notice the extra leading
   1.559 +	slash) into <filename>foo/bar</filename>.)</para>
   1.560 +
   1.561 +      <para>The <quote>standard</quote> strip count for patches is
   1.562 +	one; almost all patches contain one leading path name
   1.563 +	component that needs to be stripped. Mercurial's <command
   1.564 +	  role="hg-cmd">hg diff</command> command generates path names
   1.565 +	in this form, and the <command role="hg-cmd">hg
   1.566 +	  import</command> command and MQ expect patches to have a
   1.567 +	strip count of one.</para>
   1.568 +
   1.569 +      <para>If you receive a patch from someone that you want to add
   1.570 +	to your patch queue, and the patch needs a strip count other
   1.571 +	than one, you cannot just <command
   1.572 +	  role="hg-ext-mq">qimport</command> the patch, because
   1.573 +	<command role="hg-ext-mq">qimport</command> does not yet have
   1.574 +	a <literal>-p</literal> option (see <ulink role="hg-bug"
   1.575 +	  url="http://www.selenic.com/mercurial/bts/issue311">issue
   1.576 +	  311</ulink>).  Your best bet is to <command
   1.577 +	  role="hg-ext-mq">qnew</command> a patch of your own, then
   1.578 +	use <command>patch -pN</command> to apply their patch,
   1.579 +	followed by <command role="hg-cmd">hg addremove</command> to
   1.580 +	pick up any files added or removed by the patch, followed by
   1.581 +	<command role="hg-ext-mq">hg qrefresh</command>. This
   1.582 +	complexity may become unnecessary; see <ulink role="hg-bug"
   1.583 +	  url="http://www.selenic.com/mercurial/bts/issue311">issue
   1.584 +	  311</ulink> for details.
   1.585 +      </para>
   1.586 +    </sect2>
   1.587 +    <sect2>
   1.588 +      <title>Strategies for applying a patch</title>
   1.589 +
   1.590 +      <para>When <command>patch</command> applies a hunk, it tries a
   1.591 +	handful of successively less accurate strategies to try to
   1.592 +	make the hunk apply. This falling-back technique often makes
   1.593 +	it possible to take a patch that was generated against an old
   1.594 +	version of a file, and apply it against a newer version of
   1.595 +	that file.</para>
   1.596 +
   1.597 +      <para>First, <command>patch</command> tries an exact match,
   1.598 +	where the line numbers, the context, and the text to be
   1.599 +	modified must apply exactly.  If it cannot make an exact
   1.600 +	match, it tries to find an exact match for the context,
   1.601 +	without honouring the line numbering information.  If this
   1.602 +	succeeds, it prints a line of output saying that the hunk was
   1.603 +	applied, but at some <emphasis>offset</emphasis> from the
   1.604 +	original line number.</para>
   1.605 +
   1.606 +      <para>If a context-only match fails, <command>patch</command>
   1.607 +	removes the first and last lines of the context, and tries a
   1.608 +	<emphasis>reduced</emphasis> context-only match.  If the hunk
   1.609 +	with reduced context succeeds, it prints a message saying that
   1.610 +	it applied the hunk with a <emphasis>fuzz factor</emphasis>
   1.611 +	(the number after the fuzz factor indicates how many lines of
   1.612 +	context <command>patch</command> had to trim before the patch
   1.613 +	applied).</para>
   1.614 +
   1.615 +      <para>When neither of these techniques works,
   1.616 +	<command>patch</command> prints a message saying that the hunk
   1.617 +	in question was rejected.  It saves rejected hunks (also
   1.618 +	simply called <quote>rejects</quote>) to a file with the same
   1.619 +	name, and an added <filename role="special">.rej</filename>
   1.620 +	extension.  It also saves an unmodified copy of the file with
   1.621 +	a <filename role="special">.orig</filename> extension; the
   1.622 +	copy of the file without any extensions will contain any
   1.623 +	changes made by hunks that <emphasis>did</emphasis> apply
   1.624 +	cleanly.  If you have a patch that modifies
   1.625 +	<filename>foo</filename> with six hunks, and one of them fails
   1.626 +	to apply, you will have: an unmodified
   1.627 +	<filename>foo.orig</filename>, a <filename>foo.rej</filename>
   1.628 +	containing one hunk, and <filename>foo</filename>, containing
   1.629 +	the changes made by the five successful hunks.</para>
   1.630 +
   1.631 +    </sect2>
   1.632 +    <sect2>
   1.633 +      <title>Some quirks of patch representation</title>
   1.634 +
   1.635 +      <para>There are a few useful things to know about how
   1.636 +	<command>patch</command> works with files.</para>
   1.637 +      <itemizedlist>
   1.638 +	<listitem><para>This should already be obvious, but
   1.639 +	    <command>patch</command> cannot handle binary
   1.640 +	    files.</para>
   1.641 +	</listitem>
   1.642 +	<listitem><para>Neither does it care about the executable bit;
   1.643 +	    it creates new files as readable, but not
   1.644 +	    executable.</para>
   1.645 +	</listitem>
   1.646 +	<listitem><para><command>patch</command> treats the removal of
   1.647 +	    a file as a diff between the file to be removed and the
   1.648 +	    empty file.  So your idea of <quote>I deleted this
   1.649 +	      file</quote> looks like <quote>every line of this file
   1.650 +	      was deleted</quote> in a patch.</para>
   1.651 +	</listitem>
   1.652 +	<listitem><para>It treats the addition of a file as a diff
   1.653 +	    between the empty file and the file to be added.  So in a
   1.654 +	    patch, your idea of <quote>I added this file</quote> looks
   1.655 +	    like <quote>every line of this file was
   1.656 +	      added</quote>.</para>
   1.657 +	</listitem>
   1.658 +	<listitem><para>It treats a renamed file as the removal of the
   1.659 +	    old name, and the addition of the new name.  This means
   1.660 +	    that renamed files have a big footprint in patches.  (Note
   1.661 +	    also that Mercurial does not currently try to infer when
   1.662 +	    files have been renamed or copied in a patch.)</para>
   1.663 +	</listitem>
   1.664 +	<listitem><para><command>patch</command> cannot represent
   1.665 +	    empty files, so you cannot use a patch to represent the
   1.666 +	    notion <quote>I added this empty file to the
   1.667 +	      tree</quote>.</para>
   1.668 +	</listitem></itemizedlist>
   1.669 +    </sect2>
   1.670 +    <sect2>
   1.671 +      <title>Beware the fuzz</title>
   1.672 +
   1.673 +      <para>While applying a hunk at an offset, or with a fuzz factor,
   1.674 +	will often be completely successful, these inexact techniques
   1.675 +	naturally leave open the possibility of corrupting the patched
   1.676 +	file.  The most common cases typically involve applying a
   1.677 +	patch twice, or at an incorrect location in the file.  If
   1.678 +	<command>patch</command> or <command
   1.679 +	  role="hg-ext-mq">qpush</command> ever mentions an offset or
   1.680 +	fuzz factor, you should make sure that the modified files are
   1.681 +	correct afterwards.</para>
   1.682 +
   1.683 +      <para>It's often a good idea to refresh a patch that has applied
   1.684 +	with an offset or fuzz factor; refreshing the patch generates
   1.685 +	new context information that will make it apply cleanly.  I
   1.686 +	say <quote>often,</quote> not <quote>always,</quote> because
   1.687 +	sometimes refreshing a patch will make it fail to apply
   1.688 +	against a different revision of the underlying files.  In some
   1.689 +	cases, such as when you're maintaining a patch that must sit
   1.690 +	on top of multiple versions of a source tree, it's acceptable
   1.691 +	to have a patch apply with some fuzz, provided you've verified
   1.692 +	the results of the patching process in such cases.</para>
   1.693 +
   1.694 +    </sect2>
   1.695 +    <sect2>
   1.696 +      <title>Handling rejection</title>
   1.697 +
   1.698 +      <para>If <command role="hg-ext-mq">qpush</command> fails to
   1.699 +	apply a patch, it will print an error message and exit.  If it
   1.700 +	has left <filename role="special">.rej</filename> files
   1.701 +	behind, it is usually best to fix up the rejected hunks before
   1.702 +	you push more patches or do any further work.</para>
   1.703 +
   1.704 +      <para>If your patch <emphasis>used to</emphasis> apply cleanly,
   1.705 +	and no longer does because you've changed the underlying code
   1.706 +	that your patches are based on, Mercurial Queues can help; see
   1.707 +	section <xref
   1.708 +	  linkend="sec.mq.merge"/> for details.</para>
   1.709 +
   1.710 +      <para>Unfortunately, there aren't any great techniques for
   1.711 +	dealing with rejected hunks.  Most often, you'll need to view
   1.712 +	the <filename role="special">.rej</filename> file and edit the
   1.713 +	target file, applying the rejected hunks by hand.</para>
   1.714 +
   1.715 +      <para>If you're feeling adventurous, Neil Brown, a Linux kernel
   1.716 +	hacker, wrote a tool called <command>wiggle</command>
   1.717 +	<citation>web:wiggle</citation>, which is more vigorous than
   1.718 +	<command>patch</command> in its attempts to make a patch
   1.719 +	apply.</para>
   1.720 +
   1.721 +      <para>Another Linux kernel hacker, Chris Mason (the author of
   1.722 +	Mercurial Queues), wrote a similar tool called
   1.723 +	<command>mpatch</command> <citation>web:mpatch</citation>,
   1.724 +	which takes a simple approach to automating the application of
   1.725 +	hunks rejected by <command>patch</command>.  The
   1.726 +	<command>mpatch</command> command can help with four common
   1.727 +	reasons that a hunk may be rejected:</para>
   1.728 +
   1.729 +      <itemizedlist>
   1.730 +	<listitem><para>The context in the middle of a hunk has
   1.731 +	    changed.</para>
   1.732 +	</listitem>
   1.733 +	<listitem><para>A hunk is missing some context at the
   1.734 +	    beginning or end.</para>
   1.735 +	</listitem>
   1.736 +	<listitem><para>A large hunk might apply better&emdash;either
   1.737 +	    entirely or in part&emdash;if it was broken up into
   1.738 +	    smaller hunks.</para>
   1.739 +	</listitem>
   1.740 +	<listitem><para>A hunk removes lines with slightly different
   1.741 +	    content than those currently present in the file.</para>
   1.742 +	</listitem></itemizedlist>
   1.743 +
   1.744 +      <para>If you use <command>wiggle</command> or
   1.745 +	<command>mpatch</command>, you should be doubly careful to
   1.746 +	check your results when you're done.  In fact,
   1.747 +	<command>mpatch</command> enforces this method of
   1.748 +	double-checking the tool's output, by automatically dropping
   1.749 +	you into a merge program when it has done its job, so that you
   1.750 +	can verify its work and finish off any remaining
   1.751 +	merges.</para>
   1.752 +
   1.753 +    </sect2>
   1.754 +  </sect1>
   1.755 +  <sect1 id="sec.mq.perf">
   1.756 +    <title>Getting the best performance out of MQ</title>
   1.757 +
   1.758 +    <para>MQ is very efficient at handling a large number of patches.
   1.759 +      I ran some performance experiments in mid-2006 for a talk that I
   1.760 +      gave at the 2006 EuroPython conference
   1.761 +      <citation>web:europython</citation>.  I used as my data set the
   1.762 +      Linux 2.6.17-mm1 patch series, which consists of 1,738 patches.
   1.763 +      I applied these on top of a Linux kernel repository containing
   1.764 +      all 27,472 revisions between Linux 2.6.12-rc2 and Linux
   1.765 +      2.6.17.</para>
   1.766 +
   1.767 +    <para>On my old, slow laptop, I was able to <command
   1.768 +	role="hg-cmd">hg qpush <option
   1.769 +	  role="hg-ext-mq-cmd-qpush-opt">hg -a</option></command> all
   1.770 +      1,738 patches in 3.5 minutes, and <command role="hg-cmd">hg qpop
   1.771 +	<option role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command>
   1.772 +      them all in 30 seconds.  (On a newer laptop, the time to push
   1.773 +      all patches dropped to two minutes.)  I could <command
   1.774 +	role="hg-ext-mq">qrefresh</command> one of the biggest patches
   1.775 +      (which made 22,779 lines of changes to 287 files) in 6.6
   1.776 +      seconds.</para>
   1.777 +
   1.778 +    <para>Clearly, MQ is well suited to working in large trees, but
   1.779 +      there are a few tricks you can use to get the best performance
   1.780 +      of it.</para>
   1.781 +
   1.782 +    <para>First of all, try to <quote>batch</quote> operations
   1.783 +      together.  Every time you run <command
   1.784 +	role="hg-ext-mq">qpush</command> or <command
   1.785 +	role="hg-ext-mq">qpop</command>, these commands scan the
   1.786 +      working directory once to make sure you haven't made some
   1.787 +      changes and then forgotten to run <command
   1.788 +	role="hg-ext-mq">qrefresh</command>.  On a small tree, the
   1.789 +      time that this scan takes is unnoticeable.  However, on a
   1.790 +      medium-sized tree (containing tens of thousands of files), it
   1.791 +      can take a second or more.</para>
   1.792 +
   1.793 +    <para>The <command role="hg-ext-mq">qpush</command> and <command
   1.794 +	role="hg-ext-mq">qpop</command> commands allow you to push and
   1.795 +      pop multiple patches at a time.  You can identify the
   1.796 +      <quote>destination patch</quote> that you want to end up at.
   1.797 +      When you <command role="hg-ext-mq">qpush</command> with a
   1.798 +      destination specified, it will push patches until that patch is
   1.799 +      at the top of the applied stack.  When you <command
   1.800 +	role="hg-ext-mq">qpop</command> to a destination, MQ will pop
   1.801 +      patches until the destination patch is at the top.</para>
   1.802 +
   1.803 +    <para>You can identify a destination patch using either the name
   1.804 +      of the patch, or by number.  If you use numeric addressing,
   1.805 +      patches are counted from zero; this means that the first patch
   1.806 +      is zero, the second is one, and so on.</para>
   1.807 +
   1.808 +  </sect1>
   1.809 +  <sect1 id="sec.mq.merge">
   1.810 +    <title>Updating your patches when the underlying code
   1.811 +      changes</title>
   1.812 +
   1.813 +    <para>It's common to have a stack of patches on top of an
   1.814 +      underlying repository that you don't modify directly.  If you're
   1.815 +      working on changes to third-party code, or on a feature that is
   1.816 +      taking longer to develop than the rate of change of the code
   1.817 +      beneath, you will often need to sync up with the underlying
   1.818 +      code, and fix up any hunks in your patches that no longer apply.
   1.819 +      This is called <emphasis>rebasing</emphasis> your patch
   1.820 +      series.</para>
   1.821 +
   1.822 +    <para>The simplest way to do this is to <command role="hg-cmd">hg
   1.823 +	qpop <option role="hg-ext-mq-cmd-qpop-opt">hg
   1.824 +	  -a</option></command> your patches, then <command
   1.825 +	role="hg-cmd">hg pull</command> changes into the underlying
   1.826 +      repository, and finally <command role="hg-cmd">hg qpush <option
   1.827 +	  role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> your
   1.828 +      patches again.  MQ will stop pushing any time it runs across a
   1.829 +      patch that fails to apply during conflicts, allowing you to fix
   1.830 +      your conflicts, <command role="hg-ext-mq">qrefresh</command> the
   1.831 +      affected patch, and continue pushing until you have fixed your
   1.832 +      entire stack.</para>
   1.833 +
   1.834 +    <para>This approach is easy to use and works well if you don't
   1.835 +      expect changes to the underlying code to affect how well your
   1.836 +      patches apply. If your patch stack touches code that is modified
   1.837 +      frequently or invasively in the underlying repository, however,
   1.838 +      fixing up rejected hunks by hand quickly becomes
   1.839 +      tiresome.</para>
   1.840 +
   1.841 +    <para>It's possible to partially automate the rebasing process.
   1.842 +      If your patches apply cleanly against some revision of the
   1.843 +      underlying repo, MQ can use this information to help you to
   1.844 +      resolve conflicts between your patches and a different
   1.845 +      revision.</para>
   1.846 +
   1.847 +    <para>The process is a little involved.</para>
   1.848 +    <orderedlist>
   1.849 +      <listitem><para>To begin, <command role="hg-cmd">hg qpush
   1.850 +	    -a</command> all of your patches on top of the revision
   1.851 +	  where you know that they apply cleanly.</para>
   1.852 +      </listitem>
   1.853 +      <listitem><para>Save a backup copy of your patch directory using
   1.854 +	  <command role="hg-cmd">hg qsave <option
   1.855 +	      role="hg-ext-mq-cmd-qsave-opt">hg -e</option> <option
   1.856 +	      role="hg-ext-mq-cmd-qsave-opt">hg -c</option></command>.
   1.857 +	  This prints the name of the directory that it has saved the
   1.858 +	  patches in.  It will save the patches to a directory called
   1.859 +	  <filename role="special"
   1.860 +	    class="directory">.hg/patches.N</filename>, where
   1.861 +	  <literal>N</literal> is a small integer.  It also commits a
   1.862 +	  <quote>save changeset</quote> on top of your applied
   1.863 +	  patches; this is for internal book-keeping, and records the
   1.864 +	  states of the <filename role="special">series</filename> and
   1.865 +	  <filename role="special">status</filename> files.</para>
   1.866 +      </listitem>
   1.867 +      <listitem><para>Use <command role="hg-cmd">hg pull</command> to
   1.868 +	  bring new changes into the underlying repository.  (Don't
   1.869 +	  run <command role="hg-cmd">hg pull -u</command>; see below
   1.870 +	  for why.)</para>
   1.871 +      </listitem>
   1.872 +      <listitem><para>Update to the new tip revision, using <command
   1.873 +	    role="hg-cmd">hg update <option
   1.874 +	      role="hg-opt-update">-C</option></command> to override
   1.875 +	  the patches you have pushed.</para>
   1.876 +      </listitem>
   1.877 +      <listitem><para>Merge all patches using <command>hg qpush -m
   1.878 +	    -a</command>.  The <option
   1.879 +	    role="hg-ext-mq-cmd-qpush-opt">-m</option> option to
   1.880 +	  <command role="hg-ext-mq">qpush</command> tells MQ to
   1.881 +	  perform a three-way merge if the patch fails to
   1.882 +	  apply.</para>
   1.883 +      </listitem></orderedlist>
   1.884 +
   1.885 +    <para>During the <command role="hg-cmd">hg qpush <option
   1.886 +	  role="hg-ext-mq-cmd-qpush-opt">hg -m</option></command>,
   1.887 +      each patch in the <filename role="special">series</filename>
   1.888 +      file is applied normally.  If a patch applies with fuzz or
   1.889 +      rejects, MQ looks at the queue you <command
   1.890 +	role="hg-ext-mq">qsave</command>d, and performs a three-way
   1.891 +      merge with the corresponding changeset.  This merge uses
   1.892 +      Mercurial's normal merge machinery, so it may pop up a GUI merge
   1.893 +      tool to help you to resolve problems.</para>
   1.894 +
   1.895 +    <para>When you finish resolving the effects of a patch, MQ
   1.896 +      refreshes your patch based on the result of the merge.</para>
   1.897 +
   1.898 +    <para>At the end of this process, your repository will have one
   1.899 +      extra head from the old patch queue, and a copy of the old patch
   1.900 +      queue will be in <filename role="special"
   1.901 +	class="directory">.hg/patches.N</filename>. You can remove the
   1.902 +      extra head using <command role="hg-cmd">hg qpop -a -n
   1.903 +	patches.N</command> or <command role="hg-cmd">hg
   1.904 +	strip</command>.  You can delete <filename role="special"
   1.905 +	class="directory">.hg/patches.N</filename> once you are sure
   1.906 +      that you no longer need it as a backup.</para>
   1.907 +
   1.908 +  </sect1>
   1.909 +  <sect1>
   1.910 +    <title>Identifying patches</title>
   1.911 +
   1.912 +    <para>MQ commands that work with patches let you refer to a patch
   1.913 +      either by using its name or by a number.  By name is obvious
   1.914 +      enough; pass the name <filename>foo.patch</filename> to <command
   1.915 +	role="hg-ext-mq">qpush</command>, for example, and it will
   1.916 +      push patches until <filename>foo.patch</filename> is
   1.917 +      applied.</para>
   1.918 +
   1.919 +    <para>As a shortcut, you can refer to a patch using both a name
   1.920 +      and a numeric offset; <literal>foo.patch-2</literal> means
   1.921 +      <quote>two patches before <literal>foo.patch</literal></quote>,
   1.922 +      while <literal>bar.patch+4</literal> means <quote>four patches
   1.923 +	after <literal>bar.patch</literal></quote>.</para>
   1.924 +
   1.925 +    <para>Referring to a patch by index isn't much different.  The
   1.926 +      first patch printed in the output of <command
   1.927 +	role="hg-ext-mq">qseries</command> is patch zero (yes, it's
   1.928 +      one of those start-at-zero counting systems); the second is
   1.929 +      patch one; and so on.</para>
   1.930 +
   1.931 +    <para>MQ also makes it easy to work with patches when you are
   1.932 +      using normal Mercurial commands.  Every command that accepts a
   1.933 +      changeset ID will also accept the name of an applied patch.  MQ
   1.934 +      augments the tags normally in the repository with an eponymous
   1.935 +      one for each applied patch.  In addition, the special tags
   1.936 +      <literal role="tag">qbase</literal> and
   1.937 +      <literal role="tag">qtip</literal> identify
   1.938 +      the <quote>bottom-most</quote> and topmost applied patches,
   1.939 +      respectively.</para>
   1.940 +
   1.941 +    <para>These additions to Mercurial's normal tagging capabilities
   1.942 +      make dealing with patches even more of a breeze.</para>
   1.943 +    <itemizedlist>
   1.944 +      <listitem><para>Want to patchbomb a mailing list with your
   1.945 +	  latest series of changes?</para>
   1.946 +	<programlisting>hg email qbase:qtip</programlisting>
   1.947 +	<para>  (Don't know what <quote>patchbombing</quote> is?  See
   1.948 +	  section <xref linkend="sec.hgext.patchbomb"/>.)</para>
   1.949 +      </listitem>
   1.950 +      <listitem><para>Need to see all of the patches since
   1.951 +	  <literal>foo.patch</literal> that have touched files in a
   1.952 +	  subdirectory of your tree?</para>
   1.953 +	<programlisting>hg log -r foo.patch:qtip subdir</programlisting>
   1.954 +      </listitem>
   1.955 +    </itemizedlist>
   1.956 +
   1.957 +    <para>Because MQ makes the names of patches available to the rest
   1.958 +      of Mercurial through its normal internal tag machinery, you
   1.959 +      don't need to type in the entire name of a patch when you want
   1.960 +      to identify it by name.</para>
   1.961 +
   1.962 +    <para>Another nice consequence of representing patch names as tags
   1.963 +      is that when you run the <command role="hg-cmd">hg log</command>
   1.964 +      command, it will display a patch's name as a tag, simply as part
   1.965 +      of its normal output.  This makes it easy to visually
   1.966 +      distinguish applied patches from underlying
   1.967 +      <quote>normal</quote> revisions.  The following example shows a
   1.968 +      few normal Mercurial commands in use with applied
   1.969 +      patches.</para>
   1.970 +
   1.971 +&interaction.mq.id.output;
   1.972 +
   1.973 +  </sect1>
   1.974 +  <sect1>
   1.975 +    <title>Useful things to know about</title>
   1.976 +
   1.977 +    <para>There are a number of aspects of MQ usage that don't fit
   1.978 +      tidily into sections of their own, but that are good to know.
   1.979 +      Here they are, in one place.</para>
   1.980 +
   1.981 +    <itemizedlist>
   1.982 +      <listitem><para>Normally, when you <command
   1.983 +	    role="hg-ext-mq">qpop</command> a patch and <command
   1.984 +	    role="hg-ext-mq">qpush</command> it again, the changeset
   1.985 +	  that represents the patch after the pop/push will have a
   1.986 +	  <emphasis>different identity</emphasis> than the changeset
   1.987 +	  that represented the hash beforehand.  See section <xref
   1.988 +	    linkend="sec.mqref.cmd.qpush"/> for
   1.989 +	  information as to why this is.</para>
   1.990 +      </listitem>
   1.991 +      <listitem><para>It's not a good idea to <command
   1.992 +	    role="hg-cmd">hg merge</command> changes from another
   1.993 +	  branch with a patch changeset, at least if you want to
   1.994 +	  maintain the <quote>patchiness</quote> of that changeset and
   1.995 +	  changesets below it on the patch stack.  If you try to do
   1.996 +	  this, it will appear to succeed, but MQ will become
   1.997 +	  confused.</para>
   1.998 +      </listitem></itemizedlist>
   1.999 +
  1.1000 +  </sect1>
  1.1001 +  <sect1 id="sec.mq.repo">
  1.1002 +    <title>Managing patches in a repository</title>
  1.1003 +
  1.1004 +    <para>Because MQ's <filename role="special"
  1.1005 +	class="directory">.hg/patches</filename> directory resides
  1.1006 +      outside a Mercurial repository's working directory, the
  1.1007 +      <quote>underlying</quote> Mercurial repository knows nothing
  1.1008 +      about the management or presence of patches.</para>
  1.1009 +
  1.1010 +    <para>This presents the interesting possibility of managing the
  1.1011 +      contents of the patch directory as a Mercurial repository in its
  1.1012 +      own right.  This can be a useful way to work.  For example, you
  1.1013 +      can work on a patch for a while, <command
  1.1014 +	role="hg-ext-mq">qrefresh</command> it, then <command
  1.1015 +	role="hg-cmd">hg commit</command> the current state of the
  1.1016 +      patch.  This lets you <quote>roll back</quote> to that version
  1.1017 +      of the patch later on.</para>
  1.1018 +
  1.1019 +    <para>You can then share different versions of the same patch
  1.1020 +      stack among multiple underlying repositories.  I use this when I
  1.1021 +      am developing a Linux kernel feature.  I have a pristine copy of
  1.1022 +      my kernel sources for each of several CPU architectures, and a
  1.1023 +      cloned repository under each that contains the patches I am
  1.1024 +      working on.  When I want to test a change on a different
  1.1025 +      architecture, I push my current patches to the patch repository
  1.1026 +      associated with that kernel tree, pop and push all of my
  1.1027 +      patches, and build and test that kernel.</para>
  1.1028 +
  1.1029 +    <para>Managing patches in a repository makes it possible for
  1.1030 +      multiple developers to work on the same patch series without
  1.1031 +      colliding with each other, all on top of an underlying source
  1.1032 +      base that they may or may not control.</para>
  1.1033 +
  1.1034 +    <sect2>
  1.1035 +      <title>MQ support for patch repositories</title>
  1.1036 +
  1.1037 +      <para>MQ helps you to work with the <filename role="special"
  1.1038 +	  class="directory">.hg/patches</filename> directory as a
  1.1039 +	repository; when you prepare a repository for working with
  1.1040 +	patches using <command role="hg-ext-mq">qinit</command>, you
  1.1041 +	can pass the <option role="hg-ext-mq-cmd-qinit-opt">hg
  1.1042 +	  -c</option> option to create the <filename role="special"
  1.1043 +	  class="directory">.hg/patches</filename> directory as a
  1.1044 +	Mercurial repository.</para>
  1.1045 +
  1.1046 +      <note>
  1.1047 +	<para>  If you forget to use the <option
  1.1048 +	    role="hg-ext-mq-cmd-qinit-opt">hg -c</option> option, you
  1.1049 +	  can simply go into the <filename role="special"
  1.1050 +	    class="directory">.hg/patches</filename> directory at any
  1.1051 +	  time and run <command role="hg-cmd">hg init</command>.
  1.1052 +	  Don't forget to add an entry for the <filename
  1.1053 +	    role="special">status</filename> file to the <filename
  1.1054 +	    role="special">.hgignore</filename> file, though</para>
  1.1055 +
  1.1056 +	<para>  (<command role="hg-cmd">hg qinit <option
  1.1057 +	      role="hg-ext-mq-cmd-qinit-opt">hg -c</option></command>
  1.1058 +	  does this for you automatically); you
  1.1059 +	  <emphasis>really</emphasis> don't want to manage the
  1.1060 +	  <filename role="special">status</filename> file.</para>
  1.1061 +      </note>
  1.1062 +
  1.1063 +      <para>As a convenience, if MQ notices that the <filename
  1.1064 +	  class="directory">.hg/patches</filename> directory is a
  1.1065 +	repository, it will automatically <command role="hg-cmd">hg
  1.1066 +	  add</command> every patch that you create and import.</para>
  1.1067 +
  1.1068 +      <para>MQ provides a shortcut command, <command
  1.1069 +	  role="hg-ext-mq">qcommit</command>, that runs <command
  1.1070 +	  role="hg-cmd">hg commit</command> in the <filename
  1.1071 +	  role="special" class="directory">.hg/patches</filename>
  1.1072 +	directory.  This saves some bothersome typing.</para>
  1.1073 +
  1.1074 +      <para>Finally, as a convenience to manage the patch directory,
  1.1075 +	you can define the alias <command>mq</command> on Unix
  1.1076 +	systems. For example, on Linux systems using the
  1.1077 +	<command>bash</command> shell, you can include the following
  1.1078 +	snippet in your <filename
  1.1079 +	  role="home">~/.bashrc</filename>.</para>
  1.1080 +
  1.1081 +      <programlisting>alias mq=`hg -R $(hg root)/.hg/patches'</programlisting>
  1.1082 +
  1.1083 +      <para>You can then issue commands of the form <command>mq
  1.1084 +	  pull</command> from the main repository.</para>
  1.1085 +
  1.1086 +    </sect2>
  1.1087 +    <sect2>
  1.1088 +      <title>A few things to watch out for</title>
  1.1089 +
  1.1090 +      <para>MQ's support for working with a repository full of patches
  1.1091 +	is limited in a few small respects.</para>
  1.1092 +
  1.1093 +      <para>MQ cannot automatically detect changes that you make to
  1.1094 +	the patch directory.  If you <command role="hg-cmd">hg
  1.1095 +	  pull</command>, manually edit, or <command role="hg-cmd">hg
  1.1096 +	  update</command> changes to patches or the <filename
  1.1097 +	  role="special">series</filename> file, you will have to
  1.1098 +	<command role="hg-cmd">hg qpop <option
  1.1099 +	    role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> and
  1.1100 +	then <command role="hg-cmd">hg qpush <option
  1.1101 +	    role="hg-ext-mq-cmd-qpush-opt">hg -a</option></command> in
  1.1102 +	the underlying repository to see those changes show up there.
  1.1103 +	If you forget to do this, you can confuse MQ's idea of which
  1.1104 +	patches are applied.</para>
  1.1105 +
  1.1106 +    </sect2>
  1.1107 +  </sect1>
  1.1108 +  <sect1 id="sec.mq.tools">
  1.1109 +    <title>Third party tools for working with patches</title>
  1.1110 +
  1.1111 +    <para>Once you've been working with patches for a while, you'll
  1.1112 +      find yourself hungry for tools that will help you to understand
  1.1113 +      and manipulate the patches you're dealing with.</para>
  1.1114 +
  1.1115 +    <para>The <command>diffstat</command> command
  1.1116 +      <citation>web:diffstat</citation> generates a histogram of the
  1.1117 +      modifications made to each file in a patch.  It provides a good
  1.1118 +      way to <quote>get a sense of</quote> a patch&emdash;which files
  1.1119 +      it affects, and how much change it introduces to each file and
  1.1120 +      as a whole.  (I find that it's a good idea to use
  1.1121 +      <command>diffstat</command>'s <option
  1.1122 +	role="cmd-opt-diffstat">-p</option> option as a matter of
  1.1123 +      course, as otherwise it will try to do clever things with
  1.1124 +      prefixes of file names that inevitably confuse at least
  1.1125 +      me.)</para>
  1.1126 +
  1.1127 +&interaction.mq.tools.tools;
  1.1128 +
  1.1129 +    <para>The <literal role="package">patchutils</literal> package
  1.1130 +      <citation>web:patchutils</citation> is invaluable. It provides a
  1.1131 +      set of small utilities that follow the <quote>Unix
  1.1132 +	philosophy;</quote> each does one useful thing with a patch.
  1.1133 +      The <literal role="package">patchutils</literal> command I use
  1.1134 +      most is <command>filterdiff</command>, which extracts subsets
  1.1135 +      from a patch file.  For example, given a patch that modifies
  1.1136 +      hundreds of files across dozens of directories, a single
  1.1137 +      invocation of <command>filterdiff</command> can generate a
  1.1138 +      smaller patch that only touches files whose names match a
  1.1139 +      particular glob pattern.  See section <xref
  1.1140 +	linkend="mq-collab.tips.interdiff"/> for another
  1.1141 +      example.</para>
  1.1142 +
  1.1143 +  </sect1>
  1.1144 +  <sect1>
  1.1145 +    <title>Good ways to work with patches</title>
  1.1146 +
  1.1147 +    <para>Whether you are working on a patch series to submit to a
  1.1148 +      free software or open source project, or a series that you
  1.1149 +      intend to treat as a sequence of regular changesets when you're
  1.1150 +      done, you can use some simple techniques to keep your work well
  1.1151 +      organised.</para>
  1.1152 +
  1.1153 +    <para>Give your patches descriptive names.  A good name for a
  1.1154 +      patch might be <filename>rework-device-alloc.patch</filename>,
  1.1155 +      because it will immediately give you a hint what the purpose of
  1.1156 +      the patch is.  Long names shouldn't be a problem; you won't be
  1.1157 +      typing the names often, but you <emphasis>will</emphasis> be
  1.1158 +      running commands like <command
  1.1159 +	role="hg-ext-mq">qapplied</command> and <command
  1.1160 +	role="hg-ext-mq">qtop</command> over and over. Good naming
  1.1161 +      becomes especially important when you have a number of patches
  1.1162 +      to work with, or if you are juggling a number of different tasks
  1.1163 +      and your patches only get a fraction of your attention.</para>
  1.1164 +
  1.1165 +    <para>Be aware of what patch you're working on.  Use the <command
  1.1166 +	role="hg-ext-mq">qtop</command> command and skim over the text
  1.1167 +      of your patches frequently&emdash;for example, using <command
  1.1168 +	role="hg-cmd">hg tip <option
  1.1169 +	  role="hg-opt-tip">-p</option></command>)&emdash;to be sure
  1.1170 +      of where you stand.  I have several times worked on and <command
  1.1171 +	role="hg-ext-mq">qrefresh</command>ed a patch other than the
  1.1172 +      one I intended, and it's often tricky to migrate changes into
  1.1173 +      the right patch after making them in the wrong one.</para>
  1.1174 +
  1.1175 +    <para>For this reason, it is very much worth investing a little
  1.1176 +      time to learn how to use some of the third-party tools I
  1.1177 +      described in section <xref linkend="sec.mq.tools"/>,
  1.1178 +      particularly
  1.1179 +      <command>diffstat</command> and <command>filterdiff</command>.
  1.1180 +      The former will give you a quick idea of what changes your patch
  1.1181 +      is making, while the latter makes it easy to splice hunks
  1.1182 +      selectively out of one patch and into another.</para>
  1.1183 +
  1.1184 +  </sect1>
  1.1185 +  <sect1>
  1.1186 +    <title>MQ cookbook</title>
  1.1187 +
  1.1188 +    <sect2>
  1.1189 +      <title>Manage <quote>trivial</quote> patches</title>
  1.1190 +
  1.1191 +      <para>Because the overhead of dropping files into a new
  1.1192 +	Mercurial repository is so low, it makes a lot of sense to
  1.1193 +	manage patches this way even if you simply want to make a few
  1.1194 +	changes to a source tarball that you downloaded.</para>
  1.1195 +
  1.1196 +      <para>Begin by downloading and unpacking the source tarball, and
  1.1197 +	turning it into a Mercurial repository.</para>
  1.1198 +
  1.1199 +      &interaction.mq.tarball.download;
  1.1200 +
  1.1201 +      <para>Continue by creating a patch stack and making your
  1.1202 +	changes.</para>
  1.1203 +
  1.1204 +      &interaction.mq.tarball.qinit;
  1.1205 +
  1.1206 +      <para>Let's say a few weeks or months pass, and your package
  1.1207 +	author releases a new version.  First, bring their changes
  1.1208 +	into the repository.</para>
  1.1209 +
  1.1210 +      &interaction.mq.tarball.newsource;
  1.1211 +
  1.1212 +      <para>The pipeline starting with <command role="hg-cmd">hg
  1.1213 +	  locate</command> above deletes all files in the working
  1.1214 +	directory, so that <command role="hg-cmd">hg
  1.1215 +	  commit</command>'s <option
  1.1216 +	  role="hg-opt-commit">--addremove</option> option can
  1.1217 +	actually tell which files have really been removed in the
  1.1218 +	newer version of the source.</para>
  1.1219 +
  1.1220 +      <para>Finally, you can apply your patches on top of the new
  1.1221 +	tree.</para>
  1.1222 +
  1.1223 +      &interaction.mq.tarball.repush;
  1.1224 +
  1.1225 +    </sect2>
  1.1226 +    <sect2 id="sec.mq.combine">
  1.1227 +      <title>Combining entire patches</title>
  1.1228 +
  1.1229 +      <para>MQ provides a command, <command
  1.1230 +	  role="hg-ext-mq">qfold</command> that lets you combine
  1.1231 +	entire patches.  This <quote>folds</quote> the patches you
  1.1232 +	name, in the order you name them, into the topmost applied
  1.1233 +	patch, and concatenates their descriptions onto the end of its
  1.1234 +	description.  The patches that you fold must be unapplied
  1.1235 +	before you fold them.</para>
  1.1236 +
  1.1237 +      <para>The order in which you fold patches matters.  If your
  1.1238 +	topmost applied patch is <literal>foo</literal>, and you
  1.1239 +	<command role="hg-ext-mq">qfold</command>
  1.1240 +	<literal>bar</literal> and <literal>quux</literal> into it,
  1.1241 +	you will end up with a patch that has the same effect as if
  1.1242 +	you applied first <literal>foo</literal>, then
  1.1243 +	<literal>bar</literal>, followed by
  1.1244 +	<literal>quux</literal>.</para>
  1.1245 +
  1.1246 +    </sect2>
  1.1247 +    <sect2>
  1.1248 +      <title>Merging part of one patch into another</title>
  1.1249 +
  1.1250 +      <para>Merging <emphasis>part</emphasis> of one patch into
  1.1251 +	another is more difficult than combining entire
  1.1252 +	patches.</para>
  1.1253 +
  1.1254 +      <para>If you want to move changes to entire files, you can use
  1.1255 +	<command>filterdiff</command>'s <option
  1.1256 +	  role="cmd-opt-filterdiff">-i</option> and <option
  1.1257 +	  role="cmd-opt-filterdiff">-x</option> options to choose the
  1.1258 +	modifications to snip out of one patch, concatenating its
  1.1259 +	output onto the end of the patch you want to merge into.  You
  1.1260 +	usually won't need to modify the patch you've merged the
  1.1261 +	changes from.  Instead, MQ will report some rejected hunks
  1.1262 +	when you <command role="hg-ext-mq">qpush</command> it (from
  1.1263 +	the hunks you moved into the other patch), and you can simply
  1.1264 +	<command role="hg-ext-mq">qrefresh</command> the patch to drop
  1.1265 +	the duplicate hunks.</para>
  1.1266 +
  1.1267 +      <para>If you have a patch that has multiple hunks modifying a
  1.1268 +	file, and you only want to move a few of those hunks, the job
  1.1269 +	becomes more messy, but you can still partly automate it.  Use
  1.1270 +	<command>lsdiff -nvv</command> to print some metadata about
  1.1271 +	the patch.</para>
  1.1272 +
  1.1273 +      &interaction.mq.tools.lsdiff;
  1.1274 +
  1.1275 +      <para>This command prints three different kinds of
  1.1276 +	number:</para>
  1.1277 +      <itemizedlist>
  1.1278 +	<listitem><para>(in the first column) a <emphasis>file
  1.1279 +	      number</emphasis> to identify each file modified in the
  1.1280 +	    patch;</para>
  1.1281 +	</listitem>
  1.1282 +	<listitem><para>(on the next line, indented) the line number
  1.1283 +	    within a modified file where a hunk starts; and</para>
  1.1284 +	</listitem>
  1.1285 +	<listitem><para>(on the same line) a <emphasis>hunk
  1.1286 +	      number</emphasis> to identify that hunk.</para>
  1.1287 +	</listitem></itemizedlist>
  1.1288 +
  1.1289 +      <para>You'll have to use some visual inspection, and reading of
  1.1290 +	the patch, to identify the file and hunk numbers you'll want,
  1.1291 +	but you can then pass them to to
  1.1292 +	<command>filterdiff</command>'s <option
  1.1293 +	  role="cmd-opt-filterdiff">--files</option> and <option
  1.1294 +	  role="cmd-opt-filterdiff">--hunks</option> options, to
  1.1295 +	select exactly the file and hunk you want to extract.</para>
  1.1296 +
  1.1297 +      <para>Once you have this hunk, you can concatenate it onto the
  1.1298 +	end of your destination patch and continue with the remainder
  1.1299 +	of section <xref linkend="sec.mq.combine"/>.</para>
  1.1300 +
  1.1301 +    </sect2>
  1.1302 +  </sect1>
  1.1303 +  <sect1>
  1.1304 +    <title>Differences between quilt and MQ</title>
  1.1305 +
  1.1306 +    <para>If you are already familiar with quilt, MQ provides a
  1.1307 +      similar command set.  There are a few differences in the way
  1.1308 +      that it works.</para>
  1.1309 +
  1.1310 +    <para>You will already have noticed that most quilt commands have
  1.1311 +      MQ counterparts that simply begin with a
  1.1312 +      <quote><literal>q</literal></quote>.  The exceptions are quilt's
  1.1313 +      <literal>add</literal> and <literal>remove</literal> commands,
  1.1314 +      the counterparts for which are the normal Mercurial <command
  1.1315 +	role="hg-cmd">hg add</command> and <command role="hg-cmd">hg
  1.1316 +	remove</command> commands.  There is no MQ equivalent of the
  1.1317 +      quilt <literal>edit</literal> command.</para>
  1.1318 +
  1.1319 +  </sect1>
  1.1320 +</chapter>
  1.1321 +
  1.1322 +<!--
  1.1323 +local variables: 
  1.1324 +sgml-parent-document: ("00book.xml" "book" "chapter")
  1.1325 +end:
  1.1326 +-->