annotate en/appB-mq-ref.xml @ 658:b90b024729f1

WIP DocBook snapshot that all compiles. Mirabile dictu!

<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->

<appendix id="chap:mqref">
  <title>Mercurial Queues reference</title>

  <sect1 id="sec:mqref:cmdref">
    <title>MQ command reference</title>

    <para>For an overview of the commands provided by MQ, use the
      command <command role="hg-cmd">hg help mq</command>.</para>

    <sect2>
      <title><command role="hg-ext-mq">qapplied</command>&emdash;print
	applied patches</title>

      <para>The <command role="hg-ext-mq">qapplied</command> command
	prints the current stack of applied patches.  Patches are
	printed in oldest-to-newest order, so the last patch in the
	list is the <quote>top</quote> patch.</para>

    </sect2>
    <sect2>
      <title><command role="hg-ext-mq">qcommit</command>&emdash;commit
	changes in the queue repository</title>

      <para>The <command role="hg-ext-mq">qcommit</command> command
	commits any outstanding changes in the <filename
	  role="special" class="directory">.hg/patches</filename>
	repository.  This command only works if the <filename
	  role="special" class="directory">.hg/patches</filename>
	directory is a repository, i.e. you created the directory
	using <command role="hg-cmd">hg qinit <option
	    role="hg-ext-mq-cmd-qinit-opt">-c</option></command> or
	ran <command role="hg-cmd">hg init</command> in the directory
	after running <command
	  role="hg-ext-mq">qinit</command>.</para>

      <para>This command is shorthand for <command role="hg-cmd">hg
	  commit --cwd .hg/patches</command>.</para>

      <para>\subsection{<command
	  role="hg-ext-mq">qdelete</command>&emdash;delete a patch
	from the <filename role="special">series</filename>
	file}</para>

      <para>The <command role="hg-ext-mq">qdelete</command> command
	removes the entry for a patch from the <filename
	  role="special">series</filename> file in the <filename
	  role="special" class="directory">.hg/patches</filename>
	directory.  It does not pop the patch if the patch is already
	applied.  By default, it does not delete the patch file; use
	the <option role="hg-ext-mq-cmd-qdel-opt">-f</option> option
	to do that.</para>

      <para>Options:</para>
      <itemizedlist>
	<listitem><para><option
	      role="hg-ext-mq-cmd-qdel-opt">-f</option>: Delete the
	    patch file.</para>
	</listitem></itemizedlist>

    </sect2>
    <sect2>
      <title><command role="hg-ext-mq">qdiff</command>&emdash;print a
	diff of the topmost applied patch</title>

      <para>The <command role="hg-ext-mq">qdiff</command> command
	prints a diff of the topmost applied patch. It is equivalent
	to <command role="hg-cmd">hg diff -r-2:-1</command>.</para>

    </sect2>
    <sect2>
      <title><command role="hg-ext-mq">qfold</command>&emdash;merge
	(<quote>fold</quote>) several patches into one</title>

      <para>The <command role="hg-ext-mq">qfold</command> command
	merges multiple patches into the topmost applied patch, so
	that the topmost applied patch makes the union of all of the
	changes in the patches in question.</para>

      <para>The patches to fold must not be applied; <command
	  role="hg-ext-mq">qfold</command> will exit with an error if
	any is.  The order in which patches are folded is significant;
	<command role="hg-cmd">hg qfold a b</command> means
	<quote>apply the current topmost patch, followed by
	  <literal>a</literal>, followed by
	  <literal>b</literal></quote>.</para>

      <para>The comments from the folded patches are appended to the
	comments of the destination patch, with each block of comments
	separated by three asterisk
	(<quote><literal>*</literal></quote>) characters.  Use the
	<option role="hg-ext-mq-cmd-qfold-opt">-e</option> option to
	edit the commit message for the combined patch/changeset after
	the folding has completed.</para>

      <para>Options:</para>
      <itemizedlist>
	<listitem><para><option
	      role="hg-ext-mq-cmd-qfold-opt">-e</option>: Edit the
	    commit message and patch description for the newly folded
	    patch.</para>
	</listitem>
	<listitem><para><option
	      role="hg-ext-mq-cmd-qfold-opt">-l</option>: Use the
	    contents of the given file as the new commit message and
	    patch description for the folded patch.</para>
	</listitem>
	<listitem><para><option
	      role="hg-ext-mq-cmd-qfold-opt">-m</option>: Use the
	    given text as the new commit message and patch description
	    for the folded patch.</para>
	</listitem></itemizedlist>

    </sect2>
    <sect2>
      <title><command
	  role="hg-ext-mq">qheader</command>&emdash;display the
	header/description of a patch</title>

      <para>The <command role="hg-ext-mq">qheader</command> command
	prints the header, or description, of a patch.  By default, it
	prints the header of the topmost applied patch. Given an
	argument, it prints the header of the named patch.</para>

    </sect2>
    <sect2>
      <title><command role="hg-ext-mq">qimport</command>&emdash;import
	a third-party patch into the queue</title>

      <para>The <command role="hg-ext-mq">qimport</command> command
	adds an entry for an external patch to the <filename
	  role="special">series</filename> file, and copies the patch
	into the <filename role="special"
	  class="directory">.hg/patches</filename> directory.  It adds
	the entry immediately after the topmost applied patch, but
	does not push the patch.</para>

      <para>If the <filename role="special"
	  class="directory">.hg/patches</filename> directory is a
	repository, <command role="hg-ext-mq">qimport</command>
	automatically does an <command role="hg-cmd">hg add</command>
	of the imported patch.</para>

    </sect2>
    <sect2>
      <title><command role="hg-ext-mq">qinit</command>&emdash;prepare
	a repository to work with MQ</title>

      <para>The <command role="hg-ext-mq">qinit</command> command
	prepares a repository to work with MQ.  It creates a directory
	called <filename role="special"
	  class="directory">.hg/patches</filename>.</para>

      <para>Options:</para>
      <itemizedlist>
	<listitem><para><option
	      role="hg-ext-mq-cmd-qinit-opt">-c</option>: Create
	    <filename role="special"
	      class="directory">.hg/patches</filename> as a repository
	    in its own right.  Also creates a <filename
	      role="special">.hgignore</filename> file that will
	    ignore the <filename role="special">status</filename>
	    file.</para>
	</listitem></itemizedlist>

      <para>When the <filename role="special"
	  class="directory">.hg/patches</filename> directory is a
	repository, the <command role="hg-ext-mq">qimport</command>
	and <command role="hg-ext-mq">qnew</command> commands
	automatically <command role="hg-cmd">hg add</command> new
	patches.</para>

    </sect2>
    <sect2>
      <title><command role="hg-ext-mq">qnew</command>&emdash;create a
	new patch</title>

      <para>The <command role="hg-ext-mq">qnew</command> command
	creates a new patch.  It takes one mandatory argument, the
	name to use for the patch file.  The newly created patch is
	created empty by default.  It is added to the <filename
	  role="special">series</filename> file after the current
	topmost applied patch, and is immediately pushed on top of
	that patch.</para>

      <para>If <command role="hg-ext-mq">qnew</command> finds modified
	files in the working directory, it will refuse to create a new
	patch unless the <option
	  role="hg-ext-mq-cmd-qnew-opt">-f</option> option is used
	(see below).  This behaviour allows you to <command
	  role="hg-ext-mq">qrefresh</command> your topmost applied
	patch before you apply a new patch on top of it.</para>

      <para>Options:</para>
      <itemizedlist>
	<listitem><para><option
	      role="hg-ext-mq-cmd-qnew-opt">-f</option>: Create a new
	    patch if the contents of the working directory are
	    modified.  Any outstanding modifications are added to the
	    newly created patch, so after this command completes, the
	    working directory will no longer be modified.</para>
	</listitem>
	<listitem><para><option
	      role="hg-ext-mq-cmd-qnew-opt">-m</option>: Use the given
	    text as the commit message. This text will be stored at
	    the beginning of the patch file, before the patch
	    data.</para>
	</listitem></itemizedlist>

    </sect2>
    <sect2>
      <title><command role="hg-ext-mq">qnext</command>&emdash;print
	the name of the next patch</title>

      <para>The <command role="hg-ext-mq">qnext</command> command
	prints the name name of the next patch in the <filename
	  role="special">series</filename> file after the topmost
	applied patch.  This patch will become the topmost applied
	patch if you run <command
	  role="hg-ext-mq">qpush</command>.</para>

    </sect2>
    <sect2>
      <title><command role="hg-ext-mq">qpop</command>&emdash;pop
	patches off the stack</title>

      <para>The <command role="hg-ext-mq">qpop</command> command
	removes applied patches from the top of the stack of applied
	patches.  By default, it removes only one patch.</para>

      <para>This command removes the changesets that represent the
	popped patches from the repository, and updates the working
	directory to undo the effects of the patches.</para>

      <para>This command takes an optional argument, which it uses as
	the name or index of the patch to pop to.  If given a name, it
	will pop patches until the named patch is the topmost applied
	patch.  If given a number, <command
	  role="hg-ext-mq">qpop</command> treats the number as an
	index into the entries in the series file, counting from zero
	(empty lines and lines containing only comments do not count).
	It pops patches until the patch identified by the given index
	is the topmost applied patch.</para>

      <para>The <command role="hg-ext-mq">qpop</command> command does
	not read or write patches or the <filename
	  role="special">series</filename> file.  It is thus safe to
	<command role="hg-ext-mq">qpop</command> a patch that you have
	removed from the <filename role="special">series</filename>
	file, or a patch that you have renamed or deleted entirely.
	In the latter two cases, use the name of the patch as it was
	when you applied it.</para>

      <para>By default, the <command role="hg-ext-mq">qpop</command>
	command will not pop any patches if the working directory has
	been modified.  You can override this behaviour using the
	<option role="hg-ext-mq-cmd-qpop-opt">-f</option> option,
	which reverts all modifications in the working
	directory.</para>

      <para>Options:</para>
      <itemizedlist>
	<listitem><para><option
	      role="hg-ext-mq-cmd-qpop-opt">-a</option>: Pop all
	    applied patches.  This returns the repository to its state
	    before you applied any patches.</para>
	</listitem>
	<listitem><para><option
	      role="hg-ext-mq-cmd-qpop-opt">-f</option>: Forcibly
	    revert any modifications to the working directory when
	    popping.</para>
	</listitem>
	<listitem><para><option
	      role="hg-ext-mq-cmd-qpop-opt">-n</option>: Pop a patch
	    from the named queue.</para>
	</listitem></itemizedlist>

      <para>The <command role="hg-ext-mq">qpop</command> command
	removes one line from the end of the <filename
	  role="special">status</filename> file for each patch that it
	pops.</para>

    </sect2>
    <sect2>
      <title><command role="hg-ext-mq">qprev</command>&emdash;print
	the name of the previous patch</title>

      <para>The <command role="hg-ext-mq">qprev</command> command
	prints the name of the patch in the <filename
	  role="special">series</filename> file that comes before the
	topmost applied patch. This will become the topmost applied
	patch if you run <command
	  role="hg-ext-mq">qpop</command>.</para>

    </sect2>
    <sect2 id="sec:mqref:cmd:qpush">
      <title><command role="hg-ext-mq">qpush</command>&emdash;push
	patches onto the stack</title>

      <para>The <command role="hg-ext-mq">qpush</command> command adds
	patches onto the applied stack.  By default, it adds only one
	patch.</para>

      <para>This command creates a new changeset to represent each
	applied patch, and updates the working directory to apply the
	effects of the patches.</para>

      <para>The default data used when creating a changeset are as
	follows:</para>
      <itemizedlist>
	<listitem><para>The commit date and time zone are the current
	    date and time zone.  Because these data are used to
	    compute the identity of a changeset, this means that if
	    you <command role="hg-ext-mq">qpop</command> a patch and
	    <command role="hg-ext-mq">qpush</command> it again, the
	    changeset that you push will have a different identity
	    than the changeset you popped.</para>
	</listitem>
	<listitem><para>The author is the same as the default used by
	    the <command role="hg-cmd">hg commit</command>
	    command.</para>
	</listitem>
	<listitem><para>The commit message is any text from the patch
	    file that comes before the first diff header.  If there is
	    no such text, a default commit message is used that
	    identifies the name of the patch.</para>
	</listitem></itemizedlist>
      <para>If a patch contains a Mercurial patch header (XXX add
	link), the information in the patch header overrides these
	defaults.</para>

      <para>Options:</para>
      <itemizedlist>
	<listitem><para><option
	      role="hg-ext-mq-cmd-qpush-opt">-a</option>: Push all
	    unapplied patches from the <filename
	      role="special">series</filename> file until there are
	    none left to push.</para>
	</listitem>
	<listitem><para><option
	      role="hg-ext-mq-cmd-qpush-opt">-l</option>: Add the name
	    of the patch to the end of the commit message.</para>
	</listitem>
	<listitem><para><option
	      role="hg-ext-mq-cmd-qpush-opt">-m</option>: If a patch
	    fails to apply cleanly, use the entry for the patch in
	    another saved queue to compute the parameters for a
	    three-way merge, and perform a three-way merge using the
	    normal Mercurial merge machinery.  Use the resolution of
	    the merge as the new patch content.</para>
	</listitem>
	<listitem><para><option
	      role="hg-ext-mq-cmd-qpush-opt">-n</option>: Use the
	    named queue if merging while pushing.</para>
	</listitem></itemizedlist>

      <para>The <command role="hg-ext-mq">qpush</command> command
	reads, but does not modify, the <filename
	  role="special">series</filename> file.  It appends one line
	to the <command role="hg-cmd">hg status</command> file for
	each patch that it pushes.</para>

    </sect2>
    <sect2>
      <title><command
	  role="hg-ext-mq">qrefresh</command>&emdash;update the
	topmost applied patch</title>

      <para>The <command role="hg-ext-mq">qrefresh</command> command
	updates the topmost applied patch.  It modifies the patch,
	removes the old changeset that represented the patch, and
	creates a new changeset to represent the modified
	patch.</para>

      <para>The <command role="hg-ext-mq">qrefresh</command> command
	looks for the following modifications:</para>
      <itemizedlist>
	<listitem><para>Changes to the commit message, i.e. the text
	    before the first diff header in the patch file, are
	    reflected in the new changeset that represents the
	    patch.</para>
	</listitem>
	<listitem><para>Modifications to tracked files in the working
	    directory are added to the patch.</para>
	</listitem>
	<listitem><para>Changes to the files tracked using <command
	      role="hg-cmd">hg add</command>, <command
	      role="hg-cmd">hg copy</command>, <command
	      role="hg-cmd">hg remove</command>, or <command
	      role="hg-cmd">hg rename</command>.  Added files and copy
	    and rename destinations are added to the patch, while
	    removed files and rename sources are removed.</para>
	</listitem></itemizedlist>

      <para>Even if <command role="hg-ext-mq">qrefresh</command>
	detects no changes, it still recreates the changeset that
	represents the patch.  This causes the identity of the
	changeset to differ from the previous changeset that
	identified the patch.</para>

      <para>Options:</para>
      <itemizedlist>
	<listitem><para><option
	      role="hg-ext-mq-cmd-qrefresh-opt">-e</option>: Modify
	    the commit and patch description, using the preferred text
	    editor.</para>
	</listitem>
	<listitem><para><option
	      role="hg-ext-mq-cmd-qrefresh-opt">-m</option>: Modify
	    the commit message and patch description, using the given
	    text.</para>
	</listitem>
	<listitem><para><option
	      role="hg-ext-mq-cmd-qrefresh-opt">-l</option>: Modify
	    the commit message and patch description, using text from
	    the given file.</para>
	</listitem></itemizedlist>

    </sect2>
    <sect2>
      <title><command role="hg-ext-mq">qrename</command>&emdash;rename
	a patch</title>

      <para>The <command role="hg-ext-mq">qrename</command> command
	renames a patch, and changes the entry for the patch in the
	<filename role="special">series</filename> file.</para>

      <para>With a single argument, <command
	  role="hg-ext-mq">qrename</command> renames the topmost
	applied patch.  With two arguments, it renames its first
	argument to its second.</para>

    </sect2>
    <sect2>
      <title><command
	  role="hg-ext-mq">qrestore</command>&emdash;restore saved
	queue state</title>

      <para>XXX No idea what this does.</para>

    </sect2>
    <sect2>
      <title><command role="hg-ext-mq">qsave</command>&emdash;save
	current queue state</title>

      <para>XXX Likewise.</para>

    </sect2>
    <sect2>
      <title><command role="hg-ext-mq">qseries</command>&emdash;print
	the entire patch series</title>

      <para>The <command role="hg-ext-mq">qseries</command> command
	prints the entire patch series from the <filename
	  role="special">series</filename> file.  It prints only patch
	names, not empty lines or comments.  It prints in order from
	first to be applied to last.</para>

    </sect2>
    <sect2>
      <title><command role="hg-ext-mq">qtop</command>&emdash;print the
	name of the current patch</title>

      <para>The <command role="hg-ext-mq">qtop</command> prints the
	name of the topmost currently applied patch.</para>

    </sect2>
    <sect2>
      <title><command
	  role="hg-ext-mq">qunapplied</command>&emdash;print patches
	not yet applied</title>

      <para>The <command role="hg-ext-mq">qunapplied</command> command
	prints the names of patches from the <filename
	  role="special">series</filename> file that are not yet
	applied.  It prints them in order from the next patch that
	will be pushed to the last.</para>

    </sect2>
    <sect2>
      <title><command role="hg-cmd">hg strip</command>&emdash;remove a
	revision and descendants</title>

      <para>The <command role="hg-cmd">hg strip</command> command
	removes a revision, and all of its descendants, from the
	repository.  It undoes the effects of the removed revisions
	from the repository, and updates the working directory to the
	first parent of the removed revision.</para>

      <para>The <command role="hg-cmd">hg strip</command> command
	saves a backup of the removed changesets in a bundle, so that
	they can be reapplied if removed in error.</para>

      <para>Options:</para>
      <itemizedlist>
	<listitem><para><option role="hg-opt-strip">-b</option>: Save
	    unrelated changesets that are intermixed with the stripped
	    changesets in the backup bundle.</para>
	</listitem>
	<listitem><para><option role="hg-opt-strip">-f</option>: If a
	    branch has multiple heads, remove all heads. XXX This
	    should be renamed, and use <literal>-f</literal> to strip
	    revs when there are pending changes.</para>
	</listitem>
	<listitem><para><option role="hg-opt-strip">-n</option>: Do
	    not save a backup bundle.</para>
	</listitem></itemizedlist>

    </sect2>
  </sect1>
  <sect1>
    <title>MQ file reference</title>

    <sect2>
      <title>The <filename role="special">series</filename>
	file</title>

      <para>The <filename role="special">series</filename> file
	contains a list of the names of all patches that MQ can apply.
	It is represented as a list of names, with one name saved per
	line.  Leading and trailing white space in each line are
	ignored.</para>

      <para>Lines may contain comments.  A comment begins with the
	<quote><literal>#</literal></quote> character, and extends to
	the end of the line.  Empty lines, and lines that contain only
	comments, are ignored.</para>

      <para>You will often need to edit the <filename
	  role="special">series</filename> file by hand, hence the
	support for comments and empty lines noted above.  For
	example, you can comment out a patch temporarily, and <command
	  role="hg-ext-mq">qpush</command> will skip over that patch
	when applying patches.  You can also change the order in which
	patches are applied by reordering their entries in the
	<filename role="special">series</filename> file.</para>

      <para>Placing the <filename role="special">series</filename>
	file under revision control is also supported; it is a good
	idea to place all of the patches that it refers to under
	revision control, as well.  If you create a patch directory
	using the <option role="hg-ext-mq-cmd-qinit-opt">-c</option>
	option to <command role="hg-ext-mq">qinit</command>, this will
	be done for you automatically.</para>

    </sect2>
    <sect2>
      <title>The <filename role="special">status</filename>
	file</title>

      <para>The <filename role="special">status</filename> file
	contains the names and changeset hashes of all patches that MQ
	currently has applied.  Unlike the <filename
	  role="special">series</filename> file, this file is not
	intended for editing.  You should not place this file under
	revision control, or modify it in any way.  It is used by MQ
	strictly for internal book-keeping.</para>

    </sect2>
  </sect1>
</appendix>

<!--
local variables: 
sgml-parent-document: ("00book.xml" "book" "appendix")
end:
-->