annotate en/ch11-mq.xml @ 764:53f179393f5c

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