
bos@104: \chapter{Mercurial Queues reference}
bos@224: \label{chap:mqref}
bos@104: 
bos@104: \section{MQ command reference}
bos@224: \label{sec:mqref:cmdref}
bos@104: 
bos@104: For an overview of the commands provided by MQ, use the command
bos@104: \hgcmdargs{help}{mq}.
bos@104: 
bos@104: \subsection{\hgcmd{qapplied}---print applied patches}
bos@104: 
bos@104: The \hgcmd{qapplied} command prints the current stack of applied
bos@104: patches.  Patches are printed in oldest-to-newest order, so the last
bos@104: patch in the list is the ``top'' patch.
bos@104: 
bos@104: \subsection{\hgcmd{qcommit}---commit changes in the queue repository}
bos@104: 
bos@104: The \hgcmd{qcommit} command commits any outstanding changes in the
bos@104: \sdirname{.hg/patches} repository.  This command only works if the
bos@104: \sdirname{.hg/patches} directory is a repository, i.e.~you created the
bos@104: directory using \hgcmdargs{qinit}{\hgopt{qinit}{-c}} or ran
bos@104: \hgcmd{init} in the directory after running \hgcmd{qinit}.
bos@104: 
bos@104: This command is shorthand for \hgcmdargs{commit}{--cwd .hg/patches}.
bos@104: 
bos@104: \subsection{\hgcmd{qdelete}---delete a patch from the
bos@104:   \sfilename{series} file}
bos@104: 
bos@104: The \hgcmd{qdelete} command removes the entry for a patch from the
bos@104: \sfilename{series} file in the \sdirname{.hg/patches} directory.  It
bos@104: does not pop the patch if the patch is already applied.  By default,
bos@104: it does not delete the patch file; use the \hgopt{qdel}{-f} option to
bos@104: do that.
bos@104: 
bos@104: Options:
bos@104: \begin{itemize}
bos@104: \item[\hgopt{qdel}{-f}] Delete the patch file.
bos@104: \end{itemize}
bos@104: 
bos@104: \subsection{\hgcmd{qdiff}---print a diff of the topmost applied patch}
bos@104: 
bos@104: The \hgcmd{qdiff} command prints a diff of the topmost applied patch.
bos@104: It is equivalent to \hgcmdargs{diff}{-r-2:-1}.
bos@104: 
bos@104: \subsection{\hgcmd{qfold}---merge (``fold'') several patches into one}
bos@104: 
bos@104: The \hgcmd{qfold} command merges multiple patches into the topmost
bos@104: applied patch, so that the topmost applied patch makes the union of
bos@104: all of the changes in the patches in question.
bos@104: 
bos@104: The patches to fold must not be applied; \hgcmd{qfold} will exit with
bos@104: an error if any is.  The order in which patches are folded is
bos@104: significant; \hgcmdargs{qfold}{a b} means ``apply the current topmost
bos@104: patch, followed by \texttt{a}, followed by \texttt{b}''.
bos@104: 
bos@104: The comments from the folded patches are appended to the comments of
bos@104: the destination patch, with each block of comments separated by three
bos@104: asterisk (``\texttt{*}'') characters.  Use the \hgopt{qfold}{-e}
bos@104: option to edit the commit message for the combined patch/changeset
bos@104: after the folding has completed.
bos@104: 
bos@104: Options:
bos@104: \begin{itemize}
bos@104: \item[\hgopt{qfold}{-e}] Edit the commit message and patch description
bos@104:   for the newly folded patch.
bos@104: \item[\hgopt{qfold}{-l}] Use the contents of the given file as the new
bos@104:   commit message and patch description for the folded patch.
bos@104: \item[\hgopt{qfold}{-m}] Use the given text as the new commit message
bos@104:   and patch description for the folded patch.
bos@104: \end{itemize}
bos@104: 
bos@104: \subsection{\hgcmd{qheader}---display the header/description of a patch}
bos@104: 
bos@104: The \hgcmd{qheader} command prints the header, or description, of a
bos@104: patch.  By default, it prints the header of the topmost applied patch.
bos@104: Given an argument, it prints the header of the named patch.
bos@104: 
bos@104: \subsection{\hgcmd{qimport}---import a third-party patch into the queue}
bos@104: 
bos@104: The \hgcmd{qimport} command adds an entry for an external patch to the
bos@104: \sfilename{series} file, and copies the patch into the
bos@104: \sdirname{.hg/patches} directory.  It adds the entry immediately after
bos@104: the topmost applied patch, but does not push the patch.
bos@104: 
bos@104: If the \sdirname{.hg/patches} directory is a repository,
bos@104: \hgcmd{qimport} automatically does an \hgcmd{add} of the imported
bos@104: patch.
bos@104: 
bos@104: \subsection{\hgcmd{qinit}---prepare a repository to work with MQ}
bos@104: 
bos@104: The \hgcmd{qinit} command prepares a repository to work with MQ.  It
bos@104: creates a directory called \sdirname{.hg/patches}.
bos@104: 
bos@104: Options:
bos@104: \begin{itemize}
bos@104: \item[\hgopt{qinit}{-c}] Create \sdirname{.hg/patches} as a repository
bos@104:   in its own right.  Also creates a \sfilename{.hgignore} file that
bos@104:   will ignore the \sfilename{status} file.
bos@104: \end{itemize}
bos@104: 
bos@104: When the \sdirname{.hg/patches} directory is a repository, the
bos@104: \hgcmd{qimport} and \hgcmd{qnew} commands automatically \hgcmd{add}
bos@104: new patches.
bos@104: 
bos@104: \subsection{\hgcmd{qnew}---create a new patch}
bos@104: 
bos@104: The \hgcmd{qnew} command creates a new patch.  It takes one mandatory
bos@104: argument, the name to use for the patch file.  The newly created patch
bos@104: is created empty by default.  It is added to the \sfilename{series}
bos@104: file after the current topmost applied patch, and is immediately
bos@104: pushed on top of that patch.
bos@104: 
bos@104: If \hgcmd{qnew} finds modified files in the working directory, it will
bos@104: refuse to create a new patch unless the \hgopt{qnew}{-f} option is
bos@104: used (see below).  This behaviour allows you to \hgcmd{qrefresh} your
bos@104: topmost applied patch before you apply a new patch on top of it.
bos@104: 
bos@104: Options:
bos@104: \begin{itemize}
bos@104: \item[\hgopt{qnew}{-f}] Create a new patch if the contents of the
bos@104:   working directory are modified.  Any outstanding modifications are
bos@104:   added to the newly created patch, so after this command completes,
bos@104:   the working directory will no longer be modified.
bos@104: \item[\hgopt{qnew}{-m}] Use the given text as the commit message.
bos@104:   This text will be stored at the beginning of the patch file, before
bos@104:   the patch data.
bos@104: \end{itemize}
bos@104: 
bos@104: \subsection{\hgcmd{qnext}---print the name of the next patch}
bos@104: 
bos@104: The \hgcmd{qnext} command prints the name name of the next patch in
bos@104: the \sfilename{series} file after the topmost applied patch.  This
bos@104: patch will become the topmost applied patch if you run \hgcmd{qpush}.
bos@104: 
bos@104: \subsection{\hgcmd{qpop}---pop patches off the stack}
bos@104: 
bos@104: The \hgcmd{qpop} command removes applied patches from the top of the
bos@104: stack of applied patches.  By default, it removes only one patch.
bos@104: 
bos@104: This command removes the changesets that represent the popped patches
bos@104: from the repository, and updates the working directory to undo the
bos@104: effects of the patches.
bos@104: 
bos@104: This command takes an optional argument, which it uses as the name or
bos@104: index of the patch to pop to.  If given a name, it will pop patches
bos@104: until the named patch is the topmost applied patch.  If given a
bos@104: number, \hgcmd{qpop} treats the number as an index into the entries in
bos@104: the series file, counting from zero (empty lines and lines containing
bos@104: only comments do not count).  It pops patches until the patch
bos@104: identified by the given index is the topmost applied patch.
bos@104: 
bos@104: The \hgcmd{qpop} command does not read or write patches or the
bos@104: \sfilename{series} file.  It is thus safe to \hgcmd{qpop} a patch that
bos@104: you have removed from the \sfilename{series} file, or a patch that you
bos@104: have renamed or deleted entirely.  In the latter two cases, use the
bos@104: name of the patch as it was when you applied it.
bos@104: 
bos@104: By default, the \hgcmd{qpop} command will not pop any patches if the
bos@104: working directory has been modified.  You can override this behaviour
bos@104: using the \hgopt{qpop}{-f} option, which reverts all modifications in
bos@104: the working directory.
bos@104: 
bos@104: Options:
bos@104: \begin{itemize}
bos@104: \item[\hgopt{qpop}{-a}] Pop all applied patches.  This returns the
bos@104:   repository to its state before you applied any patches.
bos@104: \item[\hgopt{qpop}{-f}] Forcibly revert any modifications to the
bos@104:   working directory when popping.
bos@104: \item[\hgopt{qpop}{-n}] Pop a patch from the named queue.
bos@104: \end{itemize}
bos@104: 
bos@104: The \hgcmd{qpop} command removes one line from the end of the
bos@104: \sfilename{status} file for each patch that it pops.
bos@104: 
bos@104: \subsection{\hgcmd{qprev}---print the name of the previous patch}
bos@104: 
bos@104: The \hgcmd{qprev} command prints the name of the patch in the
bos@104: \sfilename{series} file that comes before the topmost applied patch.
bos@104: This will become the topmost applied patch if you run \hgcmd{qpop}.
bos@104: 
bos@104: \subsection{\hgcmd{qpush}---push patches onto the stack}
bos@224: \label{sec:mqref:cmd:qpush}
bos@104: 
bos@104: The \hgcmd{qpush} command adds patches onto the applied stack.  By
bos@104: default, it adds only one patch.
bos@104: 
bos@104: This command creates a new changeset to represent each applied patch,
bos@104: and updates the working directory to apply the effects of the patches.
bos@104: 
bos@104: The default data used when creating a changeset are as follows:
bos@104: \begin{itemize}
bos@104: \item The commit date and time zone are the current date and time
bos@104:   zone.  Because these data are used to compute the identity of a
bos@104:   changeset, this means that if you \hgcmd{qpop} a patch and
bos@104:   \hgcmd{qpush} it again, the changeset that you push will have a
bos@104:   different identity than the changeset you popped.
bos@104: \item The author is the same as the default used by the \hgcmd{commit}
bos@104:   command.
bos@104: \item The commit message is any text from the patch file that comes
bos@104:   before the first diff header.  If there is no such text, a default
bos@104:   commit message is used that identifies the name of the patch.
bos@104: \end{itemize}
bos@104: If a patch contains a Mercurial patch header (XXX add link), the
bos@104: information in the patch header overrides these defaults.
bos@104: 
bos@104: Options:
bos@104: \begin{itemize}
bos@104: \item[\hgopt{qpush}{-a}] Push all unapplied patches from the
bos@104:   \sfilename{series} file until there are none left to push.
bos@104: \item[\hgopt{qpush}{-l}] Add the name of the patch to the end
bos@104:   of the commit message.
bos@104: \item[\hgopt{qpush}{-m}] If a patch fails to apply cleanly, use the
bos@104:   entry for the patch in another saved queue to compute the parameters
bos@104:   for a three-way merge, and perform a three-way merge using the
bos@104:   normal Mercurial merge machinery.  Use the resolution of the merge
bos@104:   as the new patch content.
bos@104: \item[\hgopt{qpush}{-n}] Use the named queue if merging while pushing.
bos@104: \end{itemize}
bos@104: 
bos@104: The \hgcmd{qpush} command reads, but does not modify, the
bos@104: \sfilename{series} file.  It appends one line to the \hgcmd{status}
bos@104: file for each patch that it pushes.
bos@104: 
bos@104: \subsection{\hgcmd{qrefresh}---update the topmost applied patch}
bos@104: 
bos@104: The \hgcmd{qrefresh} command updates the topmost applied patch.  It
bos@104: modifies the patch, removes the old changeset that represented the
bos@104: patch, and creates a new changeset to represent the modified patch.
bos@104: 
bos@104: The \hgcmd{qrefresh} command looks for the following modifications:
bos@104: \begin{itemize}
bos@104: \item Changes to the commit message, i.e.~the text before the first
bos@104:   diff header in the patch file, are reflected in the new changeset
bos@104:   that represents the patch.
bos@104: \item Modifications to tracked files in the working directory are
bos@104:   added to the patch.
bos@104: \item Changes to the files tracked using \hgcmd{add}, \hgcmd{copy},
bos@104:   \hgcmd{remove}, or \hgcmd{rename}.  Added files and copy and rename
bos@104:   destinations are added to the patch, while removed files and rename
bos@104:   sources are removed.
bos@104: \end{itemize}
bos@104: 
bos@104: Even if \hgcmd{qrefresh} detects no changes, it still recreates the
bos@104: changeset that represents the patch.  This causes the identity of the
bos@104: changeset to differ from the previous changeset that identified the
bos@104: patch.
bos@104: 
bos@104: Options:
bos@104: \begin{itemize}
bos@104: \item[\hgopt{qrefresh}{-e}] Modify the commit and patch description,
bos@104:   using the preferred text editor.
bos@104: \item[\hgopt{qrefresh}{-m}] Modify the commit message and patch
bos@104:   description, using the given text.
bos@104: \item[\hgopt{qrefresh}{-l}] Modify the commit message and patch
bos@104:   description, using text from the given file.
bos@104: \end{itemize}
bos@104: 
bos@104: \subsection{\hgcmd{qrename}---rename a patch}
bos@104: 
bos@104: The \hgcmd{qrename} command renames a patch, and changes the entry for
bos@104: the patch in the \sfilename{series} file.
bos@104: 
bos@104: With a single argument, \hgcmd{qrename} renames the topmost applied
bos@104: patch.  With two arguments, it renames its first argument to its
bos@104: second.
bos@104: 
bos@104: \subsection{\hgcmd{qrestore}---restore saved queue state}
bos@104: 
bos@104: XXX No idea what this does.
bos@104: 
bos@104: \subsection{\hgcmd{qsave}---save current queue state}
bos@104: 
bos@104: XXX Likewise.
bos@104: 
bos@104: \subsection{\hgcmd{qseries}---print the entire patch series}
bos@104: 
bos@104: The \hgcmd{qseries} command prints the entire patch series from the
bos@104: \sfilename{series} file.  It prints only patch names, not empty lines
bos@104: or comments.  It prints in order from first to be applied to last.
bos@104: 
bos@104: \subsection{\hgcmd{qtop}---print the name of the current patch}
bos@104: 
bos@104: The \hgcmd{qtop} prints the name of the topmost currently applied
bos@104: patch.
bos@104: 
bos@104: \subsection{\hgcmd{qunapplied}---print patches not yet applied}
bos@104: 
bos@104: The \hgcmd{qunapplied} command prints the names of patches from the
bos@104: \sfilename{series} file that are not yet applied.  It prints them in
bos@104: order from the next patch that will be pushed to the last.
bos@104: 
bos@104: \subsection{\hgcmd{qversion}}
bos@104: 
bos@104: The \hgcmd{qversion} command prints the version of MQ that is in use.
bos@104: 
bos@104: \subsection{\hgcmd{strip}---remove a revision and descendants}
bos@104: 
bos@104: The \hgcmd{strip} command removes a revision, and all of its
bos@104: descendants, from the repository.  It undoes the effects of the
bos@104: removed revisions from the repository, and updates the working
bos@104: directory to the first parent of the removed revision.
bos@104: 
bos@104: The \hgcmd{strip} command saves a backup of the removed changesets in
bos@104: a bundle, so that they can be reapplied if removed in error.
bos@104: 
bos@104: Options:
bos@104: \begin{itemize}
bos@104: \item[\hgopt{strip}{-b}] Save unrelated changesets that are intermixed
bos@104:   with the stripped changesets in the backup bundle.
bos@104: \item[\hgopt{strip}{-f}] If a branch has multiple heads, remove all
bos@104:   heads. XXX This should be renamed, and use \texttt{-f} to strip revs
bos@104:   when there are pending changes.
bos@104: \item[\hgopt{strip}{-n}] Do not save a backup bundle.
bos@104: \end{itemize}
bos@104: 
bos@104: \section{MQ file reference}
bos@104: 
bos@104: \subsection{The \sfilename{series} file}
bos@104: 
bos@104: The \sfilename{series} file contains a list of the names of all
bos@104: patches that MQ can apply.  It is represented as a list of names, with
bos@104: one name saved per line.  Leading and trailing white space in each
bos@104: line are ignored.
bos@104: 
bos@104: Lines may contain comments.  A comment begins with the ``\texttt{\#}''
bos@104: character, and extends to the end of the line.  Empty lines, and lines
bos@104: that contain only comments, are ignored.
bos@104: 
bos@104: You will often need to edit the \sfilename{series} file by hand, hence
bos@104: the support for comments and empty lines noted above.  For example,
bos@104: you can comment out a patch temporarily, and \hgcmd{qpush} will skip
bos@104: over that patch when applying patches.  You can also change the order
bos@104: in which patches are applied by reordering their entries in the
bos@104: \sfilename{series} file.
bos@104: 
bos@104: Placing the \sfilename{series} file under revision control is also
bos@104: supported; it is a good idea to place all of the patches that it
bos@104: refers to under revision control, as well.  If you create a patch
bos@104: directory using the \hgopt{qinit}{-c} option to \hgcmd{qinit}, this
bos@104: will be done for you automatically.
bos@104: 
bos@104: \subsection{The \sfilename{status} file}
bos@104: 
bos@104: The \sfilename{status} file contains the names and changeset hashes of
bos@104: all patches that MQ currently has applied.  Unlike the
bos@104: \sfilename{series} file, this file is not intended for editing.  You
bos@104: should not place this file under revision control, or modify it in any
bos@104: way.  It is used by MQ strictly for internal book-keeping.
bos@104: 
bos@104: %%% Local Variables: 
bos@104: %%% mode: latex
bos@104: %%% TeX-master: "00book"
bos@104: %%% End: 




