hgbook
view en/appB-mq-ref.xml @ 596:4d26453ef459
Fix reviewers script.
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Thu Mar 26 23:01:51 2009 -0700 (2009-03-26) |
| parents | 8366882f67f2 |
| children | 1c13ed2130a7 |
line source
1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
3 <appendix id="chap:mqref">
4 <?dbhtml filename="mercurial-queues-reference.html"?>
5 <title>Mercurial Queues reference</title>
7 <sect1 id="sec:mqref:cmdref">
8 <title>MQ command reference</title>
10 <para id="x_5e8">For an overview of the commands provided by MQ, use the
11 command <command role="hg-cmd">hg help mq</command>.</para>
13 <sect2>
14 <title><command role="hg-ext-mq">qapplied</command>&emdash;print
15 applied patches</title>
17 <para id="x_5e9">The <command role="hg-ext-mq">qapplied</command> command
18 prints the current stack of applied patches. Patches are
19 printed in oldest-to-newest order, so the last patch in the
20 list is the <quote>top</quote> patch.</para>
22 </sect2>
23 <sect2>
24 <title><command role="hg-ext-mq">qcommit</command>&emdash;commit
25 changes in the queue repository</title>
27 <para id="x_5ea">The <command role="hg-ext-mq">qcommit</command> command
28 commits any outstanding changes in the <filename
29 role="special" class="directory">.hg/patches</filename>
30 repository. This command only works if the <filename
31 role="special" class="directory">.hg/patches</filename>
32 directory is a repository, i.e. you created the directory
33 using <command role="hg-cmd">hg qinit <option
34 role="hg-ext-mq-cmd-qinit-opt">-c</option></command> or
35 ran <command role="hg-cmd">hg init</command> in the directory
36 after running <command
37 role="hg-ext-mq">qinit</command>.</para>
39 <para id="x_5eb">This command is shorthand for <command role="hg-cmd">hg
40 commit --cwd .hg/patches</command>.</para>
41 </sect2>
42 <sect2>
43 <title><command
44 role="hg-ext-mq">qdelete</command>&emdash;delete a patch
45 from the <filename role="special">series</filename>
46 file}</title>
48 <para id="x_5ec">The <command role="hg-ext-mq">qdelete</command> command
49 removes the entry for a patch from the <filename
50 role="special">series</filename> file in the <filename
51 role="special" class="directory">.hg/patches</filename>
52 directory. It does not pop the patch if the patch is already
53 applied. By default, it does not delete the patch file; use
54 the <option role="hg-ext-mq-cmd-qdel-opt">-f</option> option
55 to do that.</para>
57 <para id="x_5ed">Options:</para>
58 <itemizedlist>
59 <listitem><para id="x_5ee"><option
60 role="hg-ext-mq-cmd-qdel-opt">-f</option>: Delete the
61 patch file.</para>
62 </listitem></itemizedlist>
64 </sect2>
65 <sect2>
66 <title><command role="hg-ext-mq">qdiff</command>&emdash;print a
67 diff of the topmost applied patch</title>
69 <para id="x_5ef">The <command role="hg-ext-mq">qdiff</command> command
70 prints a diff of the topmost applied patch. It is equivalent
71 to <command role="hg-cmd">hg diff -r-2:-1</command>.</para>
73 </sect2>
74 <sect2>
75 <title><command role="hg-ext-mq">qfold</command>&emdash;merge
76 (<quote>fold</quote>) several patches into one</title>
78 <para id="x_5f0">The <command role="hg-ext-mq">qfold</command> command
79 merges multiple patches into the topmost applied patch, so
80 that the topmost applied patch makes the union of all of the
81 changes in the patches in question.</para>
83 <para id="x_5f1">The patches to fold must not be applied; <command
84 role="hg-ext-mq">qfold</command> will exit with an error if
85 any is. The order in which patches are folded is significant;
86 <command role="hg-cmd">hg qfold a b</command> means
87 <quote>apply the current topmost patch, followed by
88 <literal>a</literal>, followed by
89 <literal>b</literal></quote>.</para>
91 <para id="x_5f2">The comments from the folded patches are appended to the
92 comments of the destination patch, with each block of comments
93 separated by three asterisk
94 (<quote><literal>*</literal></quote>) characters. Use the
95 <option role="hg-ext-mq-cmd-qfold-opt">-e</option> option to
96 edit the commit message for the combined patch/changeset after
97 the folding has completed.</para>
99 <para id="x_5f3">Options:</para>
100 <itemizedlist>
101 <listitem><para id="x_5f4"><option
102 role="hg-ext-mq-cmd-qfold-opt">-e</option>: Edit the
103 commit message and patch description for the newly folded
104 patch.</para>
105 </listitem>
106 <listitem><para id="x_5f5"><option
107 role="hg-ext-mq-cmd-qfold-opt">-l</option>: Use the
108 contents of the given file as the new commit message and
109 patch description for the folded patch.</para>
110 </listitem>
111 <listitem><para id="x_5f6"><option
112 role="hg-ext-mq-cmd-qfold-opt">-m</option>: Use the
113 given text as the new commit message and patch description
114 for the folded patch.</para>
115 </listitem></itemizedlist>
117 </sect2>
118 <sect2>
119 <title><command
120 role="hg-ext-mq">qheader</command>&emdash;display the
121 header/description of a patch</title>
123 <para id="x_5f7">The <command role="hg-ext-mq">qheader</command> command
124 prints the header, or description, of a patch. By default, it
125 prints the header of the topmost applied patch. Given an
126 argument, it prints the header of the named patch.</para>
128 </sect2>
129 <sect2>
130 <title><command role="hg-ext-mq">qimport</command>&emdash;import
131 a third-party patch into the queue</title>
133 <para id="x_5f8">The <command role="hg-ext-mq">qimport</command> command
134 adds an entry for an external patch to the <filename
135 role="special">series</filename> file, and copies the patch
136 into the <filename role="special"
137 class="directory">.hg/patches</filename> directory. It adds
138 the entry immediately after the topmost applied patch, but
139 does not push the patch.</para>
141 <para id="x_5f9">If the <filename role="special"
142 class="directory">.hg/patches</filename> directory is a
143 repository, <command role="hg-ext-mq">qimport</command>
144 automatically does an <command role="hg-cmd">hg add</command>
145 of the imported patch.</para>
147 </sect2>
148 <sect2>
149 <title><command role="hg-ext-mq">qinit</command>&emdash;prepare
150 a repository to work with MQ</title>
152 <para id="x_5fa">The <command role="hg-ext-mq">qinit</command> command
153 prepares a repository to work with MQ. It creates a directory
154 called <filename role="special"
155 class="directory">.hg/patches</filename>.</para>
157 <para id="x_5fb">Options:</para>
158 <itemizedlist>
159 <listitem><para id="x_5fc"><option
160 role="hg-ext-mq-cmd-qinit-opt">-c</option>: Create
161 <filename role="special"
162 class="directory">.hg/patches</filename> as a repository
163 in its own right. Also creates a <filename
164 role="special">.hgignore</filename> file that will
165 ignore the <filename role="special">status</filename>
166 file.</para>
167 </listitem></itemizedlist>
169 <para id="x_5fd">When the <filename role="special"
170 class="directory">.hg/patches</filename> directory is a
171 repository, the <command role="hg-ext-mq">qimport</command>
172 and <command role="hg-ext-mq">qnew</command> commands
173 automatically <command role="hg-cmd">hg add</command> new
174 patches.</para>
176 </sect2>
177 <sect2>
178 <title><command role="hg-ext-mq">qnew</command>&emdash;create a
179 new patch</title>
181 <para id="x_5fe">The <command role="hg-ext-mq">qnew</command> command
182 creates a new patch. It takes one mandatory argument, the
183 name to use for the patch file. The newly created patch is
184 created empty by default. It is added to the <filename
185 role="special">series</filename> file after the current
186 topmost applied patch, and is immediately pushed on top of
187 that patch.</para>
189 <para id="x_5ff">If <command role="hg-ext-mq">qnew</command> finds modified
190 files in the working directory, it will refuse to create a new
191 patch unless the <option
192 role="hg-ext-mq-cmd-qnew-opt">-f</option> option is used
193 (see below). This behaviour allows you to <command
194 role="hg-ext-mq">qrefresh</command> your topmost applied
195 patch before you apply a new patch on top of it.</para>
197 <para id="x_600">Options:</para>
198 <itemizedlist>
199 <listitem><para id="x_601"><option
200 role="hg-ext-mq-cmd-qnew-opt">-f</option>: Create a new
201 patch if the contents of the working directory are
202 modified. Any outstanding modifications are added to the
203 newly created patch, so after this command completes, the
204 working directory will no longer be modified.</para>
205 </listitem>
206 <listitem><para id="x_602"><option
207 role="hg-ext-mq-cmd-qnew-opt">-m</option>: Use the given
208 text as the commit message. This text will be stored at
209 the beginning of the patch file, before the patch
210 data.</para>
211 </listitem></itemizedlist>
213 </sect2>
214 <sect2>
215 <title><command role="hg-ext-mq">qnext</command>&emdash;print
216 the name of the next patch</title>
218 <para id="x_603">The <command role="hg-ext-mq">qnext</command> command
219 prints the name name of the next patch in the <filename
220 role="special">series</filename> file after the topmost
221 applied patch. This patch will become the topmost applied
222 patch if you run <command
223 role="hg-ext-mq">qpush</command>.</para>
225 </sect2>
226 <sect2>
227 <title><command role="hg-ext-mq">qpop</command>&emdash;pop
228 patches off the stack</title>
230 <para id="x_604">The <command role="hg-ext-mq">qpop</command> command
231 removes applied patches from the top of the stack of applied
232 patches. By default, it removes only one patch.</para>
234 <para id="x_605">This command removes the changesets that represent the
235 popped patches from the repository, and updates the working
236 directory to undo the effects of the patches.</para>
238 <para id="x_606">This command takes an optional argument, which it uses as
239 the name or index of the patch to pop to. If given a name, it
240 will pop patches until the named patch is the topmost applied
241 patch. If given a number, <command
242 role="hg-ext-mq">qpop</command> treats the number as an
243 index into the entries in the series file, counting from zero
244 (empty lines and lines containing only comments do not count).
245 It pops patches until the patch identified by the given index
246 is the topmost applied patch.</para>
248 <para id="x_607">The <command role="hg-ext-mq">qpop</command> command does
249 not read or write patches or the <filename
250 role="special">series</filename> file. It is thus safe to
251 <command role="hg-ext-mq">qpop</command> a patch that you have
252 removed from the <filename role="special">series</filename>
253 file, or a patch that you have renamed or deleted entirely.
254 In the latter two cases, use the name of the patch as it was
255 when you applied it.</para>
257 <para id="x_608">By default, the <command role="hg-ext-mq">qpop</command>
258 command will not pop any patches if the working directory has
259 been modified. You can override this behaviour using the
260 <option role="hg-ext-mq-cmd-qpop-opt">-f</option> option,
261 which reverts all modifications in the working
262 directory.</para>
264 <para id="x_609">Options:</para>
265 <itemizedlist>
266 <listitem><para id="x_60a"><option
267 role="hg-ext-mq-cmd-qpop-opt">-a</option>: Pop all
268 applied patches. This returns the repository to its state
269 before you applied any patches.</para>
270 </listitem>
271 <listitem><para id="x_60b"><option
272 role="hg-ext-mq-cmd-qpop-opt">-f</option>: Forcibly
273 revert any modifications to the working directory when
274 popping.</para>
275 </listitem>
276 <listitem><para id="x_60c"><option
277 role="hg-ext-mq-cmd-qpop-opt">-n</option>: Pop a patch
278 from the named queue.</para>
279 </listitem></itemizedlist>
281 <para id="x_60d">The <command role="hg-ext-mq">qpop</command> command
282 removes one line from the end of the <filename
283 role="special">status</filename> file for each patch that it
284 pops.</para>
286 </sect2>
287 <sect2>
288 <title><command role="hg-ext-mq">qprev</command>&emdash;print
289 the name of the previous patch</title>
291 <para id="x_60e">The <command role="hg-ext-mq">qprev</command> command
292 prints the name of the patch in the <filename
293 role="special">series</filename> file that comes before the
294 topmost applied patch. This will become the topmost applied
295 patch if you run <command
296 role="hg-ext-mq">qpop</command>.</para>
298 </sect2>
299 <sect2 id="sec:mqref:cmd:qpush">
300 <title><command role="hg-ext-mq">qpush</command>&emdash;push
301 patches onto the stack</title>
303 <para id="x_60f">The <command role="hg-ext-mq">qpush</command> command adds
304 patches onto the applied stack. By default, it adds only one
305 patch.</para>
307 <para id="x_610">This command creates a new changeset to represent each
308 applied patch, and updates the working directory to apply the
309 effects of the patches.</para>
311 <para id="x_611">The default data used when creating a changeset are as
312 follows:</para>
313 <itemizedlist>
314 <listitem><para id="x_612">The commit date and time zone are the current
315 date and time zone. Because these data are used to
316 compute the identity of a changeset, this means that if
317 you <command role="hg-ext-mq">qpop</command> a patch and
318 <command role="hg-ext-mq">qpush</command> it again, the
319 changeset that you push will have a different identity
320 than the changeset you popped.</para>
321 </listitem>
322 <listitem><para id="x_613">The author is the same as the default used by
323 the <command role="hg-cmd">hg commit</command>
324 command.</para>
325 </listitem>
326 <listitem><para id="x_614">The commit message is any text from the patch
327 file that comes before the first diff header. If there is
328 no such text, a default commit message is used that
329 identifies the name of the patch.</para>
330 </listitem></itemizedlist>
331 <para id="x_615">If a patch contains a Mercurial patch header (XXX add
332 link), the information in the patch header overrides these
333 defaults.</para>
335 <para id="x_616">Options:</para>
336 <itemizedlist>
337 <listitem><para id="x_617"><option
338 role="hg-ext-mq-cmd-qpush-opt">-a</option>: Push all
339 unapplied patches from the <filename
340 role="special">series</filename> file until there are
341 none left to push.</para>
342 </listitem>
343 <listitem><para id="x_618"><option
344 role="hg-ext-mq-cmd-qpush-opt">-l</option>: Add the name
345 of the patch to the end of the commit message.</para>
346 </listitem>
347 <listitem><para id="x_619"><option
348 role="hg-ext-mq-cmd-qpush-opt">-m</option>: If a patch
349 fails to apply cleanly, use the entry for the patch in
350 another saved queue to compute the parameters for a
351 three-way merge, and perform a three-way merge using the
352 normal Mercurial merge machinery. Use the resolution of
353 the merge as the new patch content.</para>
354 </listitem>
355 <listitem><para id="x_61a"><option
356 role="hg-ext-mq-cmd-qpush-opt">-n</option>: Use the
357 named queue if merging while pushing.</para>
358 </listitem></itemizedlist>
360 <para id="x_61b">The <command role="hg-ext-mq">qpush</command> command
361 reads, but does not modify, the <filename
362 role="special">series</filename> file. It appends one line
363 to the <command role="hg-cmd">hg status</command> file for
364 each patch that it pushes.</para>
366 </sect2>
367 <sect2>
368 <title><command
369 role="hg-ext-mq">qrefresh</command>&emdash;update the
370 topmost applied patch</title>
372 <para id="x_61c">The <command role="hg-ext-mq">qrefresh</command> command
373 updates the topmost applied patch. It modifies the patch,
374 removes the old changeset that represented the patch, and
375 creates a new changeset to represent the modified
376 patch.</para>
378 <para id="x_61d">The <command role="hg-ext-mq">qrefresh</command> command
379 looks for the following modifications:</para>
380 <itemizedlist>
381 <listitem><para id="x_61e">Changes to the commit message, i.e. the text
382 before the first diff header in the patch file, are
383 reflected in the new changeset that represents the
384 patch.</para>
385 </listitem>
386 <listitem><para id="x_61f">Modifications to tracked files in the working
387 directory are added to the patch.</para>
388 </listitem>
389 <listitem><para id="x_620">Changes to the files tracked using <command
390 role="hg-cmd">hg add</command>, <command
391 role="hg-cmd">hg copy</command>, <command
392 role="hg-cmd">hg remove</command>, or <command
393 role="hg-cmd">hg rename</command>. Added files and copy
394 and rename destinations are added to the patch, while
395 removed files and rename sources are removed.</para>
396 </listitem></itemizedlist>
398 <para id="x_621">Even if <command role="hg-ext-mq">qrefresh</command>
399 detects no changes, it still recreates the changeset that
400 represents the patch. This causes the identity of the
401 changeset to differ from the previous changeset that
402 identified the patch.</para>
404 <para id="x_622">Options:</para>
405 <itemizedlist>
406 <listitem><para id="x_623"><option
407 role="hg-ext-mq-cmd-qrefresh-opt">-e</option>: Modify
408 the commit and patch description, using the preferred text
409 editor.</para>
410 </listitem>
411 <listitem><para id="x_624"><option
412 role="hg-ext-mq-cmd-qrefresh-opt">-m</option>: Modify
413 the commit message and patch description, using the given
414 text.</para>
415 </listitem>
416 <listitem><para id="x_625"><option
417 role="hg-ext-mq-cmd-qrefresh-opt">-l</option>: Modify
418 the commit message and patch description, using text from
419 the given file.</para>
420 </listitem></itemizedlist>
422 </sect2>
423 <sect2>
424 <title><command role="hg-ext-mq">qrename</command>&emdash;rename
425 a patch</title>
427 <para id="x_626">The <command role="hg-ext-mq">qrename</command> command
428 renames a patch, and changes the entry for the patch in the
429 <filename role="special">series</filename> file.</para>
431 <para id="x_627">With a single argument, <command
432 role="hg-ext-mq">qrename</command> renames the topmost
433 applied patch. With two arguments, it renames its first
434 argument to its second.</para>
436 </sect2>
437 <sect2>
438 <title><command
439 role="hg-ext-mq">qrestore</command>&emdash;restore saved
440 queue state</title>
442 <para id="x_628">XXX No idea what this does.</para>
444 </sect2>
445 <sect2>
446 <title><command role="hg-ext-mq">qsave</command>&emdash;save
447 current queue state</title>
449 <para id="x_629">XXX Likewise.</para>
451 </sect2>
452 <sect2>
453 <title><command role="hg-ext-mq">qseries</command>&emdash;print
454 the entire patch series</title>
456 <para id="x_62a">The <command role="hg-ext-mq">qseries</command> command
457 prints the entire patch series from the <filename
458 role="special">series</filename> file. It prints only patch
459 names, not empty lines or comments. It prints in order from
460 first to be applied to last.</para>
462 </sect2>
463 <sect2>
464 <title><command role="hg-ext-mq">qtop</command>&emdash;print the
465 name of the current patch</title>
467 <para id="x_62b">The <command role="hg-ext-mq">qtop</command> prints the
468 name of the topmost currently applied patch.</para>
470 </sect2>
471 <sect2>
472 <title><command
473 role="hg-ext-mq">qunapplied</command>&emdash;print patches
474 not yet applied</title>
476 <para id="x_62c">The <command role="hg-ext-mq">qunapplied</command> command
477 prints the names of patches from the <filename
478 role="special">series</filename> file that are not yet
479 applied. It prints them in order from the next patch that
480 will be pushed to the last.</para>
482 </sect2>
483 <sect2>
484 <title><command role="hg-cmd">hg strip</command>&emdash;remove a
485 revision and descendants</title>
487 <para id="x_62d">The <command role="hg-cmd">hg strip</command> command
488 removes a revision, and all of its descendants, from the
489 repository. It undoes the effects of the removed revisions
490 from the repository, and updates the working directory to the
491 first parent of the removed revision.</para>
493 <para id="x_62e">The <command role="hg-cmd">hg strip</command> command
494 saves a backup of the removed changesets in a bundle, so that
495 they can be reapplied if removed in error.</para>
497 <para id="x_62f">Options:</para>
498 <itemizedlist>
499 <listitem><para id="x_630"><option role="hg-opt-strip">-b</option>: Save
500 unrelated changesets that are intermixed with the stripped
501 changesets in the backup bundle.</para>
502 </listitem>
503 <listitem><para id="x_631"><option role="hg-opt-strip">-f</option>: If a
504 branch has multiple heads, remove all heads. XXX This
505 should be renamed, and use <literal>-f</literal> to strip
506 revs when there are pending changes.</para>
507 </listitem>
508 <listitem><para id="x_632"><option role="hg-opt-strip">-n</option>: Do
509 not save a backup bundle.</para>
510 </listitem></itemizedlist>
512 </sect2>
513 </sect1>
514 <sect1>
515 <title>MQ file reference</title>
517 <sect2>
518 <title>The <filename role="special">series</filename>
519 file</title>
521 <para id="x_633">The <filename role="special">series</filename> file
522 contains a list of the names of all patches that MQ can apply.
523 It is represented as a list of names, with one name saved per
524 line. Leading and trailing white space in each line are
525 ignored.</para>
527 <para id="x_634">Lines may contain comments. A comment begins with the
528 <quote><literal>#</literal></quote> character, and extends to
529 the end of the line. Empty lines, and lines that contain only
530 comments, are ignored.</para>
532 <para id="x_635">You will often need to edit the <filename
533 role="special">series</filename> file by hand, hence the
534 support for comments and empty lines noted above. For
535 example, you can comment out a patch temporarily, and <command
536 role="hg-ext-mq">qpush</command> will skip over that patch
537 when applying patches. You can also change the order in which
538 patches are applied by reordering their entries in the
539 <filename role="special">series</filename> file.</para>
541 <para id="x_636">Placing the <filename role="special">series</filename>
542 file under revision control is also supported; it is a good
543 idea to place all of the patches that it refers to under
544 revision control, as well. If you create a patch directory
545 using the <option role="hg-ext-mq-cmd-qinit-opt">-c</option>
546 option to <command role="hg-ext-mq">qinit</command>, this will
547 be done for you automatically.</para>
549 </sect2>
550 <sect2>
551 <title>The <filename role="special">status</filename>
552 file</title>
554 <para id="x_637">The <filename role="special">status</filename> file
555 contains the names and changeset hashes of all patches that MQ
556 currently has applied. Unlike the <filename
557 role="special">series</filename> file, this file is not
558 intended for editing. You should not place this file under
559 revision control, or modify it in any way. It is used by MQ
560 strictly for internal book-keeping.</para>
562 </sect2>
563 </sect1>
564 </appendix>
566 <!--
567 local variables:
568 sgml-parent-document: ("00book.xml" "book" "appendix")
569 end:
570 -->