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