Bryan O'Sullivan avatar Bryan O'Sullivan committed 535e877

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

Comments (0)

Files changed (3)

 \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}

en/examples/mq.tutorial

 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
 \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
   \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}
 
 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
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.