hgbook
view en/ch12-mq.xml @ 646:c2cefd9f9893
Update Chinese translation
| author | Dongsheng Song <dongsheng.song@gmail.com> |
|---|---|
| date | Wed Mar 18 19:50:36 2009 +0800 (2009-03-18) |
| parents | cfdb601a3c8b |
| children | d0160b0b1a9e |
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>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>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>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>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>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 section <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>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>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>During the late 1990s, several Linux kernel developers
68 started to maintain <quote>patch series</quote> that modified
69 the behaviour 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>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>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>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>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>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>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>
122 </sect2>
123 <sect2 id="sec.mq.quilt-mq">
124 <title>From patchwork quilt to Mercurial Queues</title>
126 <para>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 behaviour to Mercurial.</para>
130 <para>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>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>I cannot overstate the value that MQ offers through the
147 unification of patches and revision control.</para>
149 <para>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>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>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>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>
185 </sect1>
186 <sect1 id="sec.mq.patch">
187 <title>Understanding patches</title>
189 <para>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>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>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>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>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>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>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>We will return to some of the more subtle aspects of patches
244 later (in section <xref linkend="sec.mq.adv-patch"/>), but you
245 should have
246 enough information now to use MQ.</para>
248 </sect1>
249 <sect1 id="sec.mq.start">
250 <title>Getting started with Mercurial Queues</title>
252 <para>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] hgext.mq =</programlisting>
261 <para>Once the extension is enabled, it will make a number of new
262 commands available. To verify that the extension is working,
263 you can use <command role="hg-cmd">hg help</command> to see if
264 the <command role="hg-ext-mq">qinit</command> command is now
265 available.</para>
267 &interaction.mq.qinit-help.help;
269 <para>You can use MQ with <emphasis>any</emphasis> Mercurial
270 repository, and its commands only operate within that
271 repository. To get started, simply prepare the repository using
272 the <command role="hg-ext-mq">qinit</command> command.</para>
274 &interaction.mq.tutorial.qinit;
276 <para>This command creates an empty directory called <filename
277 role="special" class="directory">.hg/patches</filename>, where
278 MQ will keep its metadata. As with many Mercurial commands, the
279 <command role="hg-ext-mq">qinit</command> command prints nothing
280 if it succeeds.</para>
282 <sect2>
283 <title>Creating a new patch</title>
285 <para>To begin work on a new patch, use the <command
286 role="hg-ext-mq">qnew</command> command. This command takes
287 one argument, the name of the patch to create.</para>
289 <para>MQ will use this as the name of an actual file in the
290 <filename role="special"
291 class="directory">.hg/patches</filename> directory, as you
292 can see below.</para>
294 &interaction.mq.tutorial.qnew;
296 <para>Also newly present in the <filename role="special"
297 class="directory">.hg/patches</filename> directory are two
298 other files, <filename role="special">series</filename> and
299 <filename role="special">status</filename>. The <filename
300 role="special">series</filename> file lists all of the
301 patches that MQ knows about for this repository, with one
302 patch per line. Mercurial uses the <filename
303 role="special">status</filename> file for internal
304 book-keeping; it tracks all of the patches that MQ has
305 <emphasis>applied</emphasis> in this repository.</para>
307 <note>
308 <para> You may sometimes want to edit the <filename
309 role="special">series</filename> file by hand; for
310 example, to change the sequence in which some patches are
311 applied. However, manually editing the <filename
312 role="special">status</filename> file is almost always a
313 bad idea, as it's easy to corrupt MQ's idea of what is
314 happening.</para>
315 </note>
317 <para>Once you have created your new patch, you can edit files
318 in the working directory as you usually would. All of the
319 normal Mercurial commands, such as <command role="hg-cmd">hg
320 diff</command> and <command role="hg-cmd">hg
321 annotate</command>, work exactly as they did before.</para>
323 </sect2>
324 <sect2>
325 <title>Refreshing a patch</title>
327 <para>When you reach a point where you want to save your work,
328 use the <command role="hg-ext-mq">qrefresh</command> command
329 to update the patch you are working on.</para>
331 &interaction.mq.tutorial.qrefresh;
333 <para>This command folds the changes you have made in the
334 working directory into your patch, and updates its
335 corresponding changeset to contain those changes.</para>
337 <para>You can run <command role="hg-ext-mq">qrefresh</command>
338 as often as you like, so it's a good way to
339 <quote>checkpoint</quote> your work. Refresh your patch at an
340 opportune time; try an experiment; and if the experiment
341 doesn't work out, <command role="hg-cmd">hg revert</command>
342 your modifications back to the last time you refreshed.</para>
344 &interaction.mq.tutorial.qrefresh2;
346 </sect2>
347 <sect2>
348 <title>Stacking and tracking patches</title>
350 <para>Once you have finished working on a patch, or need to work
351 on another, you can use the <command
352 role="hg-ext-mq">qnew</command> command again to create a
353 new patch. Mercurial will apply this patch on top of your
354 existing patch.</para>
356 &interaction.mq.tutorial.qnew2;
357 <para>Notice that the patch contains the changes in our prior
358 patch as part of its context (you can see this more clearly in
359 the output of <command role="hg-cmd">hg
360 annotate</command>).</para>
362 <para>So far, with the exception of <command
363 role="hg-ext-mq">qnew</command> and <command
364 role="hg-ext-mq">qrefresh</command>, we've been careful to
365 only use regular Mercurial commands. However, MQ provides
366 many commands that are easier to use when you are thinking
367 about patches, as illustrated below.</para>
369 &interaction.mq.tutorial.qseries;
371 <itemizedlist>
372 <listitem><para>The <command
373 role="hg-ext-mq">qseries</command> command lists every
374 patch that MQ knows about in this repository, from oldest
375 to newest (most recently
376 <emphasis>created</emphasis>).</para>
377 </listitem>
378 <listitem><para>The <command
379 role="hg-ext-mq">qapplied</command> command lists every
380 patch that MQ has <emphasis>applied</emphasis> in this
381 repository, again from oldest to newest (most recently
382 applied).</para>
383 </listitem></itemizedlist>
385 </sect2>
386 <sect2>
387 <title>Manipulating the patch stack</title>
389 <para>The previous discussion implied that there must be a
390 difference between <quote>known</quote> and
391 <quote>applied</quote> patches, and there is. MQ can manage a
392 patch without it being applied in the repository.</para>
394 <para>An <emphasis>applied</emphasis> patch has a corresponding
395 changeset in the repository, and the effects of the patch and
396 changeset are visible in the working directory. You can undo
397 the application of a patch using the <command
398 role="hg-ext-mq">qpop</command> command. MQ still
399 <emphasis>knows about</emphasis>, or manages, a popped patch,
400 but the patch no longer has a corresponding changeset in the
401 repository, and the working directory does not contain the
402 changes made by the patch. Figure <xref
403 endterm="fig.mq.stack.caption" linkend="fig.mq.stack"/> illustrates
404 the difference between applied and tracked patches.</para>
406 <informalfigure id="fig.mq.stack">
407 <mediaobject>
408 <imageobject><imagedata fileref="images/mq-stack.png"/></imageobject>
409 <textobject><phrase>XXX add text</phrase></textobject>
410 <caption><para id="fig.mq.stack.caption">Applied and unapplied patches
411 in the MQ patch stack</para></caption>
412 </mediaobject>
413 </informalfigure>
415 <para>You can reapply an unapplied, or popped, patch using the
416 <command role="hg-ext-mq">qpush</command> command. This
417 creates a new changeset to correspond to the patch, and the
418 patch's changes once again become present in the working
419 directory. See below for examples of <command
420 role="hg-ext-mq">qpop</command> and <command
421 role="hg-ext-mq">qpush</command> in action.</para>
422 &interaction.mq.tutorial.qpop;
424 <para>Notice that once we have popped a patch or two patches,
425 the output of <command role="hg-ext-mq">qseries</command>
426 remains the same, while that of <command
427 role="hg-ext-mq">qapplied</command> has changed.</para>
430 </sect2>
431 <sect2>
432 <title>Pushing and popping many patches</title>
434 <para>While <command role="hg-ext-mq">qpush</command> and
435 <command role="hg-ext-mq">qpop</command> each operate on a
436 single patch at a time by default, you can push and pop many
437 patches in one go. The <option
438 role="hg-ext-mq-cmd-qpush-opt">hg -a</option> option to
439 <command role="hg-ext-mq">qpush</command> causes it to push
440 all unapplied patches, while the <option
441 role="hg-ext-mq-cmd-qpop-opt">-a</option> option to <command
442 role="hg-ext-mq">qpop</command> causes it to pop all applied
443 patches. (For some more ways to push and pop many patches,
444 see section <xref linkend="sec.mq.perf"/>
445 below.)</para>
447 &interaction.mq.tutorial.qpush-a;
449 </sect2>
450 <sect2>
451 <title>Safety checks, and overriding them</title>
453 <para>Several MQ commands check the working directory before
454 they do anything, and fail if they find any modifications.
455 They do this to ensure that you won't lose any changes that
456 you have made, but not yet incorporated into a patch. The
457 example below illustrates this; the <command
458 role="hg-ext-mq">qnew</command> command will not create a
459 new patch if there are outstanding changes, caused in this
460 case by the <command role="hg-cmd">hg add</command> of
461 <filename>file3</filename>.</para>
463 &interaction.mq.tutorial.add;
465 <para>Commands that check the working directory all take an
466 <quote>I know what I'm doing</quote> option, which is always
467 named <option>-f</option>. The exact meaning of
468 <option>-f</option> depends on the command. For example,
469 <command role="hg-cmd">hg qnew <option
470 role="hg-ext-mq-cmd-qnew-opt">hg -f</option></command>
471 will incorporate any outstanding changes into the new patch it
472 creates, but <command role="hg-cmd">hg qpop <option
473 role="hg-ext-mq-cmd-qpop-opt">hg -f</option></command>
474 will revert modifications to any files affected by the patch
475 that it is popping. Be sure to read the documentation for a
476 command's <option>-f</option> option before you use it!</para>
478 </sect2>
479 <sect2>
480 <title>Working on several patches at once</title>
482 <para>The <command role="hg-ext-mq">qrefresh</command> command
483 always refreshes the <emphasis>topmost</emphasis> applied
484 patch. This means that you can suspend work on one patch (by
485 refreshing it), pop or push to make a different patch the top,
486 and work on <emphasis>that</emphasis> patch for a
487 while.</para>
489 <para>Here's an example that illustrates how you can use this
490 ability. Let's say you're developing a new feature as two
491 patches. The first is a change to the core of your software,
492 and the second&emdash;layered on top of the
493 first&emdash;changes the user interface to use the code you
494 just added to the core. If you notice a bug in the core while
495 you're working on the UI patch, it's easy to fix the core.
496 Simply <command role="hg-ext-mq">qrefresh</command> the UI
497 patch to save your in-progress changes, and <command
498 role="hg-ext-mq">qpop</command> down to the core patch. Fix
499 the core bug, <command role="hg-ext-mq">qrefresh</command> the
500 core patch, and <command role="hg-ext-mq">qpush</command> back
501 to the UI patch to continue where you left off.</para>
503 </sect2>
504 </sect1>
505 <sect1 id="sec.mq.adv-patch">
506 <title>More about patches</title>
508 <para>MQ uses the GNU <command>patch</command> command to apply
509 patches, so it's helpful to know a few more detailed aspects of
510 how <command>patch</command> works, and about patches
511 themselves.</para>
513 <sect2>
514 <title>The strip count</title>
516 <para>If you look at the file headers in a patch, you will
517 notice that the pathnames usually have an extra component on
518 the front that isn't present in the actual path name. This is
519 a holdover from the way that people used to generate patches
520 (people still do this, but it's somewhat rare with modern
521 revision control tools).</para>
523 <para>Alice would unpack a tarball, edit her files, then decide
524 that she wanted to create a patch. So she'd rename her
525 working directory, unpack the tarball again (hence the need
526 for the rename), and use the <option
527 role="cmd-opt-diff">-r</option> and <option
528 role="cmd-opt-diff">-N</option> options to
529 <command>diff</command> to recursively generate a patch
530 between the unmodified directory and the modified one. The
531 result would be that the name of the unmodified directory
532 would be at the front of the left-hand path in every file
533 header, and the name of the modified directory would be at the
534 front of the right-hand path.</para>
536 <para>Since someone receiving a patch from the Alices of the net
537 would be unlikely to have unmodified and modified directories
538 with exactly the same names, the <command>patch</command>
539 command has a <option role="cmd-opt-patch">-p</option> option
540 that indicates the number of leading path name components to
541 strip when trying to apply a patch. This number is called the
542 <emphasis>strip count</emphasis>.</para>
544 <para>An option of <quote><literal>-p1</literal></quote> means
545 <quote>use a strip count of one</quote>. If
546 <command>patch</command> sees a file name
547 <filename>foo/bar/baz</filename> in a file header, it will
548 strip <filename>foo</filename> and try to patch a file named
549 <filename>bar/baz</filename>. (Strictly speaking, the strip
550 count refers to the number of <emphasis>path
551 separators</emphasis> (and the components that go with them
552 ) to strip. A strip count of one will turn
553 <filename>foo/bar</filename> into <filename>bar</filename>,
554 but <filename>/foo/bar</filename> (notice the extra leading
555 slash) into <filename>foo/bar</filename>.)</para>
557 <para>The <quote>standard</quote> strip count for patches is
558 one; almost all patches contain one leading path name
559 component that needs to be stripped. Mercurial's <command
560 role="hg-cmd">hg diff</command> command generates path names
561 in this form, and the <command role="hg-cmd">hg
562 import</command> command and MQ expect patches to have a
563 strip count of one.</para>
565 <para>If you receive a patch from someone that you want to add
566 to your patch queue, and the patch needs a strip count other
567 than one, you cannot just <command
568 role="hg-ext-mq">qimport</command> the patch, because
569 <command role="hg-ext-mq">qimport</command> does not yet have
570 a <literal>-p</literal> option (see <ulink role="hg-bug"
571 url="http://www.selenic.com/mercurial/bts/issue311">issue
572 311</ulink>). Your best bet is to <command
573 role="hg-ext-mq">qnew</command> a patch of your own, then
574 use <command>patch -pN</command> to apply their patch,
575 followed by <command role="hg-cmd">hg addremove</command> to
576 pick up any files added or removed by the patch, followed by
577 <command role="hg-ext-mq">hg qrefresh</command>. This
578 complexity may become unnecessary; see <ulink role="hg-bug"
579 url="http://www.selenic.com/mercurial/bts/issue311">issue
580 311</ulink> for details.
581 </para>
582 </sect2>
583 <sect2>
584 <title>Strategies for applying a patch</title>
586 <para>When <command>patch</command> applies a hunk, it tries a
587 handful of successively less accurate strategies to try to
588 make the hunk apply. This falling-back technique often makes
589 it possible to take a patch that was generated against an old
590 version of a file, and apply it against a newer version of
591 that file.</para>
593 <para>First, <command>patch</command> tries an exact match,
594 where the line numbers, the context, and the text to be
595 modified must apply exactly. If it cannot make an exact
596 match, it tries to find an exact match for the context,
597 without honouring the line numbering information. If this
598 succeeds, it prints a line of output saying that the hunk was
599 applied, but at some <emphasis>offset</emphasis> from the
600 original line number.</para>
602 <para>If a context-only match fails, <command>patch</command>
603 removes the first and last lines of the context, and tries a
604 <emphasis>reduced</emphasis> context-only match. If the hunk
605 with reduced context succeeds, it prints a message saying that
606 it applied the hunk with a <emphasis>fuzz factor</emphasis>
607 (the number after the fuzz factor indicates how many lines of
608 context <command>patch</command> had to trim before the patch
609 applied).</para>
611 <para>When neither of these techniques works,
612 <command>patch</command> prints a message saying that the hunk
613 in question was rejected. It saves rejected hunks (also
614 simply called <quote>rejects</quote>) to a file with the same
615 name, and an added <filename role="special">.rej</filename>
616 extension. It also saves an unmodified copy of the file with
617 a <filename role="special">.orig</filename> extension; the
618 copy of the file without any extensions will contain any
619 changes made by hunks that <emphasis>did</emphasis> apply
620 cleanly. If you have a patch that modifies
621 <filename>foo</filename> with six hunks, and one of them fails
622 to apply, you will have: an unmodified
623 <filename>foo.orig</filename>, a <filename>foo.rej</filename>
624 containing one hunk, and <filename>foo</filename>, containing
625 the changes made by the five successful hunks.</para>
627 </sect2>
628 <sect2>
629 <title>Some quirks of patch representation</title>
631 <para>There are a few useful things to know about how
632 <command>patch</command> works with files.</para>
633 <itemizedlist>
634 <listitem><para>This should already be obvious, but
635 <command>patch</command> cannot handle binary
636 files.</para>
637 </listitem>
638 <listitem><para>Neither does it care about the executable bit;
639 it creates new files as readable, but not
640 executable.</para>
641 </listitem>
642 <listitem><para><command>patch</command> treats the removal of
643 a file as a diff between the file to be removed and the
644 empty file. So your idea of <quote>I deleted this
645 file</quote> looks like <quote>every line of this file
646 was deleted</quote> in a patch.</para>
647 </listitem>
648 <listitem><para>It treats the addition of a file as a diff
649 between the empty file and the file to be added. So in a
650 patch, your idea of <quote>I added this file</quote> looks
651 like <quote>every line of this file was
652 added</quote>.</para>
653 </listitem>
654 <listitem><para>It treats a renamed file as the removal of the
655 old name, and the addition of the new name. This means
656 that renamed files have a big footprint in patches. (Note
657 also that Mercurial does not currently try to infer when
658 files have been renamed or copied in a patch.)</para>
659 </listitem>
660 <listitem><para><command>patch</command> cannot represent
661 empty files, so you cannot use a patch to represent the
662 notion <quote>I added this empty file to the
663 tree</quote>.</para>
664 </listitem></itemizedlist>
665 </sect2>
666 <sect2>
667 <title>Beware the fuzz</title>
669 <para>While applying a hunk at an offset, or with a fuzz factor,
670 will often be completely successful, these inexact techniques
671 naturally leave open the possibility of corrupting the patched
672 file. The most common cases typically involve applying a
673 patch twice, or at an incorrect location in the file. If
674 <command>patch</command> or <command
675 role="hg-ext-mq">qpush</command> ever mentions an offset or
676 fuzz factor, you should make sure that the modified files are
677 correct afterwards.</para>
679 <para>It's often a good idea to refresh a patch that has applied
680 with an offset or fuzz factor; refreshing the patch generates
681 new context information that will make it apply cleanly. I
682 say <quote>often,</quote> not <quote>always,</quote> because
683 sometimes refreshing a patch will make it fail to apply
684 against a different revision of the underlying files. In some
685 cases, such as when you're maintaining a patch that must sit
686 on top of multiple versions of a source tree, it's acceptable
687 to have a patch apply with some fuzz, provided you've verified
688 the results of the patching process in such cases.</para>
690 </sect2>
691 <sect2>
692 <title>Handling rejection</title>
694 <para>If <command role="hg-ext-mq">qpush</command> fails to
695 apply a patch, it will print an error message and exit. If it
696 has left <filename role="special">.rej</filename> files
697 behind, it is usually best to fix up the rejected hunks before
698 you push more patches or do any further work.</para>
700 <para>If your patch <emphasis>used to</emphasis> apply cleanly,
701 and no longer does because you've changed the underlying code
702 that your patches are based on, Mercurial Queues can help; see
703 section <xref
704 linkend="sec.mq.merge"/> for details.</para>
706 <para>Unfortunately, there aren't any great techniques for
707 dealing with rejected hunks. Most often, you'll need to view
708 the <filename role="special">.rej</filename> file and edit the
709 target file, applying the rejected hunks by hand.</para>
711 <para>If you're feeling adventurous, Neil Brown, a Linux kernel
712 hacker, wrote a tool called <command>wiggle</command>
713 <citation>web:wiggle</citation>, which is more vigorous than
714 <command>patch</command> in its attempts to make a patch
715 apply.</para>
717 <para>Another Linux kernel hacker, Chris Mason (the author of
718 Mercurial Queues), wrote a similar tool called
719 <command>mpatch</command> <citation>web:mpatch</citation>,
720 which takes a simple approach to automating the application of
721 hunks rejected by <command>patch</command>. The
722 <command>mpatch</command> command can help with four common
723 reasons that a hunk may be rejected:</para>
725 <itemizedlist>
726 <listitem><para>The context in the middle of a hunk has
727 changed.</para>
728 </listitem>
729 <listitem><para>A hunk is missing some context at the
730 beginning or end.</para>
731 </listitem>
732 <listitem><para>A large hunk might apply better&emdash;either
733 entirely or in part&emdash;if it was broken up into
734 smaller hunks.</para>
735 </listitem>
736 <listitem><para>A hunk removes lines with slightly different
737 content than those currently present in the file.</para>
738 </listitem></itemizedlist>
740 <para>If you use <command>wiggle</command> or
741 <command>mpatch</command>, you should be doubly careful to
742 check your results when you're done. In fact,
743 <command>mpatch</command> enforces this method of
744 double-checking the tool's output, by automatically dropping
745 you into a merge program when it has done its job, so that you
746 can verify its work and finish off any remaining
747 merges.</para>
749 </sect2>
750 </sect1>
751 <sect1 id="sec.mq.perf">
752 <title>Getting the best performance out of MQ</title>
754 <para>MQ is very efficient at handling a large number of patches.
755 I ran some performance experiments in mid-2006 for a talk that I
756 gave at the 2006 EuroPython conference
757 <citation>web:europython</citation>. I used as my data set the
758 Linux 2.6.17-mm1 patch series, which consists of 1,738 patches.
759 I applied these on top of a Linux kernel repository containing
760 all 27,472 revisions between Linux 2.6.12-rc2 and Linux
761 2.6.17.</para>
763 <para>On my old, slow laptop, I was able to <command
764 role="hg-cmd">hg qpush <option
765 role="hg-ext-mq-cmd-qpush-opt">hg -a</option></command> all
766 1,738 patches in 3.5 minutes, and <command role="hg-cmd">hg qpop
767 <option role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command>
768 them all in 30 seconds. (On a newer laptop, the time to push
769 all patches dropped to two minutes.) I could <command
770 role="hg-ext-mq">qrefresh</command> one of the biggest patches
771 (which made 22,779 lines of changes to 287 files) in 6.6
772 seconds.</para>
774 <para>Clearly, MQ is well suited to working in large trees, but
775 there are a few tricks you can use to get the best performance
776 of it.</para>
778 <para>First of all, try to <quote>batch</quote> operations
779 together. Every time you run <command
780 role="hg-ext-mq">qpush</command> or <command
781 role="hg-ext-mq">qpop</command>, these commands scan the
782 working directory once to make sure you haven't made some
783 changes and then forgotten to run <command
784 role="hg-ext-mq">qrefresh</command>. On a small tree, the
785 time that this scan takes is unnoticeable. However, on a
786 medium-sized tree (containing tens of thousands of files), it
787 can take a second or more.</para>
789 <para>The <command role="hg-ext-mq">qpush</command> and <command
790 role="hg-ext-mq">qpop</command> commands allow you to push and
791 pop multiple patches at a time. You can identify the
792 <quote>destination patch</quote> that you want to end up at.
793 When you <command role="hg-ext-mq">qpush</command> with a
794 destination specified, it will push patches until that patch is
795 at the top of the applied stack. When you <command
796 role="hg-ext-mq">qpop</command> to a destination, MQ will pop
797 patches until the destination patch is at the top.</para>
799 <para>You can identify a destination patch using either the name
800 of the patch, or by number. If you use numeric addressing,
801 patches are counted from zero; this means that the first patch
802 is zero, the second is one, and so on.</para>
804 </sect1>
805 <sect1 id="sec.mq.merge">
806 <title>Updating your patches when the underlying code
807 changes</title>
809 <para>It's common to have a stack of patches on top of an
810 underlying repository that you don't modify directly. If you're
811 working on changes to third-party code, or on a feature that is
812 taking longer to develop than the rate of change of the code
813 beneath, you will often need to sync up with the underlying
814 code, and fix up any hunks in your patches that no longer apply.
815 This is called <emphasis>rebasing</emphasis> your patch
816 series.</para>
818 <para>The simplest way to do this is to <command role="hg-cmd">hg
819 qpop <option role="hg-ext-mq-cmd-qpop-opt">hg
820 -a</option></command> your patches, then <command
821 role="hg-cmd">hg pull</command> changes into the underlying
822 repository, and finally <command role="hg-cmd">hg qpush <option
823 role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> your
824 patches again. MQ will stop pushing any time it runs across a
825 patch that fails to apply during conflicts, allowing you to fix
826 your conflicts, <command role="hg-ext-mq">qrefresh</command> the
827 affected patch, and continue pushing until you have fixed your
828 entire stack.</para>
830 <para>This approach is easy to use and works well if you don't
831 expect changes to the underlying code to affect how well your
832 patches apply. If your patch stack touches code that is modified
833 frequently or invasively in the underlying repository, however,
834 fixing up rejected hunks by hand quickly becomes
835 tiresome.</para>
837 <para>It's possible to partially automate the rebasing process.
838 If your patches apply cleanly against some revision of the
839 underlying repo, MQ can use this information to help you to
840 resolve conflicts between your patches and a different
841 revision.</para>
843 <para>The process is a little involved.</para>
844 <orderedlist>
845 <listitem><para>To begin, <command role="hg-cmd">hg qpush
846 -a</command> all of your patches on top of the revision
847 where you know that they apply cleanly.</para>
848 </listitem>
849 <listitem><para>Save a backup copy of your patch directory using
850 <command role="hg-cmd">hg qsave <option
851 role="hg-ext-mq-cmd-qsave-opt">hg -e</option> <option
852 role="hg-ext-mq-cmd-qsave-opt">hg -c</option></command>.
853 This prints the name of the directory that it has saved the
854 patches in. It will save the patches to a directory called
855 <filename role="special"
856 class="directory">.hg/patches.N</filename>, where
857 <literal>N</literal> is a small integer. It also commits a
858 <quote>save changeset</quote> on top of your applied
859 patches; this is for internal book-keeping, and records the
860 states of the <filename role="special">series</filename> and
861 <filename role="special">status</filename> files.</para>
862 </listitem>
863 <listitem><para>Use <command role="hg-cmd">hg pull</command> to
864 bring new changes into the underlying repository. (Don't
865 run <command role="hg-cmd">hg pull -u</command>; see below
866 for why.)</para>
867 </listitem>
868 <listitem><para>Update to the new tip revision, using <command
869 role="hg-cmd">hg update <option
870 role="hg-opt-update">-C</option></command> to override
871 the patches you have pushed.</para>
872 </listitem>
873 <listitem><para>Merge all patches using
874 \hgcmdargs{qpush}{<option role="hg-ext-mq-cmd-qpush-opt">hg
875 -m</option> <option role="hg-ext-mq-cmd-qpush-opt">hg
876 -a</option>}. The <option
877 role="hg-ext-mq-cmd-qpush-opt">hg -m</option> option to
878 <command role="hg-ext-mq">qpush</command> tells MQ to
879 perform a three-way merge if the patch fails to
880 apply.</para>
881 </listitem></orderedlist>
883 <para>During the <command role="hg-cmd">hg qpush <option
884 role="hg-ext-mq-cmd-qpush-opt">hg -m</option></command>,
885 each patch in the <filename role="special">series</filename>
886 file is applied normally. If a patch applies with fuzz or
887 rejects, MQ looks at the queue you <command
888 role="hg-ext-mq">qsave</command>d, and performs a three-way
889 merge with the corresponding changeset. This merge uses
890 Mercurial's normal merge machinery, so it may pop up a GUI merge
891 tool to help you to resolve problems.</para>
893 <para>When you finish resolving the effects of a patch, MQ
894 refreshes your patch based on the result of the merge.</para>
896 <para>At the end of this process, your repository will have one
897 extra head from the old patch queue, and a copy of the old patch
898 queue will be in <filename role="special"
899 class="directory">.hg/patches.N</filename>. You can remove the
900 extra head using <command role="hg-cmd">hg qpop -a -n
901 patches.N</command> or <command role="hg-cmd">hg
902 strip</command>. You can delete <filename role="special"
903 class="directory">.hg/patches.N</filename> once you are sure
904 that you no longer need it as a backup.</para>
906 </sect1>
907 <sect1>
908 <title>Identifying patches</title>
910 <para>MQ commands that work with patches let you refer to a patch
911 either by using its name or by a number. By name is obvious
912 enough; pass the name <filename>foo.patch</filename> to <command
913 role="hg-ext-mq">qpush</command>, for example, and it will
914 push patches until <filename>foo.patch</filename> is
915 applied.</para>
917 <para>As a shortcut, you can refer to a patch using both a name
918 and a numeric offset; <literal>foo.patch-2</literal> means
919 <quote>two patches before <literal>foo.patch</literal></quote>,
920 while <literal>bar.patch+4</literal> means <quote>four patches
921 after <literal>bar.patch</literal></quote>.</para>
923 <para>Referring to a patch by index isn't much different. The
924 first patch printed in the output of <command
925 role="hg-ext-mq">qseries</command> is patch zero (yes, it's
926 one of those start-at-zero counting systems); the second is
927 patch one; and so on.</para>
929 <para>MQ also makes it easy to work with patches when you are
930 using normal Mercurial commands. Every command that accepts a
931 changeset ID will also accept the name of an applied patch. MQ
932 augments the tags normally in the repository with an eponymous
933 one for each applied patch. In addition, the special tags
934 \index{tags!special tag
935 names!<literal>qbase</literal>}<literal>qbase</literal> and
936 \index{tags!special tag
937 names!<literal>qtip</literal>}<literal>qtip</literal> identify
938 the <quote>bottom-most</quote> and topmost applied patches,
939 respectively.</para>
941 <para>These additions to Mercurial's normal tagging capabilities
942 make dealing with patches even more of a breeze.</para>
943 <itemizedlist>
944 <listitem><para>Want to patchbomb a mailing list with your
945 latest series of changes?</para>
946 <programlisting>hg email qbase:qtip
947 </programlisting>
948 <para> (Don't know what <quote>patchbombing</quote> is? See
949 section <xref linkend="sec.hgext.patchbomb"/>.)</para>
950 </listitem>
951 <listitem><para>Need to see all of the patches since
952 <literal>foo.patch</literal> that have touched files in a
953 subdirectory of your tree?</para>
954 <programlisting>
955 hg log -r foo.patch:qtip <emphasis>subdir</emphasis>
956 </programlisting>
957 </listitem>
958 </itemizedlist>
960 <para>Because MQ makes the names of patches available to the rest
961 of Mercurial through its normal internal tag machinery, you
962 don't need to type in the entire name of a patch when you want
963 to identify it by name.</para>
965 <para>Another nice consequence of representing patch names as tags
966 is that when you run the <command role="hg-cmd">hg log</command>
967 command, it will display a patch's name as a tag, simply as part
968 of its normal output. This makes it easy to visually
969 distinguish applied patches from underlying
970 <quote>normal</quote> revisions. The following example shows a
971 few normal Mercurial commands in use with applied
972 patches.</para>
974 &interaction.mq.id.output;
976 </sect1>
977 <sect1>
978 <title>Useful things to know about</title>
980 <para>There are a number of aspects of MQ usage that don't fit
981 tidily into sections of their own, but that are good to know.
982 Here they are, in one place.</para>
984 <itemizedlist>
985 <listitem><para>Normally, when you <command
986 role="hg-ext-mq">qpop</command> a patch and <command
987 role="hg-ext-mq">qpush</command> it again, the changeset
988 that represents the patch after the pop/push will have a
989 <emphasis>different identity</emphasis> than the changeset
990 that represented the hash beforehand. See section <xref
991 linkend="sec.mqref.cmd.qpush"/> for
992 information as to why this is.</para>
993 </listitem>
994 <listitem><para>It's not a good idea to <command
995 role="hg-cmd">hg merge</command> changes from another
996 branch with a patch changeset, at least if you want to
997 maintain the <quote>patchiness</quote> of that changeset and
998 changesets below it on the patch stack. If you try to do
999 this, it will appear to succeed, but MQ will become
1000 confused.</para>
1001 </listitem></itemizedlist>
1003 </sect1>
1004 <sect1 id="sec.mq.repo">
1005 <title>Managing patches in a repository</title>
1007 <para>Because MQ's <filename role="special"
1008 class="directory">.hg/patches</filename> directory resides
1009 outside a Mercurial repository's working directory, the
1010 <quote>underlying</quote> Mercurial repository knows nothing
1011 about the management or presence of patches.</para>
1013 <para>This presents the interesting possibility of managing the
1014 contents of the patch directory as a Mercurial repository in its
1015 own right. This can be a useful way to work. For example, you
1016 can work on a patch for a while, <command
1017 role="hg-ext-mq">qrefresh</command> it, then <command
1018 role="hg-cmd">hg commit</command> the current state of the
1019 patch. This lets you <quote>roll back</quote> to that version
1020 of the patch later on.</para>
1022 <para>You can then share different versions of the same patch
1023 stack among multiple underlying repositories. I use this when I
1024 am developing a Linux kernel feature. I have a pristine copy of
1025 my kernel sources for each of several CPU architectures, and a
1026 cloned repository under each that contains the patches I am
1027 working on. When I want to test a change on a different
1028 architecture, I push my current patches to the patch repository
1029 associated with that kernel tree, pop and push all of my
1030 patches, and build and test that kernel.</para>
1032 <para>Managing patches in a repository makes it possible for
1033 multiple developers to work on the same patch series without
1034 colliding with each other, all on top of an underlying source
1035 base that they may or may not control.</para>
1037 <sect2>
1038 <title>MQ support for patch repositories</title>
1040 <para>MQ helps you to work with the <filename role="special"
1041 class="directory">.hg/patches</filename> directory as a
1042 repository; when you prepare a repository for working with
1043 patches using <command role="hg-ext-mq">qinit</command>, you
1044 can pass the <option role="hg-ext-mq-cmd-qinit-opt">hg
1045 -c</option> option to create the <filename role="special"
1046 class="directory">.hg/patches</filename> directory as a
1047 Mercurial repository.</para>
1049 <note>
1050 <para> If you forget to use the <option
1051 role="hg-ext-mq-cmd-qinit-opt">hg -c</option> option, you
1052 can simply go into the <filename role="special"
1053 class="directory">.hg/patches</filename> directory at any
1054 time and run <command role="hg-cmd">hg init</command>.
1055 Don't forget to add an entry for the <filename
1056 role="special">status</filename> file to the <filename
1057 role="special">.hgignore</filename> file, though</para>
1059 <para> (<command role="hg-cmd">hg qinit <option
1060 role="hg-ext-mq-cmd-qinit-opt">hg -c</option></command>
1061 does this for you automatically); you
1062 <emphasis>really</emphasis> don't want to manage the
1063 <filename role="special">status</filename> file.</para>
1064 </note>
1066 <para>As a convenience, if MQ notices that the <filename
1067 class="directory">.hg/patches</filename> directory is a
1068 repository, it will automatically <command role="hg-cmd">hg
1069 add</command> every patch that you create and import.</para>
1071 <para>MQ provides a shortcut command, <command
1072 role="hg-ext-mq">qcommit</command>, that runs <command
1073 role="hg-cmd">hg commit</command> in the <filename
1074 role="special" class="directory">.hg/patches</filename>
1075 directory. This saves some bothersome typing.</para>
1077 <para>Finally, as a convenience to manage the patch directory,
1078 you can define the alias <command>mq</command> on Unix
1079 systems. For example, on Linux systems using the
1080 <command>bash</command> shell, you can include the following
1081 snippet in your <filename
1082 role="home">~/.bashrc</filename>.</para>
1084 <programlisting>alias mq=`hg -R $(hg
1085 root)/.hg/patches'</programlisting>
1087 <para>You can then issue commands of the form <command>mq
1088 pull</command> from the main repository.</para>
1090 </sect2>
1091 <sect2>
1092 <title>A few things to watch out for</title>
1094 <para>MQ's support for working with a repository full of patches
1095 is limited in a few small respects.</para>
1097 <para>MQ cannot automatically detect changes that you make to
1098 the patch directory. If you <command role="hg-cmd">hg
1099 pull</command>, manually edit, or <command role="hg-cmd">hg
1100 update</command> changes to patches or the <filename
1101 role="special">series</filename> file, you will have to
1102 <command role="hg-cmd">hg qpop <option
1103 role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> and
1104 then <command role="hg-cmd">hg qpush <option
1105 role="hg-ext-mq-cmd-qpush-opt">hg -a</option></command> in
1106 the underlying repository to see those changes show up there.
1107 If you forget to do this, you can confuse MQ's idea of which
1108 patches are applied.</para>
1110 </sect2>
1111 </sect1>
1112 <sect1 id="sec.mq.tools">
1113 <title>Third party tools for working with patches</title>
1115 <para>Once you've been working with patches for a while, you'll
1116 find yourself hungry for tools that will help you to understand
1117 and manipulate the patches you're dealing with.</para>
1119 <para>The <command>diffstat</command> command
1120 <citation>web:diffstat</citation> generates a histogram of the
1121 modifications made to each file in a patch. It provides a good
1122 way to <quote>get a sense of</quote> a patch&emdash;which files
1123 it affects, and how much change it introduces to each file and
1124 as a whole. (I find that it's a good idea to use
1125 <command>diffstat</command>'s <option
1126 role="cmd-opt-diffstat">-p</option> option as a matter of
1127 course, as otherwise it will try to do clever things with
1128 prefixes of file names that inevitably confuse at least
1129 me.)</para>
1131 &interaction.mq.tools.tools;
1133 <para>The <literal role="package">patchutils</literal> package
1134 <citation>web:patchutils</citation> is invaluable. It provides a
1135 set of small utilities that follow the <quote>Unix
1136 philosophy;</quote> each does one useful thing with a patch.
1137 The <literal role="package">patchutils</literal> command I use
1138 most is <command>filterdiff</command>, which extracts subsets
1139 from a patch file. For example, given a patch that modifies
1140 hundreds of files across dozens of directories, a single
1141 invocation of <command>filterdiff</command> can generate a
1142 smaller patch that only touches files whose names match a
1143 particular glob pattern. See section <xref
1144 linkend="mq-collab.tips.interdiff"/> for another
1145 example.</para>
1147 </sect1>
1148 <sect1>
1149 <title>Good ways to work with patches</title>
1151 <para>Whether you are working on a patch series to submit to a
1152 free software or open source project, or a series that you
1153 intend to treat as a sequence of regular changesets when you're
1154 done, you can use some simple techniques to keep your work well
1155 organised.</para>
1157 <para>Give your patches descriptive names. A good name for a
1158 patch might be <filename>rework-device-alloc.patch</filename>,
1159 because it will immediately give you a hint what the purpose of
1160 the patch is. Long names shouldn't be a problem; you won't be
1161 typing the names often, but you <emphasis>will</emphasis> be
1162 running commands like <command
1163 role="hg-ext-mq">qapplied</command> and <command
1164 role="hg-ext-mq">qtop</command> over and over. Good naming
1165 becomes especially important when you have a number of patches
1166 to work with, or if you are juggling a number of different tasks
1167 and your patches only get a fraction of your attention.</para>
1169 <para>Be aware of what patch you're working on. Use the <command
1170 role="hg-ext-mq">qtop</command> command and skim over the text
1171 of your patches frequently&emdash;for example, using <command
1172 role="hg-cmd">hg tip <option
1173 role="hg-opt-tip">-p</option></command>)&emdash;to be sure
1174 of where you stand. I have several times worked on and <command
1175 role="hg-ext-mq">qrefresh</command>ed a patch other than the
1176 one I intended, and it's often tricky to migrate changes into
1177 the right patch after making them in the wrong one.</para>
1179 <para>For this reason, it is very much worth investing a little
1180 time to learn how to use some of the third-party tools I
1181 described in section <xref linkend="sec.mq.tools"/>,
1182 particularly
1183 <command>diffstat</command> and <command>filterdiff</command>.
1184 The former will give you a quick idea of what changes your patch
1185 is making, while the latter makes it easy to splice hunks
1186 selectively out of one patch and into another.</para>
1188 </sect1>
1189 <sect1>
1190 <title>MQ cookbook</title>
1192 <sect2>
1193 <title>Manage <quote>trivial</quote> patches</title>
1195 <para>Because the overhead of dropping files into a new
1196 Mercurial repository is so low, it makes a lot of sense to
1197 manage patches this way even if you simply want to make a few
1198 changes to a source tarball that you downloaded.</para>
1200 <para>Begin by downloading and unpacking the source tarball, and
1201 turning it into a Mercurial repository.</para>
1203 &interaction.mq.tarball.download;
1205 <para>Continue by creating a patch stack and making your
1206 changes.</para>
1208 &interaction.mq.tarball.qinit;
1210 <para>Let's say a few weeks or months pass, and your package
1211 author releases a new version. First, bring their changes
1212 into the repository.</para>
1214 &interaction.mq.tarball.newsource;
1216 <para>The pipeline starting with <command role="hg-cmd">hg
1217 locate</command> above deletes all files in the working
1218 directory, so that <command role="hg-cmd">hg
1219 commit</command>'s <option
1220 role="hg-opt-commit">--addremove</option> option can
1221 actually tell which files have really been removed in the
1222 newer version of the source.</para>
1224 <para>Finally, you can apply your patches on top of the new
1225 tree.</para>
1227 &interaction.mq.tarball.repush;
1229 </sect2>
1230 <sect2 id="sec.mq.combine">
1231 <title>Combining entire patches</title>
1233 <para>MQ provides a command, <command
1234 role="hg-ext-mq">qfold</command> that lets you combine
1235 entire patches. This <quote>folds</quote> the patches you
1236 name, in the order you name them, into the topmost applied
1237 patch, and concatenates their descriptions onto the end of its
1238 description. The patches that you fold must be unapplied
1239 before you fold them.</para>
1241 <para>The order in which you fold patches matters. If your
1242 topmost applied patch is <literal>foo</literal>, and you
1243 <command role="hg-ext-mq">qfold</command>
1244 <literal>bar</literal> and <literal>quux</literal> into it,
1245 you will end up with a patch that has the same effect as if
1246 you applied first <literal>foo</literal>, then
1247 <literal>bar</literal>, followed by
1248 <literal>quux</literal>.</para>
1250 </sect2>
1251 <sect2>
1252 <title>Merging part of one patch into another</title>
1254 <para>Merging <emphasis>part</emphasis> of one patch into
1255 another is more difficult than combining entire
1256 patches.</para>
1258 <para>If you want to move changes to entire files, you can use
1259 <command>filterdiff</command>'s <option
1260 role="cmd-opt-filterdiff">-i</option> and <option
1261 role="cmd-opt-filterdiff">-x</option> options to choose the
1262 modifications to snip out of one patch, concatenating its
1263 output onto the end of the patch you want to merge into. You
1264 usually won't need to modify the patch you've merged the
1265 changes from. Instead, MQ will report some rejected hunks
1266 when you <command role="hg-ext-mq">qpush</command> it (from
1267 the hunks you moved into the other patch), and you can simply
1268 <command role="hg-ext-mq">qrefresh</command> the patch to drop
1269 the duplicate hunks.</para>
1271 <para>If you have a patch that has multiple hunks modifying a
1272 file, and you only want to move a few of those hunks, the job
1273 becomes more messy, but you can still partly automate it. Use
1274 <command>lsdiff -nvv</command> to print some metadata about
1275 the patch.</para>
1277 &interaction.mq.tools.lsdiff;
1279 <para>This command prints three different kinds of
1280 number:</para>
1281 <itemizedlist>
1282 <listitem><para>(in the first column) a <emphasis>file
1283 number</emphasis> to identify each file modified in the
1284 patch;</para>
1285 </listitem>
1286 <listitem><para>(on the next line, indented) the line number
1287 within a modified file where a hunk starts; and</para>
1288 </listitem>
1289 <listitem><para>(on the same line) a <emphasis>hunk
1290 number</emphasis> to identify that hunk.</para>
1291 </listitem></itemizedlist>
1293 <para>You'll have to use some visual inspection, and reading of
1294 the patch, to identify the file and hunk numbers you'll want,
1295 but you can then pass them to to
1296 <command>filterdiff</command>'s <option
1297 role="cmd-opt-filterdiff">--files</option> and <option
1298 role="cmd-opt-filterdiff">--hunks</option> options, to
1299 select exactly the file and hunk you want to extract.</para>
1301 <para>Once you have this hunk, you can concatenate it onto the
1302 end of your destination patch and continue with the remainder
1303 of section <xref linkend="sec.mq.combine"/>.</para>
1305 </sect2>
1306 </sect1>
1307 <sect1>
1308 <title>Differences between quilt and MQ</title>
1310 <para>If you are already familiar with quilt, MQ provides a
1311 similar command set. There are a few differences in the way
1312 that it works.</para>
1314 <para>You will already have noticed that most quilt commands have
1315 MQ counterparts that simply begin with a
1316 <quote><literal>q</literal></quote>. The exceptions are quilt's
1317 <literal>add</literal> and <literal>remove</literal> commands,
1318 the counterparts for which are the normal Mercurial <command
1319 role="hg-cmd">hg add</command> and <command role="hg-cmd">hg
1320 remove</command> commands. There is no MQ equivalent of the
1321 quilt <literal>edit</literal> command.</para>
1323 </sect1>
1324 </chapter>
1326 <!--
1327 local variables:
1328 sgml-parent-document: ("00book.xml" "book" "chapter")
1329 end:
1330 -->