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@233: \subsection{\hgxcmd{mq}{qapplied}---print applied patches} bos@233: bos@233: The \hgxcmd{mq}{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@233: \subsection{\hgxcmd{mq}{qcommit}---commit changes in the queue repository} bos@233: bos@233: The \hgxcmd{mq}{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@234: directory using \hgcmdargs{qinit}{\hgxopt{mq}{qinit}{-c}} or ran bos@233: \hgcmd{init} in the directory after running \hgxcmd{mq}{qinit}. bos@104: bos@104: This command is shorthand for \hgcmdargs{commit}{--cwd .hg/patches}. bos@104: bos@233: \subsection{\hgxcmd{mq}{qdelete}---delete a patch from the bos@104: \sfilename{series} file} bos@104: bos@233: The \hgxcmd{mq}{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@234: it does not delete the patch file; use the \hgxopt{mq}{qdel}{-f} option to bos@104: do that. bos@104: bos@104: Options: bos@104: \begin{itemize} bos@234: \item[\hgxopt{mq}{qdel}{-f}] Delete the patch file. bos@104: \end{itemize} bos@104: bos@233: \subsection{\hgxcmd{mq}{qdiff}---print a diff of the topmost applied patch} bos@233: bos@233: The \hgxcmd{mq}{qdiff} command prints a diff of the topmost applied patch. bos@104: It is equivalent to \hgcmdargs{diff}{-r-2:-1}. bos@104: bos@233: \subsection{\hgxcmd{mq}{qfold}---merge (``fold'') several patches into one} bos@233: bos@233: The \hgxcmd{mq}{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@233: The patches to fold must not be applied; \hgxcmd{mq}{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@234: asterisk (``\texttt{*}'') characters. Use the \hgxopt{mq}{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@234: \item[\hgxopt{mq}{qfold}{-e}] Edit the commit message and patch description bos@104: for the newly folded patch. bos@234: \item[\hgxopt{mq}{qfold}{-l}] Use the contents of the given file as the new bos@104: commit message and patch description for the folded patch. bos@234: \item[\hgxopt{mq}{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@233: \subsection{\hgxcmd{mq}{qheader}---display the header/description of a patch} bos@233: bos@233: The \hgxcmd{mq}{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@233: \subsection{\hgxcmd{mq}{qimport}---import a third-party patch into the queue} bos@233: bos@233: The \hgxcmd{mq}{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@233: \hgxcmd{mq}{qimport} automatically does an \hgcmd{add} of the imported bos@104: patch. bos@104: bos@233: \subsection{\hgxcmd{mq}{qinit}---prepare a repository to work with MQ} bos@233: bos@233: The \hgxcmd{mq}{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@234: \item[\hgxopt{mq}{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@233: \hgxcmd{mq}{qimport} and \hgxcmd{mq}{qnew} commands automatically \hgcmd{add} bos@104: new patches. bos@104: bos@233: \subsection{\hgxcmd{mq}{qnew}---create a new patch} bos@233: bos@233: The \hgxcmd{mq}{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@233: If \hgxcmd{mq}{qnew} finds modified files in the working directory, it will bos@234: refuse to create a new patch unless the \hgxopt{mq}{qnew}{-f} option is bos@233: used (see below). This behaviour allows you to \hgxcmd{mq}{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@234: \item[\hgxopt{mq}{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@234: \item[\hgxopt{mq}{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@233: \subsection{\hgxcmd{mq}{qnext}---print the name of the next patch} bos@233: bos@233: The \hgxcmd{mq}{qnext} command prints the name name of the next patch in bos@104: the \sfilename{series} file after the topmost applied patch. This bos@233: patch will become the topmost applied patch if you run \hgxcmd{mq}{qpush}. bos@233: bos@233: \subsection{\hgxcmd{mq}{qpop}---pop patches off the stack} bos@233: bos@233: The \hgxcmd{mq}{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@233: number, \hgxcmd{mq}{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@233: The \hgxcmd{mq}{qpop} command does not read or write patches or the bos@233: \sfilename{series} file. It is thus safe to \hgxcmd{mq}{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@233: By default, the \hgxcmd{mq}{qpop} command will not pop any patches if the bos@104: working directory has been modified. You can override this behaviour bos@234: using the \hgxopt{mq}{qpop}{-f} option, which reverts all modifications in bos@104: the working directory. bos@104: bos@104: Options: bos@104: \begin{itemize} bos@234: \item[\hgxopt{mq}{qpop}{-a}] Pop all applied patches. This returns the bos@104: repository to its state before you applied any patches. bos@234: \item[\hgxopt{mq}{qpop}{-f}] Forcibly revert any modifications to the bos@104: working directory when popping. bos@234: \item[\hgxopt{mq}{qpop}{-n}] Pop a patch from the named queue. bos@104: \end{itemize} bos@104: bos@233: The \hgxcmd{mq}{qpop} command removes one line from the end of the bos@104: \sfilename{status} file for each patch that it pops. bos@104: bos@233: \subsection{\hgxcmd{mq}{qprev}---print the name of the previous patch} bos@233: bos@233: The \hgxcmd{mq}{qprev} command prints the name of the patch in the bos@104: \sfilename{series} file that comes before the topmost applied patch. bos@233: This will become the topmost applied patch if you run \hgxcmd{mq}{qpop}. bos@233: bos@233: \subsection{\hgxcmd{mq}{qpush}---push patches onto the stack} bos@224: \label{sec:mqref:cmd:qpush} bos@104: bos@233: The \hgxcmd{mq}{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@233: changeset, this means that if you \hgxcmd{mq}{qpop} a patch and bos@233: \hgxcmd{mq}{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@234: \item[\hgxopt{mq}{qpush}{-a}] Push all unapplied patches from the bos@104: \sfilename{series} file until there are none left to push. bos@234: \item[\hgxopt{mq}{qpush}{-l}] Add the name of the patch to the end bos@104: of the commit message. bos@234: \item[\hgxopt{mq}{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@234: \item[\hgxopt{mq}{qpush}{-n}] Use the named queue if merging while pushing. bos@104: \end{itemize} bos@104: bos@233: The \hgxcmd{mq}{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@233: \subsection{\hgxcmd{mq}{qrefresh}---update the topmost applied patch} bos@233: bos@233: The \hgxcmd{mq}{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@233: The \hgxcmd{mq}{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@233: Even if \hgxcmd{mq}{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@234: \item[\hgxopt{mq}{qrefresh}{-e}] Modify the commit and patch description, bos@104: using the preferred text editor. bos@234: \item[\hgxopt{mq}{qrefresh}{-m}] Modify the commit message and patch bos@104: description, using the given text. bos@234: \item[\hgxopt{mq}{qrefresh}{-l}] Modify the commit message and patch bos@104: description, using text from the given file. bos@104: \end{itemize} bos@104: bos@233: \subsection{\hgxcmd{mq}{qrename}---rename a patch} bos@233: bos@233: The \hgxcmd{mq}{qrename} command renames a patch, and changes the entry for bos@104: the patch in the \sfilename{series} file. bos@104: bos@233: With a single argument, \hgxcmd{mq}{qrename} renames the topmost applied bos@104: patch. With two arguments, it renames its first argument to its bos@104: second. bos@104: bos@233: \subsection{\hgxcmd{mq}{qrestore}---restore saved queue state} bos@104: bos@104: XXX No idea what this does. bos@104: bos@233: \subsection{\hgxcmd{mq}{qsave}---save current queue state} bos@104: bos@104: XXX Likewise. bos@104: bos@233: \subsection{\hgxcmd{mq}{qseries}---print the entire patch series} bos@233: bos@233: The \hgxcmd{mq}{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@233: \subsection{\hgxcmd{mq}{qtop}---print the name of the current patch} bos@233: bos@233: The \hgxcmd{mq}{qtop} prints the name of the topmost currently applied bos@104: patch. bos@104: bos@233: \subsection{\hgxcmd{mq}{qunapplied}---print patches not yet applied} bos@233: bos@233: The \hgxcmd{mq}{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{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@233: you can comment out a patch temporarily, and \hgxcmd{mq}{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@234: directory using the \hgxopt{mq}{qinit}{-c} option to \hgxcmd{mq}{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: