hgbook
changeset 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 6e988159394b |
files | en/99defs.tex en/examples/mq.tutorial en/mq.tex |
line diff
1.1 --- a/en/99defs.tex Tue Jul 11 23:48:25 2006 -0700 1.2 +++ b/en/99defs.tex Wed Jul 12 00:14:52 2006 -0700 1.3 @@ -11,6 +11,7 @@ 1.4 \newcommand{\hgcmdargs}[2]{\index{\texttt{#1} command}``\texttt{hg #1 #2}''} 1.5 \newcommand{\hgopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}} 1.6 \newcommand{\cmdopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}} 1.7 +\newcommand{\option}[1]{\texttt{#1}} 1.8 \newcommand{\package}[1]{\index{\texttt{#1} package}\texttt{#1}} 1.9 1.10 \newsavebox{\notebox}
2.1 --- a/en/examples/mq.tutorial Tue Jul 11 23:48:25 2006 -0700 2.2 +++ b/en/examples/mq.tutorial Wed Jul 12 00:14:52 2006 -0700 2.3 @@ -55,5 +55,14 @@ 2.4 hg qseries 2.5 hg qapplied 2.6 cat file1 2.7 -hg qpush 2.8 + 2.9 +#$ name: qpush-a 2.10 + 2.11 +hg qpush -a 2.12 cat file1 2.13 + 2.14 +#$ name: add 2.15 + 2.16 +echo 'file 3, line 1' >> file3 2.17 +hg qnew add-file3.patch 2.18 +hg qnew -f add-file3.patch
3.1 --- a/en/mq.tex Tue Jul 11 23:48:25 2006 -0700 3.2 +++ b/en/mq.tex Wed Jul 12 00:14:52 2006 -0700 3.3 @@ -299,9 +299,9 @@ 3.4 \end{figure} 3.5 3.6 So far, with the exception of \hgcmd{qnew} and \hgcmd{qrefresh}, we've 3.7 -been careful to only use regular Mercurial commands. However, there 3.8 -are more ``natural'' commands you can use when thinking about patches 3.9 -with MQ, as illustrated in figure~\ref{ex:mq:qseries}: 3.10 +been careful to only use regular Mercurial commands. However, MQ 3.11 +provides many commands that are easier to use when you are thinking 3.12 +about patches, as illustrated in figure~\ref{ex:mq:qseries}: 3.13 3.14 \begin{itemize} 3.15 \item The \hgcmd{qseries} command lists every patch that MQ knows 3.16 @@ -355,9 +355,45 @@ 3.17 \label{ex:mq:qpop} 3.18 \end{figure} 3.19 3.20 -MQ does not limit you to pushing or popping one patch. You can have 3.21 -no patches, all of them, or any number in between applied at some 3.22 -point in time. 3.23 +\subsection{Pushing and popping many patches} 3.24 + 3.25 +While \hgcmd{qpush} and \hgcmd{qpop} each operate on a single patch at 3.26 +a time by default, you can push and pop many patches in one go. The 3.27 +\hgopt{qpush}{-a} option to \hgcmd{qpush} causes it to push all 3.28 +unapplied patches, while the \hgopt{qpop}{-a} option to \hgcmd{qpop} 3.29 +causes it to pop all applied patches. (For some more ways to push and 3.30 +pop many patches, see section~\ref{sec:mq:perf} below.) 3.31 + 3.32 +\begin{figure}[ht] 3.33 + \interaction{mq.tutorial.qpush-a} 3.34 + \caption{Pushing all unapplied patches} 3.35 + \label{ex:mq:qpush-a} 3.36 +\end{figure} 3.37 + 3.38 +\subsection{Safety checks, and overriding them} 3.39 + 3.40 +Several MQ commands check the working directory before they do 3.41 +anything, and fail if they find any modifications. They do this to 3.42 +ensure that you won't lose any changes that you have made, but not yet 3.43 +incorporated into a patch. Figure~\ref{ex:mq:add} illustrates this; 3.44 +the \hgcmd{qnew} command will not create a new patch if there are 3.45 +outstanding changes, caused in this case by the \hgcmd{add} of 3.46 +\filename{file3}. 3.47 + 3.48 +\begin{figure}[ht] 3.49 + \interaction{mq.tutorial.add} 3.50 + \caption{Forcibly creating a patch} 3.51 + \label{ex:mq:add} 3.52 +\end{figure} 3.53 + 3.54 +Commands that check the working directory all take an ``I know what 3.55 +I'm doing'' option, which is always named \option{-f}. The exact 3.56 +meaning of \option{-f} depends on the command. For example, 3.57 +\hgcmdargs{qnew}{\hgopt{qnew}{-f}} will incorporate any outstanding 3.58 +changes into the new patch it creates, but 3.59 +\hgcmdargs{qpop}{\hgopt{qpop}{-f}} will revert modifications to any 3.60 +files affected by the patch that it is popping. Be sure to read the 3.61 +documentation for a command's \option{-f} option before you use it! 3.62 3.63 \subsection{Working on several patches at once} 3.64 3.65 @@ -548,6 +584,7 @@ 3.66 careful to check your results when you're done. 3.67 3.68 \section{Getting the best performance out of MQ} 3.69 +\label{sec:mq:perf} 3.70 3.71 MQ is very efficient at handling a large number of patches. I ran 3.72 some performance experiments in mid-2006 for a talk that I gave at the