# HG changeset patch # User Bryan O'Sullivan # Date 1180284196 25200 # Node ID 30e97616d808a94fd01f04e58f0fc02e4d4e1eab # Parent 696b1e0c01dfc0aee590143fcf9a726a6ba8878e Tag all MQ command options as belonging to the mq extension. diff -r 696b1e0c01df -r 30e97616d808 en/mq-ref.tex --- a/en/mq-ref.tex Sun May 27 09:41:55 2007 -0700 +++ b/en/mq-ref.tex Sun May 27 09:43:16 2007 -0700 @@ -18,7 +18,7 @@ The \hgxcmd{mq}{qcommit} command commits any outstanding changes in the \sdirname{.hg/patches} repository. This command only works if the \sdirname{.hg/patches} directory is a repository, i.e.~you created the -directory using \hgcmdargs{qinit}{\hgopt{qinit}{-c}} or ran +directory using \hgcmdargs{qinit}{\hgxopt{mq}{qinit}{-c}} or ran \hgcmd{init} in the directory after running \hgxcmd{mq}{qinit}. This command is shorthand for \hgcmdargs{commit}{--cwd .hg/patches}. @@ -29,12 +29,12 @@ The \hgxcmd{mq}{qdelete} command removes the entry for a patch from the \sfilename{series} file in the \sdirname{.hg/patches} directory. It does not pop the patch if the patch is already applied. By default, -it does not delete the patch file; use the \hgopt{qdel}{-f} option to +it does not delete the patch file; use the \hgxopt{mq}{qdel}{-f} option to do that. Options: \begin{itemize} -\item[\hgopt{qdel}{-f}] Delete the patch file. +\item[\hgxopt{mq}{qdel}{-f}] Delete the patch file. \end{itemize} \subsection{\hgxcmd{mq}{qdiff}---print a diff of the topmost applied patch} @@ -55,17 +55,17 @@ The comments from the folded patches are appended to the comments of the destination patch, with each block of comments separated by three -asterisk (``\texttt{*}'') characters. Use the \hgopt{qfold}{-e} +asterisk (``\texttt{*}'') characters. Use the \hgxopt{mq}{qfold}{-e} option to edit the commit message for the combined patch/changeset after the folding has completed. Options: \begin{itemize} -\item[\hgopt{qfold}{-e}] Edit the commit message and patch description +\item[\hgxopt{mq}{qfold}{-e}] Edit the commit message and patch description for the newly folded patch. -\item[\hgopt{qfold}{-l}] Use the contents of the given file as the new +\item[\hgxopt{mq}{qfold}{-l}] Use the contents of the given file as the new commit message and patch description for the folded patch. -\item[\hgopt{qfold}{-m}] Use the given text as the new commit message +\item[\hgxopt{mq}{qfold}{-m}] Use the given text as the new commit message and patch description for the folded patch. \end{itemize} @@ -93,7 +93,7 @@ Options: \begin{itemize} -\item[\hgopt{qinit}{-c}] Create \sdirname{.hg/patches} as a repository +\item[\hgxopt{mq}{qinit}{-c}] Create \sdirname{.hg/patches} as a repository in its own right. Also creates a \sfilename{.hgignore} file that will ignore the \sfilename{status} file. \end{itemize} @@ -111,17 +111,17 @@ pushed on top of that patch. If \hgxcmd{mq}{qnew} finds modified files in the working directory, it will -refuse to create a new patch unless the \hgopt{qnew}{-f} option is +refuse to create a new patch unless the \hgxopt{mq}{qnew}{-f} option is used (see below). This behaviour allows you to \hgxcmd{mq}{qrefresh} your topmost applied patch before you apply a new patch on top of it. Options: \begin{itemize} -\item[\hgopt{qnew}{-f}] Create a new patch if the contents of the +\item[\hgxopt{mq}{qnew}{-f}] 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. -\item[\hgopt{qnew}{-m}] Use the given text as the commit message. +\item[\hgxopt{mq}{qnew}{-m}] Use the given text as the commit message. This text will be stored at the beginning of the patch file, before the patch data. \end{itemize} @@ -157,16 +157,16 @@ By default, the \hgxcmd{mq}{qpop} command will not pop any patches if the working directory has been modified. You can override this behaviour -using the \hgopt{qpop}{-f} option, which reverts all modifications in +using the \hgxopt{mq}{qpop}{-f} option, which reverts all modifications in the working directory. Options: \begin{itemize} -\item[\hgopt{qpop}{-a}] Pop all applied patches. This returns the +\item[\hgxopt{mq}{qpop}{-a}] Pop all applied patches. This returns the repository to its state before you applied any patches. -\item[\hgopt{qpop}{-f}] Forcibly revert any modifications to the +\item[\hgxopt{mq}{qpop}{-f}] Forcibly revert any modifications to the working directory when popping. -\item[\hgopt{qpop}{-n}] Pop a patch from the named queue. +\item[\hgxopt{mq}{qpop}{-n}] Pop a patch from the named queue. \end{itemize} The \hgxcmd{mq}{qpop} command removes one line from the end of the @@ -205,16 +205,16 @@ Options: \begin{itemize} -\item[\hgopt{qpush}{-a}] Push all unapplied patches from the +\item[\hgxopt{mq}{qpush}{-a}] Push all unapplied patches from the \sfilename{series} file until there are none left to push. -\item[\hgopt{qpush}{-l}] Add the name of the patch to the end +\item[\hgxopt{mq}{qpush}{-l}] Add the name of the patch to the end of the commit message. -\item[\hgopt{qpush}{-m}] If a patch fails to apply cleanly, use the +\item[\hgxopt{mq}{qpush}{-m}] 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. -\item[\hgopt{qpush}{-n}] Use the named queue if merging while pushing. +\item[\hgxopt{mq}{qpush}{-n}] Use the named queue if merging while pushing. \end{itemize} The \hgxcmd{mq}{qpush} command reads, but does not modify, the @@ -247,11 +247,11 @@ Options: \begin{itemize} -\item[\hgopt{qrefresh}{-e}] Modify the commit and patch description, +\item[\hgxopt{mq}{qrefresh}{-e}] Modify the commit and patch description, using the preferred text editor. -\item[\hgopt{qrefresh}{-m}] Modify the commit message and patch +\item[\hgxopt{mq}{qrefresh}{-m}] Modify the commit message and patch description, using the given text. -\item[\hgopt{qrefresh}{-l}] Modify the commit message and patch +\item[\hgxopt{mq}{qrefresh}{-l}] Modify the commit message and patch description, using text from the given file. \end{itemize} @@ -336,7 +336,7 @@ Placing the \sfilename{series} 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 \hgopt{qinit}{-c} option to \hgxcmd{mq}{qinit}, this +directory using the \hgxopt{mq}{qinit}{-c} option to \hgxcmd{mq}{qinit}, this will be done for you automatically. \subsection{The \sfilename{status} file} diff -r 696b1e0c01df -r 30e97616d808 en/mq.tex --- a/en/mq.tex Sun May 27 09:41:55 2007 -0700 +++ b/en/mq.tex Sun May 27 09:43:16 2007 -0700 @@ -384,8 +384,8 @@ While \hgxcmd{mq}{qpush} and \hgxcmd{mq}{qpop} each operate on a single patch at a time by default, you can push and pop many patches in one go. The -\hgopt{qpush}{-a} option to \hgxcmd{mq}{qpush} causes it to push all -unapplied patches, while the \hgopt{qpop}{-a} option to \hgxcmd{mq}{qpop} +\hgxopt{mq}{qpush}{-a} option to \hgxcmd{mq}{qpush} causes it to push all +unapplied patches, while the \hgxopt{mq}{qpop}{-a} option to \hgxcmd{mq}{qpop} causes it to pop all applied patches. (For some more ways to push and pop many patches, see section~\ref{sec:mq:perf} below.) @@ -414,9 +414,9 @@ Commands that check the working directory all take an ``I know what I'm doing'' option, which is always named \option{-f}. The exact meaning of \option{-f} depends on the command. For example, -\hgcmdargs{qnew}{\hgopt{qnew}{-f}} will incorporate any outstanding +\hgcmdargs{qnew}{\hgxopt{mq}{qnew}{-f}} will incorporate any outstanding changes into the new patch it creates, but -\hgcmdargs{qpop}{\hgopt{qpop}{-f}} will revert modifications to any +\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-f}} will revert modifications to any files affected by the patch that it is popping. Be sure to read the documentation for a command's \option{-f} option before you use it! @@ -624,8 +624,8 @@ 2.6.17. On my old, slow laptop, I was able to -\hgcmdargs{qpush}{\hgopt{qpush}{-a}} all 1,738 patches in 3.5 minutes, -and \hgcmdargs{qpop}{\hgopt{qpop}{-a}} them all in 30 seconds. (On a +\hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}} all 1,738 patches in 3.5 minutes, +and \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} them all in 30 seconds. (On a newer laptop, the time to push all patches dropped to two minutes.) I could \hgxcmd{mq}{qrefresh} one of the biggest patches (which made 22,779 lines of changes to 287 files) in 6.6 seconds. @@ -663,9 +663,9 @@ patches that no longer apply. This is called \emph{rebasing} your patch series. -The simplest way to do this is to \hgcmdargs{qpop}{\hgopt{qpop}{-a}} +The simplest way to do this is to \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} your patches, then \hgcmd{pull} changes into the underlying -repository, and finally \hgcmdargs{qpush}{\hgopt{qpop}{-a}} your +repository, and finally \hgcmdargs{qpush}{\hgxopt{mq}{qpop}{-a}} your patches again. MQ will stop pushing any time it runs across a patch that fails to apply during conflicts, allowing you to fix your conflicts, \hgxcmd{mq}{qrefresh} the affected patch, and continue pushing @@ -687,7 +687,7 @@ \item To begin, \hgcmdargs{qpush}{-a} all of your patches on top of the revision where you know that they apply cleanly. \item Save a backup copy of your patch directory using - \hgcmdargs{qsave}{\hgopt{qsave}{-e} \hgopt{qsave}{-c}}. This prints + \hgcmdargs{qsave}{\hgxopt{mq}{qsave}{-e} \hgxopt{mq}{qsave}{-c}}. This prints the name of the directory that it has saved the patches in. It will save the patches to a directory called \sdirname{.hg/patches.\emph{N}}, where \texttt{\emph{N}} is a small @@ -699,12 +699,12 @@ \item Update to the new tip revision, using \hgcmdargs{update}{\hgopt{update}{-C}} to override the patches you have pushed. -\item Merge all patches using \hgcmdargs{qpush}{\hgopt{qpush}{-m} - \hgopt{qpush}{-a}}. The \hgopt{qpush}{-m} option to \hgxcmd{mq}{qpush} +\item Merge all patches using \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m} + \hgxopt{mq}{qpush}{-a}}. The \hgxopt{mq}{qpush}{-m} option to \hgxcmd{mq}{qpush} tells MQ to perform a three-way merge if the patch fails to apply. \end{enumerate} -During the \hgcmdargs{qpush}{\hgopt{qpush}{-m}}, each patch in the +During the \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m}}, each patch in the \sfilename{series} file is applied normally. If a patch applies with fuzz or rejects, MQ looks at the queue you \hgxcmd{mq}{qsave}d, and performs a three-way merge with the corresponding changeset. This @@ -717,7 +717,7 @@ At the end of this process, your repository will have one extra head from the old patch queue, and a copy of the old patch queue will be in \sdirname{.hg/patches.\emph{N}}. You can remove the extra head using -\hgcmdargs{qpop}{\hgopt{qpop}{-a} \hgopt{qpop}{-n} patches.\emph{N}} +\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a} \hgxopt{mq}{qpop}{-n} patches.\emph{N}} or \hgcmd{strip}. You can delete \sdirname{.hg/patches.\emph{N}} once you are sure that you no longer need it as a backup. @@ -833,16 +833,16 @@ MQ helps you to work with the \sdirname{.hg/patches} directory as a repository; when you prepare a repository for working with patches -using \hgxcmd{mq}{qinit}, you can pass the \hgopt{qinit}{-c} option to +using \hgxcmd{mq}{qinit}, you can pass the \hgxopt{mq}{qinit}{-c} option to create the \sdirname{.hg/patches} directory as a Mercurial repository. \begin{note} - If you forget to use the \hgopt{qinit}{-c} option, you can simply go + If you forget to use the \hgxopt{mq}{qinit}{-c} option, you can simply go into the \sdirname{.hg/patches} directory at any time and run \hgcmd{init}. Don't forget to add an entry for the \sfilename{status} file to the \sfilename{.hgignore} file, though - (\hgcmdargs{qinit}{\hgopt{qinit}{-c}} does this for you + (\hgcmdargs{qinit}{\hgxopt{mq}{qinit}{-c}} does this for you automatically); you \emph{really} don't want to manage the \sfilename{status} file. \end{note} @@ -863,8 +863,8 @@ MQ cannot automatically detect changes that you make to the patch directory. If you \hgcmd{pull}, manually edit, or \hgcmd{update} changes to patches or the \sfilename{series} file, you will have to -\hgcmdargs{qpop}{\hgopt{qpop}{-a}} and then -\hgcmdargs{qpush}{\hgopt{qpush}{-a}} in the underlying repository to +\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} and then +\hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}} in the underlying repository to see those changes show up there. If you forget to do this, you can confuse MQ's idea of which patches are applied.