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