hgbook
view en/appB-mq-ref.xml @ 572:13513d2a128d
Add sensible names to chapters.
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Mon Mar 09 23:37:29 2009 -0700 (2009-03-09) |
| parents | b90b024729f1 |
| children | 8366882f67f2 cfdb601a3c8b |
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>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>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>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>This command is shorthand for <command role="hg-cmd">hg
40 commit --cwd .hg/patches</command>.</para>
42 <para>\subsection{<command
43 role="hg-ext-mq">qdelete</command>&emdash;delete a patch
44 from the <filename role="special">series</filename>
45 file}</para>
47 <para>The <command role="hg-ext-mq">qdelete</command> command
48 removes the entry for a patch from the <filename
49 role="special">series</filename> file in the <filename
50 role="special" class="directory">.hg/patches</filename>
51 directory. It does not pop the patch if the patch is already
52 applied. By default, it does not delete the patch file; use
53 the <option role="hg-ext-mq-cmd-qdel-opt">-f</option> option
54 to do that.</para>
56 <para>Options:</para>
57 <itemizedlist>
58 <listitem><para><option
59 role="hg-ext-mq-cmd-qdel-opt">-f</option>: Delete the
60 patch file.</para>
61 </listitem></itemizedlist>
63 </sect2>
64 <sect2>
65 <title><command role="hg-ext-mq">qdiff</command>&emdash;print a
66 diff of the topmost applied patch</title>
68 <para>The <command role="hg-ext-mq">qdiff</command> command
69 prints a diff of the topmost applied patch. It is equivalent
70 to <command role="hg-cmd">hg diff -r-2:-1</command>.</para>
72 </sect2>
73 <sect2>
74 <title><command role="hg-ext-mq">qfold</command>&emdash;merge
75 (<quote>fold</quote>) several patches into one</title>
77 <para>The <command role="hg-ext-mq">qfold</command> command
78 merges multiple patches into the topmost applied patch, so
79 that the topmost applied patch makes the union of all of the
80 changes in the patches in question.</para>
82 <para>The patches to fold must not be applied; <command
83 role="hg-ext-mq">qfold</command> will exit with an error if
84 any is. The order in which patches are folded is significant;
85 <command role="hg-cmd">hg qfold a b</command> means
86 <quote>apply the current topmost patch, followed by
87 <literal>a</literal>, followed by
88 <literal>b</literal></quote>.</para>
90 <para>The comments from the folded patches are appended to the
91 comments of the destination patch, with each block of comments
92 separated by three asterisk
93 (<quote><literal>*</literal></quote>) characters. Use the
94 <option role="hg-ext-mq-cmd-qfold-opt">-e</option> option to
95 edit the commit message for the combined patch/changeset after
96 the folding has completed.</para>
98 <para>Options:</para>
99 <itemizedlist>
100 <listitem><para><option
101 role="hg-ext-mq-cmd-qfold-opt">-e</option>: Edit the
102 commit message and patch description for the newly folded
103 patch.</para>
104 </listitem>
105 <listitem><para><option
106 role="hg-ext-mq-cmd-qfold-opt">-l</option>: Use the
107 contents of the given file as the new commit message and
108 patch description for the folded patch.</para>
109 </listitem>
110 <listitem><para><option
111 role="hg-ext-mq-cmd-qfold-opt">-m</option>: Use the
112 given text as the new commit message and patch description
113 for the folded patch.</para>
114 </listitem></itemizedlist>
116 </sect2>
117 <sect2>
118 <title><command
119 role="hg-ext-mq">qheader</command>&emdash;display the
120 header/description of a patch</title>
122 <para>The <command role="hg-ext-mq">qheader</command> command
123 prints the header, or description, of a patch. By default, it
124 prints the header of the topmost applied patch. Given an
125 argument, it prints the header of the named patch.</para>
127 </sect2>
128 <sect2>
129 <title><command role="hg-ext-mq">qimport</command>&emdash;import
130 a third-party patch into the queue</title>
132 <para>The <command role="hg-ext-mq">qimport</command> command
133 adds an entry for an external patch to the <filename
134 role="special">series</filename> file, and copies the patch
135 into the <filename role="special"
136 class="directory">.hg/patches</filename> directory. It adds
137 the entry immediately after the topmost applied patch, but
138 does not push the patch.</para>
140 <para>If the <filename role="special"
141 class="directory">.hg/patches</filename> directory is a
142 repository, <command role="hg-ext-mq">qimport</command>
143 automatically does an <command role="hg-cmd">hg add</command>
144 of the imported patch.</para>
146 </sect2>
147 <sect2>
148 <title><command role="hg-ext-mq">qinit</command>&emdash;prepare
149 a repository to work with MQ</title>
151 <para>The <command role="hg-ext-mq">qinit</command> command
152 prepares a repository to work with MQ. It creates a directory
153 called <filename role="special"
154 class="directory">.hg/patches</filename>.</para>
156 <para>Options:</para>
157 <itemizedlist>
158 <listitem><para><option
159 role="hg-ext-mq-cmd-qinit-opt">-c</option>: Create
160 <filename role="special"
161 class="directory">.hg/patches</filename> as a repository
162 in its own right. Also creates a <filename
163 role="special">.hgignore</filename> file that will
164 ignore the <filename role="special">status</filename>
165 file.</para>
166 </listitem></itemizedlist>
168 <para>When the <filename role="special"
169 class="directory">.hg/patches</filename> directory is a
170 repository, the <command role="hg-ext-mq">qimport</command>
171 and <command role="hg-ext-mq">qnew</command> commands
172 automatically <command role="hg-cmd">hg add</command> new
173 patches.</para>
175 </sect2>
176 <sect2>
177 <title><command role="hg-ext-mq">qnew</command>&emdash;create a
178 new patch</title>
180 <para>The <command role="hg-ext-mq">qnew</command> command
181 creates a new patch. It takes one mandatory argument, the
182 name to use for the patch file. The newly created patch is
183 created empty by default. It is added to the <filename
184 role="special">series</filename> file after the current
185 topmost applied patch, and is immediately pushed on top of
186 that patch.</para>
188 <para>If <command role="hg-ext-mq">qnew</command> finds modified
189 files in the working directory, it will refuse to create a new
190 patch unless the <option
191 role="hg-ext-mq-cmd-qnew-opt">-f</option> option is used
192 (see below). This behaviour allows you to <command
193 role="hg-ext-mq">qrefresh</command> your topmost applied
194 patch before you apply a new patch on top of it.</para>
196 <para>Options:</para>
197 <itemizedlist>
198 <listitem><para><option
199 role="hg-ext-mq-cmd-qnew-opt">-f</option>: Create a new
200 patch if the contents of the working directory are
201 modified. Any outstanding modifications are added to the
202 newly created patch, so after this command completes, the
203 working directory will no longer be modified.</para>
204 </listitem>
205 <listitem><para><option
206 role="hg-ext-mq-cmd-qnew-opt">-m</option>: Use the given
207 text as the commit message. This text will be stored at
208 the beginning of the patch file, before the patch
209 data.</para>
210 </listitem></itemizedlist>
212 </sect2>
213 <sect2>
214 <title><command role="hg-ext-mq">qnext</command>&emdash;print
215 the name of the next patch</title>
217 <para>The <command role="hg-ext-mq">qnext</command> command
218 prints the name name of the next patch in the <filename
219 role="special">series</filename> file after the topmost
220 applied patch. This patch will become the topmost applied
221 patch if you run <command
222 role="hg-ext-mq">qpush</command>.</para>
224 </sect2>
225 <sect2>
226 <title><command role="hg-ext-mq">qpop</command>&emdash;pop
227 patches off the stack</title>
229 <para>The <command role="hg-ext-mq">qpop</command> command
230 removes applied patches from the top of the stack of applied
231 patches. By default, it removes only one patch.</para>
233 <para>This command removes the changesets that represent the
234 popped patches from the repository, and updates the working
235 directory to undo the effects of the patches.</para>
237 <para>This command takes an optional argument, which it uses as
238 the name or index of the patch to pop to. If given a name, it
239 will pop patches until the named patch is the topmost applied
240 patch. If given a number, <command
241 role="hg-ext-mq">qpop</command> treats the number as an
242 index into the entries in the series file, counting from zero
243 (empty lines and lines containing only comments do not count).
244 It pops patches until the patch identified by the given index
245 is the topmost applied patch.</para>
247 <para>The <command role="hg-ext-mq">qpop</command> command does
248 not read or write patches or the <filename
249 role="special">series</filename> file. It is thus safe to
250 <command role="hg-ext-mq">qpop</command> a patch that you have
251 removed from the <filename role="special">series</filename>
252 file, or a patch that you have renamed or deleted entirely.
253 In the latter two cases, use the name of the patch as it was
254 when you applied it.</para>
256 <para>By default, the <command role="hg-ext-mq">qpop</command>
257 command will not pop any patches if the working directory has
258 been modified. You can override this behaviour using the
259 <option role="hg-ext-mq-cmd-qpop-opt">-f</option> option,
260 which reverts all modifications in the working
261 directory.</para>
263 <para>Options:</para>
264 <itemizedlist>
265 <listitem><para><option
266 role="hg-ext-mq-cmd-qpop-opt">-a</option>: Pop all
267 applied patches. This returns the repository to its state
268 before you applied any patches.</para>
269 </listitem>
270 <listitem><para><option
271 role="hg-ext-mq-cmd-qpop-opt">-f</option>: Forcibly
272 revert any modifications to the working directory when
273 popping.</para>
274 </listitem>
275 <listitem><para><option
276 role="hg-ext-mq-cmd-qpop-opt">-n</option>: Pop a patch
277 from the named queue.</para>
278 </listitem></itemizedlist>
280 <para>The <command role="hg-ext-mq">qpop</command> command
281 removes one line from the end of the <filename
282 role="special">status</filename> file for each patch that it
283 pops.</para>
285 </sect2>
286 <sect2>
287 <title><command role="hg-ext-mq">qprev</command>&emdash;print
288 the name of the previous patch</title>
290 <para>The <command role="hg-ext-mq">qprev</command> command
291 prints the name of the patch in the <filename
292 role="special">series</filename> file that comes before the
293 topmost applied patch. This will become the topmost applied
294 patch if you run <command
295 role="hg-ext-mq">qpop</command>.</para>
297 </sect2>
298 <sect2 id="sec:mqref:cmd:qpush">
299 <title><command role="hg-ext-mq">qpush</command>&emdash;push
300 patches onto the stack</title>
302 <para>The <command role="hg-ext-mq">qpush</command> command adds
303 patches onto the applied stack. By default, it adds only one
304 patch.</para>
306 <para>This command creates a new changeset to represent each
307 applied patch, and updates the working directory to apply the
308 effects of the patches.</para>
310 <para>The default data used when creating a changeset are as
311 follows:</para>
312 <itemizedlist>
313 <listitem><para>The commit date and time zone are the current
314 date and time zone. Because these data are used to
315 compute the identity of a changeset, this means that if
316 you <command role="hg-ext-mq">qpop</command> a patch and
317 <command role="hg-ext-mq">qpush</command> it again, the
318 changeset that you push will have a different identity
319 than the changeset you popped.</para>
320 </listitem>
321 <listitem><para>The author is the same as the default used by
322 the <command role="hg-cmd">hg commit</command>
323 command.</para>
324 </listitem>
325 <listitem><para>The commit message is any text from the patch
326 file that comes before the first diff header. If there is
327 no such text, a default commit message is used that
328 identifies the name of the patch.</para>
329 </listitem></itemizedlist>
330 <para>If a patch contains a Mercurial patch header (XXX add
331 link), the information in the patch header overrides these
332 defaults.</para>
334 <para>Options:</para>
335 <itemizedlist>
336 <listitem><para><option
337 role="hg-ext-mq-cmd-qpush-opt">-a</option>: Push all
338 unapplied patches from the <filename
339 role="special">series</filename> file until there are
340 none left to push.</para>
341 </listitem>
342 <listitem><para><option
343 role="hg-ext-mq-cmd-qpush-opt">-l</option>: Add the name
344 of the patch to the end of the commit message.</para>
345 </listitem>
346 <listitem><para><option
347 role="hg-ext-mq-cmd-qpush-opt">-m</option>: If a patch
348 fails to apply cleanly, use the entry for the patch in
349 another saved queue to compute the parameters for a
350 three-way merge, and perform a three-way merge using the
351 normal Mercurial merge machinery. Use the resolution of
352 the merge as the new patch content.</para>
353 </listitem>
354 <listitem><para><option
355 role="hg-ext-mq-cmd-qpush-opt">-n</option>: Use the
356 named queue if merging while pushing.</para>
357 </listitem></itemizedlist>
359 <para>The <command role="hg-ext-mq">qpush</command> command
360 reads, but does not modify, the <filename
361 role="special">series</filename> file. It appends one line
362 to the <command role="hg-cmd">hg status</command> file for
363 each patch that it pushes.</para>
365 </sect2>
366 <sect2>
367 <title><command
368 role="hg-ext-mq">qrefresh</command>&emdash;update the
369 topmost applied patch</title>
371 <para>The <command role="hg-ext-mq">qrefresh</command> command
372 updates the topmost applied patch. It modifies the patch,
373 removes the old changeset that represented the patch, and
374 creates a new changeset to represent the modified
375 patch.</para>
377 <para>The <command role="hg-ext-mq">qrefresh</command> command
378 looks for the following modifications:</para>
379 <itemizedlist>
380 <listitem><para>Changes to the commit message, i.e. the text
381 before the first diff header in the patch file, are
382 reflected in the new changeset that represents the
383 patch.</para>
384 </listitem>
385 <listitem><para>Modifications to tracked files in the working
386 directory are added to the patch.</para>
387 </listitem>
388 <listitem><para>Changes to the files tracked using <command
389 role="hg-cmd">hg add</command>, <command
390 role="hg-cmd">hg copy</command>, <command
391 role="hg-cmd">hg remove</command>, or <command
392 role="hg-cmd">hg rename</command>. Added files and copy
393 and rename destinations are added to the patch, while
394 removed files and rename sources are removed.</para>
395 </listitem></itemizedlist>
397 <para>Even if <command role="hg-ext-mq">qrefresh</command>
398 detects no changes, it still recreates the changeset that
399 represents the patch. This causes the identity of the
400 changeset to differ from the previous changeset that
401 identified the patch.</para>
403 <para>Options:</para>
404 <itemizedlist>
405 <listitem><para><option
406 role="hg-ext-mq-cmd-qrefresh-opt">-e</option>: Modify
407 the commit and patch description, using the preferred text
408 editor.</para>
409 </listitem>
410 <listitem><para><option
411 role="hg-ext-mq-cmd-qrefresh-opt">-m</option>: Modify
412 the commit message and patch description, using the given
413 text.</para>
414 </listitem>
415 <listitem><para><option
416 role="hg-ext-mq-cmd-qrefresh-opt">-l</option>: Modify
417 the commit message and patch description, using text from
418 the given file.</para>
419 </listitem></itemizedlist>
421 </sect2>
422 <sect2>
423 <title><command role="hg-ext-mq">qrename</command>&emdash;rename
424 a patch</title>
426 <para>The <command role="hg-ext-mq">qrename</command> command
427 renames a patch, and changes the entry for the patch in the
428 <filename role="special">series</filename> file.</para>
430 <para>With a single argument, <command
431 role="hg-ext-mq">qrename</command> renames the topmost
432 applied patch. With two arguments, it renames its first
433 argument to its second.</para>
435 </sect2>
436 <sect2>
437 <title><command
438 role="hg-ext-mq">qrestore</command>&emdash;restore saved
439 queue state</title>
441 <para>XXX No idea what this does.</para>
443 </sect2>
444 <sect2>
445 <title><command role="hg-ext-mq">qsave</command>&emdash;save
446 current queue state</title>
448 <para>XXX Likewise.</para>
450 </sect2>
451 <sect2>
452 <title><command role="hg-ext-mq">qseries</command>&emdash;print
453 the entire patch series</title>
455 <para>The <command role="hg-ext-mq">qseries</command> command
456 prints the entire patch series from the <filename
457 role="special">series</filename> file. It prints only patch
458 names, not empty lines or comments. It prints in order from
459 first to be applied to last.</para>
461 </sect2>
462 <sect2>
463 <title><command role="hg-ext-mq">qtop</command>&emdash;print the
464 name of the current patch</title>
466 <para>The <command role="hg-ext-mq">qtop</command> prints the
467 name of the topmost currently applied patch.</para>
469 </sect2>
470 <sect2>
471 <title><command
472 role="hg-ext-mq">qunapplied</command>&emdash;print patches
473 not yet applied</title>
475 <para>The <command role="hg-ext-mq">qunapplied</command> command
476 prints the names of patches from the <filename
477 role="special">series</filename> file that are not yet
478 applied. It prints them in order from the next patch that
479 will be pushed to the last.</para>
481 </sect2>
482 <sect2>
483 <title><command role="hg-cmd">hg strip</command>&emdash;remove a
484 revision and descendants</title>
486 <para>The <command role="hg-cmd">hg strip</command> command
487 removes a revision, and all of its descendants, from the
488 repository. It undoes the effects of the removed revisions
489 from the repository, and updates the working directory to the
490 first parent of the removed revision.</para>
492 <para>The <command role="hg-cmd">hg strip</command> command
493 saves a backup of the removed changesets in a bundle, so that
494 they can be reapplied if removed in error.</para>
496 <para>Options:</para>
497 <itemizedlist>
498 <listitem><para><option role="hg-opt-strip">-b</option>: Save
499 unrelated changesets that are intermixed with the stripped
500 changesets in the backup bundle.</para>
501 </listitem>
502 <listitem><para><option role="hg-opt-strip">-f</option>: If a
503 branch has multiple heads, remove all heads. XXX This
504 should be renamed, and use <literal>-f</literal> to strip
505 revs when there are pending changes.</para>
506 </listitem>
507 <listitem><para><option role="hg-opt-strip">-n</option>: Do
508 not save a backup bundle.</para>
509 </listitem></itemizedlist>
511 </sect2>
512 </sect1>
513 <sect1>
514 <title>MQ file reference</title>
516 <sect2>
517 <title>The <filename role="special">series</filename>
518 file</title>
520 <para>The <filename role="special">series</filename> file
521 contains a list of the names of all patches that MQ can apply.
522 It is represented as a list of names, with one name saved per
523 line. Leading and trailing white space in each line are
524 ignored.</para>
526 <para>Lines may contain comments. A comment begins with the
527 <quote><literal>#</literal></quote> character, and extends to
528 the end of the line. Empty lines, and lines that contain only
529 comments, are ignored.</para>
531 <para>You will often need to edit the <filename
532 role="special">series</filename> file by hand, hence the
533 support for comments and empty lines noted above. For
534 example, you can comment out a patch temporarily, and <command
535 role="hg-ext-mq">qpush</command> will skip over that patch
536 when applying patches. You can also change the order in which
537 patches are applied by reordering their entries in the
538 <filename role="special">series</filename> file.</para>
540 <para>Placing the <filename role="special">series</filename>
541 file under revision control is also supported; it is a good
542 idea to place all of the patches that it refers to under
543 revision control, as well. If you create a patch directory
544 using the <option role="hg-ext-mq-cmd-qinit-opt">-c</option>
545 option to <command role="hg-ext-mq">qinit</command>, this will
546 be done for you automatically.</para>
548 </sect2>
549 <sect2>
550 <title>The <filename role="special">status</filename>
551 file</title>
553 <para>The <filename role="special">status</filename> file
554 contains the names and changeset hashes of all patches that MQ
555 currently has applied. Unlike the <filename
556 role="special">series</filename> file, this file is not
557 intended for editing. You should not place this file under
558 revision control, or modify it in any way. It is used by MQ
559 strictly for internal book-keeping.</para>
561 </sect2>
562 </sect1>
563 </appendix>
565 <!--
566 local variables:
567 sgml-parent-document: ("00book.xml" "book" "appendix")
568 end:
569 -->