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