hgbook
view fr/ch12-mq.xml @ 979:64475a75365b
Merged from rpelisse
| author | Jean-Marie Clément <JeanMarieClement@web.de> |
|---|---|
| date | Fri Sep 04 18:24:06 2009 +0200 (2009-09-04) |
| parents | |
| children | 6f8c48362758 |
line source
1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
3 <chapter>
4 <title>Managing change with Mercurial Queues</title>
5 <para>\label{chap:mq}</para>
7 <sect1>
8 <title>The patch management problem</title>
9 <para>\label{sec:mq:patch-mgmt}</para>
11 <para>Here is a common scenario: you need to install a software package from
12 source, but you find a bug that you must fix in the source before you
13 can start using the package. You make your changes, forget about the
14 package for a while, and a few months later you need to upgrade to a
15 newer version of the package. If the newer version of the package
16 still has the bug, you must extract your fix from the older source
17 tree and apply it against the newer version. This is a tedious task,
18 and it's easy to make mistakes.</para>
20 <para>This is a simple case of the <quote>patch management</quote> problem. You have
21 an <quote>upstream</quote> source tree that you can't change; you need to make
22 some local changes on top of the upstream tree; and you'd like to be
23 able to keep those changes separate, so that you can apply them to
24 newer versions of the upstream source.</para>
26 <para>The patch management problem arises in many situations. Probably the
27 most visible is that a user of an open source software project will
28 contribute a bug fix or new feature to the project's maintainers in the
29 form of a patch.</para>
31 <para>Distributors of operating systems that include open source software
32 often need to make changes to the packages they distribute so that
33 they will build properly in their environments.</para>
35 <para>When you have few changes to maintain, it is easy to manage a single
36 patch using the standard <command>diff</command> and <command>patch</command> programs
37 (see section <xref linkend="sec:mq:patch"/> for a discussion of these tools).
38 Once the number of changes grows, it starts to make sense to maintain
39 patches as discrete <quote>chunks of work,</quote> so that for example a single
40 patch will contain only one bug fix (the patch might modify several
41 files, but it's doing <quote>only one thing</quote>), and you may have a number
42 of such patches for different bugs you need fixed and local changes
43 you require. In this situation, if you submit a bug fix patch to the
44 upstream maintainers of a package and they include your fix in a
45 subsequent release, you can simply drop that single patch when you're
46 updating to the newer release.</para>
48 <para>Maintaining a single patch against an upstream tree is a little
49 tedious and error-prone, but not difficult. However, the complexity
50 of the problem grows rapidly as the number of patches you have to
51 maintain increases. With more than a tiny number of patches in hand,
52 understanding which ones you have applied and maintaining them moves
53 from messy to overwhelming.</para>
55 <para>Fortunately, Mercurial includes a powerful extension, Mercurial Queues
56 (or simply <quote>MQ</quote>), that massively simplifies the patch management
57 problem.
58 </para>
60 </sect1>
61 <sect1>
62 <title>The prehistory of Mercurial Queues</title>
63 <para>\label{sec:mq:history}
64 </para>
66 <para>During the late 1990s, several Linux kernel developers started to
67 maintain <quote>patch series</quote> that modified the behaviour of the Linux
68 kernel. Some of these series were focused on stability, some on
69 feature coverage, and others were more speculative.
70 </para>
72 <para>The sizes of these patch series grew rapidly. In 2002, Andrew Morton
73 published some shell scripts he had been using to automate the task of
74 managing his patch queues. Andrew was successfully using these
75 scripts to manage hundreds (sometimes thousands) of patches on top of
76 the Linux kernel.
77 </para>
79 <sect2>
80 <title>A patchwork quilt</title>
81 <para>\label{sec:mq:quilt}
82 </para>
84 <para>In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the
85 approach of Andrew's scripts and published a tool called <quote>patchwork
86 quilt</quote> <citation>web:quilt</citation>, or simply <quote>quilt</quote>
87 (see <citation>gruenbacher:2005</citation> for a paper describing it). Because
88 quilt substantially automated patch management, it rapidly gained a
89 large following among open source software developers.
90 </para>
92 <para>Quilt manages a <emphasis>stack of patches</emphasis> on top of a directory tree.
93 To begin, you tell quilt to manage a directory tree, and tell it which
94 files you want to manage; it stores away the names and contents of
95 those files. To fix a bug, you create a new patch (using a single
96 command), edit the files you need to fix, then <quote>refresh</quote> the patch.
97 </para>
99 <para>The refresh step causes quilt to scan the directory tree; it updates
100 the patch with all of the changes you have made. You can create
101 another patch on top of the first, which will track the changes
102 required to modify the tree from <quote>tree with one patch applied</quote> to
103 <quote>tree with two patches applied</quote>.
104 </para>
106 <para>You can <emphasis>change</emphasis> which patches are applied to the tree. If you
107 <quote>pop</quote> a patch, the changes made by that patch will vanish from the
108 directory tree. Quilt remembers which patches you have popped,
109 though, so you can <quote>push</quote> a popped patch again, and the directory
110 tree will be restored to contain the modifications in the patch. Most
111 importantly, you can run the <quote>refresh</quote> command at any time, and the
112 topmost applied patch will be updated. This means that you can, at
113 any time, change both which patches are applied and what
114 modifications those patches make.
115 </para>
117 <para>Quilt knows nothing about revision control tools, so it works equally
118 well on top of an unpacked tarball or a Subversion working copy.
119 </para>
121 </sect2>
122 <sect2>
123 <title>From patchwork quilt to Mercurial Queues</title>
124 <para>\label{sec:mq:quilt-mq}
125 </para>
127 <para>In mid-2005, Chris Mason took the features of quilt and wrote an
128 extension that he called Mercurial Queues, which added quilt-like
129 behaviour to Mercurial.
130 </para>
132 <para>The key difference between quilt and MQ is that quilt knows nothing
133 about revision control systems, while MQ is <emphasis>integrated</emphasis> into
134 Mercurial. Each patch that you push is represented as a Mercurial
135 changeset. Pop a patch, and the changeset goes away.
136 </para>
138 <para>Because quilt does not care about revision control tools, it is still
139 a tremendously useful piece of software to know about for situations
140 where you cannot use Mercurial and MQ.
141 </para>
143 </sect2>
144 </sect1>
145 <sect1>
146 <title>The huge advantage of MQ</title>
148 <para>I cannot overstate the value that MQ offers through the unification of
149 patches and revision control.
150 </para>
152 <para>A major reason that patches have persisted in the free software and
153 open source world&emdash;in spite of the availability of increasingly
154 capable revision control tools over the years&emdash;is the <emphasis>agility</emphasis>
155 they offer.
156 </para>
158 <para>Traditional revision control tools make a permanent, irreversible
159 record of everything that you do. While this has great value, it's
160 also somewhat stifling. If you want to perform a wild-eyed
161 experiment, you have to be careful in how you go about it, or you risk
162 leaving unneeded&emdash;or worse, misleading or destabilising&emdash;traces of
163 your missteps and errors in the permanent revision record.
164 </para>
166 <para>By contrast, MQ's marriage of distributed revision control with
167 patches makes it much easier to isolate your work. Your patches live
168 on top of normal revision history, and you can make them disappear or
169 reappear at will. If you don't like a patch, you can drop it. If a
170 patch isn't quite as you want it to be, simply fix it&emdash;as many times
171 as you need to, until you have refined it into the form you desire.
172 </para>
174 <para>As an example, the integration of patches with revision control makes
175 understanding patches and debugging their effects&emdash;and their
176 interplay with the code they're based on&emdash;<emphasis>enormously</emphasis> easier.
177 Since every applied patch has an associated changeset, you can use
178 <command role="hg-cmd">hg log <emphasis>filename</emphasis></command> to see which changesets and patches
179 affected a file. You can use the <literal role="hg-ext">bisect</literal> command to
180 binary-search through all changesets and applied patches to see where
181 a bug got introduced or fixed. You can use the <command role="hg-cmd">hg annotate</command>
182 command to see which changeset or patch modified a particular line of
183 a source file. And so on.
184 </para>
186 </sect1>
187 <sect1>
188 <title>Understanding patches</title>
189 <para>\label{sec:mq:patch}
190 </para>
192 <para>Because MQ doesn't hide its patch-oriented nature, it is helpful to
193 understand what patches are, and a little about the tools that work
194 with them.
195 </para>
197 <para>The traditional Unix <command>diff</command> command compares two files, and
198 prints a list of differences between them. The <command>patch</command> command
199 understands these differences as <emphasis>modifications</emphasis> to make to a
200 file. Take a look at figure <xref linkend="ex:mq:diff"/> for a simple example of
201 these commands in action.
202 </para>
204 <informalfigure>
205 <para> <!-- &interaction.mq.dodiff.diff; -->
206 <caption><para>Simple uses of the <command>diff</para></caption> and \command{patch</command> commands}
207 \label{ex:mq:diff}
208 </para>
209 </informalfigure>
211 <para>The type of file that <command>diff</command> generates (and <command>patch</command>
212 takes as input) is called a <quote>patch</quote> or a <quote>diff</quote>; there is no
213 difference between a patch and a diff. (We'll use the term <quote>patch</quote>,
214 since it's more commonly used.)
215 </para>
217 <para>A patch file can start with arbitrary text; the <command>patch</command>
218 command ignores this text, but MQ uses it as the commit message when
219 creating changesets. To find the beginning of the patch content,
220 <command>patch</command> searches for the first line that starts with the
221 string <quote><literal>diff -</literal></quote>.
222 </para>
224 <para>MQ works with <emphasis>unified</emphasis> diffs (<command>patch</command> can accept several
225 other diff formats, but MQ doesn't). A unified diff contains two
226 kinds of header. The <emphasis>file header</emphasis> describes the file being
227 modified; it contains the name of the file to modify. When
228 <command>patch</command> sees a new file header, it looks for a file with that
229 name to start modifying.
230 </para>
232 <para>After the file header comes a series of <emphasis>hunks</emphasis>. Each hunk
233 starts with a header; this identifies the range of line numbers within
234 the file that the hunk should modify. Following the header, a hunk
235 starts and ends with a few (usually three) lines of text from the
236 unmodified file; these are called the <emphasis>context</emphasis> for the hunk. If
237 there's only a small amount of context between successive hunks,
238 <command>diff</command> doesn't print a new hunk header; it just runs the hunks
239 together, with a few lines of context between modifications.
240 </para>
242 <para>Each line of context begins with a space character. Within the hunk,
243 a line that begins with <quote><literal>-</literal></quote> means <quote>remove this line,</quote>
244 while a line that begins with <quote><literal>+</literal></quote> means <quote>insert this
245 line.</quote> For example, a line that is modified is represented by one
246 deletion and one insertion.
247 </para>
249 <para>We will return to some of the more subtle aspects of patches later (in
250 section <xref linkend="sec:mq:adv-patch"/>), but you should have enough information
251 now to use MQ.
252 </para>
254 </sect1>
255 <sect1>
256 <title>Getting started with Mercurial Queues</title>
257 <para>\label{sec:mq:start}
258 </para>
260 <para>Because MQ is implemented as an extension, you must explicitly enable
261 before you can use it. (You don't need to download anything; MQ ships
262 with the standard Mercurial distribution.) To enable MQ, edit your
263 <filename role="home">~/.hgrc</filename> file, and add the lines in figure <xref linkend="ex:mq:config"/>.
264 </para>
266 <informalfigure>
267 <programlisting>
268 <para> [extensions]
269 hgext.mq =
270 </para>
271 </programlisting>
272 <para> \label{ex:mq:config}
273 <caption><para>Contents to add to <filename role="home">~/.hgrc</para></caption> to enable the MQ extension</filename>
274 </para>
275 </informalfigure>
277 <para>Once the extension is enabled, it will make a number of new commands
278 available. To verify that the extension is working, you can use
279 <command role="hg-cmd">hg help</command> to see if the <command role="hg-ext-mq">qinit</command> command is now available; see
280 the example in figure <xref linkend="ex:mq:enabled"/>.
281 </para>
283 <informalfigure>
284 <para> <!-- &interaction.mq.qinit-help.help; -->
285 <caption><para>How to verify that MQ is enabled</para></caption>
286 \label{ex:mq:enabled}
287 </para>
288 </informalfigure>
290 <para>You can use MQ with <emphasis>any</emphasis> Mercurial repository, and its commands
291 only operate within that repository. To get started, simply prepare
292 the repository using the <command role="hg-ext-mq">qinit</command> command (see
293 figure <xref linkend="ex:mq:qinit"/>). This command creates an empty directory
294 called <filename role="special" class="directory">.hg/patches</filename>, where MQ will keep its metadata. As
295 with many Mercurial commands, the <command role="hg-ext-mq">qinit</command> command prints nothing
296 if it succeeds.
297 </para>
299 <informalfigure>
300 <para> <!-- &interaction.mq.tutorial.qinit; -->
301 <caption><para>Preparing a repository for use with MQ</para></caption>
302 \label{ex:mq:qinit}
303 </para>
304 </informalfigure>
306 <informalfigure>
307 <para> <!-- &interaction.mq.tutorial.qnew; -->
308 <caption><para>Creating a new patch</para></caption>
309 \label{ex:mq:qnew}
310 </para>
311 </informalfigure>
313 <sect2>
314 <title>Creating a new patch</title>
316 <para>To begin work on a new patch, use the <command role="hg-ext-mq">qnew</command> command. This
317 command takes one argument, the name of the patch to create. MQ will
318 use this as the name of an actual file in the <filename role="special" class="directory">.hg/patches</filename>
319 directory, as you can see in figure <xref linkend="ex:mq:qnew"/>.
320 </para>
322 <para>Also newly present in the <filename role="special" class="directory">.hg/patches</filename> directory are two
323 other files, <filename role="special">series</filename> and <filename role="special">status</filename>. The
324 <filename role="special">series</filename> file lists all of the patches that MQ knows about
325 for this repository, with one patch per line. Mercurial uses the
326 <filename role="special">status</filename> file for internal book-keeping; it tracks all of the
327 patches that MQ has <emphasis>applied</emphasis> in this repository.
328 </para>
330 <note>
331 <para> You may sometimes want to edit the <filename role="special">series</filename> file by hand;
332 for example, to change the sequence in which some patches are
333 applied. However, manually editing the <filename role="special">status</filename> file is
334 almost always a bad idea, as it's easy to corrupt MQ's idea of what
335 is happening.
336 </para>
337 </note>
339 <para>Once you have created your new patch, you can edit files in the
340 working directory as you usually would. All of the normal Mercurial
341 commands, such as <command role="hg-cmd">hg diff</command> and <command role="hg-cmd">hg annotate</command>, work exactly as
342 they did before.
343 </para>
345 </sect2>
346 <sect2>
347 <title>Refreshing a patch</title>
349 <para>When you reach a point where you want to save your work, use the
350 <command role="hg-ext-mq">qrefresh</command> command (figure <xref linkend="ex:mq:qnew"/>) to update the patch
351 you are working on. This command folds the changes you have made in
352 the working directory into your patch, and updates its corresponding
353 changeset to contain those changes.
354 </para>
356 <informalfigure>
357 <para> <!-- &interaction.mq.tutorial.qrefresh; -->
358 <caption><para>Refreshing a patch</para></caption>
359 \label{ex:mq:qrefresh}
360 </para>
361 </informalfigure>
363 <para>You can run <command role="hg-ext-mq">qrefresh</command> as often as you like, so it's a good way
364 to <quote>checkpoint</quote> your work. Refresh your patch at an opportune
365 time; try an experiment; and if the experiment doesn't work out,
366 <command role="hg-cmd">hg revert</command> your modifications back to the last time you refreshed.
367 </para>
369 <informalfigure>
370 <para> <!-- &interaction.mq.tutorial.qrefresh2; -->
371 <caption><para>Refresh a patch many times to accumulate changes</para></caption>
372 \label{ex:mq:qrefresh2}
373 </para>
374 </informalfigure>
376 </sect2>
377 <sect2>
378 <title>Stacking and tracking patches</title>
380 <para>Once you have finished working on a patch, or need to work on another,
381 you can use the <command role="hg-ext-mq">qnew</command> command again to create a new patch.
382 Mercurial will apply this patch on top of your existing patch. See
383 figure <xref linkend="ex:mq:qnew2"/> for an example. Notice that the patch
384 contains the changes in our prior patch as part of its context (you
385 can see this more clearly in the output of <command role="hg-cmd">hg annotate</command>).
386 </para>
388 <informalfigure>
389 <para> <!-- &interaction.mq.tutorial.qnew2; -->
390 <caption><para>Stacking a second patch on top of the first</para></caption>
391 \label{ex:mq:qnew2}
392 </para>
393 </informalfigure>
395 <para>So far, with the exception of <command role="hg-ext-mq">qnew</command> and <command role="hg-ext-mq">qrefresh</command>, we've
396 been careful to only use regular Mercurial commands. However, MQ
397 provides many commands that are easier to use when you are thinking
398 about patches, as illustrated in figure <xref linkend="ex:mq:qseries"/>:
399 </para>
401 <itemizedlist>
402 <listitem><para>The <command role="hg-ext-mq">qseries</command> command lists every patch that MQ knows
403 about in this repository, from oldest to newest (most recently
404 <emphasis>created</emphasis>).
405 </para>
406 </listitem>
407 <listitem><para>The <command role="hg-ext-mq">qapplied</command> command lists every patch that MQ has
408 <emphasis>applied</emphasis> in this repository, again from oldest to newest (most
409 recently applied).
410 </para>
411 </listitem></itemizedlist>
413 <informalfigure>
414 <para> <!-- &interaction.mq.tutorial.qseries; -->
415 \caption{Understanding the patch stack with <command role="hg-ext-mq">qseries</command> and
416 <command role="hg-ext-mq">qapplied</command>}
417 \label{ex:mq:qseries}
418 </para>
419 </informalfigure>
421 </sect2>
422 <sect2>
423 <title>Manipulating the patch stack</title>
425 <para>The previous discussion implied that there must be a difference
426 between <quote>known</quote> and <quote>applied</quote> patches, and there is. MQ can
427 manage a patch without it being applied in the repository.
428 </para>
430 <para>An <emphasis>applied</emphasis> patch has a corresponding changeset in the
431 repository, and the effects of the patch and changeset are visible in
432 the working directory. You can undo the application of a patch using
433 the <command role="hg-ext-mq">qpop</command> command. MQ still <emphasis>knows about</emphasis>, or manages, a
434 popped patch, but the patch no longer has a corresponding changeset in
435 the repository, and the working directory does not contain the changes
436 made by the patch. Figure <xref linkend="fig:mq:stack"/> illustrates the
437 difference between applied and tracked patches.
438 </para>
440 <informalfigure>
442 <para> <mediaobject><imageobject><imagedata fileref="mq-stack"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject>
443 <caption><para>Applied and unapplied patches in the MQ patch stack</para></caption>
444 \label{fig:mq:stack}
445 </para>
446 </informalfigure>
448 <para>You can reapply an unapplied, or popped, patch using the <command role="hg-ext-mq">qpush</command>
449 command. This creates a new changeset to correspond to the patch, and
450 the patch's changes once again become present in the working
451 directory. See figure <xref linkend="ex:mq:qpop"/> for examples of <command role="hg-ext-mq">qpop</command>
452 and <command role="hg-ext-mq">qpush</command> in action. Notice that once we have popped a patch
453 or two patches, the output of <command role="hg-ext-mq">qseries</command> remains the same, while
454 that of <command role="hg-ext-mq">qapplied</command> has changed.
455 </para>
457 <informalfigure>
458 <para> <!-- &interaction.mq.tutorial.qpop; -->
459 <caption><para>Modifying the stack of applied patches</para></caption>
460 \label{ex:mq:qpop}
461 </para>
462 </informalfigure>
464 </sect2>
465 <sect2>
466 <title>Pushing and popping many patches</title>
468 <para>While <command role="hg-ext-mq">qpush</command> and <command role="hg-ext-mq">qpop</command> each operate on a single patch at
469 a time by default, you can push and pop many patches in one go. The
470 <option role="hg-ext-mq-cmd-qpush-opt">-a</option> option to <command role="hg-ext-mq">qpush</command> causes it to push all
471 unapplied patches, while the <option role="hg-ext-mq-cmd-qpop-opt">-a</option> option to <command role="hg-ext-mq">qpop</command>
472 causes it to pop all applied patches. (For some more ways to push and
473 pop many patches, see section <xref linkend="sec:mq:perf"/> below.)
474 </para>
476 <informalfigure>
477 <para> <!-- &interaction.mq.tutorial.qpush-a; -->
478 <caption><para>Pushing all unapplied patches</para></caption>
479 \label{ex:mq:qpush-a}
480 </para>
481 </informalfigure>
483 </sect2>
484 <sect2>
485 <title>Safety checks, and overriding them</title>
487 <para>Several MQ commands check the working directory before they do
488 anything, and fail if they find any modifications. They do this to
489 ensure that you won't lose any changes that you have made, but not yet
490 incorporated into a patch. Figure <xref linkend="ex:mq:add"/> illustrates this;
491 the <command role="hg-ext-mq">qnew</command> command will not create a new patch if there are
492 outstanding changes, caused in this case by the <command role="hg-cmd">hg add</command> of
493 <filename>file3</filename>.
494 </para>
496 <informalfigure>
497 <para> <!-- &interaction.mq.tutorial.add; -->
498 <caption><para>Forcibly creating a patch</para></caption>
499 \label{ex:mq:add}
500 </para>
501 </informalfigure>
503 <para>Commands that check the working directory all take an <quote>I know what
504 I'm doing</quote> option, which is always named <option>-f</option>. The exact
505 meaning of <option>-f</option> depends on the command. For example,
506 <command role="hg-cmd">hg qnew <option role="hg-ext-mq-cmd-qnew-opt">-f</option></command> will incorporate any outstanding
507 changes into the new patch it creates, but
508 <command role="hg-cmd">hg qpop <option role="hg-ext-mq-cmd-qpop-opt">-f</option></command> will revert modifications to any
509 files affected by the patch that it is popping. Be sure to read the
510 documentation for a command's <option>-f</option> option before you use it!
511 </para>
513 </sect2>
514 <sect2>
515 <title>Working on several patches at once</title>
517 <para>The <command role="hg-ext-mq">qrefresh</command> command always refreshes the <emphasis>topmost</emphasis>
518 applied patch. This means that you can suspend work on one patch (by
519 refreshing it), pop or push to make a different patch the top, and
520 work on <emphasis>that</emphasis> patch for a while.
521 </para>
523 <para>Here's an example that illustrates how you can use this ability.
524 Let's say you're developing a new feature as two patches. The first
525 is a change to the core of your software, and the second&emdash;layered on
526 top of the first&emdash;changes the user interface to use the code you just
527 added to the core. If you notice a bug in the core while you're
528 working on the UI patch, it's easy to fix the core. Simply
529 <command role="hg-ext-mq">qrefresh</command> the UI patch to save your in-progress changes, and
530 <command role="hg-ext-mq">qpop</command> down to the core patch. Fix the core bug,
531 <command role="hg-ext-mq">qrefresh</command> the core patch, and <command role="hg-ext-mq">qpush</command> back to the UI
532 patch to continue where you left off.
533 </para>
535 </sect2>
536 </sect1>
537 <sect1>
538 <title>More about patches</title>
539 <para>\label{sec:mq:adv-patch}
540 </para>
542 <para>MQ uses the GNU <command>patch</command> command to apply patches, so it's
543 helpful to know a few more detailed aspects of how <command>patch</command>
544 works, and about patches themselves.
545 </para>
547 <sect2>
548 <title>The strip count</title>
550 <para>If you look at the file headers in a patch, you will notice that the
551 pathnames usually have an extra component on the front that isn't
552 present in the actual path name. This is a holdover from the way that
553 people used to generate patches (people still do this, but it's
554 somewhat rare with modern revision control tools).
555 </para>
557 <para>Alice would unpack a tarball, edit her files, then decide that she
558 wanted to create a patch. So she'd rename her working directory,
559 unpack the tarball again (hence the need for the rename), and use the
560 <option role="cmd-opt-diff">-r</option> and <option role="cmd-opt-diff">-N</option> options to <command>diff</command> to
561 recursively generate a patch between the unmodified directory and the
562 modified one. The result would be that the name of the unmodified
563 directory would be at the front of the left-hand path in every file
564 header, and the name of the modified directory would be at the front
565 of the right-hand path.
566 </para>
568 <para>Since someone receiving a patch from the Alices of the net would be
569 unlikely to have unmodified and modified directories with exactly the
570 same names, the <command>patch</command> command has a <option role="cmd-opt-patch">-p</option>
571 option that indicates the number of leading path name components to
572 strip when trying to apply a patch. This number is called the
573 <emphasis>strip count</emphasis>.
574 </para>
576 <para>An option of <quote><literal>-p1</literal></quote> means <quote>use a strip count of one</quote>. If
577 <command>patch</command> sees a file name <filename>foo/bar/baz</filename> in a file
578 header, it will strip <filename>foo</filename> and try to patch a file named
579 <filename>bar/baz</filename>. (Strictly speaking, the strip count refers to the
580 number of <emphasis>path separators</emphasis> (and the components that go with them
581 ) to strip. A strip count of one will turn <filename>foo/bar</filename> into
582 <filename>bar</filename>, but <filename>/foo/bar</filename> (notice the extra leading
583 slash) into <filename>foo/bar</filename>.)
584 </para>
586 <para>The <quote>standard</quote> strip count for patches is one; almost all patches
587 contain one leading path name component that needs to be stripped.
588 Mercurial's <command role="hg-cmd">hg diff</command> command generates path names in this form,
589 and the <command role="hg-cmd">hg import</command> command and MQ expect patches to have a strip
590 count of one.
591 </para>
593 <para>If you receive a patch from someone that you want to add to your patch
594 queue, and the patch needs a strip count other than one, you cannot
595 just <command role="hg-ext-mq">qimport</command> the patch, because <command role="hg-ext-mq">qimport</command> does not yet
596 have a <literal>-p</literal> option (see <ulink role="hg-bug" url="http://www.selenic.com/mercurial/bts/issue311">issue 311</ulink>). Your best bet is to
597 <command role="hg-ext-mq">qnew</command> a patch of your own, then use <command>patch -p<emphasis>N</emphasis></command>
598 to apply their patch, followed by <command role="hg-cmd">hg addremove</command> to pick up any
599 files added or removed by the patch, followed by <command role="hg-ext-mq">qrefresh</command>.
600 This complexity may become unnecessary; see <ulink role="hg-bug" url="http://www.selenic.com/mercurial/bts/issue311">issue 311</ulink> for details.
601 </sect2>
602 <sect2>
603 <title>Strategies for applying a patch</title>
604 </para>
606 <para>When <command>patch</command> applies a hunk, it tries a handful of
607 successively less accurate strategies to try to make the hunk apply.
608 This falling-back technique often makes it possible to take a patch
609 that was generated against an old version of a file, and apply it
610 against a newer version of that file.
611 </para>
613 <para>First, <command>patch</command> tries an exact match, where the line numbers,
614 the context, and the text to be modified must apply exactly. If it
615 cannot make an exact match, it tries to find an exact match for the
616 context, without honouring the line numbering information. If this
617 succeeds, it prints a line of output saying that the hunk was applied,
618 but at some <emphasis>offset</emphasis> from the original line number.
619 </para>
621 <para>If a context-only match fails, <command>patch</command> removes the first and
622 last lines of the context, and tries a <emphasis>reduced</emphasis> context-only
623 match. If the hunk with reduced context succeeds, it prints a message
624 saying that it applied the hunk with a <emphasis>fuzz factor</emphasis> (the number
625 after the fuzz factor indicates how many lines of context
626 <command>patch</command> had to trim before the patch applied).
627 </para>
629 <para>When neither of these techniques works, <command>patch</command> prints a
630 message saying that the hunk in question was rejected. It saves
631 rejected hunks (also simply called <quote>rejects</quote>) to a file with the
632 same name, and an added <filename role="special">.rej</filename> extension. It also saves an
633 unmodified copy of the file with a <filename role="special">.orig</filename> extension; the
634 copy of the file without any extensions will contain any changes made
635 by hunks that <emphasis>did</emphasis> apply cleanly. If you have a patch that
636 modifies <filename>foo</filename> with six hunks, and one of them fails to
637 apply, you will have: an unmodified <filename>foo.orig</filename>, a
638 <filename>foo.rej</filename> containing one hunk, and <filename>foo</filename>, containing
639 the changes made by the five successful hunks.
640 </para>
642 </sect2>
643 <sect2>
644 <title>Some quirks of patch representation</title>
646 <para>There are a few useful things to know about how <command>patch</command> works
647 with files.
648 </para>
649 <itemizedlist>
650 <listitem><para>This should already be obvious, but <command>patch</command> cannot
651 handle binary files.
652 </para>
653 </listitem>
654 <listitem><para>Neither does it care about the executable bit; it creates new
655 files as readable, but not executable.
656 </para>
657 </listitem>
658 <listitem><para><command>patch</command> treats the removal of a file as a diff between
659 the file to be removed and the empty file. So your idea of <quote>I
660 deleted this file</quote> looks like <quote>every line of this file was
661 deleted</quote> in a patch.
662 </para>
663 </listitem>
664 <listitem><para>It treats the addition of a file as a diff between the empty
665 file and the file to be added. So in a patch, your idea of <quote>I
666 added this file</quote> looks like <quote>every line of this file was added</quote>.
667 </para>
668 </listitem>
669 <listitem><para>It treats a renamed file as the removal of the old name, and the
670 addition of the new name. This means that renamed files have a big
671 footprint in patches. (Note also that Mercurial does not currently
672 try to infer when files have been renamed or copied in a patch.)
673 </para>
674 </listitem>
675 <listitem><para><command>patch</command> cannot represent empty files, so you cannot use
676 a patch to represent the notion <quote>I added this empty file to the
677 tree</quote>.
678 </para>
679 </listitem></itemizedlist>
680 </sect2>
681 <sect2>
682 <title>Beware the fuzz</title>
684 <para>While applying a hunk at an offset, or with a fuzz factor, will often
685 be completely successful, these inexact techniques naturally leave
686 open the possibility of corrupting the patched file. The most common
687 cases typically involve applying a patch twice, or at an incorrect
688 location in the file. If <command>patch</command> or <command role="hg-ext-mq">qpush</command> ever
689 mentions an offset or fuzz factor, you should make sure that the
690 modified files are correct afterwards.
691 </para>
693 <para>It's often a good idea to refresh a patch that has applied with an
694 offset or fuzz factor; refreshing the patch generates new context
695 information that will make it apply cleanly. I say <quote>often,</quote> not
696 <quote>always,</quote> because sometimes refreshing a patch will make it fail to
697 apply against a different revision of the underlying files. In some
698 cases, such as when you're maintaining a patch that must sit on top of
699 multiple versions of a source tree, it's acceptable to have a patch
700 apply with some fuzz, provided you've verified the results of the
701 patching process in such cases.
702 </para>
704 </sect2>
705 <sect2>
706 <title>Handling rejection</title>
708 <para>If <command role="hg-ext-mq">qpush</command> fails to apply a patch, it will print an error
709 message and exit. If it has left <filename role="special">.rej</filename> files behind, it is
710 usually best to fix up the rejected hunks before you push more patches
711 or do any further work.
712 </para>
714 <para>If your patch <emphasis>used to</emphasis> apply cleanly, and no longer does because
715 you've changed the underlying code that your patches are based on,
716 Mercurial Queues can help; see section <xref linkend="sec:mq:merge"/> for details.
717 </para>
719 <para>Unfortunately, there aren't any great techniques for dealing with
720 rejected hunks. Most often, you'll need to view the <filename role="special">.rej</filename>
721 file and edit the target file, applying the rejected hunks by hand.
722 </para>
724 <para>If you're feeling adventurous, Neil Brown, a Linux kernel hacker,
725 wrote a tool called <command>wiggle</command> <citation>web:wiggle</citation>, which is more
726 vigorous than <command>patch</command> in its attempts to make a patch apply.
727 </para>
729 <para>Another Linux kernel hacker, Chris Mason (the author of Mercurial
730 Queues), wrote a similar tool called
731 <command>mpatch</command> <citation>web:mpatch</citation>, which takes a simple approach to
732 automating the application of hunks rejected by <command>patch</command>. The
733 <command>mpatch</command> command can help with four common reasons that a hunk
734 may be rejected:
735 </para>
737 <itemizedlist>
738 <listitem><para>The context in the middle of a hunk has changed.
739 </para>
740 </listitem>
741 <listitem><para>A hunk is missing some context at the beginning or end.
742 </para>
743 </listitem>
744 <listitem><para>A large hunk might apply better&emdash;either entirely or in
745 part&emdash;if it was broken up into smaller hunks.
746 </para>
747 </listitem>
748 <listitem><para>A hunk removes lines with slightly different content than those
749 currently present in the file.
750 </para>
751 </listitem></itemizedlist>
753 <para>If you use <command>wiggle</command> or <command>mpatch</command>, you should be doubly
754 careful to check your results when you're done. In fact,
755 <command>mpatch</command> enforces this method of double-checking the tool's
756 output, by automatically dropping you into a merge program when it has
757 done its job, so that you can verify its work and finish off any
758 remaining merges.
759 </para>
761 </sect2>
762 </sect1>
763 <sect1>
764 <title>Getting the best performance out of MQ</title>
765 <para>\label{sec:mq:perf}
766 </para>
768 <para>MQ is very efficient at handling a large number of patches. I ran
769 some performance experiments in mid-2006 for a talk that I gave at the
770 2006 EuroPython conference <citation>web:europython</citation>. I used as my data
771 set the Linux 2.6.17-mm1 patch series, which consists of 1,738
772 patches. I applied these on top of a Linux kernel repository
773 containing all 27,472 revisions between Linux 2.6.12-rc2 and Linux
774 2.6.17.
775 </para>
777 <para>On my old, slow laptop, I was able to
778 <command role="hg-cmd">hg qpush <option role="hg-ext-mq-cmd-qpush-opt">-a</option></command> all 1,738 patches in 3.5 minutes,
779 and <command role="hg-cmd">hg qpop <option role="hg-ext-mq-cmd-qpop-opt">-a</option></command> them all in 30 seconds. (On a
780 newer laptop, the time to push all patches dropped to two minutes.) I
781 could <command role="hg-ext-mq">qrefresh</command> one of the biggest patches (which made 22,779
782 lines of changes to 287 files) in 6.6 seconds.
783 </para>
785 <para>Clearly, MQ is well suited to working in large trees, but there are a
786 few tricks you can use to get the best performance of it.
787 </para>
789 <para>First of all, try to <quote>batch</quote> operations together. Every time you
790 run <command role="hg-ext-mq">qpush</command> or <command role="hg-ext-mq">qpop</command>, these commands scan the working
791 directory once to make sure you haven't made some changes and then
792 forgotten to run <command role="hg-ext-mq">qrefresh</command>. On a small tree, the time that
793 this scan takes is unnoticeable. However, on a medium-sized tree
794 (containing tens of thousands of files), it can take a second or more.
795 </para>
797 <para>The <command role="hg-ext-mq">qpush</command> and <command role="hg-ext-mq">qpop</command> commands allow you to push and pop
798 multiple patches at a time. You can identify the <quote>destination
799 patch</quote> that you want to end up at. When you <command role="hg-ext-mq">qpush</command> with a
800 destination specified, it will push patches until that patch is at the
801 top of the applied stack. When you <command role="hg-ext-mq">qpop</command> to a destination, MQ
802 will pop patches until the destination patch is at the top.
803 </para>
805 <para>You can identify a destination patch using either the name of the
806 patch, or by number. If you use numeric addressing, patches are
807 counted from zero; this means that the first patch is zero, the second
808 is one, and so on.
809 </para>
811 </sect1>
812 <sect1>
813 <title>Updating your patches when the underlying code changes</title>
814 <para>\label{sec:mq:merge}
815 </para>
817 <para>It's common to have a stack of patches on top of an underlying
818 repository that you don't modify directly. If you're working on
819 changes to third-party code, or on a feature that is taking longer to
820 develop than the rate of change of the code beneath, you will often
821 need to sync up with the underlying code, and fix up any hunks in your
822 patches that no longer apply. This is called <emphasis>rebasing</emphasis> your
823 patch series.
824 </para>
826 <para>The simplest way to do this is to <command role="hg-cmd">hg qpop <option role="hg-ext-mq-cmd-qpop-opt">-a</option></command>
827 your patches, then <command role="hg-cmd">hg pull</command> changes into the underlying
828 repository, and finally <command role="hg-cmd">hg qpush <option role="hg-ext-mq-cmd-qpop-opt">-a</option></command> your
829 patches again. MQ will stop pushing any time it runs across a patch
830 that fails to apply during conflicts, allowing you to fix your
831 conflicts, <command role="hg-ext-mq">qrefresh</command> the affected patch, and continue pushing
832 until you have fixed your entire stack.
833 </para>
835 <para>This approach is easy to use and works well if you don't expect
836 changes to the underlying code to affect how well your patches apply.
837 If your patch stack touches code that is modified frequently or
838 invasively in the underlying repository, however, fixing up rejected
839 hunks by hand quickly becomes tiresome.
840 </para>
842 <para>It's possible to partially automate the rebasing process. If your
843 patches apply cleanly against some revision of the underlying repo, MQ
844 can use this information to help you to resolve conflicts between your
845 patches and a different revision.
846 </para>
848 <para>The process is a little involved.
849 </para>
850 <orderedlist>
851 <listitem><para>To begin, <command role="hg-cmd">hg qpush -a</command> all of your patches on top of
852 the revision where you know that they apply cleanly.
853 </para>
854 </listitem>
855 <listitem><para>Save a backup copy of your patch directory using
856 <command role="hg-cmd">hg qsave <option role="hg-ext-mq-cmd-qsave-opt">-e</option> <option role="hg-ext-mq-cmd-qsave-opt">-c</option></command>. This prints
857 the name of the directory that it has saved the patches in. It will
858 save the patches to a directory called
859 <filename role="special" class="directory">.hg/patches.<emphasis>N</filename></emphasis>, where <literal><emphasis>N</emphasis></literal> is a small
860 integer. It also commits a <quote>save changeset</quote> on top of your
861 applied patches; this is for internal book-keeping, and records the
862 states of the <filename role="special">series</filename> and <filename role="special">status</filename> files.
863 </para>
864 </listitem>
865 <listitem><para>Use <command role="hg-cmd">hg pull</command> to bring new changes into the underlying
866 repository. (Don't run <command role="hg-cmd">hg pull -u</command>; see below for why.)
867 </para>
868 </listitem>
869 <listitem><para>Update to the new tip revision, using
870 <command role="hg-cmd">hg update <option role="hg-opt-update">-C</option></command> to override the patches you
871 have pushed.
872 </para>
873 </listitem>
874 <listitem><para>Merge all patches using \hgcmdargs{qpush}{<option role="hg-ext-mq-cmd-qpush-opt">-m</option>
875 <option role="hg-ext-mq-cmd-qpush-opt">-a</option>}. The <option role="hg-ext-mq-cmd-qpush-opt">-m</option> option to <command role="hg-ext-mq">qpush</command>
876 tells MQ to perform a three-way merge if the patch fails to apply.
877 </para>
878 </listitem></orderedlist>
880 <para>During the <command role="hg-cmd">hg qpush <option role="hg-ext-mq-cmd-qpush-opt">-m</option></command>, each patch in the
881 <filename role="special">series</filename> file is applied normally. If a patch applies with
882 fuzz or rejects, MQ looks at the queue you <command role="hg-ext-mq">qsave</command>d, and
883 performs a three-way merge with the corresponding changeset. This
884 merge uses Mercurial's normal merge machinery, so it may pop up a GUI
885 merge tool to help you to resolve problems.
886 </para>
888 <para>When you finish resolving the effects of a patch, MQ refreshes your
889 patch based on the result of the merge.
890 </para>
892 <para>At the end of this process, your repository will have one extra head
893 from the old patch queue, and a copy of the old patch queue will be in
894 <filename role="special" class="directory">.hg/patches.<emphasis>N</filename></emphasis>. You can remove the extra head using
895 <command role="hg-cmd">hg qpop <option role="hg-ext-mq-cmd-qpop-opt">-a</option> <option role="hg-ext-mq-cmd-qpop-opt">-n</option> patches.<emphasis>N</emphasis></command>
896 or <command role="hg-cmd">hg strip</command>. You can delete <filename role="special" class="directory">.hg/patches.<emphasis>N</filename></emphasis> once
897 you are sure that you no longer need it as a backup.
898 </para>
900 </sect1>
901 <sect1>
902 <title>Identifying patches</title>
904 <para>MQ commands that work with patches let you refer to a patch either by
905 using its name or by a number. By name is obvious enough; pass the
906 name <filename>foo.patch</filename> to <command role="hg-ext-mq">qpush</command>, for example, and it will
907 push patches until <filename>foo.patch</filename> is applied.
908 </para>
910 <para>As a shortcut, you can refer to a patch using both a name and a
911 numeric offset; <literal>foo.patch-2</literal> means <quote>two patches before
912 <literal>foo.patch</literal></quote>, while <literal>bar.patch+4</literal> means <quote>four patches
913 after <literal>bar.patch</literal></quote>.
914 </para>
916 <para>Referring to a patch by index isn't much different. The first patch
917 printed in the output of <command role="hg-ext-mq">qseries</command> is patch zero (yes, it's one
918 of those start-at-zero counting systems); the second is patch one; and
919 so on.
920 </para>
922 <para>MQ also makes it easy to work with patches when you are using normal
923 Mercurial commands. Every command that accepts a changeset ID will
924 also accept the name of an applied patch. MQ augments the tags
925 normally in the repository with an eponymous one for each applied
926 patch. In addition, the special tags \index{tags!special tag
927 names!<literal>qbase</literal>}<literal>qbase</literal> and \index{tags!special tag
928 names!<literal>qtip</literal>}<literal>qtip</literal> identify the <quote>bottom-most</quote> and
929 topmost applied patches, respectively.
930 </para>
932 <para>These additions to Mercurial's normal tagging capabilities make
933 dealing with patches even more of a breeze.
934 </para>
935 <itemizedlist>
936 <listitem><para>Want to patchbomb a mailing list with your latest series of
937 changes?
938 </para>
939 </listitem><programlisting>
940 <listitem><para> hg email qbase:qtip
941 </para>
942 </listitem></programlisting>
943 <listitem><para> (Don't know what <quote>patchbombing</quote> is? See
944 section <xref linkend="sec:hgext:patchbomb"/>.)
945 </para>
946 </listitem>
947 <listitem><para>Need to see all of the patches since <literal>foo.patch</literal> that
948 have touched files in a subdirectory of your tree?
949 </para>
950 </listitem><programlisting>
951 <listitem><para> hg log -r foo.patch:qtip <emphasis>subdir</emphasis>
952 </para>
953 </listitem></programlisting>
954 </itemizedlist>
956 <para>Because MQ makes the names of patches available to the rest of
957 Mercurial through its normal internal tag machinery, you don't need to
958 type in the entire name of a patch when you want to identify it by
959 name.
960 </para>
962 <informalfigure>
963 <para> <!-- &interaction.mq.id.output; -->
964 <caption><para>Using MQ's tag features to work with patches</para></caption>
965 \label{ex:mq:id}
966 </para>
967 </informalfigure>
969 <para>Another nice consequence of representing patch names as tags is that
970 when you run the <command role="hg-cmd">hg log</command> command, it will display a patch's name
971 as a tag, simply as part of its normal output. This makes it easy to
972 visually distinguish applied patches from underlying <quote>normal</quote>
973 revisions. Figure <xref linkend="ex:mq:id"/> shows a few normal Mercurial
974 commands in use with applied patches.
975 </para>
977 </sect1>
978 <sect1>
979 <title>Useful things to know about</title>
981 <para>There are a number of aspects of MQ usage that don't fit tidily into
982 sections of their own, but that are good to know. Here they are, in
983 one place.
984 </para>
986 <itemizedlist>
987 <listitem><para>Normally, when you <command role="hg-ext-mq">qpop</command> a patch and <command role="hg-ext-mq">qpush</command> it
988 again, the changeset that represents the patch after the pop/push
989 will have a <emphasis>different identity</emphasis> than the changeset that
990 represented the hash beforehand. See
991 section <xref linkend="sec:mqref:cmd:qpush"/> for information as to why this is.
992 </para>
993 </listitem>
994 <listitem><para>It's not a good idea to <command role="hg-cmd">hg merge</command> changes from another
995 branch with a patch changeset, at least if you want to maintain the
996 <quote>patchiness</quote> of that changeset and changesets below it on the
997 patch stack. If you try to do this, it will appear to succeed, but
998 MQ will become confused.
999 </para>
1000 </listitem></itemizedlist>
1002 </sect1>
1003 <sect1>
1004 <title>Managing patches in a repository</title>
1005 <para>\label{sec:mq:repo}
1006 </para>
1008 <para>Because MQ's <filename role="special" class="directory">.hg/patches</filename> directory resides outside a
1009 Mercurial repository's working directory, the <quote>underlying</quote> Mercurial
1010 repository knows nothing about the management or presence of patches.
1011 </para>
1013 <para>This presents the interesting possibility of managing the contents of
1014 the patch directory as a Mercurial repository in its own right. This
1015 can be a useful way to work. For example, you can work on a patch for
1016 a while, <command role="hg-ext-mq">qrefresh</command> it, then <command role="hg-cmd">hg commit</command> the current state of
1017 the patch. This lets you <quote>roll back</quote> to that version of the patch
1018 later on.
1019 </para>
1021 <para>You can then share different versions of the same patch stack among
1022 multiple underlying repositories. I use this when I am developing a
1023 Linux kernel feature. I have a pristine copy of my kernel sources for
1024 each of several CPU architectures, and a cloned repository under each
1025 that contains the patches I am working on. When I want to test a
1026 change on a different architecture, I push my current patches to the
1027 patch repository associated with that kernel tree, pop and push all of
1028 my patches, and build and test that kernel.
1029 </para>
1031 <para>Managing patches in a repository makes it possible for multiple
1032 developers to work on the same patch series without colliding with
1033 each other, all on top of an underlying source base that they may or
1034 may not control.
1035 </para>
1037 <sect2>
1038 <title>MQ support for patch repositories</title>
1040 <para>MQ helps you to work with the <filename role="special" class="directory">.hg/patches</filename> directory as a
1041 repository; when you prepare a repository for working with patches
1042 using <command role="hg-ext-mq">qinit</command>, you can pass the <option role="hg-ext-mq-cmd-qinit-opt">-c</option> option to
1043 create the <filename role="special" class="directory">.hg/patches</filename> directory as a Mercurial repository.
1044 </para>
1046 <note>
1047 <para> If you forget to use the <option role="hg-ext-mq-cmd-qinit-opt">-c</option> option, you can simply go
1048 into the <filename role="special" class="directory">.hg/patches</filename> directory at any time and run
1049 <command role="hg-cmd">hg init</command>. Don't forget to add an entry for the
1050 <filename role="special">status</filename> file to the <filename role="special">.hgignore</filename> file, though
1051 </para>
1053 <para> (<command role="hg-cmd">hg qinit <option role="hg-ext-mq-cmd-qinit-opt">-c</option></command> does this for you
1054 automatically); you <emphasis>really</emphasis> don't want to manage the
1055 <filename role="special">status</filename> file.
1056 </para>
1057 </note>
1059 <para>As a convenience, if MQ notices that the <filename class="directory">.hg/patches</filename>
1060 directory is a repository, it will automatically <command role="hg-cmd">hg add</command> every
1061 patch that you create and import.
1062 </para>
1064 <para>MQ provides a shortcut command, <command role="hg-ext-mq">qcommit</command>, that runs
1065 <command role="hg-cmd">hg commit</command> in the <filename role="special" class="directory">.hg/patches</filename> directory. This saves
1066 some bothersome typing.
1067 </para>
1069 <para>Finally, as a convenience to manage the patch directory, you can
1070 define the alias <command>mq</command> on Unix systems. For example, on Linux
1071 systems using the <command>bash</command> shell, you can include the following
1072 snippet in your <filename role="home">~/.bashrc</filename>.
1073 </para>
1075 <programlisting>
1076 <para> alias mq=`hg -R $(hg root)/.hg/patches'
1077 </para>
1078 </programlisting>
1080 <para>You can then issue commands of the form <command>mq pull</command> from
1081 the main repository.
1082 </para>
1084 </sect2>
1085 <sect2>
1086 <title>A few things to watch out for</title>
1088 <para>MQ's support for working with a repository full of patches is limited
1089 in a few small respects.
1090 </para>
1092 <para>MQ cannot automatically detect changes that you make to the patch
1093 directory. If you <command role="hg-cmd">hg pull</command>, manually edit, or <command role="hg-cmd">hg update</command>
1094 changes to patches or the <filename role="special">series</filename> file, you will have to
1095 <command role="hg-cmd">hg qpop <option role="hg-ext-mq-cmd-qpop-opt">-a</option></command> and then
1096 <command role="hg-cmd">hg qpush <option role="hg-ext-mq-cmd-qpush-opt">-a</option></command> in the underlying repository to
1097 see those changes show up there. If you forget to do this, you can
1098 confuse MQ's idea of which patches are applied.
1099 </para>
1101 </sect2>
1102 </sect1>
1103 <sect1>
1104 <title>Third party tools for working with patches</title>
1105 <para>\label{sec:mq:tools}
1106 </para>
1108 <para>Once you've been working with patches for a while, you'll find
1109 yourself hungry for tools that will help you to understand and
1110 manipulate the patches you're dealing with.
1111 </para>
1113 <para>The <command>diffstat</command> command <citation>web:diffstat</citation> generates a
1114 histogram of the modifications made to each file in a patch. It
1115 provides a good way to <quote>get a sense of</quote> a patch&emdash;which files it
1116 affects, and how much change it introduces to each file and as a
1117 whole. (I find that it's a good idea to use <command>diffstat</command>'s
1118 <option role="cmd-opt-diffstat">-p</option> option as a matter of course, as otherwise it
1119 will try to do clever things with prefixes of file names that
1120 inevitably confuse at least me.)
1121 </para>
1123 <informalfigure>
1124 <para> <!-- &interaction.mq.tools.tools; -->
1125 <caption><para>The <command>diffstat</para></caption>, \command{filterdiff</command>, and <command>lsdiff</command> commands}
1126 \label{ex:mq:tools}
1127 </para>
1128 </informalfigure>
1130 <para>The <literal role="package">patchutils</literal> package <citation>web:patchutils</citation> is invaluable.
1131 It provides a set of small utilities that follow the <quote>Unix
1132 philosophy;</quote> each does one useful thing with a patch. The
1133 <literal role="package">patchutils</literal> command I use most is <command>filterdiff</command>, which
1134 extracts subsets from a patch file. For example, given a patch that
1135 modifies hundreds of files across dozens of directories, a single
1136 invocation of <command>filterdiff</command> can generate a smaller patch that
1137 only touches files whose names match a particular glob pattern. See
1138 section <xref linkend="mq-collab:tips:interdiff"/> for another example.
1139 </para>
1141 </sect1>
1142 <sect1>
1143 <title>Good ways to work with patches</title>
1145 <para>Whether you are working on a patch series to submit to a free software
1146 or open source project, or a series that you intend to treat as a
1147 sequence of regular changesets when you're done, you can use some
1148 simple techniques to keep your work well organised.
1149 </para>
1151 <para>Give your patches descriptive names. A good name for a patch might be
1152 <filename>rework-device-alloc.patch</filename>, because it will immediately give
1153 you a hint what the purpose of the patch is. Long names shouldn't be
1154 a problem; you won't be typing the names often, but you <emphasis>will</emphasis> be
1155 running commands like <command role="hg-ext-mq">qapplied</command> and <command role="hg-ext-mq">qtop</command> over and over.
1156 Good naming becomes especially important when you have a number of
1157 patches to work with, or if you are juggling a number of different
1158 tasks and your patches only get a fraction of your attention.
1159 </para>
1161 <para>Be aware of what patch you're working on. Use the <command role="hg-ext-mq">qtop</command>
1162 command and skim over the text of your patches frequently&emdash;for
1163 example, using <command role="hg-cmd">hg tip <option role="hg-opt-tip">-p</option></command>)&emdash;to be sure of where
1164 you stand. I have several times worked on and <command role="hg-ext-mq">qrefresh</command>ed a
1165 patch other than the one I intended, and it's often tricky to migrate
1166 changes into the right patch after making them in the wrong one.
1167 </para>
1169 <para>For this reason, it is very much worth investing a little time to
1170 learn how to use some of the third-party tools I described in
1171 section <xref linkend="sec:mq:tools"/>, particularly <command>diffstat</command> and
1172 <command>filterdiff</command>. The former will give you a quick idea of what
1173 changes your patch is making, while the latter makes it easy to splice
1174 hunks selectively out of one patch and into another.
1175 </para>
1177 </sect1>
1178 <sect1>
1179 <title>MQ cookbook</title>
1181 <sect2>
1182 <title>Manage <quote>trivial</quote> patches</title>
1184 <para>Because the overhead of dropping files into a new Mercurial repository
1185 is so low, it makes a lot of sense to manage patches this way even if
1186 you simply want to make a few changes to a source tarball that you
1187 downloaded.
1188 </para>
1190 <para>Begin by downloading and unpacking the source tarball,
1191 and turning it into a Mercurial repository.
1192 <!-- &interaction.mq.tarball.download; -->
1193 </para>
1195 <para>Continue by creating a patch stack and making your changes.
1196 <!-- &interaction.mq.tarball.qinit; -->
1197 </para>
1199 <para>Let's say a few weeks or months pass, and your package author releases
1200 a new version. First, bring their changes into the repository.
1201 <!-- &interaction.mq.tarball.newsource; -->
1202 The pipeline starting with <command role="hg-cmd">hg locate</command> above deletes all files in
1203 the working directory, so that <command role="hg-cmd">hg commit</command>'s
1204 <option role="hg-opt-commit">--addremove</option> option can actually tell which files have
1205 really been removed in the newer version of the source.
1206 </para>
1208 <para>Finally, you can apply your patches on top of the new tree.
1209 <!-- &interaction.mq.tarball.repush; -->
1210 </para>
1212 </sect2>
1213 <sect2>
1214 <title>Combining entire patches</title>
1215 <para>\label{sec:mq:combine}
1216 </para>
1218 <para>MQ provides a command, <command role="hg-ext-mq">qfold</command> that lets you combine entire
1219 patches. This <quote>folds</quote> the patches you name, in the order you name
1220 them, into the topmost applied patch, and concatenates their
1221 descriptions onto the end of its description. The patches that you
1222 fold must be unapplied before you fold them.
1223 </para>
1225 <para>The order in which you fold patches matters. If your topmost applied
1226 patch is <literal>foo</literal>, and you <command role="hg-ext-mq">qfold</command> <literal>bar</literal> and
1227 <literal>quux</literal> into it, you will end up with a patch that has the same
1228 effect as if you applied first <literal>foo</literal>, then <literal>bar</literal>,
1229 followed by <literal>quux</literal>.
1230 </para>
1232 </sect2>
1233 <sect2>
1234 <title>Merging part of one patch into another</title>
1236 <para>Merging <emphasis>part</emphasis> of one patch into another is more difficult than
1237 combining entire patches.
1238 </para>
1240 <para>If you want to move changes to entire files, you can use
1241 <command>filterdiff</command>'s <option role="cmd-opt-filterdiff">-i</option> and
1242 <option role="cmd-opt-filterdiff">-x</option> options to choose the modifications to snip
1243 out of one patch, concatenating its output onto the end of the patch
1244 you want to merge into. You usually won't need to modify the patch
1245 you've merged the changes from. Instead, MQ will report some rejected
1246 hunks when you <command role="hg-ext-mq">qpush</command> it (from the hunks you moved into the
1247 other patch), and you can simply <command role="hg-ext-mq">qrefresh</command> the patch to drop
1248 the duplicate hunks.
1249 </para>
1251 <para>If you have a patch that has multiple hunks modifying a file, and you
1252 only want to move a few of those hunks, the job becomes more messy,
1253 but you can still partly automate it. Use <command>lsdiff -nvv</command> to
1254 print some metadata about the patch.
1255 <!-- &interaction.mq.tools.lsdiff; -->
1256 </para>
1258 <para>This command prints three different kinds of number:
1259 </para>
1260 <itemizedlist>
1261 <listitem><para>(in the first column) a <emphasis>file number</emphasis> to identify each file
1262 modified in the patch;
1263 </para>
1264 </listitem>
1265 <listitem><para>(on the next line, indented) the line number within a modified
1266 file where a hunk starts; and
1267 </para>
1268 </listitem>
1269 <listitem><para>(on the same line) a <emphasis>hunk number</emphasis> to identify that hunk.
1270 </para>
1271 </listitem></itemizedlist>
1273 <para>You'll have to use some visual inspection, and reading of the patch,
1274 to identify the file and hunk numbers you'll want, but you can then
1275 pass them to to <command>filterdiff</command>'s <option role="cmd-opt-filterdiff">--files</option>
1276 and <option role="cmd-opt-filterdiff">--hunks</option> options, to select exactly the file
1277 and hunk you want to extract.
1278 </para>
1280 <para>Once you have this hunk, you can concatenate it onto the end of your
1281 destination patch and continue with the remainder of
1282 section <xref linkend="sec:mq:combine"/>.
1283 </para>
1285 </sect2>
1286 </sect1>
1287 <sect1>
1288 <title>Differences between quilt and MQ</title>
1290 <para>If you are already familiar with quilt, MQ provides a similar command
1291 set. There are a few differences in the way that it works.
1292 </para>
1294 <para>You will already have noticed that most quilt commands have MQ
1295 counterparts that simply begin with a <quote><literal>q</literal></quote>. The exceptions
1296 are quilt's <literal>add</literal> and <literal>remove</literal> commands, the
1297 counterparts for which are the normal Mercurial <command role="hg-cmd">hg add</command> and
1298 <command role="hg-cmd">hg remove</command> commands. There is no MQ equivalent of the quilt
1299 <literal>edit</literal> command.
1300 </para>
1302 </sect1>
1303 </chapter>
1305 <!--
1306 local variables:
1307 sgml-parent-document: ("00book.xml" "book" "chapter")
1308 end:
1309 -->