comparison en/ch11-mq.xml @ 809:ef53d025f410

Mention qdelete and qimport -r.

808:557552d4699f

	modifications those patches make.</para>

      <para id="x_3b9">Quilt knows nothing about revision control tools, so it
	works equally well on top of an unpacked tarball or a
	Subversion working copy.</para>

    </sect2>
    <sect2 id="sec:mq:quilt-mq">
      <title>From patchwork quilt to Mercurial Queues</title>

      <para id="x_3ba">In mid-2005, Chris Mason took the features of quilt and
	wrote an extension that he called Mercurial Queues, which

      binary-search through all changesets and applied patches to see
      where a bug got introduced or fixed.  You can use the <command
	role="hg-cmd">hg annotate</command> command to see which
      changeset or patch modified a particular line of a source file.
      And so on.</para>

  </sect1>
  <sect1 id="sec:mq:patch">
    <title>Understanding patches</title>

    <para id="x_3c2">Because MQ doesn't hide its patch-oriented nature, it is
      helpful to understand what patches are, and a little about the

    <para id="x_3c9">We will return to some of the more subtle aspects of patches
      later (in <xref linkend="sec:mq:adv-patch"/>), but you
      should have
      enough information now to use MQ.</para>

  </sect1>
  <sect1 id="sec:mq:start">
    <title>Getting started with Mercurial Queues</title>

    <para id="x_3ca">Because MQ is implemented as an extension, you must
      explicitly enable before you can use it.  (You don't need to

      commands available.  To verify that the extension is working,
      you can use <command role="hg-cmd">hg help</command> to see if
      the <command role="hg-ext-mq">qinit</command> command is now
      available.</para>

&interaction.mq.qinit-help.help;

    <para id="x_3cc">You can use MQ with <emphasis>any</emphasis> Mercurial
      repository, and its commands only operate within that
      repository.  To get started, simply prepare the repository using
      the <command role="hg-ext-mq">qinit</command> command.</para>

&interaction.mq.tutorial.qinit;

    <para id="x_3cd">This command creates an empty directory called <filename
	role="special" class="directory">.hg/patches</filename>, where
      MQ will keep its metadata.  As with many Mercurial commands, the
      <command role="hg-ext-mq">qinit</command> command prints nothing

      <para id="x_3cf">MQ will use this as the name of an actual file in the
	<filename role="special"
	  class="directory">.hg/patches</filename> directory, as you
	can see below.</para>

&interaction.mq.tutorial.qnew;

      <para id="x_3d0">Also newly present in the <filename role="special"
	  class="directory">.hg/patches</filename> directory are two
	other files, <filename role="special">series</filename> and
	<filename role="special">status</filename>.  The <filename

      <para id="x_3d2">Once you have created your new patch, you can edit files
	in the working directory as you usually would.  All of the
	normal Mercurial commands, such as <command role="hg-cmd">hg
	  diff</command> and <command role="hg-cmd">hg
	  annotate</command>, work exactly as they did before.</para>

    </sect2>
    <sect2>
      <title>Refreshing a patch</title>

      <para id="x_3d3">When you reach a point where you want to save your work,
	use the <command role="hg-ext-mq">qrefresh</command> command
	to update the patch you are working on.</para>

&interaction.mq.tutorial.qrefresh;

      <para id="x_3d4">This command folds the changes you have made in the
	working directory into your patch, and updates its
	corresponding changeset to contain those changes.</para>

	<quote>checkpoint</quote> your work.  Refresh your patch at an
	opportune time; try an experiment; and if the experiment
	doesn't work out, <command role="hg-cmd">hg revert</command>
	your modifications back to the last time you refreshed.</para>

&interaction.mq.tutorial.qrefresh2;

    </sect2>
    <sect2>
      <title>Stacking and tracking patches</title>

      <para id="x_3d6">Once you have finished working on a patch, or need to work
	on another, you can use the <command
	  role="hg-ext-mq">qnew</command> command again to create a
	new patch. Mercurial will apply this patch on top of your
	existing patch.</para>

&interaction.mq.tutorial.qnew2;
      <para id="x_3d7">Notice that the patch contains the changes in our prior
	patch as part of its context (you can see this more clearly in
	the output of <command role="hg-cmd">hg
	  annotate</command>).</para>

	  role="hg-ext-mq">qrefresh</command>, we've been careful to
	only use regular Mercurial commands.  However, MQ provides
	many commands that are easier to use when you are thinking
	about patches, as illustrated below.</para>

&interaction.mq.tutorial.qseries;

      <itemizedlist>
	<listitem><para id="x_3d9">The <command
	      role="hg-ext-mq">qseries</command> command lists every
	    patch that MQ knows about in this repository, from oldest

	      role="hg-ext-mq">qapplied</command> command lists every
	    patch that MQ has <emphasis>applied</emphasis> in this
	    repository, again from oldest to newest (most recently
	    applied).</para>
	</listitem></itemizedlist>

    </sect2>
    <sect2>
      <title>Manipulating the patch stack</title>

      <para id="x_3db">The previous discussion implied that there must be a
	difference between <quote>known</quote> and

	creates a new changeset to correspond to the patch, and the
	patch's changes once again become present in the working
	directory.  See below for examples of <command
	  role="hg-ext-mq">qpop</command> and <command
	  role="hg-ext-mq">qpush</command> in action.</para>
&interaction.mq.tutorial.qpop;

      <para id="x_3df">Notice that once we have popped a patch or two patches,
	the output of <command role="hg-ext-mq">qseries</command>
	remains the same, while that of <command
	  role="hg-ext-mq">qapplied</command> has changed.</para>


    </sect2>
    <sect2>
      <title>Pushing and popping many patches</title>

      <para id="x_3e0">While <command role="hg-ext-mq">qpush</command> and
	<command role="hg-ext-mq">qpop</command> each operate on a

	  role="hg-ext-mq-cmd-qpop-opt">-a</option> option to <command
	  role="hg-ext-mq">qpop</command> causes it to pop all applied
	patches.  (For some more ways to push and pop many patches,
	see <xref linkend="sec:mq:perf"/> below.)</para>

&interaction.mq.tutorial.qpush-a;

    </sect2>
    <sect2>
      <title>Safety checks, and overriding them</title>

      <para id="x_3e1">Several MQ commands check the working directory before
	they do anything, and fail if they find any modifications.

	  role="hg-ext-mq">qnew</command> command will not create a
	new patch if there are outstanding changes, caused in this
	case by the <command role="hg-cmd">hg add</command> of
	<filename>file3</filename>.</para>

&interaction.mq.tutorial.add;

      <para id="x_3e2">Commands that check the working directory all take an
	<quote>I know what I'm doing</quote> option, which is always
	named <option>-f</option>.  The exact meaning of
	<option>-f</option> depends on the command.  For example,

	creates, but <command role="hg-cmd">hg qpop <option
	    role="hg-ext-mq-cmd-qpop-opt">hg -f</option></command>
	will revert modifications to any files affected by the patch
	that it is popping.  Be sure to read the documentation for a
	command's <option>-f</option> option before you use it!</para>

    </sect2>
    <sect2>
      <title>Working on several patches at once</title>

      <para id="x_3e3">The <command role="hg-ext-mq">qrefresh</command> command
	always refreshes the <emphasis>topmost</emphasis> applied

	patch to save your in-progress changes, and <command
	  role="hg-ext-mq">qpop</command> down to the core patch.  Fix
	the core bug, <command role="hg-ext-mq">qrefresh</command> the
	core patch, and <command role="hg-ext-mq">qpush</command> back
	to the UI patch to continue where you left off.</para>

    </sect2>
  </sect1>
  <sect1 id="sec:mq:adv-patch">
    <title>More about patches</title>

    <para id="x_3e5">MQ uses the GNU <command>patch</command> command to apply
      patches, so it's helpful to know a few more detailed aspects of

	complexity may become unnecessary; see <ulink role="hg-bug"
	  url="http://www.selenic.com/mercurial/bts/issue311">issue
	  311</ulink> for details.
      </para>
    </sect2>
    <sect2>
      <title>Strategies for applying a patch</title>

      <para id="x_3ec">When <command>patch</command> applies a hunk, it tries a
	handful of successively less accurate strategies to try to

	<filename>foo</filename> with six hunks, and one of them fails
	to apply, you will have: an unmodified
	<filename>foo.orig</filename>, a <filename>foo.rej</filename>
	containing one hunk, and <filename>foo</filename>, containing
	the changes made by the five successful hunks.</para>

    </sect2>
    <sect2>
      <title>Some quirks of patch representation</title>

      <para id="x_3f0">There are a few useful things to know about how
	<command>patch</command> works with files.</para>

	    empty files, so you cannot use a patch to represent the
	    notion <quote>I added this empty file to the
	      tree</quote>.</para>
	</listitem></itemizedlist>
    </sect2>
    <sect2>
      <title>Beware the fuzz</title>

      <para id="x_3f7">While applying a hunk at an offset, or with a fuzz factor,
	will often be completely successful, these inexact techniques

	against a different revision of the underlying files.  In some
	cases, such as when you're maintaining a patch that must sit
	on top of multiple versions of a source tree, it's acceptable
	to have a patch apply with some fuzz, provided you've verified
	the results of the patching process in such cases.</para>

    </sect2>
    <sect2>
      <title>Handling rejection</title>

      <para id="x_3f9">If <command role="hg-ext-mq">qpush</command> fails to
	apply a patch, it will print an error message and exit.  If it

      <para id="x_3fb">Unfortunately, there aren't any great techniques for
	dealing with rejected hunks.  Most often, you'll need to view
	the <filename role="special">.rej</filename> file and edit the
	target file, applying the rejected hunks by hand.</para>

      <para id="x_3fc">If you're feeling adventurous, Neil Brown, a Linux kernel
	hacker, wrote a tool called <command>wiggle</command>
	<citation>web:wiggle</citation>, which is more vigorous than
	<command>patch</command> in its attempts to make a patch
	apply.</para>

      <para id="x_3fd">Another Linux kernel hacker, Chris Mason (the author of
	Mercurial Queues), wrote a similar tool called
	<command>mpatch</command> <citation>web:mpatch</citation>,
	which takes a simple approach to automating the application of
	hunks rejected by <command>patch</command>.  The
	<command>mpatch</command> command can help with four common
	reasons that a hunk may be rejected:</para>

	</listitem>
	<listitem><para id="x_401">A hunk removes lines with slightly different
	    content than those currently present in the file.</para>
	</listitem></itemizedlist>

      <para id="x_402">If you use <command>wiggle</command> or
	<command>mpatch</command>, you should be doubly careful to
	check your results when you're done.  In fact,
	<command>mpatch</command> enforces this method of
	double-checking the tool's output, by automatically dropping
	you into a merge program when it has done its job, so that you
	can verify its work and finish off any remaining
	merges.</para>

    </sect2>
  </sect1>
  <sect1 id="sec:mq:perf">
    <title>Getting the best performance out of MQ</title>

    <para id="x_403">MQ is very efficient at handling a large number of patches.
      I ran some performance experiments in mid-2006 for a talk that I
      gave at the 2006 EuroPython conference
      <citation>web:europython</citation>.  I used as my data set the
      Linux 2.6.17-mm1 patch series, which consists of 1,738 patches.
      I applied these on top of a Linux kernel repository containing
      all 27,472 revisions between Linux 2.6.12-rc2 and Linux
      2.6.17.</para>

    <para id="x_408">You can identify a destination patch using either the name
      of the patch, or by number.  If you use numeric addressing,
      patches are counted from zero; this means that the first patch
      is zero, the second is one, and so on.</para>

  </sect1>
  <sect1 id="sec:mq:merge">
    <title>Updating your patches when the underlying code
      changes</title>

    <para id="x_409">It's common to have a stack of patches on top of an

      extra head using <command role="hg-cmd">hg qpop -a -n
	patches.N</command> or <command role="hg-cmd">hg
	strip</command>.  You can delete <filename role="special"
	class="directory">.hg/patches.N</filename> once you are sure
      that you no longer need it as a backup.</para>

  </sect1>
  <sect1>
    <title>Identifying patches</title>

    <para id="x_416">MQ commands that work with patches let you refer to a patch
      either by using its name or by a number.  By name is obvious

      distinguish applied patches from underlying
      <quote>normal</quote> revisions.  The following example shows a
      few normal Mercurial commands in use with applied
      patches.</para>

&interaction.mq.id.output;

  </sect1>
  <sect1>
    <title>Useful things to know about</title>

    <para id="x_420">There are a number of aspects of MQ usage that don't fit
      tidily into sections of their own, but that are good to know.

	  maintain the <quote>patchiness</quote> of that changeset and
	  changesets below it on the patch stack.  If you try to do
	  this, it will appear to succeed, but MQ will become
	  confused.</para>
      </listitem></itemizedlist>

  </sect1>
  <sect1 id="sec:mq:repo">
    <title>Managing patches in a repository</title>

    <para id="x_423">Because MQ's <filename role="special"
	class="directory">.hg/patches</filename> directory resides

      <programlisting>alias mq=`hg -R $(hg root)/.hg/patches'</programlisting>

      <para id="x_42d">You can then issue commands of the form <command>mq
	  pull</command> from the main repository.</para>

    </sect2>
    <sect2>
      <title>A few things to watch out for</title>

      <para id="x_42e">MQ's support for working with a repository full of patches
	is limited in a few small respects.</para>

      <para id="x_43c">Finally, you can apply your patches on top of the new
	tree.</para>

      &interaction.mq.tarball.repush;

    </sect2>
    <sect2 id="sec:mq:combine">
      <title>Combining entire patches</title>

      <para id="x_43d">MQ provides a command, <command
	  role="hg-ext-mq">qfold</command> that lets you combine

	<literal>bar</literal> and <literal>quux</literal> into it,
	you will end up with a patch that has the same effect as if
	you applied first <literal>foo</literal>, then
	<literal>bar</literal>, followed by
	<literal>quux</literal>.</para>

    </sect2>
    <sect2>
      <title>Merging part of one patch into another</title>

      <para id="x_43f">Merging <emphasis>part</emphasis> of one patch into
	another is more difficult than combining entire

809:ef53d025f410

	modifications those patches make.</para>

      <para id="x_3b9">Quilt knows nothing about revision control tools, so it
	works equally well on top of an unpacked tarball or a
	Subversion working copy.</para>
    </sect2>

    <sect2 id="sec:mq:quilt-mq">
      <title>From patchwork quilt to Mercurial Queues</title>

      <para id="x_3ba">In mid-2005, Chris Mason took the features of quilt and
	wrote an extension that he called Mercurial Queues, which

      binary-search through all changesets and applied patches to see
      where a bug got introduced or fixed.  You can use the <command
	role="hg-cmd">hg annotate</command> command to see which
      changeset or patch modified a particular line of a source file.
      And so on.</para>
  </sect1>

  <sect1 id="sec:mq:patch">
    <title>Understanding patches</title>

    <para id="x_3c2">Because MQ doesn't hide its patch-oriented nature, it is
      helpful to understand what patches are, and a little about the

    <para id="x_3c9">We will return to some of the more subtle aspects of patches
      later (in <xref linkend="sec:mq:adv-patch"/>), but you
      should have
      enough information now to use MQ.</para>
  </sect1>

  <sect1 id="sec:mq:start">
    <title>Getting started with Mercurial Queues</title>

    <para id="x_3ca">Because MQ is implemented as an extension, you must
      explicitly enable before you can use it.  (You don't need to

      commands available.  To verify that the extension is working,
      you can use <command role="hg-cmd">hg help</command> to see if
      the <command role="hg-ext-mq">qinit</command> command is now
      available.</para>

    &interaction.mq.qinit-help.help;

    <para id="x_3cc">You can use MQ with <emphasis>any</emphasis> Mercurial
      repository, and its commands only operate within that
      repository.  To get started, simply prepare the repository using
      the <command role="hg-ext-mq">qinit</command> command.</para>

    &interaction.mq.tutorial.qinit;

    <para id="x_3cd">This command creates an empty directory called <filename
	role="special" class="directory">.hg/patches</filename>, where
      MQ will keep its metadata.  As with many Mercurial commands, the
      <command role="hg-ext-mq">qinit</command> command prints nothing

      <para id="x_3cf">MQ will use this as the name of an actual file in the
	<filename role="special"
	  class="directory">.hg/patches</filename> directory, as you
	can see below.</para>

      &interaction.mq.tutorial.qnew;

      <para id="x_3d0">Also newly present in the <filename role="special"
	  class="directory">.hg/patches</filename> directory are two
	other files, <filename role="special">series</filename> and
	<filename role="special">status</filename>.  The <filename

      <para id="x_3d2">Once you have created your new patch, you can edit files
	in the working directory as you usually would.  All of the
	normal Mercurial commands, such as <command role="hg-cmd">hg
	  diff</command> and <command role="hg-cmd">hg
	  annotate</command>, work exactly as they did before.</para>
    </sect2>

    <sect2>
      <title>Refreshing a patch</title>

      <para id="x_3d3">When you reach a point where you want to save your work,
	use the <command role="hg-ext-mq">qrefresh</command> command
	to update the patch you are working on.</para>

      &interaction.mq.tutorial.qrefresh;

      <para id="x_3d4">This command folds the changes you have made in the
	working directory into your patch, and updates its
	corresponding changeset to contain those changes.</para>

	<quote>checkpoint</quote> your work.  Refresh your patch at an
	opportune time; try an experiment; and if the experiment
	doesn't work out, <command role="hg-cmd">hg revert</command>
	your modifications back to the last time you refreshed.</para>

      &interaction.mq.tutorial.qrefresh2;
    </sect2>

    <sect2>
      <title>Stacking and tracking patches</title>

      <para id="x_3d6">Once you have finished working on a patch, or need to work
	on another, you can use the <command
	  role="hg-ext-mq">qnew</command> command again to create a
	new patch. Mercurial will apply this patch on top of your
	existing patch.</para>

      &interaction.mq.tutorial.qnew2;

      <para id="x_3d7">Notice that the patch contains the changes in our prior
	patch as part of its context (you can see this more clearly in
	the output of <command role="hg-cmd">hg
	  annotate</command>).</para>

	  role="hg-ext-mq">qrefresh</command>, we've been careful to
	only use regular Mercurial commands.  However, MQ provides
	many commands that are easier to use when you are thinking
	about patches, as illustrated below.</para>

      &interaction.mq.tutorial.qseries;

      <itemizedlist>
	<listitem><para id="x_3d9">The <command
	      role="hg-ext-mq">qseries</command> command lists every
	    patch that MQ knows about in this repository, from oldest

	      role="hg-ext-mq">qapplied</command> command lists every
	    patch that MQ has <emphasis>applied</emphasis> in this
	    repository, again from oldest to newest (most recently
	    applied).</para>
	</listitem></itemizedlist>
    </sect2>

    <sect2>
      <title>Manipulating the patch stack</title>

      <para id="x_3db">The previous discussion implied that there must be a
	difference between <quote>known</quote> and

	creates a new changeset to correspond to the patch, and the
	patch's changes once again become present in the working
	directory.  See below for examples of <command
	  role="hg-ext-mq">qpop</command> and <command
	  role="hg-ext-mq">qpush</command> in action.</para>

      &interaction.mq.tutorial.qpop;

      <para id="x_3df">Notice that once we have popped a patch or two patches,
	the output of <command role="hg-ext-mq">qseries</command>
	remains the same, while that of <command
	  role="hg-ext-mq">qapplied</command> has changed.</para>

    </sect2>

    <sect2>
      <title>Pushing and popping many patches</title>

      <para id="x_3e0">While <command role="hg-ext-mq">qpush</command> and
	<command role="hg-ext-mq">qpop</command> each operate on a

	  role="hg-ext-mq-cmd-qpop-opt">-a</option> option to <command
	  role="hg-ext-mq">qpop</command> causes it to pop all applied
	patches.  (For some more ways to push and pop many patches,
	see <xref linkend="sec:mq:perf"/> below.)</para>

      &interaction.mq.tutorial.qpush-a;
    </sect2>

    <sect2>
      <title>Safety checks, and overriding them</title>

      <para id="x_3e1">Several MQ commands check the working directory before
	they do anything, and fail if they find any modifications.

	  role="hg-ext-mq">qnew</command> command will not create a
	new patch if there are outstanding changes, caused in this
	case by the <command role="hg-cmd">hg add</command> of
	<filename>file3</filename>.</para>

      &interaction.mq.tutorial.add;

      <para id="x_3e2">Commands that check the working directory all take an
	<quote>I know what I'm doing</quote> option, which is always
	named <option>-f</option>.  The exact meaning of
	<option>-f</option> depends on the command.  For example,

	creates, but <command role="hg-cmd">hg qpop <option
	    role="hg-ext-mq-cmd-qpop-opt">hg -f</option></command>
	will revert modifications to any files affected by the patch
	that it is popping.  Be sure to read the documentation for a
	command's <option>-f</option> option before you use it!</para>
    </sect2>

    <sect2>
      <title>Working on several patches at once</title>

      <para id="x_3e3">The <command role="hg-ext-mq">qrefresh</command> command
	always refreshes the <emphasis>topmost</emphasis> applied

	patch to save your in-progress changes, and <command
	  role="hg-ext-mq">qpop</command> down to the core patch.  Fix
	the core bug, <command role="hg-ext-mq">qrefresh</command> the
	core patch, and <command role="hg-ext-mq">qpush</command> back
	to the UI patch to continue where you left off.</para>
    </sect2>
  </sect1>

  <sect1 id="sec:mq:adv-patch">
    <title>More about patches</title>

    <para id="x_3e5">MQ uses the GNU <command>patch</command> command to apply
      patches, so it's helpful to know a few more detailed aspects of

	complexity may become unnecessary; see <ulink role="hg-bug"
	  url="http://www.selenic.com/mercurial/bts/issue311">issue
	  311</ulink> for details.
      </para>
    </sect2>

    <sect2>
      <title>Strategies for applying a patch</title>

      <para id="x_3ec">When <command>patch</command> applies a hunk, it tries a
	handful of successively less accurate strategies to try to

	<filename>foo</filename> with six hunks, and one of them fails
	to apply, you will have: an unmodified
	<filename>foo.orig</filename>, a <filename>foo.rej</filename>
	containing one hunk, and <filename>foo</filename>, containing
	the changes made by the five successful hunks.</para>
    </sect2>

    <sect2>
      <title>Some quirks of patch representation</title>

      <para id="x_3f0">There are a few useful things to know about how
	<command>patch</command> works with files.</para>

	    empty files, so you cannot use a patch to represent the
	    notion <quote>I added this empty file to the
	      tree</quote>.</para>
	</listitem></itemizedlist>
    </sect2>

    <sect2>
      <title>Beware the fuzz</title>

      <para id="x_3f7">While applying a hunk at an offset, or with a fuzz factor,
	will often be completely successful, these inexact techniques

	against a different revision of the underlying files.  In some
	cases, such as when you're maintaining a patch that must sit
	on top of multiple versions of a source tree, it's acceptable
	to have a patch apply with some fuzz, provided you've verified
	the results of the patching process in such cases.</para>
    </sect2>

    <sect2>
      <title>Handling rejection</title>

      <para id="x_3f9">If <command role="hg-ext-mq">qpush</command> fails to
	apply a patch, it will print an error message and exit.  If it

      <para id="x_3fb">Unfortunately, there aren't any great techniques for
	dealing with rejected hunks.  Most often, you'll need to view
	the <filename role="special">.rej</filename> file and edit the
	target file, applying the rejected hunks by hand.</para>

      <para id="x_3fd">A Linux kernel hacker, Chris Mason (the author
	of Mercurial Queues), wrote a tool called
	<command>mpatch</command> (<ulink
	  url="http://oss.oracle.com/~mason/mpatch/">http://oss.oracle.com/~mason/mpatch/</ulink>), 
	which takes a simple approach to automating the application of
	hunks rejected by <command>patch</command>.  The
	<command>mpatch</command> command can help with four common
	reasons that a hunk may be rejected:</para>

	</listitem>
	<listitem><para id="x_401">A hunk removes lines with slightly different
	    content than those currently present in the file.</para>
	</listitem></itemizedlist>

      <para id="x_402">If you use <command>mpatch</command>, you
	should be doubly careful to check your results when you're
	done.  In fact, <command>mpatch</command> enforces this method
	of double-checking the tool's output, by automatically
	dropping you into a merge program when it has done its job, so
	that you can verify its work and finish off any remaining
	merges.</para>
    </sect2>
  </sect1>

  <sect1>
    <title>More on patch management</title>

    <para>As you grow familiar with MQ, you will find yourself wanting
      to perform other kinds of patch management operations.</para>

    <sect2>
      <title>Deleting unwanted patches</title>

      <para>If you want to get rid of a patch, use the <command
	  role="hg-ext-mq">hg qdelete</command> command to delete the
	patch file and remove its entry from the patch series.  If you
	try to delete a patch that is still applied, <command
	  role="hg-ext-mq">hg qdelete</command> will refuse.</para>

      &interaction.ch11-qdelete.go;
    </sect2>

    <sect2>
      <title>Converting to and from permanent revisions</title>

      <para>Once you're done working on a patch and want to turn it
	into a permanent changeset, use the <command
	  role="hg-ext-mq">hg qdelete -r</command> command.  Pass a
	revision to the <option>-r</option> option to identify the
	patch that you want to turn into a regular changeset; this
	patch must already be applied.</para>

      &interaction.ch11-qdelete.convert;

      <para>It is also possible to turn an existing changeset into a
	patch, by passing the <option>-r</option> option to <command
	  role="hg-ext-mq">hg qimport</command>.</para>

      &interaction.ch11-qdelete.import;

      <para>Note that it only makes sense to convert a changeset into
	a patch if you have not propagated that changeset into any
	other repositories.  The imported changeset's ID will change
	every time you refresh the patch, which will make Mercurial
	treat it as unrelated to the original changeset if you have
	pushed it somewhere else.</para>
    </sect2>
  </sect1>

  <sect1 id="sec:mq:perf">
    <title>Getting the best performance out of MQ</title>

    <para id="x_403">MQ is very efficient at handling a large number of patches.
      I ran some performance experiments in mid-2006 for a talk that I
      gave at the 2006 EuroPython conference.  I used as my data set the
      Linux 2.6.17-mm1 patch series, which consists of 1,738 patches.
      I applied these on top of a Linux kernel repository containing
      all 27,472 revisions between Linux 2.6.12-rc2 and Linux
      2.6.17.</para>

    <para id="x_408">You can identify a destination patch using either the name
      of the patch, or by number.  If you use numeric addressing,
      patches are counted from zero; this means that the first patch
      is zero, the second is one, and so on.</para>
  </sect1>

  <sect1 id="sec:mq:merge">
    <title>Updating your patches when the underlying code
      changes</title>

    <para id="x_409">It's common to have a stack of patches on top of an

      extra head using <command role="hg-cmd">hg qpop -a -n
	patches.N</command> or <command role="hg-cmd">hg
	strip</command>.  You can delete <filename role="special"
	class="directory">.hg/patches.N</filename> once you are sure
      that you no longer need it as a backup.</para>
  </sect1>

  <sect1>
    <title>Identifying patches</title>

    <para id="x_416">MQ commands that work with patches let you refer to a patch
      either by using its name or by a number.  By name is obvious

      distinguish applied patches from underlying
      <quote>normal</quote> revisions.  The following example shows a
      few normal Mercurial commands in use with applied
      patches.</para>

    &interaction.mq.id.output;
  </sect1>

  <sect1>
    <title>Useful things to know about</title>

    <para id="x_420">There are a number of aspects of MQ usage that don't fit
      tidily into sections of their own, but that are good to know.

	  maintain the <quote>patchiness</quote> of that changeset and
	  changesets below it on the patch stack.  If you try to do
	  this, it will appear to succeed, but MQ will become
	  confused.</para>
      </listitem></itemizedlist>
  </sect1>

  <sect1 id="sec:mq:repo">
    <title>Managing patches in a repository</title>

    <para id="x_423">Because MQ's <filename role="special"
	class="directory">.hg/patches</filename> directory resides

      <programlisting>alias mq=`hg -R $(hg root)/.hg/patches'</programlisting>

      <para id="x_42d">You can then issue commands of the form <command>mq
	  pull</command> from the main repository.</para>
    </sect2>

    <sect2>
      <title>A few things to watch out for</title>

      <para id="x_42e">MQ's support for working with a repository full of patches
	is limited in a few small respects.</para>

      <para id="x_43c">Finally, you can apply your patches on top of the new
	tree.</para>

      &interaction.mq.tarball.repush;
    </sect2>

    <sect2 id="sec:mq:combine">
      <title>Combining entire patches</title>

      <para id="x_43d">MQ provides a command, <command
	  role="hg-ext-mq">qfold</command> that lets you combine

	<literal>bar</literal> and <literal>quux</literal> into it,
	you will end up with a patch that has the same effect as if
	you applied first <literal>foo</literal>, then
	<literal>bar</literal>, followed by
	<literal>quux</literal>.</para>
    </sect2>

    <sect2>
      <title>Merging part of one patch into another</title>

      <para id="x_43f">Merging <emphasis>part</emphasis> of one patch into
	another is more difficult than combining entire