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