changeset 27:535e87792eb1

More MQ content and examples. Note -f option to some commands. Note -a option to qpush and qpop.

--- a/en/99defs.tex	Tue Jul 11 23:48:25 2006 -0700
+++ b/en/99defs.tex	Wed Jul 12 00:14:52 2006 -0700
@@ -11,6 +11,7 @@
 \newcommand{\hgcmdargs}[2]{\index{\texttt{#1} command}``\texttt{hg #1 #2}''}
 \newcommand{\hgopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}}
 \newcommand{\cmdopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}}
+\newcommand{\option}[1]{\texttt{#1}}
 \newcommand{\package}[1]{\index{\texttt{#1} package}\texttt{#1}}
 
 \newsavebox{\notebox}

--- a/en/examples/mq.tutorial	Tue Jul 11 23:48:25 2006 -0700
+++ b/en/examples/mq.tutorial	Wed Jul 12 00:14:52 2006 -0700
@@ -55,5 +55,14 @@
 hg qseries
 hg qapplied
 cat file1
-hg qpush
+
+#$ name: qpush-a
+
+hg qpush -a
 cat file1
+
+#$ name: add
+
+echo 'file 3, line 1' >> file3
+hg qnew add-file3.patch
+hg qnew -f add-file3.patch

--- a/en/mq.tex	Tue Jul 11 23:48:25 2006 -0700
+++ b/en/mq.tex	Wed Jul 12 00:14:52 2006 -0700
@@ -299,9 +299,9 @@
 \end{figure}
 
 So far, with the exception of \hgcmd{qnew} and \hgcmd{qrefresh}, we've
-been careful to only use regular Mercurial commands.  However, there
-are more ``natural'' commands you can use when thinking about patches
-with MQ, as illustrated in figure~\ref{ex:mq:qseries}:
+been careful to only use regular Mercurial commands.  However, MQ
+provides many commands that are easier to use when you are thinking
+about patches, as illustrated in figure~\ref{ex:mq:qseries}:
 
 \begin{itemize}
 \item The \hgcmd{qseries} command lists every patch that MQ knows
@@ -355,9 +355,45 @@
   \label{ex:mq:qpop}
 \end{figure}
 
-MQ does not limit you to pushing or popping one patch.  You can have
-no patches, all of them, or any number in between applied at some
-point in time.
+\subsection{Pushing and popping many patches}
+
+While \hgcmd{qpush} and \hgcmd{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 \hgcmd{qpush} causes it to push all
+unapplied patches, while the \hgopt{qpop}{-a} option to \hgcmd{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.)
+
+\begin{figure}[ht]
+  \interaction{mq.tutorial.qpush-a}
+  \caption{Pushing all unapplied patches}
+  \label{ex:mq:qpush-a}
+\end{figure}
+
+\subsection{Safety checks, and overriding them}
+
+Several MQ commands check the working directory before they do
+anything, and fail if they find any modifications.  They do this to
+ensure that you won't lose any changes that you have made, but not yet
+incorporated into a patch.  Figure~\ref{ex:mq:add} illustrates this;
+the \hgcmd{qnew} command will not create a new patch if there are
+outstanding changes, caused in this case by the \hgcmd{add} of
+\filename{file3}.
+
+\begin{figure}[ht]
+  \interaction{mq.tutorial.add}
+  \caption{Forcibly creating a patch}
+  \label{ex:mq:add}
+\end{figure}
+
+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
+changes into the new patch it creates, but
+\hgcmdargs{qpop}{\hgopt{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!
 
 \subsection{Working on several patches at once}
 
@@ -548,6 +584,7 @@
 careful to check your results when you're done.
 
 \section{Getting the best performance out of MQ}
+\label{sec:mq:perf}
 
 MQ is very efficient at handling a large number of patches.  I ran
 some performance experiments in mid-2006 for a talk that I gave at the