hgbook
diff en/mq.tex @ 27:535e87792eb1
More MQ content and examples.
Note -f option to some commands.
Note -a option to qpush and qpop.
Note -f option to some commands.
Note -a option to qpush and qpop.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Wed Jul 12 00:14:52 2006 -0700 (2006-07-12) |
parents | 1bc6c1f0192a |
children | f5ce861d6fcc |
line diff
1.1 --- a/en/mq.tex Tue Jul 11 23:48:25 2006 -0700 1.2 +++ b/en/mq.tex Wed Jul 12 00:14:52 2006 -0700 1.3 @@ -299,9 +299,9 @@ 1.4 \end{figure} 1.5 1.6 So far, with the exception of \hgcmd{qnew} and \hgcmd{qrefresh}, we've 1.7 -been careful to only use regular Mercurial commands. However, there 1.8 -are more ``natural'' commands you can use when thinking about patches 1.9 -with MQ, as illustrated in figure~\ref{ex:mq:qseries}: 1.10 +been careful to only use regular Mercurial commands. However, MQ 1.11 +provides many commands that are easier to use when you are thinking 1.12 +about patches, as illustrated in figure~\ref{ex:mq:qseries}: 1.13 1.14 \begin{itemize} 1.15 \item The \hgcmd{qseries} command lists every patch that MQ knows 1.16 @@ -355,9 +355,45 @@ 1.17 \label{ex:mq:qpop} 1.18 \end{figure} 1.19 1.20 -MQ does not limit you to pushing or popping one patch. You can have 1.21 -no patches, all of them, or any number in between applied at some 1.22 -point in time. 1.23 +\subsection{Pushing and popping many patches} 1.24 + 1.25 +While \hgcmd{qpush} and \hgcmd{qpop} each operate on a single patch at 1.26 +a time by default, you can push and pop many patches in one go. The 1.27 +\hgopt{qpush}{-a} option to \hgcmd{qpush} causes it to push all 1.28 +unapplied patches, while the \hgopt{qpop}{-a} option to \hgcmd{qpop} 1.29 +causes it to pop all applied patches. (For some more ways to push and 1.30 +pop many patches, see section~\ref{sec:mq:perf} below.) 1.31 + 1.32 +\begin{figure}[ht] 1.33 + \interaction{mq.tutorial.qpush-a} 1.34 + \caption{Pushing all unapplied patches} 1.35 + \label{ex:mq:qpush-a} 1.36 +\end{figure} 1.37 + 1.38 +\subsection{Safety checks, and overriding them} 1.39 + 1.40 +Several MQ commands check the working directory before they do 1.41 +anything, and fail if they find any modifications. They do this to 1.42 +ensure that you won't lose any changes that you have made, but not yet 1.43 +incorporated into a patch. Figure~\ref{ex:mq:add} illustrates this; 1.44 +the \hgcmd{qnew} command will not create a new patch if there are 1.45 +outstanding changes, caused in this case by the \hgcmd{add} of 1.46 +\filename{file3}. 1.47 + 1.48 +\begin{figure}[ht] 1.49 + \interaction{mq.tutorial.add} 1.50 + \caption{Forcibly creating a patch} 1.51 + \label{ex:mq:add} 1.52 +\end{figure} 1.53 + 1.54 +Commands that check the working directory all take an ``I know what 1.55 +I'm doing'' option, which is always named \option{-f}. The exact 1.56 +meaning of \option{-f} depends on the command. For example, 1.57 +\hgcmdargs{qnew}{\hgopt{qnew}{-f}} will incorporate any outstanding 1.58 +changes into the new patch it creates, but 1.59 +\hgcmdargs{qpop}{\hgopt{qpop}{-f}} will revert modifications to any 1.60 +files affected by the patch that it is popping. Be sure to read the 1.61 +documentation for a command's \option{-f} option before you use it! 1.62 1.63 \subsection{Working on several patches at once} 1.64 1.65 @@ -548,6 +584,7 @@ 1.66 careful to check your results when you're done. 1.67 1.68 \section{Getting the best performance out of MQ} 1.69 +\label{sec:mq:perf} 1.70 1.71 MQ is very efficient at handling a large number of patches. I ran 1.72 some performance experiments in mid-2006 for a talk that I gave at the