hgbook
view fr/ch12-mq.xml @ 1011:a05a5ae66c38
merge
| author | Romain PELISSE <belaran@gmail.com> |
|---|---|
| date | Mon Nov 23 10:51:14 2009 +0100 (2009-11-23) |
| parents | en/ch12-mq.xml@102f89d20be1 en/ch12-mq.xml@6f8c48362758 |
| children |
line source
1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
3 <chapter id="chap:mq">
4 <?dbhtml filename="managing-change-with-mercurial-queues.html"?>
5 <title>Managing change with Mercurial Queues</title>
7 <sect1 id="sec:mq:patch-mgmt">
8 <title>The patch management problem</title>
10 <para id="x_3ac">Here is a common scenario: you need to install a software
11 package from source, but you find a bug that you must fix in the
12 source before you can start using the package. You make your
13 changes, forget about the package for a while, and a few months
14 later you need to upgrade to a newer version of the package. If
15 the newer version of the package still has the bug, you must
16 extract your fix from the older source tree and apply it against
17 the newer version. This is a tedious task, and it's easy to
18 make mistakes.</para>
20 <para id="x_3ad">This is a simple case of the <quote>patch management</quote>
21 problem. You have an <quote>upstream</quote> source tree that
22 you can't change; you need to make some local changes on top of
23 the upstream tree; and you'd like to be able to keep those
24 changes separate, so that you can apply them to newer versions
25 of the upstream source.</para>
27 <para id="x_3ae">The patch management problem arises in many situations.
28 Probably the most visible is that a user of an open source
29 software project will contribute a bug fix or new feature to the
30 project's maintainers in the form of a patch.</para>
32 <para id="x_3af">Distributors of operating systems that include open source
33 software often need to make changes to the packages they
34 distribute so that they will build properly in their
35 environments.</para>
37 <para id="x_3b0">When you have few changes to maintain, it is easy to manage
38 a single patch using the standard <command>diff</command> and
39 <command>patch</command> programs (see <xref
40 linkend="sec:mq:patch"/> for a discussion of these
41 tools). Once the number of changes grows, it starts to make
42 sense to maintain patches as discrete <quote>chunks of
43 work,</quote> so that for example a single patch will contain
44 only one bug fix (the patch might modify several files, but it's
45 doing <quote>only one thing</quote>), and you may have a number
46 of such patches for different bugs you need fixed and local
47 changes you require. In this situation, if you submit a bug fix
48 patch to the upstream maintainers of a package and they include
49 your fix in a subsequent release, you can simply drop that
50 single patch when you're updating to the newer release.</para>
52 <para id="x_3b1">Maintaining a single patch against an upstream tree is a
53 little tedious and error-prone, but not difficult. However, the
54 complexity of the problem grows rapidly as the number of patches
55 you have to maintain increases. With more than a tiny number of
56 patches in hand, understanding which ones you have applied and
57 maintaining them moves from messy to overwhelming.</para>
59 <para id="x_3b2">Fortunately, Mercurial includes a powerful extension,
60 Mercurial Queues (or simply <quote>MQ</quote>), that massively
61 simplifies the patch management problem.</para>
63 </sect1>
64 <sect1 id="sec:mq:history">
65 <title>The prehistory of Mercurial Queues</title>
67 <para id="x_3b3">During the late 1990s, several Linux kernel developers
68 started to maintain <quote>patch series</quote> that modified
69 the behavior of the Linux kernel. Some of these series were
70 focused on stability, some on feature coverage, and others were
71 more speculative.</para>
73 <para id="x_3b4">The sizes of these patch series grew rapidly. In 2002,
74 Andrew Morton published some shell scripts he had been using to
75 automate the task of managing his patch queues. Andrew was
76 successfully using these scripts to manage hundreds (sometimes
77 thousands) of patches on top of the Linux kernel.</para>
79 <sect2 id="sec:mq:quilt">
80 <title>A patchwork quilt</title>
82 <para id="x_3b5">In early 2003, Andreas Gruenbacher and Martin Quinson
83 borrowed the approach of Andrew's scripts and published a tool
84 called <quote>patchwork quilt</quote>
85 <citation>web:quilt</citation>, or simply <quote>quilt</quote>
86 (see <citation>gruenbacher:2005</citation> for a paper
87 describing it). Because quilt substantially automated patch
88 management, it rapidly gained a large following among open
89 source software developers.</para>
91 <para id="x_3b6">Quilt manages a <emphasis>stack of patches</emphasis> on
92 top of a directory tree. To begin, you tell quilt to manage a
93 directory tree, and tell it which files you want to manage; it
94 stores away the names and contents of those files. To fix a
95 bug, you create a new patch (using a single command), edit the
96 files you need to fix, then <quote>refresh</quote> the
97 patch.</para>
99 <para id="x_3b7">The refresh step causes quilt to scan the directory tree;
100 it updates the patch with all of the changes you have made.
101 You can create another patch on top of the first, which will
102 track the changes required to modify the tree from <quote>tree
103 with one patch applied</quote> to <quote>tree with two
104 patches applied</quote>.</para>
106 <para id="x_3b8">You can <emphasis>change</emphasis> which patches are
107 applied to the tree. If you <quote>pop</quote> a patch, the
108 changes made by that patch will vanish from the directory
109 tree. Quilt remembers which patches you have popped, though,
110 so you can <quote>push</quote> a popped patch again, and the
111 directory tree will be restored to contain the modifications
112 in the patch. Most importantly, you can run the
113 <quote>refresh</quote> command at any time, and the topmost
114 applied patch will be updated. This means that you can, at
115 any time, change both which patches are applied and what
116 modifications those patches make.</para>
118 <para id="x_3b9">Quilt knows nothing about revision control tools, so it
119 works equally well on top of an unpacked tarball or a
120 Subversion working copy.</para>
121 </sect2>
123 <sect2 id="sec:mq:quilt-mq">
124 <title>From patchwork quilt to Mercurial Queues</title>
126 <para id="x_3ba">In mid-2005, Chris Mason took the features of quilt and
127 wrote an extension that he called Mercurial Queues, which
128 added quilt-like behavior to Mercurial.</para>
130 <para id="x_3bb">The key difference between quilt and MQ is that quilt
131 knows nothing about revision control systems, while MQ is
132 <emphasis>integrated</emphasis> into Mercurial. Each patch
133 that you push is represented as a Mercurial changeset. Pop a
134 patch, and the changeset goes away.</para>
136 <para id="x_3bc">Because quilt does not care about revision control tools,
137 it is still a tremendously useful piece of software to know
138 about for situations where you cannot use Mercurial and
139 MQ.</para>
141 </sect2>
142 </sect1>
143 <sect1>
144 <title>The huge advantage of MQ</title>
146 <para id="x_3bd">I cannot overstate the value that MQ offers through the
147 unification of patches and revision control.</para>
149 <para id="x_3be">A major reason that patches have persisted in the free
150 software and open source world&emdash;in spite of the
151 availability of increasingly capable revision control tools over
152 the years&emdash;is the <emphasis>agility</emphasis> they
153 offer.</para>
155 <para id="x_3bf">Traditional revision control tools make a permanent,
156 irreversible record of everything that you do. While this has
157 great value, it's also somewhat stifling. If you want to
158 perform a wild-eyed experiment, you have to be careful in how
159 you go about it, or you risk leaving unneeded&emdash;or worse,
160 misleading or destabilising&emdash;traces of your missteps and
161 errors in the permanent revision record.</para>
163 <para id="x_3c0">By contrast, MQ's marriage of distributed revision control
164 with patches makes it much easier to isolate your work. Your
165 patches live on top of normal revision history, and you can make
166 them disappear or reappear at will. If you don't like a patch,
167 you can drop it. If a patch isn't quite as you want it to be,
168 simply fix it&emdash;as many times as you need to, until you
169 have refined it into the form you desire.</para>
171 <para id="x_3c1">As an example, the integration of patches with revision
172 control makes understanding patches and debugging their
173 effects&emdash;and their interplay with the code they're based
174 on&emdash;<emphasis>enormously</emphasis> easier. Since every
175 applied patch has an associated changeset, you can give <command
176 role="hg-cmd">hg log</command> a file name to see which
177 changesets and patches affected the file. You can use the
178 <command role="hg-cmd">hg bisect</command> command to
179 binary-search through all changesets and applied patches to see
180 where a bug got introduced or fixed. You can use the <command
181 role="hg-cmd">hg annotate</command> command to see which
182 changeset or patch modified a particular line of a source file.
183 And so on.</para>
184 </sect1>
186 <sect1 id="sec:mq:patch">
187 <title>Understanding patches</title>
189 <para id="x_3c2">Because MQ doesn't hide its patch-oriented nature, it is
190 helpful to understand what patches are, and a little about the
191 tools that work with them.</para>
193 <para id="x_3c3">The traditional Unix <command>diff</command> command
194 compares two files, and prints a list of differences between
195 them. The <command>patch</command> command understands these
196 differences as <emphasis>modifications</emphasis> to make to a
197 file. Take a look below for a simple example of these commands
198 in action.</para>
200 &interaction.mq.dodiff.diff;
202 <para id="x_3c4">The type of file that <command>diff</command> generates (and
203 <command>patch</command> takes as input) is called a
204 <quote>patch</quote> or a <quote>diff</quote>; there is no
205 difference between a patch and a diff. (We'll use the term
206 <quote>patch</quote>, since it's more commonly used.)</para>
208 <para id="x_3c5">A patch file can start with arbitrary text; the
209 <command>patch</command> command ignores this text, but MQ uses
210 it as the commit message when creating changesets. To find the
211 beginning of the patch content, <command>patch</command>
212 searches for the first line that starts with the string
213 <quote><literal>diff -</literal></quote>.</para>
215 <para id="x_3c6">MQ works with <emphasis>unified</emphasis> diffs
216 (<command>patch</command> can accept several other diff formats,
217 but MQ doesn't). A unified diff contains two kinds of header.
218 The <emphasis>file header</emphasis> describes the file being
219 modified; it contains the name of the file to modify. When
220 <command>patch</command> sees a new file header, it looks for a
221 file with that name to start modifying.</para>
223 <para id="x_3c7">After the file header comes a series of
224 <emphasis>hunks</emphasis>. Each hunk starts with a header;
225 this identifies the range of line numbers within the file that
226 the hunk should modify. Following the header, a hunk starts and
227 ends with a few (usually three) lines of text from the
228 unmodified file; these are called the
229 <emphasis>context</emphasis> for the hunk. If there's only a
230 small amount of context between successive hunks,
231 <command>diff</command> doesn't print a new hunk header; it just
232 runs the hunks together, with a few lines of context between
233 modifications.</para>
235 <para id="x_3c8">Each line of context begins with a space character. Within
236 the hunk, a line that begins with
237 <quote><literal>-</literal></quote> means <quote>remove this
238 line,</quote> while a line that begins with
239 <quote><literal>+</literal></quote> means <quote>insert this
240 line.</quote> For example, a line that is modified is
241 represented by one deletion and one insertion.</para>
243 <para id="x_3c9">We will return to some of the more subtle aspects of patches
244 later (in <xref linkend="sec:mq:adv-patch"/>), but you
245 should have
246 enough information now to use MQ.</para>
247 </sect1>
249 <sect1 id="sec:mq:start">
250 <title>Getting started with Mercurial Queues</title>
252 <para id="x_3ca">Because MQ is implemented as an extension, you must
253 explicitly enable before you can use it. (You don't need to
254 download anything; MQ ships with the standard Mercurial
255 distribution.) To enable MQ, edit your <filename
256 role="home">~/.hgrc</filename> file, and add the lines
257 below.</para>
259 <programlisting>[extensions]
260 hgext.mq =</programlisting>
262 <para id="x_3cb">Once the extension is enabled, it will make a number of new
263 commands available. To verify that the extension is working,
264 you can use <command role="hg-cmd">hg help</command> to see if
265 the <command role="hg-ext-mq">qinit</command> command is now
266 available.</para>
268 &interaction.mq.qinit-help.help;
270 <para id="x_3cc">You can use MQ with <emphasis>any</emphasis> Mercurial
271 repository, and its commands only operate within that
272 repository. To get started, simply prepare the repository using
273 the <command role="hg-ext-mq">qinit</command> command.</para>
275 &interaction.mq.tutorial.qinit;
277 <para id="x_3cd">This command creates an empty directory called <filename
278 role="special" class="directory">.hg/patches</filename>, where
279 MQ will keep its metadata. As with many Mercurial commands, the
280 <command role="hg-ext-mq">qinit</command> command prints nothing
281 if it succeeds.</para>
283 <sect2>
284 <title>Creating a new patch</title>
286 <para id="x_3ce">To begin work on a new patch, use the <command
287 role="hg-ext-mq">qnew</command> command. This command takes
288 one argument, the name of the patch to create.</para>
290 <para id="x_3cf">MQ will use this as the name of an actual file in the
291 <filename role="special"
292 class="directory">.hg/patches</filename> directory, as you
293 can see below.</para>
295 &interaction.mq.tutorial.qnew;
297 <para id="x_3d0">Also newly present in the <filename role="special"
298 class="directory">.hg/patches</filename> directory are two
299 other files, <filename role="special">series</filename> and
300 <filename role="special">status</filename>. The <filename
301 role="special">series</filename> file lists all of the
302 patches that MQ knows about for this repository, with one
303 patch per line. Mercurial uses the <filename
304 role="special">status</filename> file for internal
305 book-keeping; it tracks all of the patches that MQ has
306 <emphasis>applied</emphasis> in this repository.</para>
308 <note>
309 <para id="x_3d1"> You may sometimes want to edit the <filename
310 role="special">series</filename> file by hand; for
311 example, to change the sequence in which some patches are
312 applied. However, manually editing the <filename
313 role="special">status</filename> file is almost always a
314 bad idea, as it's easy to corrupt MQ's idea of what is
315 happening.</para>
316 </note>
318 <para id="x_3d2">Once you have created your new patch, you can edit files
319 in the working directory as you usually would. All of the
320 normal Mercurial commands, such as <command role="hg-cmd">hg
321 diff</command> and <command role="hg-cmd">hg
322 annotate</command>, work exactly as they did before.</para>
323 </sect2>
325 <sect2>
326 <title>Refreshing a patch</title>
328 <para id="x_3d3">When you reach a point where you want to save your work,
329 use the <command role="hg-ext-mq">qrefresh</command> command
330 to update the patch you are working on.</para>
332 &interaction.mq.tutorial.qrefresh;
334 <para id="x_3d4">This command folds the changes you have made in the
335 working directory into your patch, and updates its
336 corresponding changeset to contain those changes.</para>
338 <para id="x_3d5">You can run <command role="hg-ext-mq">qrefresh</command>
339 as often as you like, so it's a good way to
340 <quote>checkpoint</quote> your work. Refresh your patch at an
341 opportune time; try an experiment; and if the experiment
342 doesn't work out, <command role="hg-cmd">hg revert</command>
343 your modifications back to the last time you refreshed.</para>
345 &interaction.mq.tutorial.qrefresh2;
346 </sect2>
348 <sect2>
349 <title>Stacking and tracking patches</title>
351 <para id="x_3d6">Once you have finished working on a patch, or need to work
352 on another, you can use the <command
353 role="hg-ext-mq">qnew</command> command again to create a
354 new patch. Mercurial will apply this patch on top of your
355 existing patch.</para>
357 &interaction.mq.tutorial.qnew2;
359 <para id="x_3d7">Notice that the patch contains the changes in our prior
360 patch as part of its context (you can see this more clearly in
361 the output of <command role="hg-cmd">hg
362 annotate</command>).</para>
364 <para id="x_3d8">So far, with the exception of <command
365 role="hg-ext-mq">qnew</command> and <command
366 role="hg-ext-mq">qrefresh</command>, we've been careful to
367 only use regular Mercurial commands. However, MQ provides
368 many commands that are easier to use when you are thinking
369 about patches, as illustrated below.</para>
371 &interaction.mq.tutorial.qseries;
373 <itemizedlist>
374 <listitem><para id="x_3d9">The <command
375 role="hg-ext-mq">qseries</command> command lists every
376 patch that MQ knows about in this repository, from oldest
377 to newest (most recently
378 <emphasis>created</emphasis>).</para>
379 </listitem>
380 <listitem><para id="x_3da">The <command
381 role="hg-ext-mq">qapplied</command> command lists every
382 patch that MQ has <emphasis>applied</emphasis> in this
383 repository, again from oldest to newest (most recently
384 applied).</para>
385 </listitem></itemizedlist>
386 </sect2>
388 <sect2>
389 <title>Manipulating the patch stack</title>
391 <para id="x_3db">The previous discussion implied that there must be a
392 difference between <quote>known</quote> and
393 <quote>applied</quote> patches, and there is. MQ can manage a
394 patch without it being applied in the repository.</para>
396 <para id="x_3dc">An <emphasis>applied</emphasis> patch has a corresponding
397 changeset in the repository, and the effects of the patch and
398 changeset are visible in the working directory. You can undo
399 the application of a patch using the <command
400 role="hg-ext-mq">qpop</command> command. MQ still
401 <emphasis>knows about</emphasis>, or manages, a popped patch,
402 but the patch no longer has a corresponding changeset in the
403 repository, and the working directory does not contain the
404 changes made by the patch. <xref
405 linkend="fig:mq:stack"/> illustrates
406 the difference between applied and tracked patches.</para>
408 <figure id="fig:mq:stack">
409 <title>Applied and unapplied patches in the MQ patch
410 stack</title>
411 <mediaobject>
412 <imageobject><imagedata fileref="figs/mq-stack.png"/></imageobject>
413 <textobject><phrase>XXX add text</phrase></textobject>
414 </mediaobject>
415 </figure>
417 <para id="x_3de">You can reapply an unapplied, or popped, patch using the
418 <command role="hg-ext-mq">qpush</command> command. This
419 creates a new changeset to correspond to the patch, and the
420 patch's changes once again become present in the working
421 directory. See below for examples of <command
422 role="hg-ext-mq">qpop</command> and <command
423 role="hg-ext-mq">qpush</command> in action.</para>
425 &interaction.mq.tutorial.qpop;
427 <para id="x_3df">Notice that once we have popped a patch or two patches,
428 the output of <command role="hg-ext-mq">qseries</command>
429 remains the same, while that of <command
430 role="hg-ext-mq">qapplied</command> has changed.</para>
432 </sect2>
434 <sect2>
435 <title>Pushing and popping many patches</title>
437 <para id="x_3e0">While <command role="hg-ext-mq">qpush</command> and
438 <command role="hg-ext-mq">qpop</command> each operate on a
439 single patch at a time by default, you can push and pop many
440 patches in one go. The <option
441 role="hg-ext-mq-cmd-qpush-opt">-a</option> option to
442 <command role="hg-ext-mq">qpush</command> causes it to push
443 all unapplied patches, while the <option
444 role="hg-ext-mq-cmd-qpop-opt">-a</option> option to <command
445 role="hg-ext-mq">qpop</command> causes it to pop all applied
446 patches. (For some more ways to push and pop many patches,
447 see <xref linkend="sec:mq:perf"/> below.)</para>
449 &interaction.mq.tutorial.qpush-a;
450 </sect2>
452 <sect2>
453 <title>Safety checks, and overriding them</title>
455 <para id="x_3e1">Several MQ commands check the working directory before
456 they do anything, and fail if they find any modifications.
457 They do this to ensure that you won't lose any changes that
458 you have made, but not yet incorporated into a patch. The
459 example below illustrates this; the <command
460 role="hg-ext-mq">qnew</command> command will not create a
461 new patch if there are outstanding changes, caused in this
462 case by the <command role="hg-cmd">hg add</command> of
463 <filename>file3</filename>.</para>
465 &interaction.mq.tutorial.add;
467 <para id="x_3e2">Commands that check the working directory all take an
468 <quote>I know what I'm doing</quote> option, which is always
469 named <option>-f</option>. The exact meaning of
470 <option>-f</option> depends on the command. For example,
471 <command role="hg-cmd">hg qnew <option
472 role="hg-ext-mq-cmd-qnew-opt">-f</option></command>
473 will incorporate any outstanding changes into the new patch it
474 creates, but <command role="hg-cmd">hg qpop <option
475 role="hg-ext-mq-cmd-qpop-opt">-f</option></command>
476 will revert modifications to any files affected by the patch
477 that it is popping. Be sure to read the documentation for a
478 command's <option>-f</option> option before you use it!</para>
479 </sect2>
481 <sect2>
482 <title>Working on several patches at once</title>
484 <para id="x_3e3">The <command role="hg-ext-mq">qrefresh</command> command
485 always refreshes the <emphasis>topmost</emphasis> applied
486 patch. This means that you can suspend work on one patch (by
487 refreshing it), pop or push to make a different patch the top,
488 and work on <emphasis>that</emphasis> patch for a
489 while.</para>
491 <para id="x_3e4">Here's an example that illustrates how you can use this
492 ability. Let's say you're developing a new feature as two
493 patches. The first is a change to the core of your software,
494 and the second&emdash;layered on top of the
495 first&emdash;changes the user interface to use the code you
496 just added to the core. If you notice a bug in the core while
497 you're working on the UI patch, it's easy to fix the core.
498 Simply <command role="hg-ext-mq">qrefresh</command> the UI
499 patch to save your in-progress changes, and <command
500 role="hg-ext-mq">qpop</command> down to the core patch. Fix
501 the core bug, <command role="hg-ext-mq">qrefresh</command> the
502 core patch, and <command role="hg-ext-mq">qpush</command> back
503 to the UI patch to continue where you left off.</para>
504 </sect2>
505 </sect1>
507 <sect1 id="sec:mq:adv-patch">
508 <title>More about patches</title>
510 <para id="x_3e5">MQ uses the GNU <command>patch</command> command to apply
511 patches, so it's helpful to know a few more detailed aspects of
512 how <command>patch</command> works, and about patches
513 themselves.</para>
515 <sect2>
516 <title>The strip count</title>
518 <para id="x_3e6">If you look at the file headers in a patch, you will
519 notice that the pathnames usually have an extra component on
520 the front that isn't present in the actual path name. This is
521 a holdover from the way that people used to generate patches
522 (people still do this, but it's somewhat rare with modern
523 revision control tools).</para>
525 <para id="x_3e7">Alice would unpack a tarball, edit her files, then decide
526 that she wanted to create a patch. So she'd rename her
527 working directory, unpack the tarball again (hence the need
528 for the rename), and use the <option
529 role="cmd-opt-diff">-r</option> and <option
530 role="cmd-opt-diff">-N</option> options to
531 <command>diff</command> to recursively generate a patch
532 between the unmodified directory and the modified one. The
533 result would be that the name of the unmodified directory
534 would be at the front of the left-hand path in every file
535 header, and the name of the modified directory would be at the
536 front of the right-hand path.</para>
538 <para id="x_3e8">Since someone receiving a patch from the Alices of the net
539 would be unlikely to have unmodified and modified directories
540 with exactly the same names, the <command>patch</command>
541 command has a <option role="cmd-opt-patch">-p</option> option
542 that indicates the number of leading path name components to
543 strip when trying to apply a patch. This number is called the
544 <emphasis>strip count</emphasis>.</para>
546 <para id="x_3e9">An option of <quote><literal>-p1</literal></quote> means
547 <quote>use a strip count of one</quote>. If
548 <command>patch</command> sees a file name
549 <filename>foo/bar/baz</filename> in a file header, it will
550 strip <filename>foo</filename> and try to patch a file named
551 <filename>bar/baz</filename>. (Strictly speaking, the strip
552 count refers to the number of <emphasis>path
553 separators</emphasis> (and the components that go with them
554 ) to strip. A strip count of one will turn
555 <filename>foo/bar</filename> into <filename>bar</filename>,
556 but <filename>/foo/bar</filename> (notice the extra leading
557 slash) into <filename>foo/bar</filename>.)</para>
559 <para id="x_3ea">The <quote>standard</quote> strip count for patches is
560 one; almost all patches contain one leading path name
561 component that needs to be stripped. Mercurial's <command
562 role="hg-cmd">hg diff</command> command generates path names
563 in this form, and the <command role="hg-cmd">hg
564 import</command> command and MQ expect patches to have a
565 strip count of one.</para>
567 <para id="x_3eb">If you receive a patch from someone that you want to add
568 to your patch queue, and the patch needs a strip count other
569 than one, you cannot just <command
570 role="hg-ext-mq">qimport</command> the patch, because
571 <command role="hg-ext-mq">qimport</command> does not yet have
572 a <literal>-p</literal> option (see <ulink role="hg-bug"
573 url="http://www.selenic.com/mercurial/bts/issue311">issue
574 311</ulink>). Your best bet is to <command
575 role="hg-ext-mq">qnew</command> a patch of your own, then
576 use <command>patch -pN</command> to apply their patch,
577 followed by <command role="hg-cmd">hg addremove</command> to
578 pick up any files added or removed by the patch, followed by
579 <command role="hg-ext-mq">hg qrefresh</command>. This
580 complexity may become unnecessary; see <ulink role="hg-bug"
581 url="http://www.selenic.com/mercurial/bts/issue311">issue
582 311</ulink> for details.
583 </para>
584 </sect2>
586 <sect2>
587 <title>Strategies for applying a patch</title>
589 <para id="x_3ec">When <command>patch</command> applies a hunk, it tries a
590 handful of successively less accurate strategies to try to
591 make the hunk apply. This falling-back technique often makes
592 it possible to take a patch that was generated against an old
593 version of a file, and apply it against a newer version of
594 that file.</para>
596 <para id="x_3ed">First, <command>patch</command> tries an exact match,
597 where the line numbers, the context, and the text to be
598 modified must apply exactly. If it cannot make an exact
599 match, it tries to find an exact match for the context,
600 without honouring the line numbering information. If this
601 succeeds, it prints a line of output saying that the hunk was
602 applied, but at some <emphasis>offset</emphasis> from the
603 original line number.</para>
605 <para id="x_3ee">If a context-only match fails, <command>patch</command>
606 removes the first and last lines of the context, and tries a
607 <emphasis>reduced</emphasis> context-only match. If the hunk
608 with reduced context succeeds, it prints a message saying that
609 it applied the hunk with a <emphasis>fuzz factor</emphasis>
610 (the number after the fuzz factor indicates how many lines of
611 context <command>patch</command> had to trim before the patch
612 applied).</para>
614 <para id="x_3ef">When neither of these techniques works,
615 <command>patch</command> prints a message saying that the hunk
616 in question was rejected. It saves rejected hunks (also
617 simply called <quote>rejects</quote>) to a file with the same
618 name, and an added <filename role="special">.rej</filename>
619 extension. It also saves an unmodified copy of the file with
620 a <filename role="special">.orig</filename> extension; the
621 copy of the file without any extensions will contain any
622 changes made by hunks that <emphasis>did</emphasis> apply
623 cleanly. If you have a patch that modifies
624 <filename>foo</filename> with six hunks, and one of them fails
625 to apply, you will have: an unmodified
626 <filename>foo.orig</filename>, a <filename>foo.rej</filename>
627 containing one hunk, and <filename>foo</filename>, containing
628 the changes made by the five successful hunks.</para>
629 </sect2>
631 <sect2>
632 <title>Some quirks of patch representation</title>
634 <para id="x_3f0">There are a few useful things to know about how
635 <command>patch</command> works with files.</para>
636 <itemizedlist>
637 <listitem><para id="x_3f1">This should already be obvious, but
638 <command>patch</command> cannot handle binary
639 files.</para>
640 </listitem>
641 <listitem><para id="x_3f2">Neither does it care about the executable bit;
642 it creates new files as readable, but not
643 executable.</para>
644 </listitem>
645 <listitem><para id="x_3f3"><command>patch</command> treats the removal of
646 a file as a diff between the file to be removed and the
647 empty file. So your idea of <quote>I deleted this
648 file</quote> looks like <quote>every line of this file
649 was deleted</quote> in a patch.</para>
650 </listitem>
651 <listitem><para id="x_3f4">It treats the addition of a file as a diff
652 between the empty file and the file to be added. So in a
653 patch, your idea of <quote>I added this file</quote> looks
654 like <quote>every line of this file was
655 added</quote>.</para>
656 </listitem>
657 <listitem><para id="x_3f5">It treats a renamed file as the removal of the
658 old name, and the addition of the new name. This means
659 that renamed files have a big footprint in patches. (Note
660 also that Mercurial does not currently try to infer when
661 files have been renamed or copied in a patch.)</para>
662 </listitem>
663 <listitem><para id="x_3f6"><command>patch</command> cannot represent
664 empty files, so you cannot use a patch to represent the
665 notion <quote>I added this empty file to the
666 tree</quote>.</para>
667 </listitem></itemizedlist>
668 </sect2>
670 <sect2>
671 <title>Beware the fuzz</title>
673 <para id="x_3f7">While applying a hunk at an offset, or with a fuzz factor,
674 will often be completely successful, these inexact techniques
675 naturally leave open the possibility of corrupting the patched
676 file. The most common cases typically involve applying a
677 patch twice, or at an incorrect location in the file. If
678 <command>patch</command> or <command
679 role="hg-ext-mq">qpush</command> ever mentions an offset or
680 fuzz factor, you should make sure that the modified files are
681 correct afterwards.</para>
683 <para id="x_3f8">It's often a good idea to refresh a patch that has applied
684 with an offset or fuzz factor; refreshing the patch generates
685 new context information that will make it apply cleanly. I
686 say <quote>often,</quote> not <quote>always,</quote> because
687 sometimes refreshing a patch will make it fail to apply
688 against a different revision of the underlying files. In some
689 cases, such as when you're maintaining a patch that must sit
690 on top of multiple versions of a source tree, it's acceptable
691 to have a patch apply with some fuzz, provided you've verified
692 the results of the patching process in such cases.</para>
693 </sect2>
695 <sect2>
696 <title>Handling rejection</title>
698 <para id="x_3f9">If <command role="hg-ext-mq">qpush</command> fails to
699 apply a patch, it will print an error message and exit. If it
700 has left <filename role="special">.rej</filename> files
701 behind, it is usually best to fix up the rejected hunks before
702 you push more patches or do any further work.</para>
704 <para id="x_3fa">If your patch <emphasis>used to</emphasis> apply cleanly,
705 and no longer does because you've changed the underlying code
706 that your patches are based on, Mercurial Queues can help; see
707 <xref linkend="sec:mq:merge"/> for details.</para>
709 <para id="x_3fb">Unfortunately, there aren't any great techniques for
710 dealing with rejected hunks. Most often, you'll need to view
711 the <filename role="special">.rej</filename> file and edit the
712 target file, applying the rejected hunks by hand.</para>
714 <para id="x_3fd">A Linux kernel hacker, Chris Mason (the author
715 of Mercurial Queues), wrote a tool called
716 <command>mpatch</command> (<ulink
717 url="http://oss.oracle.com/~mason/mpatch/">http://oss.oracle.com/~mason/mpatch/</ulink>),
718 which takes a simple approach to automating the application of
719 hunks rejected by <command>patch</command>. The
720 <command>mpatch</command> command can help with four common
721 reasons that a hunk may be rejected:</para>
723 <itemizedlist>
724 <listitem><para id="x_3fe">The context in the middle of a hunk has
725 changed.</para>
726 </listitem>
727 <listitem><para id="x_3ff">A hunk is missing some context at the
728 beginning or end.</para>
729 </listitem>
730 <listitem><para id="x_400">A large hunk might apply better&emdash;either
731 entirely or in part&emdash;if it was broken up into
732 smaller hunks.</para>
733 </listitem>
734 <listitem><para id="x_401">A hunk removes lines with slightly different
735 content than those currently present in the file.</para>
736 </listitem></itemizedlist>
738 <para id="x_402">If you use <command>mpatch</command>, you
739 should be doubly careful to check your results when you're
740 done. In fact, <command>mpatch</command> enforces this method
741 of double-checking the tool's output, by automatically
742 dropping you into a merge program when it has done its job, so
743 that you can verify its work and finish off any remaining
744 merges.</para>
745 </sect2>
746 </sect1>
748 <sect1>
749 <title>More on patch management</title>
751 <para id="x_6db">As you grow familiar with MQ, you will find yourself wanting
752 to perform other kinds of patch management operations.</para>
754 <sect2>
755 <title>Deleting unwanted patches</title>
757 <para id="x_6dc">If you want to get rid of a patch, use the <command
758 role="hg-ext-mq">hg qdelete</command> command to delete the
759 patch file and remove its entry from the patch series. If you
760 try to delete a patch that is still applied, <command
761 role="hg-ext-mq">hg qdelete</command> will refuse.</para>
763 &interaction.ch11-qdelete.go;
764 </sect2>
766 <sect2>
767 <title>Converting to and from permanent revisions</title>
769 <para id="x_6dd">Once you're done working on a patch and want to
770 turn it into a permanent changeset, use the <command
771 role="hg-ext-mq">hg qfinish</command> command. Pass a revision
772 to the command to identify the patch that you want to turn into
773 a regular changeset; this patch must already be applied.</para>
775 &interaction.ch11-qdelete.convert;
777 <para id="x_6e0">The <command role="hg-ext-mq">hg qfinish</command> command
778 accepts an <option>--all</option> or <option>-a</option>
779 option, which turns all applied patches into regular
780 changesets.</para>
782 <para id="x_6de">It is also possible to turn an existing changeset into a
783 patch, by passing the <option>-r</option> option to <command
784 role="hg-ext-mq">hg qimport</command>.</para>
786 &interaction.ch11-qdelete.import;
788 <para id="x_6df">Note that it only makes sense to convert a changeset into
789 a patch if you have not propagated that changeset into any
790 other repositories. The imported changeset's ID will change
791 every time you refresh the patch, which will make Mercurial
792 treat it as unrelated to the original changeset if you have
793 pushed it somewhere else.</para>
794 </sect2>
795 </sect1>
797 <sect1 id="sec:mq:perf">
798 <title>Getting the best performance out of MQ</title>
800 <para id="x_403">MQ is very efficient at handling a large number
801 of patches. I ran some performance experiments in mid-2006 for a
802 talk that I gave at the 2006 EuroPython conference (on modern
803 hardware, you should expect better performance than you'll see
804 below). I used as my data set the Linux 2.6.17-mm1 patch
805 series, which consists of 1,738 patches. I applied these on top
806 of a Linux kernel repository containing all 27,472 revisions
807 between Linux 2.6.12-rc2 and Linux 2.6.17.</para>
809 <para id="x_404">On my old, slow laptop, I was able to <command
810 role="hg-cmd">hg qpush <option
811 role="hg-ext-mq-cmd-qpush-opt">-a</option></command> all
812 1,738 patches in 3.5 minutes, and <command role="hg-cmd">hg qpop
813 <option role="hg-ext-mq-cmd-qpop-opt">-a</option></command>
814 them all in 30 seconds. (On a newer laptop, the time to push
815 all patches dropped to two minutes.) I could <command
816 role="hg-ext-mq">qrefresh</command> one of the biggest patches
817 (which made 22,779 lines of changes to 287 files) in 6.6
818 seconds.</para>
820 <para id="x_405">Clearly, MQ is well suited to working in large trees, but
821 there are a few tricks you can use to get the best performance
822 of it.</para>
824 <para id="x_406">First of all, try to <quote>batch</quote> operations
825 together. Every time you run <command
826 role="hg-ext-mq">qpush</command> or <command
827 role="hg-ext-mq">qpop</command>, these commands scan the
828 working directory once to make sure you haven't made some
829 changes and then forgotten to run <command
830 role="hg-ext-mq">qrefresh</command>. On a small tree, the
831 time that this scan takes is unnoticeable. However, on a
832 medium-sized tree (containing tens of thousands of files), it
833 can take a second or more.</para>
835 <para id="x_407">The <command role="hg-ext-mq">qpush</command> and <command
836 role="hg-ext-mq">qpop</command> commands allow you to push and
837 pop multiple patches at a time. You can identify the
838 <quote>destination patch</quote> that you want to end up at.
839 When you <command role="hg-ext-mq">qpush</command> with a
840 destination specified, it will push patches until that patch is
841 at the top of the applied stack. When you <command
842 role="hg-ext-mq">qpop</command> to a destination, MQ will pop
843 patches until the destination patch is at the top.</para>
845 <para id="x_408">You can identify a destination patch using either the name
846 of the patch, or by number. If you use numeric addressing,
847 patches are counted from zero; this means that the first patch
848 is zero, the second is one, and so on.</para>
849 </sect1>
851 <sect1 id="sec:mq:merge">
852 <title>Updating your patches when the underlying code
853 changes</title>
855 <para id="x_409">It's common to have a stack of patches on top of an
856 underlying repository that you don't modify directly. If you're
857 working on changes to third-party code, or on a feature that is
858 taking longer to develop than the rate of change of the code
859 beneath, you will often need to sync up with the underlying
860 code, and fix up any hunks in your patches that no longer apply.
861 This is called <emphasis>rebasing</emphasis> your patch
862 series.</para>
864 <para id="x_40a">The simplest way to do this is to <command role="hg-cmd">hg
865 qpop <option role="hg-ext-mq-cmd-qpop-opt">hg
866 -a</option></command> your patches, then <command
867 role="hg-cmd">hg pull</command> changes into the underlying
868 repository, and finally <command role="hg-cmd">hg qpush <option
869 role="hg-ext-mq-cmd-qpop-opt">-a</option></command> your
870 patches again. MQ will stop pushing any time it runs across a
871 patch that fails to apply during conflicts, allowing you to fix
872 your conflicts, <command role="hg-ext-mq">qrefresh</command> the
873 affected patch, and continue pushing until you have fixed your
874 entire stack.</para>
876 <para id="x_40b">This approach is easy to use and works well if you don't
877 expect changes to the underlying code to affect how well your
878 patches apply. If your patch stack touches code that is modified
879 frequently or invasively in the underlying repository, however,
880 fixing up rejected hunks by hand quickly becomes
881 tiresome.</para>
883 <para id="x_40c">It's possible to partially automate the rebasing process.
884 If your patches apply cleanly against some revision of the
885 underlying repo, MQ can use this information to help you to
886 resolve conflicts between your patches and a different
887 revision.</para>
889 <para id="x_40d">The process is a little involved.</para>
890 <orderedlist>
891 <listitem><para id="x_40e">To begin, <command role="hg-cmd">hg qpush
892 -a</command> all of your patches on top of the revision
893 where you know that they apply cleanly.</para>
894 </listitem>
895 <listitem><para id="x_40f">Save a backup copy of your patch directory using
896 <command role="hg-cmd">hg qsave <option
897 role="hg-ext-mq-cmd-qsave-opt">hg -e</option> <option
898 role="hg-ext-mq-cmd-qsave-opt">hg -c</option></command>.
899 This prints the name of the directory that it has saved the
900 patches in. It will save the patches to a directory called
901 <filename role="special"
902 class="directory">.hg/patches.N</filename>, where
903 <literal>N</literal> is a small integer. It also commits a
904 <quote>save changeset</quote> on top of your applied
905 patches; this is for internal book-keeping, and records the
906 states of the <filename role="special">series</filename> and
907 <filename role="special">status</filename> files.</para>
908 </listitem>
909 <listitem><para id="x_410">Use <command role="hg-cmd">hg pull</command> to
910 bring new changes into the underlying repository. (Don't
911 run <command role="hg-cmd">hg pull -u</command>; see below
912 for why.)</para>
913 </listitem>
914 <listitem><para id="x_411">Update to the new tip revision, using <command
915 role="hg-cmd">hg update <option
916 role="hg-opt-update">-C</option></command> to override
917 the patches you have pushed.</para>
918 </listitem>
919 <listitem><para id="x_412">Merge all patches using <command>hg qpush -m
920 -a</command>. The <option
921 role="hg-ext-mq-cmd-qpush-opt">-m</option> option to
922 <command role="hg-ext-mq">qpush</command> tells MQ to
923 perform a three-way merge if the patch fails to
924 apply.</para>
925 </listitem></orderedlist>
927 <para id="x_413">During the <command role="hg-cmd">hg qpush <option
928 role="hg-ext-mq-cmd-qpush-opt">hg -m</option></command>,
929 each patch in the <filename role="special">series</filename>
930 file is applied normally. If a patch applies with fuzz or
931 rejects, MQ looks at the queue you <command
932 role="hg-ext-mq">qsave</command>d, and performs a three-way
933 merge with the corresponding changeset. This merge uses
934 Mercurial's normal merge machinery, so it may pop up a GUI merge
935 tool to help you to resolve problems.</para>
937 <para id="x_414">When you finish resolving the effects of a patch, MQ
938 refreshes your patch based on the result of the merge.</para>
940 <para id="x_415">At the end of this process, your repository will have one
941 extra head from the old patch queue, and a copy of the old patch
942 queue will be in <filename role="special"
943 class="directory">.hg/patches.N</filename>. You can remove the
944 extra head using <command role="hg-cmd">hg qpop -a -n
945 patches.N</command> or <command role="hg-cmd">hg
946 strip</command>. You can delete <filename role="special"
947 class="directory">.hg/patches.N</filename> once you are sure
948 that you no longer need it as a backup.</para>
949 </sect1>
951 <sect1>
952 <title>Identifying patches</title>
954 <para id="x_416">MQ commands that work with patches let you refer to a patch
955 either by using its name or by a number. By name is obvious
956 enough; pass the name <filename>foo.patch</filename> to <command
957 role="hg-ext-mq">qpush</command>, for example, and it will
958 push patches until <filename>foo.patch</filename> is
959 applied.</para>
961 <para id="x_417">As a shortcut, you can refer to a patch using both a name
962 and a numeric offset; <literal>foo.patch-2</literal> means
963 <quote>two patches before <literal>foo.patch</literal></quote>,
964 while <literal>bar.patch+4</literal> means <quote>four patches
965 after <literal>bar.patch</literal></quote>.</para>
967 <para id="x_418">Referring to a patch by index isn't much different. The
968 first patch printed in the output of <command
969 role="hg-ext-mq">qseries</command> is patch zero (yes, it's
970 one of those start-at-zero counting systems); the second is
971 patch one; and so on.</para>
973 <para id="x_419">MQ also makes it easy to work with patches when you are
974 using normal Mercurial commands. Every command that accepts a
975 changeset ID will also accept the name of an applied patch. MQ
976 augments the tags normally in the repository with an eponymous
977 one for each applied patch. In addition, the special tags
978 <literal role="tag">qbase</literal> and
979 <literal role="tag">qtip</literal> identify
980 the <quote>bottom-most</quote> and topmost applied patches,
981 respectively.</para>
983 <para id="x_41a">These additions to Mercurial's normal tagging capabilities
984 make dealing with patches even more of a breeze.</para>
985 <itemizedlist>
986 <listitem><para id="x_41b">Want to patchbomb a mailing list with your
987 latest series of changes?</para>
988 <programlisting>hg email qbase:qtip</programlisting>
989 <para id="x_41c"> (Don't know what <quote>patchbombing</quote> is? See
990 <xref linkend="sec:hgext:patchbomb"/>.)</para>
991 </listitem>
992 <listitem><para id="x_41d">Need to see all of the patches since
993 <literal>foo.patch</literal> that have touched files in a
994 subdirectory of your tree?</para>
995 <programlisting>hg log -r foo.patch:qtip subdir</programlisting>
996 </listitem>
997 </itemizedlist>
999 <para id="x_41e">Because MQ makes the names of patches available to the rest
1000 of Mercurial through its normal internal tag machinery, you
1001 don't need to type in the entire name of a patch when you want
1002 to identify it by name.</para>
1004 <para id="x_41f">Another nice consequence of representing patch names as tags
1005 is that when you run the <command role="hg-cmd">hg log</command>
1006 command, it will display a patch's name as a tag, simply as part
1007 of its normal output. This makes it easy to visually
1008 distinguish applied patches from underlying
1009 <quote>normal</quote> revisions. The following example shows a
1010 few normal Mercurial commands in use with applied
1011 patches.</para>
1013 &interaction.mq.id.output;
1014 </sect1>
1016 <sect1>
1017 <title>Useful things to know about</title>
1019 <para id="x_420">There are a number of aspects of MQ usage that don't fit
1020 tidily into sections of their own, but that are good to know.
1021 Here they are, in one place.</para>
1023 <itemizedlist>
1024 <listitem><para id="x_421">Normally, when you <command
1025 role="hg-ext-mq">qpop</command> a patch and <command
1026 role="hg-ext-mq">qpush</command> it again, the changeset
1027 that represents the patch after the pop/push will have a
1028 <emphasis>different identity</emphasis> than the changeset
1029 that represented the hash beforehand. See <xref
1030 linkend="sec:mqref:cmd:qpush"/> for
1031 information as to why this is.</para>
1032 </listitem>
1033 <listitem><para id="x_422">It's not a good idea to <command
1034 role="hg-cmd">hg merge</command> changes from another
1035 branch with a patch changeset, at least if you want to
1036 maintain the <quote>patchiness</quote> of that changeset and
1037 changesets below it on the patch stack. If you try to do
1038 this, it will appear to succeed, but MQ will become
1039 confused.</para>
1040 </listitem></itemizedlist>
1041 </sect1>
1043 <sect1 id="sec:mq:repo">
1044 <title>Managing patches in a repository</title>
1046 <para id="x_423">Because MQ's <filename role="special"
1047 class="directory">.hg/patches</filename> directory resides
1048 outside a Mercurial repository's working directory, the
1049 <quote>underlying</quote> Mercurial repository knows nothing
1050 about the management or presence of patches.</para>
1052 <para id="x_424">This presents the interesting possibility of managing the
1053 contents of the patch directory as a Mercurial repository in its
1054 own right. This can be a useful way to work. For example, you
1055 can work on a patch for a while, <command
1056 role="hg-ext-mq">qrefresh</command> it, then <command
1057 role="hg-cmd">hg commit</command> the current state of the
1058 patch. This lets you <quote>roll back</quote> to that version
1059 of the patch later on.</para>
1061 <para id="x_425">You can then share different versions of the same patch
1062 stack among multiple underlying repositories. I use this when I
1063 am developing a Linux kernel feature. I have a pristine copy of
1064 my kernel sources for each of several CPU architectures, and a
1065 cloned repository under each that contains the patches I am
1066 working on. When I want to test a change on a different
1067 architecture, I push my current patches to the patch repository
1068 associated with that kernel tree, pop and push all of my
1069 patches, and build and test that kernel.</para>
1071 <para id="x_426">Managing patches in a repository makes it possible for
1072 multiple developers to work on the same patch series without
1073 colliding with each other, all on top of an underlying source
1074 base that they may or may not control.</para>
1076 <sect2>
1077 <title>MQ support for patch repositories</title>
1079 <para id="x_427">MQ helps you to work with the <filename role="special"
1080 class="directory">.hg/patches</filename> directory as a
1081 repository; when you prepare a repository for working with
1082 patches using <command role="hg-ext-mq">qinit</command>, you
1083 can pass the <option role="hg-ext-mq-cmd-qinit-opt">hg
1084 -c</option> option to create the <filename role="special"
1085 class="directory">.hg/patches</filename> directory as a
1086 Mercurial repository.</para>
1088 <note>
1089 <para id="x_428"> If you forget to use the <option
1090 role="hg-ext-mq-cmd-qinit-opt">hg -c</option> option, you
1091 can simply go into the <filename role="special"
1092 class="directory">.hg/patches</filename> directory at any
1093 time and run <command role="hg-cmd">hg init</command>.
1094 Don't forget to add an entry for the <filename
1095 role="special">status</filename> file to the <filename
1096 role="special">.hgignore</filename> file, though</para>
1098 <para id="x_429"> (<command role="hg-cmd">hg qinit <option
1099 role="hg-ext-mq-cmd-qinit-opt">hg -c</option></command>
1100 does this for you automatically); you
1101 <emphasis>really</emphasis> don't want to manage the
1102 <filename role="special">status</filename> file.</para>
1103 </note>
1105 <para id="x_42a">As a convenience, if MQ notices that the <filename
1106 class="directory">.hg/patches</filename> directory is a
1107 repository, it will automatically <command role="hg-cmd">hg
1108 add</command> every patch that you create and import.</para>
1110 <para id="x_42b">MQ provides a shortcut command, <command
1111 role="hg-ext-mq">qcommit</command>, that runs <command
1112 role="hg-cmd">hg commit</command> in the <filename
1113 role="special" class="directory">.hg/patches</filename>
1114 directory. This saves some bothersome typing.</para>
1116 <para id="x_42c">Finally, as a convenience to manage the patch directory,
1117 you can define the alias <command>mq</command> on Unix
1118 systems. For example, on Linux systems using the
1119 <command>bash</command> shell, you can include the following
1120 snippet in your <filename
1121 role="home">~/.bashrc</filename>.</para>
1123 <programlisting>alias mq=`hg -R $(hg root)/.hg/patches'</programlisting>
1125 <para id="x_42d">You can then issue commands of the form <command>mq
1126 pull</command> from the main repository.</para>
1127 </sect2>
1129 <sect2>
1130 <title>A few things to watch out for</title>
1132 <para id="x_42e">MQ's support for working with a repository full of patches
1133 is limited in a few small respects.</para>
1135 <para id="x_42f">MQ cannot automatically detect changes that you make to
1136 the patch directory. If you <command role="hg-cmd">hg
1137 pull</command>, manually edit, or <command role="hg-cmd">hg
1138 update</command> changes to patches or the <filename
1139 role="special">series</filename> file, you will have to
1140 <command role="hg-cmd">hg qpop <option
1141 role="hg-ext-mq-cmd-qpop-opt">-a</option></command> and
1142 then <command role="hg-cmd">hg qpush <option
1143 role="hg-ext-mq-cmd-qpush-opt">-a</option></command> in
1144 the underlying repository to see those changes show up there.
1145 If you forget to do this, you can confuse MQ's idea of which
1146 patches are applied.</para>
1148 </sect2>
1149 </sect1>
1150 <sect1 id="sec:mq:tools">
1151 <title>Third party tools for working with patches</title>
1153 <para id="x_430">Once you've been working with patches for a while, you'll
1154 find yourself hungry for tools that will help you to understand
1155 and manipulate the patches you're dealing with.</para>
1157 <para id="x_431">The <command>diffstat</command> command
1158 <citation>web:diffstat</citation> generates a histogram of the
1159 modifications made to each file in a patch. It provides a good
1160 way to <quote>get a sense of</quote> a patch&emdash;which files
1161 it affects, and how much change it introduces to each file and
1162 as a whole. (I find that it's a good idea to use
1163 <command>diffstat</command>'s <option
1164 role="cmd-opt-diffstat">-p</option> option as a matter of
1165 course, as otherwise it will try to do clever things with
1166 prefixes of file names that inevitably confuse at least
1167 me.)</para>
1169 &interaction.mq.tools.tools;
1171 <para id="x_432">The <literal role="package">patchutils</literal> package
1172 <citation>web:patchutils</citation> is invaluable. It provides a
1173 set of small utilities that follow the <quote>Unix
1174 philosophy;</quote> each does one useful thing with a patch.
1175 The <literal role="package">patchutils</literal> command I use
1176 most is <command>filterdiff</command>, which extracts subsets
1177 from a patch file. For example, given a patch that modifies
1178 hundreds of files across dozens of directories, a single
1179 invocation of <command>filterdiff</command> can generate a
1180 smaller patch that only touches files whose names match a
1181 particular glob pattern. See <xref
1182 linkend="mq-collab:tips:interdiff"/> for another
1183 example.</para>
1185 </sect1>
1186 <sect1>
1187 <title>Good ways to work with patches</title>
1189 <para id="x_433">Whether you are working on a patch series to submit to a
1190 free software or open source project, or a series that you
1191 intend to treat as a sequence of regular changesets when you're
1192 done, you can use some simple techniques to keep your work well
1193 organized.</para>
1195 <para id="x_434">Give your patches descriptive names. A good name for a
1196 patch might be <filename>rework-device-alloc.patch</filename>,
1197 because it will immediately give you a hint what the purpose of
1198 the patch is. Long names shouldn't be a problem; you won't be
1199 typing the names often, but you <emphasis>will</emphasis> be
1200 running commands like <command
1201 role="hg-ext-mq">qapplied</command> and <command
1202 role="hg-ext-mq">qtop</command> over and over. Good naming
1203 becomes especially important when you have a number of patches
1204 to work with, or if you are juggling a number of different tasks
1205 and your patches only get a fraction of your attention.</para>
1207 <para id="x_435">Be aware of what patch you're working on. Use the <command
1208 role="hg-ext-mq">qtop</command> command and skim over the text
1209 of your patches frequently&emdash;for example, using <command
1210 role="hg-cmd">hg tip <option
1211 role="hg-opt-tip">-p</option></command>)&emdash;to be sure
1212 of where you stand. I have several times worked on and <command
1213 role="hg-ext-mq">qrefresh</command>ed a patch other than the
1214 one I intended, and it's often tricky to migrate changes into
1215 the right patch after making them in the wrong one.</para>
1217 <para id="x_436">For this reason, it is very much worth investing a little
1218 time to learn how to use some of the third-party tools I
1219 described in <xref linkend="sec:mq:tools"/>,
1220 particularly
1221 <command>diffstat</command> and <command>filterdiff</command>.
1222 The former will give you a quick idea of what changes your patch
1223 is making, while the latter makes it easy to splice hunks
1224 selectively out of one patch and into another.</para>
1226 </sect1>
1227 <sect1>
1228 <title>MQ cookbook</title>
1230 <sect2>
1231 <title>Manage <quote>trivial</quote> patches</title>
1233 <para id="x_437">Because the overhead of dropping files into a new
1234 Mercurial repository is so low, it makes a lot of sense to
1235 manage patches this way even if you simply want to make a few
1236 changes to a source tarball that you downloaded.</para>
1238 <para id="x_438">Begin by downloading and unpacking the source tarball, and
1239 turning it into a Mercurial repository.</para>
1241 &interaction.mq.tarball.download;
1243 <para id="x_439">Continue by creating a patch stack and making your
1244 changes.</para>
1246 &interaction.mq.tarball.qinit;
1248 <para id="x_43a">Let's say a few weeks or months pass, and your package
1249 author releases a new version. First, bring their changes
1250 into the repository.</para>
1252 &interaction.mq.tarball.newsource;
1254 <para id="x_43b">The pipeline starting with <command role="hg-cmd">hg
1255 locate</command> above deletes all files in the working
1256 directory, so that <command role="hg-cmd">hg
1257 commit</command>'s <option
1258 role="hg-opt-commit">--addremove</option> option can
1259 actually tell which files have really been removed in the
1260 newer version of the source.</para>
1262 <para id="x_43c">Finally, you can apply your patches on top of the new
1263 tree.</para>
1265 &interaction.mq.tarball.repush;
1266 </sect2>
1268 <sect2 id="sec:mq:combine">
1269 <title>Combining entire patches</title>
1271 <para id="x_43d">MQ provides a command, <command
1272 role="hg-ext-mq">qfold</command> that lets you combine
1273 entire patches. This <quote>folds</quote> the patches you
1274 name, in the order you name them, into the topmost applied
1275 patch, and concatenates their descriptions onto the end of its
1276 description. The patches that you fold must be unapplied
1277 before you fold them.</para>
1279 <para id="x_43e">The order in which you fold patches matters. If your
1280 topmost applied patch is <literal>foo</literal>, and you
1281 <command role="hg-ext-mq">qfold</command>
1282 <literal>bar</literal> and <literal>quux</literal> into it,
1283 you will end up with a patch that has the same effect as if
1284 you applied first <literal>foo</literal>, then
1285 <literal>bar</literal>, followed by
1286 <literal>quux</literal>.</para>
1287 </sect2>
1289 <sect2>
1290 <title>Merging part of one patch into another</title>
1292 <para id="x_43f">Merging <emphasis>part</emphasis> of one patch into
1293 another is more difficult than combining entire
1294 patches.</para>
1296 <para id="x_440">If you want to move changes to entire files, you can use
1297 <command>filterdiff</command>'s <option
1298 role="cmd-opt-filterdiff">-i</option> and <option
1299 role="cmd-opt-filterdiff">-x</option> options to choose the
1300 modifications to snip out of one patch, concatenating its
1301 output onto the end of the patch you want to merge into. You
1302 usually won't need to modify the patch you've merged the
1303 changes from. Instead, MQ will report some rejected hunks
1304 when you <command role="hg-ext-mq">qpush</command> it (from
1305 the hunks you moved into the other patch), and you can simply
1306 <command role="hg-ext-mq">qrefresh</command> the patch to drop
1307 the duplicate hunks.</para>
1309 <para id="x_441">If you have a patch that has multiple hunks modifying a
1310 file, and you only want to move a few of those hunks, the job
1311 becomes more messy, but you can still partly automate it. Use
1312 <command>lsdiff -nvv</command> to print some metadata about
1313 the patch.</para>
1315 &interaction.mq.tools.lsdiff;
1317 <para id="x_442">This command prints three different kinds of
1318 number:</para>
1319 <itemizedlist>
1320 <listitem><para id="x_443">(in the first column) a <emphasis>file
1321 number</emphasis> to identify each file modified in the
1322 patch;</para>
1323 </listitem>
1324 <listitem><para id="x_444">(on the next line, indented) the line number
1325 within a modified file where a hunk starts; and</para>
1326 </listitem>
1327 <listitem><para id="x_445">(on the same line) a <emphasis>hunk
1328 number</emphasis> to identify that hunk.</para>
1329 </listitem></itemizedlist>
1331 <para id="x_446">You'll have to use some visual inspection, and reading of
1332 the patch, to identify the file and hunk numbers you'll want,
1333 but you can then pass them to to
1334 <command>filterdiff</command>'s <option
1335 role="cmd-opt-filterdiff">--files</option> and <option
1336 role="cmd-opt-filterdiff">--hunks</option> options, to
1337 select exactly the file and hunk you want to extract.</para>
1339 <para id="x_447">Once you have this hunk, you can concatenate it onto the
1340 end of your destination patch and continue with the remainder
1341 of <xref linkend="sec:mq:combine"/>.</para>
1343 </sect2>
1344 </sect1>
1345 <sect1>
1346 <title>Differences between quilt and MQ</title>
1348 <para id="x_448">If you are already familiar with quilt, MQ provides a
1349 similar command set. There are a few differences in the way
1350 that it works.</para>
1352 <para id="x_449">You will already have noticed that most quilt commands have
1353 MQ counterparts that simply begin with a
1354 <quote><literal>q</literal></quote>. The exceptions are quilt's
1355 <literal>add</literal> and <literal>remove</literal> commands,
1356 the counterparts for which are the normal Mercurial <command
1357 role="hg-cmd">hg add</command> and <command role="hg-cmd">hg
1358 remove</command> commands. There is no MQ equivalent of the
1359 quilt <literal>edit</literal> command.</para>
1361 </sect1>
1362 </chapter>
1364 <!--
1365 local variables:
1366 sgml-parent-document: ("00book.xml" "book" "chapter")
1367 end:
1368 -->