comparison en/ch11-mq.xml @ 691:4ce9d0754af3

Remove the words "section", "chapter", etc from in front of xref tags.

690:b788b405e141

      distribute so that they will build properly in their
      environments.</para>

    <para id="x_3b0">When you have few changes to maintain, it is easy to manage
      a single patch using the standard <command>diff</command> and
      <command>patch</command> programs (see section <xref
	linkend="sec:mq:patch"/> for a discussion of these
      tools). Once the number of changes grows, it starts to make
      sense to maintain patches as discrete <quote>chunks of
	work,</quote> so that for example a single patch will contain
      only one bug fix (the patch might modify several files, but it's

      <quote><literal>+</literal></quote> means <quote>insert this
	line.</quote>  For example, a line that is modified is
      represented by one deletion and one insertion.</para>

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

  </sect1>
  <sect1 id="sec:mq:start">

	the application of a patch using the <command
	  role="hg-ext-mq">qpop</command> command.  MQ still
	<emphasis>knows about</emphasis>, or manages, a popped patch,
	but the patch no longer has a corresponding changeset in the
	repository, and the working directory does not contain the
	changes made by the patch.  Figure <xref
	  linkend="fig:mq:stack"/> illustrates
	the difference between applied and tracked patches.</para>

      <informalfigure id="fig:mq:stack">
	<mediaobject><imageobject><imagedata
				    fileref="mq-stack"/></imageobject><textobject><phrase>XXX 
	      add text</phrase></textobject><caption><para id="x_3dd">Applied and
	      unapplied patches in the MQ patch
	      stack</para></caption></mediaobject>
      </informalfigure>

      <para id="x_3de">You can reapply an unapplied, or popped, patch using the
	<command role="hg-ext-mq">qpush</command> command.  This
	creates a new changeset to correspond to the patch, and the
	patch's changes once again become present in the working

	<command role="hg-ext-mq">qpush</command> causes it to push
	all unapplied patches, while the <option
	  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 section <xref linkend="sec:mq:perf"/>
	below.)</para>

&interaction.mq.tutorial.qpush-a;

    </sect2>
    <sect2>

	you push more patches or do any further work.</para>

      <para id="x_3fa">If your patch <emphasis>used to</emphasis> apply cleanly,
	and no longer does because you've changed the underlying code
	that your patches are based on, Mercurial Queues can help; see
	section <xref
	  linkend="sec:mq:merge"/> for details.</para>

      <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>

    <itemizedlist>
      <listitem><para id="x_41b">Want to patchbomb a mailing list with your
	  latest series of changes?</para>
	<programlisting>hg email qbase:qtip</programlisting>
	<para id="x_41c">  (Don't know what <quote>patchbombing</quote> is?  See
	  section <xref linkend="sec:hgext:patchbomb"/>.)</para>
      </listitem>
      <listitem><para id="x_41d">Need to see all of the patches since
	  <literal>foo.patch</literal> that have touched files in a
	  subdirectory of your tree?</para>
	<programlisting>hg log -r foo.patch:qtip subdir</programlisting>

      <listitem><para id="x_421">Normally, when you <command
	    role="hg-ext-mq">qpop</command> a patch and <command
	    role="hg-ext-mq">qpush</command> it again, the changeset
	  that represents the patch after the pop/push will have a
	  <emphasis>different identity</emphasis> than the changeset
	  that represented the hash beforehand.  See section <xref
	    linkend="sec:mqref:cmd:qpush"/> for
	  information as to why this is.</para>
      </listitem>
      <listitem><para id="x_422">It's not a good idea to <command
	    role="hg-cmd">hg merge</command> changes from another

      most is <command>filterdiff</command>, which extracts subsets
      from a patch file.  For example, given a patch that modifies
      hundreds of files across dozens of directories, a single
      invocation of <command>filterdiff</command> can generate a
      smaller patch that only touches files whose names match a
      particular glob pattern.  See section <xref
	linkend="mq-collab:tips:interdiff"/> for another
      example.</para>

  </sect1>
  <sect1>

      one I intended, and it's often tricky to migrate changes into
      the right patch after making them in the wrong one.</para>

    <para id="x_436">For this reason, it is very much worth investing a little
      time to learn how to use some of the third-party tools I
      described in section <xref linkend="sec:mq:tools"/>,
      particularly
      <command>diffstat</command> and <command>filterdiff</command>.
      The former will give you a quick idea of what changes your patch
      is making, while the latter makes it easy to splice hunks
      selectively out of one patch and into another.</para>

	  role="cmd-opt-filterdiff">--hunks</option> options, to
	select exactly the file and hunk you want to extract.</para>

      <para id="x_447">Once you have this hunk, you can concatenate it onto the
	end of your destination patch and continue with the remainder
	of section <xref linkend="sec:mq:combine"/>.</para>

    </sect2>
  </sect1>
  <sect1>
    <title>Differences between quilt and MQ</title>

