annotate en/ch12-mq-collab.xml @ 810:1a0a78e197c3

Incorporate feedback from Greg Lindahl.
author Bryan O'Sullivan <bos@serpentine.com>
date Fri, 24 Apr 2009 00:27:05 -0700
parents 1c13ed2130a7
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
2
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
3 <chapter id="chap:mq-collab">
671
13513d2a128d Add sensible names to chapters.
Bryan O'Sullivan <bos@serpentine.com>
parents: 666
diff changeset
4 <?dbhtml filename="advanced-uses-of-mercurial-queues.html"?>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
5 <title>Advanced uses of Mercurial Queues</title>
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
6
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
7 <para id="x_15d">While it's easy to pick up straightforward uses of Mercurial
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
8 Queues, use of a little discipline and some of MQ's less
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
9 frequently used capabilities makes it possible to work in
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
10 complicated development environments.</para>
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
11
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
12 <para id="x_15e">In this chapter, I will use as an example a technique I have
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
13 used to manage the development of an Infiniband device driver for
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
14 the Linux kernel. The driver in question is large (at least as
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
15 drivers go), with 25,000 lines of code spread across 35 source
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
16 files. It is maintained by a small team of developers.</para>
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
17
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
18 <para id="x_15f">While much of the material in this chapter is specific to
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
19 Linux, the same principles apply to any code base for which you're
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
20 not the primary owner, and upon which you need to do a lot of
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
21 development.</para>
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
22
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
23 <sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
24 <title>The problem of many targets</title>
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
25
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
26 <para id="x_160">The Linux kernel changes rapidly, and has never been
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
27 internally stable; developers frequently make drastic changes
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
28 between releases. This means that a version of the driver that
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
29 works well with a particular released version of the kernel will
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
30 not even <emphasis>compile</emphasis> correctly against,
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
31 typically, any other version.</para>
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
32
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
33 <para id="x_161">To maintain a driver, we have to keep a number of distinct
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
34 versions of Linux in mind.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
35 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
36 <listitem><para id="x_162">One target is the main Linux kernel development
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
37 tree. Maintenance of the code is in this case partly shared
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
38 by other developers in the kernel community, who make
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
39 <quote>drive-by</quote> modifications to the driver as they
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
40 develop and refine kernel subsystems.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
41 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
42 <listitem><para id="x_163">We also maintain a number of
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
43 <quote>backports</quote> to older versions of the Linux
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
44 kernel, to support the needs of customers who are running
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
45 older Linux distributions that do not incorporate our
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
46 drivers. (To <emphasis>backport</emphasis> a piece of code
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
47 is to modify it to work in an older version of its target
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
48 environment than the version it was developed for.)</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
49 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
50 <listitem><para id="x_164">Finally, we make software releases on a schedule
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
51 that is necessarily not aligned with those used by Linux
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
52 distributors and kernel developers, so that we can deliver
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
53 new features to customers without forcing them to upgrade
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
54 their entire kernels or distributions.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
55 </listitem></itemizedlist>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
56
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
57 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
58 <title>Tempting approaches that don't work well</title>
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
59
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
60 <para id="x_165">There are two <quote>standard</quote> ways to maintain a
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
61 piece of software that has to target many different
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
62 environments.</para>
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
63
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
64 <para id="x_166">The first is to maintain a number of branches, each
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
65 intended for a single target. The trouble with this approach
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
66 is that you must maintain iron discipline in the flow of
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
67 changes between repositories. A new feature or bug fix must
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
68 start life in a <quote>pristine</quote> repository, then
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
69 percolate out to every backport repository. Backport changes
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
70 are more limited in the branches they should propagate to; a
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
71 backport change that is applied to a branch where it doesn't
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
72 belong will probably stop the driver from compiling.</para>
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
73
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
74 <para id="x_167">The second is to maintain a single source tree filled with
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
75 conditional statements that turn chunks of code on or off
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
76 depending on the intended target. Because these
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
77 <quote>ifdefs</quote> are not allowed in the Linux kernel
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
78 tree, a manual or automatic process must be followed to strip
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
79 them out and yield a clean tree. A code base maintained in
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
80 this fashion rapidly becomes a rat's nest of conditional
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
81 blocks that are difficult to understand and maintain.</para>
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
82
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
83 <para id="x_168">Neither of these approaches is well suited to a situation
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
84 where you don't <quote>own</quote> the canonical copy of a
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
85 source tree. In the case of a Linux driver that is
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
86 distributed with the standard kernel, Linus's tree contains
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
87 the copy of the code that will be treated by the world as
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
88 canonical. The upstream version of <quote>my</quote> driver
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
89 can be modified by people I don't know, without me even
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
90 finding out about it until after the changes show up in
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
91 Linus's tree.</para>
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
92
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
93 <para id="x_169">These approaches have the added weakness of making it
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
94 difficult to generate well-formed patches to submit
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
95 upstream.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
96
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
97 <para id="x_16a">In principle, Mercurial Queues seems like a good candidate
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
98 to manage a development scenario such as the above. While
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
99 this is indeed the case, MQ contains a few added features that
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
100 make the job more pleasant.</para>
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
101
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
102 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
103 </sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
104 <sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
105 <title>Conditionally applying patches with guards</title>
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
106
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
107 <para id="x_16b">Perhaps the best way to maintain sanity with so many targets
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
108 is to be able to choose specific patches to apply for a given
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
109 situation. MQ provides a feature called <quote>guards</quote>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
110 (which originates with quilt's <literal>guards</literal>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
111 command) that does just this. To start off, let's create a
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
112 simple repository for experimenting in.</para>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
113
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
114 &interaction.mq.guards.init;
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
115
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
116 <para id="x_16c">This gives us a tiny repository that contains two patches
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
117 that don't have any dependencies on each other, because they
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
118 touch different files.</para>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
119
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
120 <para id="x_16d">The idea behind conditional application is that you can
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
121 <quote>tag</quote> a patch with a <emphasis>guard</emphasis>,
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
122 which is simply a text string of your choosing, then tell MQ to
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
123 select specific guards to use when applying patches. MQ will
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
124 then either apply, or skip over, a guarded patch, depending on
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
125 the guards that you have selected.</para>
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
126
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
127 <para id="x_16e">A patch can have an arbitrary number of guards; each one is
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
128 <emphasis>positive</emphasis> (<quote>apply this patch if this
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
129 guard is selected</quote>) or <emphasis>negative</emphasis>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
130 (<quote>skip this patch if this guard is selected</quote>). A
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
131 patch with no guards is always applied.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
132
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
133 </sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
134 <sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
135 <title>Controlling the guards on a patch</title>
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
136
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
137 <para id="x_16f">The <command role="hg-ext-mq">qguard</command> command lets
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
138 you determine which guards should apply to a patch, or display
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
139 the guards that are already in effect. Without any arguments, it
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
140 displays the guards on the current topmost patch.</para>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
141
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
142 &interaction.mq.guards.qguard;
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
143
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
144 <para id="x_170">To set a positive guard on a patch, prefix the name of the
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
145 guard with a <quote><literal>+</literal></quote>.</para>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
146
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
147 &interaction.mq.guards.qguard.pos;
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
148
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
149 <para id="x_171">To set a negative guard
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
150 on a patch, prefix the name of the guard with a
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
151 <quote><literal>-</literal></quote>.</para>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
152
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
153 &interaction.mq.guards.qguard.neg;
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
154
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
155 <note>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
156 <para id="x_172"> The <command role="hg-ext-mq">qguard</command> command
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
157 <emphasis>sets</emphasis> the guards on a patch; it doesn't
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
158 <emphasis>modify</emphasis> them. What this means is that if
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
159 you run <command role="hg-cmd">hg qguard +a +b</command> on a
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
160 patch, then <command role="hg-cmd">hg qguard +c</command> on
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
161 the same patch, the <emphasis>only</emphasis> guard that will
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
162 be set on it afterwards is <literal>+c</literal>.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
163 </note>
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
164
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
165 <para id="x_173">Mercurial stores guards in the <filename
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
166 role="special">series</filename> file; the form in which they
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
167 are stored is easy both to understand and to edit by hand. (In
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
168 other words, you don't have to use the <command
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
169 role="hg-ext-mq">qguard</command> command if you don't want
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
170 to; it's okay to simply edit the <filename
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
171 role="special">series</filename> file.)</para>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
172
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
173 &interaction.mq.guards.series;
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
174
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
175 </sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
176 <sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
177 <title>Selecting the guards to use</title>
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
178
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
179 <para id="x_174">The <command role="hg-ext-mq">qselect</command> command
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
180 determines which guards are active at a given time. The effect
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
181 of this is to determine which patches MQ will apply the next
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
182 time you run <command role="hg-ext-mq">qpush</command>. It has
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
183 no other effect; in particular, it doesn't do anything to
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
184 patches that are already applied.</para>
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
185
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
186 <para id="x_175">With no arguments, the <command
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
187 role="hg-ext-mq">qselect</command> command lists the guards
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
188 currently in effect, one per line of output. Each argument is
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
189 treated as the name of a guard to apply.</para>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
190
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
191 &interaction.mq.guards.qselect.foo;
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
192
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
193 <para id="x_176">In case you're interested, the currently selected guards are
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
194 stored in the <filename role="special">guards</filename> file.</para>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
195
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
196 &interaction.mq.guards.qselect.cat;
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
197
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
198 <para id="x_177">We can see the effect the selected guards have when we run
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
199 <command role="hg-ext-mq">qpush</command>.</para>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
200
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
201 &interaction.mq.guards.qselect.qpush;
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
202
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
203 <para id="x_178">A guard cannot start with a
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
204 <quote><literal>+</literal></quote> or
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
205 <quote><literal>-</literal></quote> character. The name of a
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
206 guard must not contain white space, but most other characters
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
207 are acceptable. If you try to use a guard with an invalid name,
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
208 MQ will complain:</para>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
209
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
210 &interaction.mq.guards.qselect.error;
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
211
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
212 <para id="x_179">Changing the selected guards changes the patches that are
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
213 applied.</para>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
214
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
215 &interaction.mq.guards.qselect.quux;
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
216
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
217 <para id="x_17a">You can see in the example below that negative guards take
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
218 precedence over positive guards.</para>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
219
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 658
diff changeset
220 &interaction.mq.guards.qselect.foobar;
104
32bf9a5f22c0 Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
221
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
222 </sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
223 <sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
224 <title>MQ's rules for applying patches</title>
105
ecacb6b4c9fd Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents: 104
diff changeset
225
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
226 <para id="x_17b">The rules that MQ uses when deciding whether to apply a
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
227 patch are as follows.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
228 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
229 <listitem><para id="x_17c">A patch that has no guards is always
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
230 applied.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
231 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
232 <listitem><para id="x_17d">If the patch has any negative guard that matches
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
233 any currently selected guard, the patch is skipped.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
234 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
235 <listitem><para id="x_17e">If the patch has any positive guard that matches
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
236 any currently selected guard, the patch is applied.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
237 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
238 <listitem><para id="x_17f">If the patch has positive or negative guards,
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
239 but none matches any currently selected guard, the patch is
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
240 skipped.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
241 </listitem></itemizedlist>
105
ecacb6b4c9fd Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents: 104
diff changeset
242
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
243 </sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
244 <sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
245 <title>Trimming the work environment</title>
105
ecacb6b4c9fd Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents: 104
diff changeset
246
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
247 <para id="x_180">In working on the device driver I mentioned earlier, I don't
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
248 apply the patches to a normal Linux kernel tree. Instead, I use
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
249 a repository that contains only a snapshot of the source files
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
250 and headers that are relevant to Infiniband development. This
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
251 repository is 1% the size of a kernel repository, so it's easier
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
252 to work with.</para>
105
ecacb6b4c9fd Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents: 104
diff changeset
253
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
254 <para id="x_181">I then choose a <quote>base</quote> version on top of which
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
255 the patches are applied. This is a snapshot of the Linux kernel
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
256 tree as of a revision of my choosing. When I take the snapshot,
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
257 I record the changeset ID from the kernel repository in the
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
258 commit message. Since the snapshot preserves the
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
259 <quote>shape</quote> and content of the relevant parts of the
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
260 kernel tree, I can apply my patches on top of either my tiny
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
261 repository or a normal kernel tree.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
262
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
263 <para id="x_182">Normally, the base tree atop which the patches apply should
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
264 be a snapshot of a very recent upstream tree. This best
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
265 facilitates the development of patches that can easily be
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
266 submitted upstream with few or no modifications.</para>
105
ecacb6b4c9fd Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents: 104
diff changeset
267
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
268 </sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
269 <sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
270 <title>Dividing up the <filename role="special">series</filename>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
271 file</title>
105
ecacb6b4c9fd Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents: 104
diff changeset
272
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
273 <para id="x_183">I categorise the patches in the <filename
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
274 role="special">series</filename> file into a number of logical
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
275 groups. Each section of like patches begins with a block of
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
276 comments that describes the purpose of the patches that
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
277 follow.</para>
105
ecacb6b4c9fd Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents: 104
diff changeset
278
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
279 <para id="x_184">The sequence of patch groups that I maintain follows. The
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
280 ordering of these groups is important; I'll describe why after I
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
281 introduce the groups.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
282 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
283 <listitem><para id="x_185">The <quote>accepted</quote> group. Patches that
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
284 the development team has submitted to the maintainer of the
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
285 Infiniband subsystem, and which he has accepted, but which
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
286 are not present in the snapshot that the tiny repository is
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
287 based on. These are <quote>read only</quote> patches,
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
288 present only to transform the tree into a similar state as
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
289 it is in the upstream maintainer's repository.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
290 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
291 <listitem><para id="x_186">The <quote>rework</quote> group. Patches that I
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
292 have submitted, but that the upstream maintainer has
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
293 requested modifications to before he will accept
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
294 them.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
295 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
296 <listitem><para id="x_187">The <quote>pending</quote> group. Patches that
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
297 I have not yet submitted to the upstream maintainer, but
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
298 which we have finished working on. These will be <quote>read
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
299 only</quote> for a while. If the upstream maintainer
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
300 accepts them upon submission, I'll move them to the end of
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
301 the <quote>accepted</quote> group. If he requests that I
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
302 modify any, I'll move them to the beginning of the
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
303 <quote>rework</quote> group.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
304 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
305 <listitem><para id="x_188">The <quote>in progress</quote> group. Patches
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
306 that are actively being developed, and should not be
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
307 submitted anywhere yet.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
308 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
309 <listitem><para id="x_189">The <quote>backport</quote> group. Patches that
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
310 adapt the source tree to older versions of the kernel
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
311 tree.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
312 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
313 <listitem><para id="x_18a">The <quote>do not ship</quote> group. Patches
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
314 that for some reason should never be submitted upstream.
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
315 For example, one such patch might change embedded driver
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
316 identification strings to make it easier to distinguish, in
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
317 the field, between an out-of-tree version of the driver and
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
318 a version shipped by a distribution vendor.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
319 </listitem></itemizedlist>
105
ecacb6b4c9fd Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents: 104
diff changeset
320
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
321 <para id="x_18b">Now to return to the reasons for ordering groups of patches
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
322 in this way. We would like the lowest patches in the stack to
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
323 be as stable as possible, so that we will not need to rework
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
324 higher patches due to changes in context. Putting patches that
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
325 will never be changed first in the <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
326 role="special">series</filename> file serves this
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
327 purpose.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
328
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
329 <para id="x_18c">We would also like the patches that we know we'll need to
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
330 modify to be applied on top of a source tree that resembles the
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
331 upstream tree as closely as possible. This is why we keep
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
332 accepted patches around for a while.</para>
105
ecacb6b4c9fd Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents: 104
diff changeset
333
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
334 <para id="x_18d">The <quote>backport</quote> and <quote>do not ship</quote>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
335 patches float at the end of the <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
336 role="special">series</filename> file. The backport patches
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
337 must be applied on top of all other patches, and the <quote>do
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
338 not ship</quote> patches might as well stay out of harm's
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
339 way.</para>
105
ecacb6b4c9fd Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents: 104
diff changeset
340
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
341 </sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
342 <sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
343 <title>Maintaining the patch series</title>
106
9cbc5d0db542 Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents: 105
diff changeset
344
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
345 <para id="x_18e">In my work, I use a number of guards to control which
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
346 patches are to be applied.</para>
106
9cbc5d0db542 Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents: 105
diff changeset
347
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
348 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
349 <listitem><para id="x_18f"><quote>Accepted</quote> patches are guarded with
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
350 <literal>accepted</literal>. I enable this guard most of
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
351 the time. When I'm applying the patches on top of a tree
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
352 where the patches are already present, I can turn this patch
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
353 off, and the patches that follow it will apply
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
354 cleanly.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
355 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
356 <listitem><para id="x_190">Patches that are <quote>finished</quote>, but
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
357 not yet submitted, have no guards. If I'm applying the
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
358 patch stack to a copy of the upstream tree, I don't need to
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
359 enable any guards in order to get a reasonably safe source
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
360 tree.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
361 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
362 <listitem><para id="x_191">Those patches that need reworking before being
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
363 resubmitted are guarded with
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
364 <literal>rework</literal>.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
365 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
366 <listitem><para id="x_192">For those patches that are still under
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
367 development, I use <literal>devel</literal>.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
368 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
369 <listitem><para id="x_193">A backport patch may have several guards, one
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
370 for each version of the kernel to which it applies. For
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
371 example, a patch that backports a piece of code to 2.6.9
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
372 will have a <literal>2.6.9</literal> guard.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
373 </listitem></itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
374 <para id="x_194">This variety of guards gives me considerable flexibility in
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
375 determining what kind of source tree I want to end up with. For
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
376 most situations, the selection of appropriate guards is
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
377 automated during the build process, but I can manually tune the
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
378 guards to use for less common circumstances.</para>
106
9cbc5d0db542 Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents: 105
diff changeset
379
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
380 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
381 <title>The art of writing backport patches</title>
106
9cbc5d0db542 Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents: 105
diff changeset
382
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
383 <para id="x_195">Using MQ, writing a backport patch is a simple process.
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
384 All such a patch has to do is modify a piece of code that uses
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
385 a kernel feature not present in the older version of the
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
386 kernel, so that the driver continues to work correctly under
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
387 that older version.</para>
106
9cbc5d0db542 Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents: 105
diff changeset
388
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
389 <para id="x_196">A useful goal when writing a good backport patch is to
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
390 make your code look as if it was written for the older version
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
391 of the kernel you're targeting. The less obtrusive the patch,
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
392 the easier it will be to understand and maintain. If you're
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
393 writing a collection of backport patches to avoid the
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
394 <quote>rat's nest</quote> effect of lots of
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
395 <literal>#ifdef</literal>s (hunks of source code that are only
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
396 used conditionally) in your code, don't introduce
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
397 version-dependent <literal>#ifdef</literal>s into the patches.
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
398 Instead, write several patches, each of which makes
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
399 unconditional changes, and control their application using
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
400 guards.</para>
106
9cbc5d0db542 Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents: 105
diff changeset
401
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
402 <para id="x_197">There are two reasons to divide backport patches into a
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
403 distinct group, away from the <quote>regular</quote> patches
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
404 whose effects they modify. The first is that intermingling the
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
405 two makes it more difficult to use a tool like the <literal
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
406 role="hg-ext">patchbomb</literal> extension to automate the
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
407 process of submitting the patches to an upstream maintainer.
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
408 The second is that a backport patch could perturb the context
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
409 in which a subsequent regular patch is applied, making it
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
410 impossible to apply the regular patch cleanly
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
411 <emphasis>without</emphasis> the earlier backport patch
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
412 already being applied.</para>
106
9cbc5d0db542 Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents: 105
diff changeset
413
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
414 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
415 </sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
416 <sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
417 <title>Useful tips for developing with MQ</title>
106
9cbc5d0db542 Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents: 105
diff changeset
418
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
419 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
420 <title>Organising patches in directories</title>
106
9cbc5d0db542 Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents: 105
diff changeset
421
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
422 <para id="x_198">If you're working on a substantial project with MQ, it's
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
423 not difficult to accumulate a large number of patches. For
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
424 example, I have one patch repository that contains over 250
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
425 patches.</para>
106
9cbc5d0db542 Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents: 105
diff changeset
426
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
427 <para id="x_199">If you can group these patches into separate logical
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
428 categories, you can if you like store them in different
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
429 directories; MQ has no problems with patch names that contain
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
430 path separators.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
431
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
432 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
433 <sect2 id="mq-collab:tips:interdiff">
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
434 <title>Viewing the history of a patch</title>
106
9cbc5d0db542 Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents: 105
diff changeset
435
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
436 <para id="x_19a">If you're developing a set of patches over a long time,
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
437 it's a good idea to maintain them in a repository, as
691
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 683
diff changeset
438 discussed in <xref linkend="sec:mq:repo"/>. If you do
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
439 so, you'll quickly
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
440 discover that using the <command role="hg-cmd">hg
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
441 diff</command> command to look at the history of changes to
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
442 a patch is unworkable. This is in part because you're looking
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
443 at the second derivative of the real code (a diff of a diff),
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
444 but also because MQ adds noise to the process by modifying
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
445 time stamps and directory names when it updates a
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
446 patch.</para>
106
9cbc5d0db542 Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents: 105
diff changeset
447
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
448 <para id="x_19b">However, you can use the <literal
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
449 role="hg-ext">extdiff</literal> extension, which is bundled
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
450 with Mercurial, to turn a diff of two versions of a patch into
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
451 something readable. To do this, you will need a third-party
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
452 package called <literal role="package">patchutils</literal>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
453 <citation>web:patchutils</citation>. This provides a command
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
454 named <command>interdiff</command>, which shows the
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
455 differences between two diffs as a diff. Used on two versions
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
456 of the same diff, it generates a diff that represents the diff
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
457 from the first to the second version.</para>
106
9cbc5d0db542 Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents: 105
diff changeset
458
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
459 <para id="x_19c">You can enable the <literal
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
460 role="hg-ext">extdiff</literal> extension in the usual way,
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
461 by adding a line to the <literal
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
462 role="rc-extensions">extensions</literal> section of your
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
463 <filename role="special">~/.hgrc</filename>.</para>
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
464 <programlisting>[extensions]
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
465 extdiff =</programlisting>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
466 <para id="x_19d">The <command>interdiff</command> command expects to be
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
467 passed the names of two files, but the <literal
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
468 role="hg-ext">extdiff</literal> extension passes the program
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
469 it runs a pair of directories, each of which can contain an
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
470 arbitrary number of files. We thus need a small program that
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
471 will run <command>interdiff</command> on each pair of files in
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
472 these two directories. This program is available as <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
473 role="special">hg-interdiff</filename> in the <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
474 class="directory">examples</filename> directory of the
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
475 source code repository that accompanies this book. <!--
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
476 &example.hg-interdiff; --></para>
106
9cbc5d0db542 Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents: 105
diff changeset
477
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
478 <para id="x_19e">With the <filename role="special">hg-interdiff</filename>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
479 program in your shell's search path, you can run it as
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
480 follows, from inside an MQ patch directory:</para>
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
481 <programlisting>hg extdiff -p hg-interdiff -r A:B my-change.patch</programlisting>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
482 <para id="x_19f">Since you'll probably want to use this long-winded command
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
483 a lot, you can get <literal role="hg-ext">hgext</literal> to
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
484 make it available as a normal Mercurial command, again by
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
485 editing your <filename
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
486 role="special">~/.hgrc</filename>.</para>
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
487 <programlisting>[extdiff]
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
488 cmd.interdiff = hg-interdiff</programlisting>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
489 <para id="x_1a0">This directs <literal role="hg-ext">hgext</literal> to
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
490 make an <literal>interdiff</literal> command available, so you
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
491 can now shorten the previous invocation of <command
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
492 role="hg-ext-extdiff">extdiff</command> to something a
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
493 little more wieldy.</para>
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
494 <programlisting>hg interdiff -r A:B my-change.patch</programlisting>
105
ecacb6b4c9fd Grouping patches in the series file.
Bryan O'Sullivan <bos@serpentine.com>
parents: 104
diff changeset
495
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
496 <note>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
497 <para id="x_1a1"> The <command>interdiff</command> command works well
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
498 only if the underlying files against which versions of a
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
499 patch are generated remain the same. If you create a patch,
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
500 modify the underlying files, and then regenerate the patch,
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
501 <command>interdiff</command> may not produce useful
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
502 output.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
503 </note>
107
a0d7e11db169 A brief note on interdiff.
Bryan O'Sullivan <bos@serpentine.com>
parents: 106
diff changeset
504
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
505 <para id="x_1a2">The <literal role="hg-ext">extdiff</literal> extension is
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
506 useful for more than merely improving the presentation of MQ
691
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 683
diff changeset
507 patches. To read more about it, go to <xref
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
508 linkend="sec:hgext:extdiff"/>.</para>
239
fe8598eb99c4 Refer to main coverage of extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 238
diff changeset
509
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
510 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
511 </sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
512 </chapter>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
513
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
514 <!--
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
515 local variables:
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
516 sgml-parent-document: ("00book.xml" "book" "chapter")
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
517 end:
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
518 -->