1.1 --- a/en/mq.tex	Tue Aug 01 12:38:13 2006 -0700
     1.2 +++ b/en/mq.tex	Fri Aug 04 13:43:26 2006 -0700
     1.3 @@ -606,7 +606,11 @@
     1.4  \end{itemize}
     1.5  
     1.6  If you use \command{wiggle} or \command{rej}, you should be doubly
     1.7 -careful to check your results when you're done.
     1.8 +careful to check your results when you're done.  In fact,
     1.9 +\command{rej} enforces this method of double-checking the tool's
    1.10 +output, by automatically dropping you into a merge program when it has
    1.11 +done its job, so that you can verify its work and finish off any
    1.12 +remaining merges.
    1.13  
    1.14  \section{Getting the best performance out of MQ}
    1.15  \label{sec:mq:perf}
    1.16 @@ -722,7 +726,12 @@
    1.17  MQ commands that work with patches let you refer to a patch either by
    1.18  using its name or by a number.  By name is obvious enough; pass the
    1.19  name \filename{foo.patch} to \hgcmd{qpush}, for example, and it will
    1.20 -push patches until \filename{foo.patch} is applied.
    1.21 +push patches until \filename{foo.patch} is applied.  
    1.22 +
    1.23 +As a shortcut, you can refer to a patch using both a name and a
    1.24 +numeric offset; \texttt{foo.patch-2} means ``two patches before
    1.25 +\texttt{foo.patch}'', while \texttt{bar.patch+4} means ``four patches
    1.26 +after \texttt{bar.patch}''.
    1.27  
    1.28  Referring to a patch by index isn't much different.  The first patch
    1.29  printed in the output of \hgcmd{qseries} is patch zero (yes, it's one
    1.30 @@ -946,23 +955,17 @@
    1.31  \subsection{Combining entire patches}
    1.32  \label{sec:mq:combine}
    1.33  
    1.34 -It's easy to combine entire patches.
    1.35 -
    1.36 -\begin{enumerate}
    1.37 -\item \hgcmd{qpop} your applied patches until neither patch is
    1.38 -  applied.
    1.39 -\item Concatenate the patches that you want to combine together:
    1.40 -  \begin{codesample4}
    1.41 -    cat patch-to-drop.patch >> patch-to-augment.patch
    1.42 -  \end{codesample4}
    1.43 -  The description from the first patch (if you have one) will be used
    1.44 -  as the commit comment when you \hgcmd{qpush} the combined patch.
    1.45 -  Edit the patch description if you need to.
    1.46 -\item Use the \hgcmd{qdel} command to delete the patch you're dropping
    1.47 -  from the \sfilename{series} file.
    1.48 -\item \hgcmd{qpush} the combined patch.  Fix up any rejects.
    1.49 -\item \hgcmd{qrefresh} the combined patch to tidy it up.
    1.50 -\end{enumerate}
    1.51 +MQ provides a command, \hgcmd{qfold} that lets you combine entire
    1.52 +patches.  This ``folds'' the patches you name, in the order you name
    1.53 +them, into the topmost applied patch, and concatenates their
    1.54 +descriptions onto the end of its description.  The patches that you
    1.55 +fold must be unapplied before you fold them.
    1.56 +
    1.57 +The order in which you fold patches matters.  If your topmost applied
    1.58 +patch is \texttt{foo}, and you \hgcmd{qfold} \texttt{bar} and
    1.59 +\texttt{quux} into it, you will end up with a patch that has the same
    1.60 +effect as if you applied first \texttt{foo}, then \texttt{bar},
    1.61 +followed by \texttt{quux}.
    1.62  
    1.63  \subsection{Merging part of one patch into another}
    1.64  
    1.65 @@ -1057,6 +1060,33 @@
    1.66  The \hgcmd{qdiff} command prints a diff of the topmost applied patch.
    1.67  It is equivalent to \hgcmdargs{diff}{-r-2:-1}.
    1.68  
    1.69 +\subsection{\hgcmd{qfold}---merge (``fold'') several patches into one}
    1.70 +
    1.71 +The \hgcmd{qfold} command merges multiple patches into the topmost
    1.72 +applied patch, so that the topmost applied patch makes the union of
    1.73 +all of the changes in the patches in question.
    1.74 +
    1.75 +The patches to fold must not be applied; \hgcmd{qfold} will exit with
    1.76 +an error if any is.  The order in which patches are folded is
    1.77 +significant; \hgcmdargs{qfold}{a b} means ``apply the current topmost
    1.78 +patch, followed by \texttt{a}, followed by \texttt{b}''.
    1.79 +
    1.80 +The comments from the folded patches are appended to the comments of
    1.81 +the destination patch, with each block of comments separated by three
    1.82 +asterisk (``\texttt{*}'') characters.  Use the \hgopt{qfold}{-e}
    1.83 +option to edit the commit message for the combined patch/changeset
    1.84 +after the folding has completed.
    1.85 +
    1.86 +Options:
    1.87 +\begin{itemize}
    1.88 +\item[\hgopt{qfold}{-e}] Edit the commit message and patch description
    1.89 +  for the newly folded patch.
    1.90 +\item[\hgopt{qfold}{-l}] Use the contents of the given file as the new
    1.91 +  commit message and patch description for the folded patch.
    1.92 +\item[\hgopt{qfold}{-m}] Use the given text as the new commit message
    1.93 +  and patch description for the folded patch.
    1.94 +\end{itemize}
    1.95 +
    1.96  \subsection{\hgcmd{qheader}---display the header/description of a patch}
    1.97  
    1.98  The \hgcmd{qheader} command prints the header, or description, of a