691:4ce9d0754af3

      distribute so that they will build properly in their
      environments.</para>

    <para id="x_3b0">When you have few changes to maintain, it is easy to manage
      a single patch using the standard <command>diff</command> and
      <command>patch</command> programs (see <xref
	linkend="sec:mq:patch"/> for a discussion of these
      tools). Once the number of changes grows, it starts to make
      sense to maintain patches as discrete <quote>chunks of
	work,</quote> so that for example a single patch will contain
      only one bug fix (the patch might modify several files, but it's

      <quote><literal>+</literal></quote> means <quote>insert this
	line.</quote>  For example, a line that is modified is
      represented by one deletion and one insertion.</para>

    <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">

	the application of a patch using the <command
	  role="hg-ext-mq">qpop</command> command.  MQ still
	<emphasis>knows about</emphasis>, or manages, a popped patch,
	but the patch no longer has a corresponding changeset in the
	repository, and the working directory does not contain the
	changes made by the patch.  <xref
	  linkend="fig:mq:stack"/> illustrates
	the difference between applied and tracked patches.</para>

      <figure id="fig:mq:stack">
	<title>Applied and unapplied patches in the MQ patch
	  stack</title>
	<mediaobject>
	  <imageobject><imagedata fileref="mq-stack"/></imageobject>
	  <textobject><phrase>XXX add text</phrase></textobject>
	</mediaobject>
      </figure>

      <para id="x_3de">You can reapply an unapplied, or popped, patch using the
	<command role="hg-ext-mq">qpush</command> command.  This
	creates a new changeset to correspond to the patch, and the
	patch's changes once again become present in the working

	<command role="hg-ext-mq">qpush</command> causes it to push
	all unapplied patches, while the <option
	  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>

	you push more patches or do any further work.</para>

      <para id="x_3fa">If your patch <emphasis>used to</emphasis> apply cleanly,
	and no longer does because you've changed the underlying code
	that your patches are based on, Mercurial Queues can help; see
	<xref linkend="sec:mq:merge"/> for details.</para>

      <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>

    <itemizedlist>
      <listitem><para id="x_41b">Want to patchbomb a mailing list with your
	  latest series of changes?</para>
	<programlisting>hg email qbase:qtip</programlisting>
	<para id="x_41c">  (Don't know what <quote>patchbombing</quote> is?  See
	  <xref linkend="sec:hgext:patchbomb"/>.)</para>
      </listitem>
      <listitem><para id="x_41d">Need to see all of the patches since
	  <literal>foo.patch</literal> that have touched files in a
	  subdirectory of your tree?</para>
	<programlisting>hg log -r foo.patch:qtip subdir</programlisting>

      <listitem><para id="x_421">Normally, when you <command
	    role="hg-ext-mq">qpop</command> a patch and <command
	    role="hg-ext-mq">qpush</command> it again, the changeset
	  that represents the patch after the pop/push will have a
	  <emphasis>different identity</emphasis> than the changeset
	  that represented the hash beforehand.  See <xref
	    linkend="sec:mqref:cmd:qpush"/> for
	  information as to why this is.</para>
      </listitem>
      <listitem><para id="x_422">It's not a good idea to <command
	    role="hg-cmd">hg merge</command> changes from another

      most is <command>filterdiff</command>, which extracts subsets
      from a patch file.  For example, given a patch that modifies
      hundreds of files across dozens of directories, a single
      invocation of <command>filterdiff</command> can generate a
      smaller patch that only touches files whose names match a
      particular glob pattern.  See <xref
	linkend="mq-collab:tips:interdiff"/> for another
      example.</para>

  </sect1>
  <sect1>

      one I intended, and it's often tricky to migrate changes into
      the right patch after making them in the wrong one.</para>

    <para id="x_436">For this reason, it is very much worth investing a little
      time to learn how to use some of the third-party tools I
      described in <xref linkend="sec:mq:tools"/>,
      particularly
      <command>diffstat</command> and <command>filterdiff</command>.
      The former will give you a quick idea of what changes your patch
      is making, while the latter makes it easy to splice hunks
      selectively out of one patch and into another.</para>

	  role="cmd-opt-filterdiff">--hunks</option> options, to
	select exactly the file and hunk you want to extract.</para>

      <para id="x_447">Once you have this hunk, you can concatenate it onto the
	end of your destination patch and continue with the remainder
	of <xref linkend="sec:mq:combine"/>.</para>

    </sect2>
  </sect1>
  <sect1>
    <title>Differences between quilt and MQ</title>