hgbook
view en/appB-mq-ref.xml @ 994:c05663baf56b
merge with Bryan
| author | Romain PELISSE <belaran@gmail.com> |
|---|---|
| date | Sat Sep 12 16:01:16 2009 +0200 (2009-09-12) |
| parents | 477d6a3e5023 |
| children |
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;move
76 applied patches into repository history</title>
78 <para id="x_72d">The <command>hg qfinish</command> command converts the
79 specified applied patches into permanent changes by moving
80 them out of MQ's control so that they will be treated as
81 normal repository history.</para>
82 </sect2>
84 <sect2>
85 <title><command role="hg-ext-mq">qfold</command>&emdash;merge
86 (<quote>fold</quote>) several patches into one</title>
88 <para id="x_5f0">The <command role="hg-ext-mq">qfold</command> command
89 merges multiple patches into the topmost applied patch, so
90 that the topmost applied patch makes the union of all of the
91 changes in the patches in question.</para>
93 <para id="x_5f1">The patches to fold must not be applied; <command
94 role="hg-ext-mq">qfold</command> will exit with an error if
95 any is. The order in which patches are folded is significant;
96 <command role="hg-cmd">hg qfold a b</command> means
97 <quote>apply the current topmost patch, followed by
98 <literal>a</literal>, followed by
99 <literal>b</literal></quote>.</para>
101 <para id="x_5f2">The comments from the folded patches are appended to the
102 comments of the destination patch, with each block of comments
103 separated by three asterisk
104 (<quote><literal>*</literal></quote>) characters. Use the
105 <option role="hg-ext-mq-cmd-qfold-opt">-e</option> option to
106 edit the commit message for the combined patch/changeset after
107 the folding has completed.</para>
109 <para id="x_5f3">Options:</para>
110 <itemizedlist>
111 <listitem><para id="x_5f4"><option
112 role="hg-ext-mq-cmd-qfold-opt">-e</option>: Edit the
113 commit message and patch description for the newly folded
114 patch.</para>
115 </listitem>
116 <listitem><para id="x_5f5"><option
117 role="hg-ext-mq-cmd-qfold-opt">-l</option>: Use the
118 contents of the given file as the new commit message and
119 patch description for the folded patch.</para>
120 </listitem>
121 <listitem><para id="x_5f6"><option
122 role="hg-ext-mq-cmd-qfold-opt">-m</option>: Use the
123 given text as the new commit message and patch description
124 for the folded patch.</para>
125 </listitem></itemizedlist>
127 </sect2>
128 <sect2>
129 <title><command
130 role="hg-ext-mq">qheader</command>&emdash;display the
131 header/description of a patch</title>
133 <para id="x_5f7">The <command role="hg-ext-mq">qheader</command> command
134 prints the header, or description, of a patch. By default, it
135 prints the header of the topmost applied patch. Given an
136 argument, it prints the header of the named patch.</para>
138 </sect2>
139 <sect2>
140 <title><command role="hg-ext-mq">qimport</command>&emdash;import
141 a third-party patch into the queue</title>
143 <para id="x_5f8">The <command role="hg-ext-mq">qimport</command> command
144 adds an entry for an external patch to the <filename
145 role="special">series</filename> file, and copies the patch
146 into the <filename role="special"
147 class="directory">.hg/patches</filename> directory. It adds
148 the entry immediately after the topmost applied patch, but
149 does not push the patch.</para>
151 <para id="x_5f9">If the <filename role="special"
152 class="directory">.hg/patches</filename> directory is a
153 repository, <command role="hg-ext-mq">qimport</command>
154 automatically does an <command role="hg-cmd">hg add</command>
155 of the imported patch.</para>
157 </sect2>
158 <sect2>
159 <title><command role="hg-ext-mq">qinit</command>&emdash;prepare
160 a repository to work with MQ</title>
162 <para id="x_5fa">The <command role="hg-ext-mq">qinit</command> command
163 prepares a repository to work with MQ. It creates a directory
164 called <filename role="special"
165 class="directory">.hg/patches</filename>.</para>
167 <para id="x_5fb">Options:</para>
168 <itemizedlist>
169 <listitem><para id="x_5fc"><option
170 role="hg-ext-mq-cmd-qinit-opt">-c</option>: Create
171 <filename role="special"
172 class="directory">.hg/patches</filename> as a repository
173 in its own right. Also creates a <filename
174 role="special">.hgignore</filename> file that will
175 ignore the <filename role="special">status</filename>
176 file.</para>
177 </listitem></itemizedlist>
179 <para id="x_5fd">When the <filename role="special"
180 class="directory">.hg/patches</filename> directory is a
181 repository, the <command role="hg-ext-mq">qimport</command>
182 and <command role="hg-ext-mq">qnew</command> commands
183 automatically <command role="hg-cmd">hg add</command> new
184 patches.</para>
186 </sect2>
187 <sect2>
188 <title><command role="hg-ext-mq">qnew</command>&emdash;create a
189 new patch</title>
191 <para id="x_5fe">The <command role="hg-ext-mq">qnew</command> command
192 creates a new patch. It takes one mandatory argument, the
193 name to use for the patch file. The newly created patch is
194 created empty by default. It is added to the <filename
195 role="special">series</filename> file after the current
196 topmost applied patch, and is immediately pushed on top of
197 that patch.</para>
199 <para id="x_5ff">If <command role="hg-ext-mq">qnew</command> finds modified
200 files in the working directory, it will refuse to create a new
201 patch unless the <option
202 role="hg-ext-mq-cmd-qnew-opt">-f</option> option is used
203 (see below). This behavior allows you to <command
204 role="hg-ext-mq">qrefresh</command> your topmost applied
205 patch before you apply a new patch on top of it.</para>
207 <para id="x_600">Options:</para>
208 <itemizedlist>
209 <listitem><para id="x_601"><option
210 role="hg-ext-mq-cmd-qnew-opt">-f</option>: Create a new
211 patch if the contents of the working directory are
212 modified. Any outstanding modifications are added to the
213 newly created patch, so after this command completes, the
214 working directory will no longer be modified.</para>
215 </listitem>
216 <listitem><para id="x_602"><option
217 role="hg-ext-mq-cmd-qnew-opt">-m</option>: Use the given
218 text as the commit message. This text will be stored at
219 the beginning of the patch file, before the patch
220 data.</para>
221 </listitem></itemizedlist>
223 </sect2>
224 <sect2>
225 <title><command role="hg-ext-mq">qnext</command>&emdash;print
226 the name of the next patch</title>
228 <para id="x_603">The <command role="hg-ext-mq">qnext</command> command
229 prints the name name of the next patch in the <filename
230 role="special">series</filename> file after the topmost
231 applied patch. This patch will become the topmost applied
232 patch if you run <command
233 role="hg-ext-mq">qpush</command>.</para>
235 </sect2>
236 <sect2>
237 <title><command role="hg-ext-mq">qpop</command>&emdash;pop
238 patches off the stack</title>
240 <para id="x_604">The <command role="hg-ext-mq">qpop</command> command
241 removes applied patches from the top of the stack of applied
242 patches. By default, it removes only one patch.</para>
244 <para id="x_605">This command removes the changesets that represent the
245 popped patches from the repository, and updates the working
246 directory to undo the effects of the patches.</para>
248 <para id="x_606">This command takes an optional argument, which it uses as
249 the name or index of the patch to pop to. If given a name, it
250 will pop patches until the named patch is the topmost applied
251 patch. If given a number, <command
252 role="hg-ext-mq">qpop</command> treats the number as an
253 index into the entries in the series file, counting from zero
254 (empty lines and lines containing only comments do not count).
255 It pops patches until the patch identified by the given index
256 is the topmost applied patch.</para>
258 <para id="x_607">The <command role="hg-ext-mq">qpop</command> command does
259 not read or write patches or the <filename
260 role="special">series</filename> file. It is thus safe to
261 <command role="hg-ext-mq">qpop</command> a patch that you have
262 removed from the <filename role="special">series</filename>
263 file, or a patch that you have renamed or deleted entirely.
264 In the latter two cases, use the name of the patch as it was
265 when you applied it.</para>
267 <para id="x_608">By default, the <command role="hg-ext-mq">qpop</command>
268 command will not pop any patches if the working directory has
269 been modified. You can override this behavior using the
270 <option role="hg-ext-mq-cmd-qpop-opt">-f</option> option,
271 which reverts all modifications in the working
272 directory.</para>
274 <para id="x_609">Options:</para>
275 <itemizedlist>
276 <listitem><para id="x_60a"><option
277 role="hg-ext-mq-cmd-qpop-opt">-a</option>: Pop all
278 applied patches. This returns the repository to its state
279 before you applied any patches.</para>
280 </listitem>
281 <listitem><para id="x_60b"><option
282 role="hg-ext-mq-cmd-qpop-opt">-f</option>: Forcibly
283 revert any modifications to the working directory when
284 popping.</para>
285 </listitem>
286 <listitem><para id="x_60c"><option
287 role="hg-ext-mq-cmd-qpop-opt">-n</option>: Pop a patch
288 from the named queue.</para>
289 </listitem></itemizedlist>
291 <para id="x_60d">The <command role="hg-ext-mq">qpop</command> command
292 removes one line from the end of the <filename
293 role="special">status</filename> file for each patch that it
294 pops.</para>
296 </sect2>
297 <sect2>
298 <title><command role="hg-ext-mq">qprev</command>&emdash;print
299 the name of the previous patch</title>
301 <para id="x_60e">The <command role="hg-ext-mq">qprev</command> command
302 prints the name of the patch in the <filename
303 role="special">series</filename> file that comes before the
304 topmost applied patch. This will become the topmost applied
305 patch if you run <command
306 role="hg-ext-mq">qpop</command>.</para>
308 </sect2>
309 <sect2 id="sec:mqref:cmd:qpush">
310 <title><command role="hg-ext-mq">qpush</command>&emdash;push
311 patches onto the stack</title>
313 <para id="x_60f">The <command role="hg-ext-mq">qpush</command> command adds
314 patches onto the applied stack. By default, it adds only one
315 patch.</para>
317 <para id="x_610">This command creates a new changeset to represent each
318 applied patch, and updates the working directory to apply the
319 effects of the patches.</para>
321 <para id="x_611">The default data used when creating a changeset are as
322 follows:</para>
323 <itemizedlist>
324 <listitem><para id="x_612">The commit date and time zone are the current
325 date and time zone. Because these data are used to
326 compute the identity of a changeset, this means that if
327 you <command role="hg-ext-mq">qpop</command> a patch and
328 <command role="hg-ext-mq">qpush</command> it again, the
329 changeset that you push will have a different identity
330 than the changeset you popped.</para>
331 </listitem>
332 <listitem><para id="x_613">The author is the same as the default used by
333 the <command role="hg-cmd">hg commit</command>
334 command.</para>
335 </listitem>
336 <listitem><para id="x_614">The commit message is any text from the patch
337 file that comes before the first diff header. If there is
338 no such text, a default commit message is used that
339 identifies the name of the patch.</para>
340 </listitem></itemizedlist>
341 <para id="x_615">If a patch contains a Mercurial patch header,
342 the information in the patch header overrides these
343 defaults.</para>
345 <para id="x_616">Options:</para>
346 <itemizedlist>
347 <listitem><para id="x_617"><option
348 role="hg-ext-mq-cmd-qpush-opt">-a</option>: Push all
349 unapplied patches from the <filename
350 role="special">series</filename> file until there are
351 none left to push.</para>
352 </listitem>
353 <listitem><para id="x_618"><option
354 role="hg-ext-mq-cmd-qpush-opt">-l</option>: Add the name
355 of the patch to the end of the commit message.</para>
356 </listitem>
357 <listitem><para id="x_619"><option
358 role="hg-ext-mq-cmd-qpush-opt">-m</option>: If a patch
359 fails to apply cleanly, use the entry for the patch in
360 another saved queue to compute the parameters for a
361 three-way merge, and perform a three-way merge using the
362 normal Mercurial merge machinery. Use the resolution of
363 the merge as the new patch content.</para>
364 </listitem>
365 <listitem><para id="x_61a"><option
366 role="hg-ext-mq-cmd-qpush-opt">-n</option>: Use the
367 named queue if merging while pushing.</para>
368 </listitem></itemizedlist>
370 <para id="x_61b">The <command role="hg-ext-mq">qpush</command> command
371 reads, but does not modify, the <filename
372 role="special">series</filename> file. It appends one line
373 to the <command role="hg-cmd">hg status</command> file for
374 each patch that it pushes.</para>
376 </sect2>
377 <sect2>
378 <title><command
379 role="hg-ext-mq">qrefresh</command>&emdash;update the
380 topmost applied patch</title>
382 <para id="x_61c">The <command role="hg-ext-mq">qrefresh</command> command
383 updates the topmost applied patch. It modifies the patch,
384 removes the old changeset that represented the patch, and
385 creates a new changeset to represent the modified
386 patch.</para>
388 <para id="x_61d">The <command role="hg-ext-mq">qrefresh</command> command
389 looks for the following modifications:</para>
390 <itemizedlist>
391 <listitem><para id="x_61e">Changes to the commit message, i.e. the text
392 before the first diff header in the patch file, are
393 reflected in the new changeset that represents the
394 patch.</para>
395 </listitem>
396 <listitem><para id="x_61f">Modifications to tracked files in the working
397 directory are added to the patch.</para>
398 </listitem>
399 <listitem><para id="x_620">Changes to the files tracked using <command
400 role="hg-cmd">hg add</command>, <command
401 role="hg-cmd">hg copy</command>, <command
402 role="hg-cmd">hg remove</command>, or <command
403 role="hg-cmd">hg rename</command>. Added files and copy
404 and rename destinations are added to the patch, while
405 removed files and rename sources are removed.</para>
406 </listitem></itemizedlist>
408 <para id="x_621">Even if <command role="hg-ext-mq">qrefresh</command>
409 detects no changes, it still recreates the changeset that
410 represents the patch. This causes the identity of the
411 changeset to differ from the previous changeset that
412 identified the patch.</para>
414 <para id="x_622">Options:</para>
415 <itemizedlist>
416 <listitem><para id="x_623"><option
417 role="hg-ext-mq-cmd-qrefresh-opt">-e</option>: Modify
418 the commit and patch description, using the preferred text
419 editor.</para>
420 </listitem>
421 <listitem><para id="x_624"><option
422 role="hg-ext-mq-cmd-qrefresh-opt">-m</option>: Modify
423 the commit message and patch description, using the given
424 text.</para>
425 </listitem>
426 <listitem><para id="x_625"><option
427 role="hg-ext-mq-cmd-qrefresh-opt">-l</option>: Modify
428 the commit message and patch description, using text from
429 the given file.</para>
430 </listitem></itemizedlist>
432 </sect2>
433 <sect2>
434 <title><command role="hg-ext-mq">qrename</command>&emdash;rename
435 a patch</title>
437 <para id="x_626">The <command role="hg-ext-mq">qrename</command> command
438 renames a patch, and changes the entry for the patch in the
439 <filename role="special">series</filename> file.</para>
441 <para id="x_627">With a single argument, <command
442 role="hg-ext-mq">qrename</command> renames the topmost
443 applied patch. With two arguments, it renames its first
444 argument to its second.</para>
446 </sect2>
447 <sect2>
448 <title><command role="hg-ext-mq">qseries</command>&emdash;print
449 the entire patch series</title>
451 <para id="x_62a">The <command role="hg-ext-mq">qseries</command> command
452 prints the entire patch series from the <filename
453 role="special">series</filename> file. It prints only patch
454 names, not empty lines or comments. It prints in order from
455 first to be applied to last.</para>
457 </sect2>
458 <sect2>
459 <title><command role="hg-ext-mq">qtop</command>&emdash;print the
460 name of the current patch</title>
462 <para id="x_62b">The <command role="hg-ext-mq">qtop</command> prints the
463 name of the topmost currently applied patch.</para>
465 </sect2>
466 <sect2>
467 <title><command
468 role="hg-ext-mq">qunapplied</command>&emdash;print patches
469 not yet applied</title>
471 <para id="x_62c">The <command role="hg-ext-mq">qunapplied</command> command
472 prints the names of patches from the <filename
473 role="special">series</filename> file that are not yet
474 applied. It prints them in order from the next patch that
475 will be pushed to the last.</para>
477 </sect2>
478 <sect2>
479 <title><command role="hg-cmd">hg strip</command>&emdash;remove a
480 revision and descendants</title>
482 <para id="x_62d">The <command role="hg-cmd">hg strip</command> command
483 removes a revision, and all of its descendants, from the
484 repository. It undoes the effects of the removed revisions
485 from the repository, and updates the working directory to the
486 first parent of the removed revision.</para>
488 <para id="x_62e">The <command role="hg-cmd">hg strip</command> command
489 saves a backup of the removed changesets in a bundle, so that
490 they can be reapplied if removed in error.</para>
492 <para id="x_62f">Options:</para>
493 <itemizedlist>
494 <listitem><para id="x_630"><option role="hg-opt-strip">-b</option>: Save
495 unrelated changesets that are intermixed with the stripped
496 changesets in the backup bundle.</para>
497 </listitem>
498 <listitem><para id="x_631"><option role="hg-opt-strip">-f</option>: If a
499 branch has multiple heads, remove all heads.</para>
500 </listitem>
501 <listitem><para id="x_632"><option role="hg-opt-strip">-n</option>: Do
502 not save a backup bundle.</para>
503 </listitem></itemizedlist>
505 </sect2>
506 </sect1>
507 <sect1>
508 <title>MQ file reference</title>
510 <sect2>
511 <title>The <filename role="special">series</filename>
512 file</title>
514 <para id="x_633">The <filename role="special">series</filename> file
515 contains a list of the names of all patches that MQ can apply.
516 It is represented as a list of names, with one name saved per
517 line. Leading and trailing white space in each line are
518 ignored.</para>
520 <para id="x_634">Lines may contain comments. A comment begins with the
521 <quote><literal>#</literal></quote> character, and extends to
522 the end of the line. Empty lines, and lines that contain only
523 comments, are ignored.</para>
525 <para id="x_635">You will often need to edit the <filename
526 role="special">series</filename> file by hand, hence the
527 support for comments and empty lines noted above. For
528 example, you can comment out a patch temporarily, and <command
529 role="hg-ext-mq">qpush</command> will skip over that patch
530 when applying patches. You can also change the order in which
531 patches are applied by reordering their entries in the
532 <filename role="special">series</filename> file.</para>
534 <para id="x_636">Placing the <filename role="special">series</filename>
535 file under revision control is also supported; it is a good
536 idea to place all of the patches that it refers to under
537 revision control, as well. If you create a patch directory
538 using the <option role="hg-ext-mq-cmd-qinit-opt">-c</option>
539 option to <command role="hg-ext-mq">qinit</command>, this will
540 be done for you automatically.</para>
542 </sect2>
543 <sect2>
544 <title>The <filename role="special">status</filename>
545 file</title>
547 <para id="x_637">The <filename role="special">status</filename> file
548 contains the names and changeset hashes of all patches that MQ
549 currently has applied. Unlike the <filename
550 role="special">series</filename> file, this file is not
551 intended for editing. You should not place this file under
552 revision control, or modify it in any way. It is used by MQ
553 strictly for internal book-keeping.</para>
555 </sect2>
556 </sect1>
557 </appendix>
559 <!--
560 local variables:
561 sgml-parent-document: ("00book.xml" "book" "appendix")
562 end:
563 -->