belaran@964: <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
belaran@964: 
belaran@964: <chapter>
belaran@964: <title>Advanced uses of Mercurial Queues</title>
belaran@964: <para>\label{chap:mq-collab}</para>
belaran@964: 
belaran@964: <para>While it's easy to pick up straightforward uses of Mercurial Queues,
belaran@964: use of a little discipline and some of MQ's less frequently used
belaran@964: capabilities makes it possible to work in complicated development
belaran@964: environments.</para>
belaran@964: 
belaran@964: <para>In this chapter, I will use as an example a technique I have used to
belaran@964: manage the development of an Infiniband device driver for the Linux
belaran@964: kernel.  The driver in question is large (at least as drivers go),
belaran@964: with 25,000 lines of code spread across 35 source files.  It is
belaran@964: maintained by a small team of developers.</para>
belaran@964: 
belaran@964: <para>While much of the material in this chapter is specific to Linux, the
belaran@964: same principles apply to any code base for which you're not the
belaran@964: primary owner, and upon which you need to do a lot of development.</para>
belaran@964: 
belaran@964: <sect1>
belaran@964: <title>The problem of many targets</title>
belaran@964: 
belaran@964: <para>The Linux kernel changes rapidly, and has never been internally
belaran@964: stable; developers frequently make drastic changes between releases.
belaran@964: This means that a version of the driver that works well with a
belaran@964: particular released version of the kernel will not even <emphasis>compile</emphasis>
belaran@964: correctly against, typically, any other version.</para>
belaran@964: 
belaran@964: <para>To maintain a driver, we have to keep a number of distinct versions of
belaran@964: Linux in mind.</para>
belaran@964: <itemizedlist>
belaran@964: <listitem><para>One target is the main Linux kernel development tree.
belaran@964:   Maintenance of the code is in this case partly shared by other
belaran@964:   developers in the kernel community, who make <quote>drive-by</quote>
belaran@964:   modifications to the driver as they develop and refine kernel
belaran@964:   subsystems.</para>
belaran@964: </listitem>
belaran@964: <listitem><para>We also maintain a number of <quote>backports</quote> to older versions of
belaran@964:   the Linux kernel, to support the needs of customers who are running
belaran@964:   older Linux distributions that do not incorporate our drivers.  (To
belaran@964:   <emphasis>backport</emphasis> a piece of code is to modify it to work in an older
belaran@964:   version of its target environment than the version it was developed
belaran@964:   for.)</para>
belaran@964: </listitem>
belaran@964: <listitem><para>Finally, we make software releases on a schedule that is
belaran@964:   necessarily not aligned with those used by Linux distributors and
belaran@964:   kernel developers, so that we can deliver new features to customers
belaran@964:   without forcing them to upgrade their entire kernels or
belaran@964:   distributions.
belaran@964: </para>
belaran@964: </listitem></itemizedlist>
belaran@964: 
belaran@964: <sect2>
belaran@964: <title>Tempting approaches that don't work well</title>
belaran@964: 
belaran@964: <para>There are two <quote>standard</quote> ways to maintain a piece of software that
belaran@964: has to target many different environments.
belaran@964: </para>
belaran@964: 
belaran@964: <para>The first is to maintain a number of branches, each intended for a
belaran@964: single target.  The trouble with this approach is that you must
belaran@964: maintain iron discipline in the flow of changes between repositories.
belaran@964: A new feature or bug fix must start life in a <quote>pristine</quote> repository,
belaran@964: then percolate out to every backport repository.  Backport changes are
belaran@964: more limited in the branches they should propagate to; a backport
belaran@964: change that is applied to a branch where it doesn't belong will
belaran@964: probably stop the driver from compiling.
belaran@964: </para>
belaran@964: 
belaran@964: <para>The second is to maintain a single source tree filled with conditional
belaran@964: statements that turn chunks of code on or off depending on the
belaran@964: intended target.  Because these <quote>ifdefs</quote> are not allowed in the
belaran@964: Linux kernel tree, a manual or automatic process must be followed to
belaran@964: strip them out and yield a clean tree.  A code base maintained in this
belaran@964: fashion rapidly becomes a rat's nest of conditional blocks that are
belaran@964: difficult to understand and maintain.
belaran@964: </para>
belaran@964: 
belaran@964: <para>Neither of these approaches is well suited to a situation where you
belaran@964: don't <quote>own</quote> the canonical copy of a source tree.  In the case of a
belaran@964: Linux driver that is distributed with the standard kernel, Linus's
belaran@964: tree contains the copy of the code that will be treated by the world
belaran@964: as canonical.  The upstream version of <quote>my</quote> driver can be modified
belaran@964: by people I don't know, without me even finding out about it until
belaran@964: after the changes show up in Linus's tree.
belaran@964: </para>
belaran@964: 
belaran@964: <para>These approaches have the added weakness of making it difficult to
belaran@964: generate well-formed patches to submit upstream.
belaran@964: </para>
belaran@964: 
belaran@964: <para>In principle, Mercurial Queues seems like a good candidate to manage a
belaran@964: development scenario such as the above.  While this is indeed the
belaran@964: case, MQ contains a few added features that make the job more
belaran@964: pleasant.
belaran@964: </para>
belaran@964: 
belaran@964: <para>\section{Conditionally applying patches with
belaran@964:   guards}
belaran@964: </para>
belaran@964: 
belaran@964: <para>Perhaps the best way to maintain sanity with so many targets is to be
belaran@964: able to choose specific patches to apply for a given situation.  MQ
belaran@964: provides a feature called <quote>guards</quote> (which originates with quilt's
belaran@964: <literal>guards</literal> command) that does just this.  To start off, let's
belaran@964: create a simple repository for experimenting in.
belaran@964: <!-- &interaction.mq.guards.init; -->
belaran@964: This gives us a tiny repository that contains two patches that don't
belaran@964: have any dependencies on each other, because they touch different files.
belaran@964: </para>
belaran@964: 
belaran@964: <para>The idea behind conditional application is that you can <quote>tag</quote> a
belaran@964: patch with a <emphasis>guard</emphasis>, which is simply a text string of your
belaran@964: choosing, then tell MQ to select specific guards to use when applying
belaran@964: patches.  MQ will then either apply, or skip over, a guarded patch,
belaran@964: depending on the guards that you have selected.
belaran@964: </para>
belaran@964: 
belaran@964: <para>A patch can have an arbitrary number of guards;
belaran@964: each one is <emphasis>positive</emphasis> (<quote>apply this patch if this guard is
belaran@964: selected</quote>) or <emphasis>negative</emphasis> (<quote>skip this patch if this guard is
belaran@964: selected</quote>).  A patch with no guards is always applied.
belaran@964: </para>
belaran@964: 
belaran@964: </sect2>
belaran@964: </sect1>
belaran@964: <sect1>
belaran@964: <title>Controlling the guards on a patch</title>
belaran@964: 
belaran@964: <para>The <command role="hg-ext-mq">qguard</command> command lets you determine which guards should
belaran@964: apply to a patch, or display the guards that are already in effect.
belaran@964: Without any arguments, it displays the guards on the current topmost
belaran@964: patch.
belaran@964: <!-- &interaction.mq.guards.qguard; -->
belaran@964: To set a positive guard on a patch, prefix the name of the guard with
belaran@964: a <quote><literal>+</literal></quote>.
belaran@964: <!-- &interaction.mq.guards.qguard.pos; -->
belaran@964: To set a negative guard on a patch, prefix the name of the guard with
belaran@964: a <quote><literal>-</literal></quote>.
belaran@964: <!-- &interaction.mq.guards.qguard.neg; -->
belaran@964: </para>
belaran@964: 
belaran@964: <note>
belaran@964: <para>  The <command role="hg-ext-mq">qguard</command> command <emphasis>sets</emphasis> the guards on a patch; it
belaran@964:   doesn't <emphasis>modify</emphasis> them.  What this means is that if you run
belaran@964:   <command role="hg-cmd">hg qguard +a +b</command> on a patch, then <command role="hg-cmd">hg qguard +c</command> on
belaran@964:   the same patch, the <emphasis>only</emphasis> guard that will be set on it
belaran@964:   afterwards is <literal>+c</literal>.
belaran@964: </para>
belaran@964: </note>
belaran@964: 
belaran@964: <para>Mercurial stores guards in the <filename role="special">series</filename> file; the form in
belaran@964: which they are stored is easy both to understand and to edit by hand.
belaran@964: (In other words, you don't have to use the <command role="hg-ext-mq">qguard</command> command if
belaran@964: you don't want to; it's okay to simply edit the <filename role="special">series</filename>
belaran@964: file.)
belaran@964: <!-- &interaction.mq.guards.series; -->
belaran@964: </para>
belaran@964: 
belaran@964: </sect1>
belaran@964: <sect1>
belaran@964: <title>Selecting the guards to use</title>
belaran@964: 
belaran@964: <para>The <command role="hg-ext-mq">qselect</command> command determines which guards are active at a
belaran@964: given time.  The effect of this is to determine which patches MQ will
belaran@964: apply the next time you run <command role="hg-ext-mq">qpush</command>.  It has no other effect; in
belaran@964: particular, it doesn't do anything to patches that are already
belaran@964: applied.
belaran@964: </para>
belaran@964: 
belaran@964: <para>With no arguments, the <command role="hg-ext-mq">qselect</command> command lists the guards
belaran@964: currently in effect, one per line of output.  Each argument is treated
belaran@964: as the name of a guard to apply.
belaran@964: <!-- &interaction.mq.guards.qselect.foo; -->
belaran@964: In case you're interested, the currently selected guards are stored in
belaran@964: the <filename role="special">guards</filename> file.
belaran@964: <!-- &interaction.mq.guards.qselect.cat; -->
belaran@964: We can see the effect the selected guards have when we run
belaran@964: <command role="hg-ext-mq">qpush</command>.
belaran@964: <!-- &interaction.mq.guards.qselect.qpush; -->
belaran@964: </para>
belaran@964: 
belaran@964: <para>A guard cannot start with a <quote><literal>+</literal></quote> or <quote><literal>-</literal></quote>
belaran@964: character.  The name of a guard must not contain white space, but most
belaran@964: other characters are acceptable.  If you try to use a guard with an
belaran@964: invalid name, MQ will complain:
belaran@964: <!-- &interaction.mq.guards.qselect.error; -->
belaran@964: Changing the selected guards changes the patches that are applied.
belaran@964: <!-- &interaction.mq.guards.qselect.quux; -->
belaran@964: You can see in the example below that negative guards take precedence
belaran@964: over positive guards.
belaran@964: <!-- &interaction.mq.guards.qselect.foobar; -->
belaran@964: </para>
belaran@964: 
belaran@964: </sect1>
belaran@964: <sect1>
belaran@964: <title>MQ's rules for applying patches</title>
belaran@964: 
belaran@964: <para>The rules that MQ uses when deciding whether to apply a patch
belaran@964: are as follows.
belaran@964: </para>
belaran@964: <itemizedlist>
belaran@964: <listitem><para>A patch that has no guards is always applied.
belaran@964: </para>
belaran@964: </listitem>
belaran@964: <listitem><para>If the patch has any negative guard that matches any currently
belaran@964:   selected guard, the patch is skipped.
belaran@964: </para>
belaran@964: </listitem>
belaran@964: <listitem><para>If the patch has any positive guard that matches any currently
belaran@964:   selected guard, the patch is applied.
belaran@964: </para>
belaran@964: </listitem>
belaran@964: <listitem><para>If the patch has positive or negative guards, but none matches
belaran@964:   any currently selected guard, the patch is skipped.
belaran@964: </para>
belaran@964: </listitem></itemizedlist>
belaran@964: 
belaran@964: </sect1>
belaran@964: <sect1>
belaran@964: <title>Trimming the work environment</title>
belaran@964: 
belaran@964: <para>In working on the device driver I mentioned earlier, I don't apply the
belaran@964: patches to a normal Linux kernel tree.  Instead, I use a repository
belaran@964: that contains only a snapshot of the source files and headers that are
belaran@964: relevant to Infiniband development.  This repository is 1% the size
belaran@964: of a kernel repository, so it's easier to work with.
belaran@964: </para>
belaran@964: 
belaran@964: <para>I then choose a <quote>base</quote> version on top of which the patches are
belaran@964: applied.  This is a snapshot of the Linux kernel tree as of a revision
belaran@964: of my choosing.  When I take the snapshot, I record the changeset ID
belaran@964: from the kernel repository in the commit message.  Since the snapshot
belaran@964: preserves the <quote>shape</quote> and content of the relevant parts of the
belaran@964: kernel tree, I can apply my patches on top of either my tiny
belaran@964: repository or a normal kernel tree.
belaran@964: </para>
belaran@964: 
belaran@964: <para>Normally, the base tree atop which the patches apply should be a
belaran@964: snapshot of a very recent upstream tree.  This best facilitates the
belaran@964: development of patches that can easily be submitted upstream with few
belaran@964: or no modifications.
belaran@964: </para>
belaran@964: 
belaran@964: </sect1>
belaran@964: <sect1>
belaran@964: <title>Dividing up the <filename role="special">series</filename> file</title>
belaran@964: 
belaran@964: <para>I categorise the patches in the <filename role="special">series</filename> file into a number
belaran@964: of logical groups.  Each section of like patches begins with a block
belaran@964: of comments that describes the purpose of the patches that follow.
belaran@964: </para>
belaran@964: 
belaran@964: <para>The sequence of patch groups that I maintain follows.  The ordering of
belaran@964: these groups is important; I'll describe why after I introduce the
belaran@964: groups.
belaran@964: </para>
belaran@964: <itemizedlist>
belaran@964: <listitem><para>The <quote>accepted</quote> group.  Patches that the development team has
belaran@964:   submitted to the maintainer of the Infiniband subsystem, and which
belaran@964:   he has accepted, but which are not present in the snapshot that the
belaran@964:   tiny repository is based on.  These are <quote>read only</quote> patches,
belaran@964:   present only to transform the tree into a similar state as it is in
belaran@964:   the upstream maintainer's repository.
belaran@964: </para>
belaran@964: </listitem>
belaran@964: <listitem><para>The <quote>rework</quote> group.  Patches that I have submitted, but that
belaran@964:   the upstream maintainer has requested modifications to before he
belaran@964:   will accept them.
belaran@964: </para>
belaran@964: </listitem>
belaran@964: <listitem><para>The <quote>pending</quote> group.  Patches that I have not yet submitted to
belaran@964:   the upstream maintainer, but which we have finished working on.
belaran@964:   These will be <quote>read only</quote> for a while.  If the upstream maintainer
belaran@964:   accepts them upon submission, I'll move them to the end of the
belaran@964:   <quote>accepted</quote> group.  If he requests that I modify any, I'll move
belaran@964:   them to the beginning of the <quote>rework</quote> group.
belaran@964: </para>
belaran@964: </listitem>
belaran@964: <listitem><para>The <quote>in progress</quote> group.  Patches that are actively being
belaran@964:   developed, and should not be submitted anywhere yet.
belaran@964: </para>
belaran@964: </listitem>
belaran@964: <listitem><para>The <quote>backport</quote> group.  Patches that adapt the source tree to
belaran@964:   older versions of the kernel tree.
belaran@964: </para>
belaran@964: </listitem>
belaran@964: <listitem><para>The <quote>do not ship</quote> group.  Patches that for some reason should
belaran@964:   never be submitted upstream.  For example, one such patch might
belaran@964:   change embedded driver identification strings to make it easier to
belaran@964:   distinguish, in the field, between an out-of-tree version of the
belaran@964:   driver and a version shipped by a distribution vendor.
belaran@964: </para>
belaran@964: </listitem></itemizedlist>
belaran@964: 
belaran@964: <para>Now to return to the reasons for ordering groups of patches in this
belaran@964: way.  We would like the lowest patches in the stack to be as stable as
belaran@964: possible, so that we will not need to rework higher patches due to
belaran@964: changes in context.  Putting patches that will never be changed first
belaran@964: in the <filename role="special">series</filename> file serves this purpose.
belaran@964: </para>
belaran@964: 
belaran@964: <para>We would also like the patches that we know we'll need to modify to be
belaran@964: applied on top of a source tree that resembles the upstream tree as
belaran@964: closely as possible.  This is why we keep accepted patches around for
belaran@964: a while.
belaran@964: </para>
belaran@964: 
belaran@964: <para>The <quote>backport</quote> and <quote>do not ship</quote> patches float at the end of the
belaran@964: <filename role="special">series</filename> file.  The backport patches must be applied on top
belaran@964: of all other patches, and the <quote>do not ship</quote> patches might as well
belaran@964: stay out of harm's way.
belaran@964: </para>
belaran@964: 
belaran@964: </sect1>
belaran@964: <sect1>
belaran@964: <title>Maintaining the patch series</title>
belaran@964: 
belaran@964: <para>In my work, I use a number of guards to control which patches are to
belaran@964: be applied.
belaran@964: </para>
belaran@964: 
belaran@964: <itemizedlist>
belaran@964: <listitem><para><quote>Accepted</quote> patches are guarded with <literal>accepted</literal>.  I
belaran@964:   enable this guard most of the time.  When I'm applying the patches
belaran@964:   on top of a tree where the patches are already present, I can turn
belaran@964:   this patch off, and the patches that follow it will apply cleanly.
belaran@964: </para>
belaran@964: </listitem>
belaran@964: <listitem><para>Patches that are <quote>finished</quote>, but not yet submitted, have no
belaran@964:   guards.  If I'm applying the patch stack to a copy of the upstream
belaran@964:   tree, I don't need to enable any guards in order to get a reasonably
belaran@964:   safe source tree.
belaran@964: </para>
belaran@964: </listitem>
belaran@964: <listitem><para>Those patches that need reworking before being resubmitted are
belaran@964:   guarded with <literal>rework</literal>.
belaran@964: </para>
belaran@964: </listitem>
belaran@964: <listitem><para>For those patches that are still under development, I use
belaran@964:   <literal>devel</literal>.
belaran@964: </para>
belaran@964: </listitem>
belaran@964: <listitem><para>A backport patch may have several guards, one for each version
belaran@964:   of the kernel to which it applies.  For example, a patch that
belaran@964:   backports a piece of code to 2.6.9 will have a <literal>2.6.9</literal> guard.
belaran@964: </para>
belaran@964: </listitem></itemizedlist>
belaran@964: <para>This variety of guards gives me considerable flexibility in
belaran@964: determining what kind of source tree I want to end up with.  For most
belaran@964: situations, the selection of appropriate guards is automated during
belaran@964: the build process, but I can manually tune the guards to use for less
belaran@964: common circumstances.
belaran@964: </para>
belaran@964: 
belaran@964: <sect2>
belaran@964: <title>The art of writing backport patches</title>
belaran@964: 
belaran@964: <para>Using MQ, writing a backport patch is a simple process.  All such a
belaran@964: patch has to do is modify a piece of code that uses a kernel feature
belaran@964: not present in the older version of the kernel, so that the driver
belaran@964: continues to work correctly under that older version.
belaran@964: </para>
belaran@964: 
belaran@964: <para>A useful goal when writing a good backport patch is to make your code
belaran@964: look as if it was written for the older version of the kernel you're
belaran@964: targeting.  The less obtrusive the patch, the easier it will be to
belaran@964: understand and maintain.  If you're writing a collection of backport
belaran@964: patches to avoid the <quote>rat's nest</quote> effect of lots of
belaran@964: <literal>#ifdef</literal>s (hunks of source code that are only used
belaran@964: conditionally) in your code, don't introduce version-dependent
belaran@964: <literal>#ifdef</literal>s into the patches.  Instead, write several patches,
belaran@964: each of which makes unconditional changes, and control their
belaran@964: application using guards.
belaran@964: </para>
belaran@964: 
belaran@964: <para>There are two reasons to divide backport patches into a distinct
belaran@964: group, away from the <quote>regular</quote> patches whose effects they modify.
belaran@964: The first is that intermingling the two makes it more difficult to use
belaran@964: a tool like the <literal role="hg-ext">patchbomb</literal> extension to automate the process of
belaran@964: submitting the patches to an upstream maintainer.  The second is that
belaran@964: a backport patch could perturb the context in which a subsequent
belaran@964: regular patch is applied, making it impossible to apply the regular
belaran@964: patch cleanly <emphasis>without</emphasis> the earlier backport patch already being
belaran@964: applied.
belaran@964: </para>
belaran@964: 
belaran@964: </sect2>
belaran@964: </sect1>
belaran@964: <sect1>
belaran@964: <title>Useful tips for developing with MQ</title>
belaran@964: 
belaran@964: <sect2>
belaran@964: <title>Organising patches in directories</title>
belaran@964: 
belaran@964: <para>If you're working on a substantial project with MQ, it's not difficult
belaran@964: to accumulate a large number of patches.  For example, I have one
belaran@964: patch repository that contains over 250 patches.
belaran@964: </para>
belaran@964: 
belaran@964: <para>If you can group these patches into separate logical categories, you
belaran@964: can if you like store them in different directories; MQ has no
belaran@964: problems with patch names that contain path separators.
belaran@964: </para>
belaran@964: 
belaran@964: </sect2>
belaran@964: <sect2>
belaran@964: <title>Viewing the history of a patch</title>
belaran@964: <para>\label{mq-collab:tips:interdiff}
belaran@964: </para>
belaran@964: 
belaran@964: <para>If you're developing a set of patches over a long time, it's a good
belaran@964: idea to maintain them in a repository, as discussed in
belaran@964: section <xref linkend="sec:mq:repo"/>.  If you do so, you'll quickly discover that
belaran@964: using the <command role="hg-cmd">hg diff</command> command to look at the history of changes to a
belaran@964: patch is unworkable.  This is in part because you're looking at the
belaran@964: second derivative of the real code (a diff of a diff), but also
belaran@964: because MQ adds noise to the process by modifying time stamps and
belaran@964: directory names when it updates a patch.
belaran@964: </para>
belaran@964: 
belaran@964: <para>However, you can use the <literal role="hg-ext">extdiff</literal> extension, which is bundled
belaran@964: with Mercurial, to turn a diff of two versions of a patch into
belaran@964: something readable.  To do this, you will need a third-party package
belaran@964: called <literal role="package">patchutils</literal> <citation>web:patchutils</citation>.  This provides a
belaran@964: command named <command>interdiff</command>, which shows the differences between
belaran@964: two diffs as a diff.  Used on two versions of the same diff, it
belaran@964: generates a diff that represents the diff from the first to the second
belaran@964: version.
belaran@964: </para>
belaran@964: 
belaran@964: <para>You can enable the <literal role="hg-ext">extdiff</literal> extension in the usual way, by
belaran@964: adding a line to the <literal role="rc-extensions">extensions</literal> section of your <filename role="special"> /.hgrc</filename>.
belaran@964: </para>
belaran@964: <programlisting>
belaran@964: <para>  [extensions]
belaran@964:   extdiff =
belaran@964: </para>
belaran@964: </programlisting>
belaran@964: <para>The <command>interdiff</command> command expects to be passed the names of two
belaran@964: files, but the <literal role="hg-ext">extdiff</literal> extension passes the program it runs a
belaran@964: pair of directories, each of which can contain an arbitrary number of
belaran@964: files.  We thus need a small program that will run <command>interdiff</command>
belaran@964: on each pair of files in these two directories.  This program is
belaran@964: available as <filename role="special">hg-interdiff</filename> in the <filename class="directory">examples</filename>
belaran@964: directory of the source code repository that accompanies this book.
belaran@964: <!-- &example.hg-interdiff; -->
belaran@964: </para>
belaran@964: 
belaran@964: <para>With the <filename role="special">hg-interdiff</filename> program in your shell's search path,
belaran@964: you can run it as follows, from inside an MQ patch directory:
belaran@964: </para>
belaran@964: <programlisting>
belaran@964: <para>  hg extdiff -p hg-interdiff -r A:B my-change.patch
belaran@964: </para>
belaran@964: </programlisting>
belaran@964: <para>Since you'll probably want to use this long-winded command a lot, you
belaran@964: can get <literal role="hg-ext">hgext</literal> to make it available as a normal Mercurial
belaran@964: command, again by editing your <filename role="special"> /.hgrc</filename>.
belaran@964: </para>
belaran@964: <programlisting>
belaran@964: <para>  [extdiff]
belaran@964:   cmd.interdiff = hg-interdiff
belaran@964: </para>
belaran@964: </programlisting>
belaran@964: <para>This directs <literal role="hg-ext">hgext</literal> to make an <literal>interdiff</literal> command
belaran@964: available, so you can now shorten the previous invocation of
belaran@964: <command role="hg-ext-extdiff">extdiff</command> to something a little more wieldy.
belaran@964: </para>
belaran@964: <programlisting>
belaran@964: <para>  hg interdiff -r A:B my-change.patch
belaran@964: </para>
belaran@964: </programlisting>
belaran@964: 
belaran@964: <note>
belaran@964: <para>  The <command>interdiff</command> command works well only if the underlying
belaran@964:   files against which versions of a patch are generated remain the
belaran@964:   same.  If you create a patch, modify the underlying files, and then
belaran@964:   regenerate the patch, <command>interdiff</command> may not produce useful
belaran@964:   output.
belaran@964: </para>
belaran@964: </note>
belaran@964: 
belaran@964: <para>The <literal role="hg-ext">extdiff</literal> extension is useful for more than merely improving
belaran@964: the presentation of MQ patches.  To read more about it, go to
belaran@964: section <xref linkend="sec:hgext:extdiff"/>.
belaran@964: </para>
belaran@964: 
belaran@964: </sect2>
belaran@964: </sect1>
belaran@964: </chapter>
belaran@964: 
belaran@964: <!--
belaran@964: local variables: 
belaran@964: sgml-parent-document: ("00book.xml" "book" "chapter")
belaran@964: end:
belaran@964: -->