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




