Mercurial > hgbook

changeset 59:0aae9d676e0f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merge with jeffpc.
author Bryan O'Sullivan <bos@serpentine.com>
date Wed, 02 Aug 2006 19:53:34 -0700
parents 3f0176046fdc (diff) 3649ee841264 (current diff)
children 70d07ff31ee4
files en/99defs.tex en/Makefile
diffstat 6 files changed, 339 insertions(+), 174 deletions(-) [+]
line wrap: on
line diff
--- a/.hgignore	Tue Jul 25 09:07:20 2006 -0400
+++ b/.hgignore	Wed Aug 02 19:53:34 2006 -0700
@@ -20,6 +20,7 @@
 *.out
 *.pdf
 *.png
+*.run
 *.tmp
 *.toc
 *.xref
--- a/en/99defs.tex	Tue Jul 25 09:07:20 2006 -0400
+++ b/en/99defs.tex	Wed Aug 02 19:53:34 2006 -0700
@@ -70,9 +70,6 @@
 % Python module.
 \newcommand{\pymod}[1]{\index{\texttt{#1} module}\texttt{#1}}
 
-% Bundled extension.
-\newcommand{\hgext}[1]{\index{\texttt{#1} extension}\texttt{#1}}
-
 % Python class in a module.
 \newcommand{\pymodclass}[2]{\index{\texttt{#1} module!\texttt{#2}
     class}\texttt{#1.#2}}
--- a/en/Makefile	Tue Jul 25 09:07:20 2006 -0400
+++ b/en/Makefile	Wed Aug 02 19:53:34 2006 -0700
@@ -1,127 +1,128 @@
-# This makefile requires GNU make.
-
-hg_id := $(shell hg parents --template '{node|short}\n' | head -1)
-
-sources := \
-	00book.tex \
-	99book.bib \
-	99defs.tex \
-	build_id.tex \
-	concepts.tex \
-	daily.tex \
-	hook.tex \
-	intro.tex \
-	mq.tex \
-	preface.tex
-
-image-sources := \
-	mq-stack.svg
-
-example-sources := \
-	examples/daily.files \
-	examples/hook.msglen \
-	examples/hook.simple \
-	examples/hook.ws \
-	examples/concepts \
-	examples/mq.qinit-help \
-	examples/mq.dodiff \
-	examples/mq.tarball \
-	examples/mq.tools \
-	examples/mq.tutorial
-
-latex-options = \
-	-interaction batchmode \
-	-output-directory $(dir $(1)) \
-	-jobname $(basename $(notdir $(1)))
-
-all: pdf html
-
-pdf: pdf/hgbook.pdf
-
-define pdf
-	mkdir -p $(dir $@)
-	TEXINPUTS=$(dir $<): pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
-	cp 99book.bib $(dir $@)
-	cd $(dir $@) && bibtex $(basename $(notdir $@))
-	cd $(dir $@) && makeindex $(basename $(notdir $@))
-	TEXINPUTS=$(dir $<): pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
-	TEXINPUTS=$(dir $<): pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
-	if grep 'Reference.*undefined' $(@:.pdf=.log); then exit 1; fi
-endef
-
-pdf/hgbook.pdf: $(sources) $(image-sources:%.svg=%.pdf) examples
-	$(call pdf)
-
-html: html/onepage/hgbook.html html/split/hgbook.html
-
-# This is a horrible hack to work around the fact that the htlatex
-# command in tex4ht is itself a horrible hack.  I really don't want to
-# include verbatim the big wad of TeX that is repeated in that script,
-# so instead I mangle the script itself.
-
-define htlatex
-	mkdir -p $(dir $(1))
-	head -2 $(shell which htlatex) > $(dir $(1))/htlatex.book
-	cp 99book.bib $(dir $@)
-	echo '(cd $(dir $@) && bibtex $(basename $(notdir $@)))' >> $(dir $(1))/htlatex.book
-	echo '(cd $(dir $@) && makeindex $(basename $(notdir $@)))' >> $(dir $(1))/htlatex.book
-	head -3 $(shell which htlatex) >> $(dir $(1))/htlatex.book
-	echo 'echo status $$$$' >>  $(dir $(1))/htlatex.book
-	chmod 755 $(dir $(1))/htlatex.book
-	TEXINPUTS=$(dir $(2)): $(dir $(1))/htlatex.book $(2) "xhtml,html4-uni,$(3)" " -cunihtf -utf8" "" "$(call latex-options,$(1))" || (rm -f $(1); exit 1)
-	cd $(dir $(1)) && tex4ht -f/$(basename $(notdir $(1))) -cvalidate -cunihtf
-	cd $(dir $(1)) && t4ht -f/$(basename $(notdir $(1)))
-	perl -pi -e 's/&#x00([0-7][0-9a-f]);/chr(hex($$1))/egi' $(dir $(1))/*.html
-endef
-
-html/onepage/hgbook.html: $(sources) $(image-sources:%.svg=%.png) examples
-	$(call htlatex,$@,$<)
-	cp $(image-sources:%.svg=%.png) $(dir $@)
-
-html/split/hgbook.html: $(sources) $(image-sources:%.svg=%.png) examples
-	$(call htlatex,$@,$<,2)
-	cp $(image-sources:%.svg=%.png) $(dir $@)
-
-beta: beta/pdf/hgbook.pdf beta/html/onepage/hgbook.html beta/html/split/hgbook.html
-
-beta/%.tex: %.tex
-	./fblinks $(hg_id) $(dir $@) $<
-
-beta/pdf/hgbook.pdf: $(sources:%.tex=beta/%.tex) $(image-sources:%.svg=%.pdf) examples fblinks
-	$(call pdf)
-
-beta/html/onepage/hgbook.html: $(sources:%.tex=beta/%.tex) $(image-sources:%.svg=%.png) examples
-	$(call htlatex,$@,$<)
-	cp $(image-sources:%.svg=%.png) $(dir $@)
-
-beta/html/split/hgbook.html: $(sources:%.tex=beta/%.tex) $(image-sources:%.svg=%.png) examples
-	$(call htlatex,$@,$<,2)
-	cp $(image-sources:%.svg=%.png) $(dir $@)
-
-# Produce 90dpi PNGs for the web.
-
-%.png: %.svg
-	inkscape -D -e $@ $<
-
-# Produce eps & pdf for the pdf
-
-%.pdf: %.eps
-	epstopdf $<
-
-%.eps: %.svg
-	inkscape -E $@ $<
-
-examples: examples/.run
-
-examples/.run: $(example-sources:%=%.run)
-	touch examples/.run
-
-examples/%.run: examples/% examples/run-example
-	cd examples && ./run-example $(notdir $<)
-
-build_id.tex: $(wildcard ../.hg/00changelog.[id])
-	echo -n $(hg_id) > build_id.tex
-
-clean:
-	rm -rf beta html pdf *.eps *.pdf *.png *.aux *.dvi *.log *.out \
-		examples/*.{out,run} examples/.run build_id.tex
+# This makefile requires GNU make.
+
+hg_id := $(shell hg parents --template '{node|short}\n' | head -1)
+
+sources := \
+	00book.tex \
+	99book.bib \
+	99defs.tex \
+	build_id.tex \
+	concepts.tex \
+	daily.tex \
+	hook.tex \
+	intro.tex \
+	mq.tex \
+	preface.tex
+
+image-sources := \
+	mq-stack.svg
+
+example-sources := \
+	examples/daily.files \
+	examples/hook.msglen \
+	examples/hook.simple \
+	examples/hook.ws \
+	examples/concepts \
+	examples/mq.qinit-help \
+	examples/mq.dodiff \
+	examples/mq.id \
+	examples/mq.tarball \
+	examples/mq.tools \
+	examples/mq.tutorial
+
+latex-options = \
+	-interaction batchmode \
+	-output-directory $(dir $(1)) \
+	-jobname $(basename $(notdir $(1)))
+
+all: pdf html
+
+pdf: pdf/hgbook.pdf
+
+define pdf
+	mkdir -p $(dir $@)
+	TEXINPUTS=$(dir $<): pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
+	cp 99book.bib $(dir $@)
+	cd $(dir $@) && bibtex $(basename $(notdir $@))
+	cd $(dir $@) && makeindex $(basename $(notdir $@))
+	TEXINPUTS=$(dir $<): pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
+	TEXINPUTS=$(dir $<): pdflatex $(call latex-options,$@) $< || (rm -f $@; exit 1)
+	if grep 'Reference.*undefined' $(@:.pdf=.log); then exit 1; fi
+endef
+
+pdf/hgbook.pdf: $(sources) $(image-sources:%.svg=%.pdf) examples
+	$(call pdf)
+
+html: html/onepage/hgbook.html html/split/hgbook.html
+
+# This is a horrible hack to work around the fact that the htlatex
+# command in tex4ht is itself a horrible hack.  I really don't want to
+# include verbatim the big wad of TeX that is repeated in that script,
+# so instead I mangle the script itself.
+
+define htlatex
+	mkdir -p $(dir $(1))
+	head -2 $(shell which htlatex) > $(dir $(1))/htlatex.book
+	cp 99book.bib $(dir $@)
+	echo '(cd $(dir $@) && bibtex $(basename $(notdir $@)))' >> $(dir $(1))/htlatex.book
+	echo '(cd $(dir $@) && makeindex $(basename $(notdir $@)))' >> $(dir $(1))/htlatex.book
+	head -3 $(shell which htlatex) >> $(dir $(1))/htlatex.book
+	echo 'echo status $$$$' >>  $(dir $(1))/htlatex.book
+	chmod 755 $(dir $(1))/htlatex.book
+	TEXINPUTS=$(dir $(2)): $(dir $(1))/htlatex.book $(2) "xhtml,html4-uni,$(3)" " -cunihtf -utf8" "" "$(call latex-options,$(1))" || (rm -f $(1); exit 1)
+	cd $(dir $(1)) && tex4ht -f/$(basename $(notdir $(1))) -cvalidate -cunihtf
+	cd $(dir $(1)) && t4ht -f/$(basename $(notdir $(1)))
+	perl -pi -e 's/&#x00([0-7][0-9a-f]);/chr(hex($$1))/egi' $(dir $(1))/*.html
+endef
+
+html/onepage/hgbook.html: $(sources) $(image-sources:%.svg=%.png) examples
+	$(call htlatex,$@,$<)
+	cp $(image-sources:%.svg=%.png) $(dir $@)
+
+html/split/hgbook.html: $(sources) $(image-sources:%.svg=%.png) examples
+	$(call htlatex,$@,$<,2)
+	cp $(image-sources:%.svg=%.png) $(dir $@)
+
+beta: beta/pdf/hgbook.pdf beta/html/onepage/hgbook.html beta/html/split/hgbook.html
+
+beta/%.tex: %.tex
+	./fblinks $(hg_id) $(dir $@) $<
+
+beta/pdf/hgbook.pdf: $(sources:%.tex=beta/%.tex) $(image-sources:%.svg=%.pdf) examples fblinks
+	$(call pdf)
+
+beta/html/onepage/hgbook.html: $(sources:%.tex=beta/%.tex) $(image-sources:%.svg=%.png) examples
+	$(call htlatex,$@,$<)
+	cp $(image-sources:%.svg=%.png) $(dir $@)
+
+beta/html/split/hgbook.html: $(sources:%.tex=beta/%.tex) $(image-sources:%.svg=%.png) examples
+	$(call htlatex,$@,$<,2)
+	cp $(image-sources:%.svg=%.png) $(dir $@)
+
+# Produce 90dpi PNGs for the web.
+
+%.png: %.svg
+	inkscape -D -e $@ $<
+
+# Produce eps & pdf for the pdf
+
+%.pdf: %.eps
+	epstopdf $<
+
+%.eps: %.svg
+	inkscape -E $@ $<
+
+examples: examples/.run
+
+examples/.run: $(example-sources:%=%.run)
+	touch examples/.run
+
+examples/%.run: examples/% examples/run-example
+	cd examples && ./run-example $(notdir $<)
+
+build_id.tex: $(wildcard ../.hg/00changelog.[id])
+	echo -n $(hg_id) > build_id.tex
+
+clean:
+	rm -rf beta html pdf *.eps *.pdf *.png *.aux *.dvi *.log *.out \
+		examples/*.{out,run} examples/.run build_id.tex
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/en/examples/mq.id	Wed Aug 02 19:53:34 2006 -0700
@@ -0,0 +1,22 @@
+#!/bin/sh
+
+hg init a
+cd a
+hg qinit
+echo 'int x;' > test.c
+hg ci -Ama
+
+hg qnew first.patch
+echo 'float c;' >> test.c
+hg qrefresh
+
+hg qnew second.patch
+echo 'double u;' > other.c
+hg add other.c
+hg qrefresh
+
+#$ name: out
+
+hg qapplied
+hg log -r qbase:qtip
+hg export second.patch
--- a/en/hook.tex	Tue Jul 25 09:07:20 2006 -0400
+++ b/en/hook.tex	Wed Aug 02 19:53:34 2006 -0700
@@ -151,7 +151,7 @@
 \section{Using hooks with shared access to a repository}
 
 If you want to use hooks to so some automated work in a repository
-that a number of people have ahred access to, you need to be careful
+that a number of people have shared access to, you need to be careful
 in how you do this.
 
 Mercurial only locks a repository when it is writing to the
@@ -177,7 +177,7 @@
 (which contains pointers to the new manifest data).  Before the first
 write to each file, it stores a record of where the end of the file
 was in its transaction log.  If the transaction must be rolled back,
-Mercurial simply truncates each file back to te size it was before the
+Mercurial simply truncates each file back to the size it was before the
 transaction began.
 
 When Mercurial \emph{reads} metadata, it reads the changelog first,
@@ -341,8 +341,8 @@
 number 1 (for ``true'') or 0 (for ``false'') as an environment
 variable for an external hook.  If a hook parameter is named
 \texttt{foo}, the keyword argument for a Python hook will also be
-named \texttt{foo} Python, while the environment variable for an
-external hook will be named \texttt{HG\_FOO}.
+named \texttt{foo}, while the environment variable for an external
+hook will be named \texttt{HG\_FOO}.
 
 \subsection{Hook return values and activity control}
 
@@ -492,7 +492,7 @@
 whitespace from a file.  This is concise and useful enough that I will
 reproduce it here.
 \begin{codesample2}
-  perl -pi -e 's,\\s+$,,' filename
+  perl -pi -e 's,\\s+\$,,' filename
 \end{codesample2}
 
 \section{Bundled hooks}
@@ -631,7 +631,7 @@
 
 You can use this hook for the same purposes as the \hook{changegroup}
 hook (section~\ref{sec:hook:changegroup}); it's simply more convenient
-sometimes to run a hook once per group of changesets, while othher
+sometimes to run a hook once per group of changesets, while other
 times it's handier once per changeset.
 
 Parameters to this hook:
--- a/en/mq.tex	Tue Jul 25 09:07:20 2006 -0400
+++ b/en/mq.tex	Wed Aug 02 19:53:34 2006 -0700
@@ -69,7 +69,6 @@
 \subsection{A patchwork quilt}
 \label{sec:mq:quilt}
 
-
 In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the
 approach of Andrew's scripts and published a tool called ``patchwork
 quilt''~\cite{web:quilt}, or simply ``quilt''
@@ -114,19 +113,45 @@
 Mercurial.  Each patch that you push is represented as a Mercurial
 changeset.  Pop a patch, and the changeset goes away.
 
-This integration makes understanding patches and debugging their
-effects \emph{enormously} easier.  Since every applied patch has an
-associated changeset, you can use \hgcmdargs{log}{\emph{filename}} to
-see which changesets and patches affected a file.  You can use the
-\hgext{bisect} extension to binary-search through all changesets and
-applied patches to see where a bug got introduced or fixed.  You can
-use the \hgcmd{annotate} command to see which changeset or patch
-modified a particular line of a source file.  And so on.
-
 Because quilt does not care about revision control tools, it is still
 a tremendously useful piece of software to know about for situations
 where you cannot use Mercurial and MQ.
 
+\section{The huge advantage of MQ}
+
+I cannot overstate the value that MQ offers through the unification of
+patches and revision control.
+
+A major reaon that patches have persisted in the free software and
+open source world---in spite of the availability of increasingly
+capable revision control tools over the years---is the \emph{agility}
+they offer.  
+
+Traditional revision control tools make a permanent, irreversible
+record of everything that you do.  While this has great value, it's
+also somewhat stifling.  If you want to perform a wild-eyed
+experiment, you have to be careful in how you go about it, or you risk
+leaving unneeded---or worse, misleading or destabilising---traces of
+your missteps and errors in the permanent revision record.
+
+By contrast, MQ's marriage of distributed revision control with
+patches makes it much easier to isolate your work.  Your patches live
+on top of normal revision history, and you can make them disappear or
+reappear at will.  If you don't like a patch, you can drop it.  If a
+patch isn't quite as you want it to be, simply fix it---as many times
+as you need to, until you have refined it into the form you desire.
+
+As an example, the integration of patches with revision control makes
+understanding patches and debugging their effects---and their
+interplay with the code they're based on---\emph{enormously} easier.
+Since every applied patch has an associated changeset, you can use
+\hgcmdargs{log}{\emph{filename}} to see which changesets and patches
+affected a file.  You can use the \hgext{bisect} extension to
+binary-search through all changesets and applied patches to see where
+a bug got introduced or fixed.  You can use the \hgcmd{annotate}
+command to see which changeset or patch modified a particular line of
+a source file.  And so on.
+
 \section{Understanding patches}
 \label{sec:mq:patch}
 
@@ -581,7 +606,11 @@
 \end{itemize}
 
 If you use \command{wiggle} or \command{rej}, you should be doubly
-careful to check your results when you're done.
+careful to check your results when you're done.  In fact,
+\command{rej} enforces this method of double-checking the tool's
+output, by automatically dropping you into a merge program when it has
+done its job, so that you can verify its work and finish off any
+remaining merges.
 
 \section{Getting the best performance out of MQ}
 \label{sec:mq:perf}
@@ -596,7 +625,8 @@
 
 On my old, slow laptop, I was able to
 \hgcmdargs{qpush}{\hgopt{qpush}{-a}} all 1,738 patches in 3.5 minutes,
-and \hgcmdargs{qpop}{\hgopt{qpop}{-a}} them all in 30 seconds.  I
+and \hgcmdargs{qpop}{\hgopt{qpop}{-a}} them all in 30 seconds.  (On a
+newer laptop, the time to push all patches dropped to two minutes.)  I
 could \hgcmd{qrefresh} one of the biggest patches (which made 22,779
 lines of changes to 287 files) in 6.6 seconds.
 
@@ -615,8 +645,7 @@
 patch'' that you want to end up at.  When you \hgcmd{qpush} with a
 destination specified, it will push patches until that patch is at the
 top of the applied stack.  When you \hgcmd{qpop} to a destination, MQ
-will pop patches until the destination patch \emph{is no longer}
-applied.
+will pop patches until the destination patch is at the top.
 
 You can identify a destination patch using either the name of the
 patch, or by number.  If you use numeric addressing, patches are
@@ -692,6 +721,65 @@
 or \hgcmd{strip}.  You can delete \sdirname{.hg/patches.\emph{N}} once
 you are sure that you no longer need it as a backup.
 
+\section{Identifying patches}
+
+MQ commands that work with patches let you refer to a patch either by
+using its name or by a number.  By name is obvious enough; pass the
+name \filename{foo.patch} to \hgcmd{qpush}, for example, and it will
+push patches until \filename{foo.patch} is applied.  
+
+As a shortcut, you can refer to a patch using both a name and a
+numeric offset; \texttt{foo.patch-2} means ``two patches before
+\texttt{foo.patch}'', while \texttt{bar.patch+4} means ``four patches
+after \texttt{bar.patch}''.
+
+Referring to a patch by index isn't much different.  The first patch
+printed in the output of \hgcmd{qseries} is patch zero (yes, it's one
+of those start-at-zero counting systems); the second is patch one; and
+so on
+
+MQ also makes it easy to work with patches when you are using normal
+Mercurial commands.  Every command that accepts a changeset ID will
+also accept the name of an applied patch.  MQ augments the tags
+normally in the repository with an eponymous one for each applied
+patch.  In addition, the special tags \index{tags!special tag
+  names!\texttt{qbase}}\texttt{qbase} and \index{tags!special tag
+  names!\texttt{qtip}}\texttt{qtip} identify the ``bottom-most'' and
+topmost applied patches, respectively.
+
+These additions to Mercurial's normal tagging capabilities make
+dealing with patches even more of a breeze.
+\begin{itemize}
+\item Want to patchbomb a mailing list with your latest series of
+  changes?
+  \begin{codesample4}
+    hg email qbase:qtip
+  \end{codesample4}
+\item Need to see all of the patches since \texttt{foo.patch} that
+  have touched files in a subdirectory of your tree?
+  \begin{codesample4}
+    hg log -r foo.patch:qtip \emph{subdir}
+  \end{codesample4}
+\end{itemize}
+
+Because MQ makes the names of patches available to the rest of
+Mercurial through its normal internal tag machinery, you don't need to
+type in the entire name of a patch when you want to identify it by
+name.
+
+\begin{figure}[ht]
+  \interaction{mq.id.out}
+  \caption{Using MQ's tag features to work with patches}
+  \label{ex:mq:id}
+\end{figure}
+
+Another nice consequence of representing patch names as tags is that
+when you run the \hgcmd{log} command, it will display a patch's name
+as a tag, simply as part of its normal output.  This makes it easy to
+visually distinguish applied patches from underlying ``normal''
+revisions.  Figure~\ref{ex:mq:id} shows a few normal Mercurial
+commands in use with applied patches.
+
 \section{Useful things to know about}
 
 There are a number of aspects of MQ usage that don't fit tidily into
@@ -710,6 +798,7 @@
   patch stack.  If you try to do this, it will appear to succeed, but
   MQ will become confused.
 \end{itemize}
+
 \section{Managing patches in a repository}
 
 Because MQ's \sdirname{.hg/patches} directory resides outside a
@@ -866,23 +955,17 @@
 \subsection{Combining entire patches}
 \label{sec:mq:combine}
 
-It's easy to combine entire patches.
+MQ provides a command, \hgcmd{qfold} that lets you combine entire
+patches.  This ``folds'' the patches you name, in the order you name
+them, into the topmost applied patch, and concatenates their
+descriptions onto the end of its description.  The patches that you
+fold must be unapplied before you fold them.
 
-\begin{enumerate}
-\item \hgcmd{qpop} your applied patches until neither patch is
-  applied.
-\item Concatenate the patches that you want to combine together:
-  \begin{codesample4}
-    cat patch-to-drop.patch >> patch-to-augment.patch
-  \end{codesample4}
-  The description from the first patch (if you have one) will be used
-  as the commit comment when you \hgcmd{qpush} the combined patch.
-  Edit the patch description if you need to.
-\item Use the \hgcmd{qdel} command to delete the patch you're dropping
-  from the \sfilename{series} file.
-\item \hgcmd{qpush} the combined patch.  Fix up any rejects.
-\item \hgcmd{qrefresh} the combined patch to tidy it up.
-\end{enumerate}
+The order in which you fold patches matters.  If your topmost applied
+patch is \texttt{foo}, and you \hgcmd{qfold} \texttt{bar} and
+\texttt{quux} into it, you will end up with a patch that has the same
+effect as if you applied first \texttt{foo}, then \texttt{bar},
+followed by \texttt{quux}.
 
 \subsection{Merging part of one patch into another}
 
@@ -935,6 +1018,7 @@
 counterparts for which are the normal Mercurial \hgcmd{add} and
 \hgcmd{remove} commands.  There is no MQ equivalent of the quilt
 \texttt{edit} command.
+
 \section{MQ command reference}
 \label{sec:mq:cmdref}
 
@@ -962,14 +1046,53 @@
 
 The \hgcmd{qdelete} command removes the entry for a patch from the
 \sfilename{series} file in the \sdirname{.hg/patches} directory.  It
-does not delete the patch file, nor does it pop the patch if the patch
-is already applied.
+does not pop the patch if the patch is already applied.  By default,
+it does not delete the patch file; use the \hgopt{qdel}{-f} option to
+do that.
+
+Options:
+\begin{itemize}
+\item[\hgopt{qdel}{-f}] Delete the patch file.
+\end{itemize}
 
 \subsection{\hgcmd{qdiff}---print a diff of the topmost applied patch}
 
 The \hgcmd{qdiff} command prints a diff of the topmost applied patch.
 It is equivalent to \hgcmdargs{diff}{-r-2:-1}.
 
+\subsection{\hgcmd{qfold}---merge (``fold'') several patches into one}
+
+The \hgcmd{qfold} command merges multiple patches into the topmost
+applied patch, so that the topmost applied patch makes the union of
+all of the changes in the patches in question.
+
+The patches to fold must not be applied; \hgcmd{qfold} will exit with
+an error if any is.  The order in which patches are folded is
+significant; \hgcmdargs{qfold}{a b} means ``apply the current topmost
+patch, followed by \texttt{a}, followed by \texttt{b}''.
+
+The comments from the folded patches are appended to the comments of
+the destination patch, with each block of comments separated by three
+asterisk (``\texttt{*}'') characters.  Use the \hgopt{qfold}{-e}
+option to edit the commit message for the combined patch/changeset
+after the folding has completed.
+
+Options:
+\begin{itemize}
+\item[\hgopt{qfold}{-e}] Edit the commit message and patch description
+  for the newly folded patch.
+\item[\hgopt{qfold}{-l}] Use the contents of the given file as the new
+  commit message and patch description for the folded patch.
+\item[\hgopt{qfold}{-m}] Use the given text as the new commit message
+  and patch description for the folded patch.
+\end{itemize}
+
+\subsection{\hgcmd{qheader}---display the header/description of a patch}
+
+The \hgcmd{qheader} command prints the header, or description, of a
+patch.  By default, it prints the header of the topmost applied patch.
+Given an argument, it prints the header of the named patch.
+
 \subsection{\hgcmd{qimport}---import a third-party patch into the queue}
 
 The \hgcmd{qimport} command adds an entry for an external patch to the
@@ -1038,11 +1161,11 @@
 
 This command takes an optional argument, which it uses as the name or
 index of the patch to pop to.  If given a name, it will pop patches
-until the named patch is no longer applied.  If given a number,
-\hgcmd{qpop} treats the number as an index into the entries in the
-series file, counting from zero (empty lines and lines containing only
-comments do not count).  It pops patches until the patch identified by
-the given index is no longer applied.
+until the named patch is the topmost applied patch.  If given a
+number, \hgcmd{qpop} treats the number as an index into the entries in
+the series file, counting from zero (empty lines and lines containing
+only comments do not count).  It pops patches until the patch
+identified by the given index is the topmost applied patch.
 
 The \hgcmd{qpop} command does not read or write patches or the
 \sfilename{series} file.  It is thus safe to \hgcmd{qpop} a patch that
@@ -1066,6 +1189,7 @@
 
 The \hgcmd{qpop} command removes one line from the end of the
 \sfilename{status} file for each patch that it pops.
+
 \subsection{\hgcmd{qprev}---print the name of the previous patch}
 
 The \hgcmd{qprev} command prints the name of the patch in the
@@ -1139,6 +1263,25 @@
 changeset to differ from the previous changeset that identified the
 patch.
 
+Options:
+\begin{itemize}
+\item[\hgopt{qrefresh}{-e}] Modify the commit and patch description,
+  using the preferred text editor.
+\item[\hgopt{qrefresh}{-m}] Modify the commit message and patch
+  description, using the given text.
+\item[\hgopt{qrefresh}{-l}] Modify the commit message and patch
+  description, using text from the given file.
+\end{itemize}
+
+\subsection{\hgcmd{qrename}---rename a patch}
+
+The \hgcmd{qrename} command renames a patch, and changes the entry for
+the patch in the \sfilename{series} file.
+
+With a single argument, \hgcmd{qrename} renames the topmost applied
+patch.  With two arguments, it renames its first argument to its
+second.
+
 \subsection{\hgcmd{qrestore}---restore saved queue state}
 
 XXX No idea what this does.
@@ -1187,9 +1330,9 @@
   when there are pending changes.
 \item[\hgopt{strip}{-n}] Do not save a backup bundle.
 \end{itemize}
+
 \section{MQ file reference}
 
-
 \subsection{The \sfilename{series} file}
 
 The \sfilename{series} file contains a list of the names of all
@@ -1213,6 +1356,7 @@
 refers to under revision control, as well.  If you create a patch
 directory using the \hgopt{qinit}{-c} option to \hgcmd{qinit}, this
 will be done for you automatically.
+
 \subsection{The \sfilename{status} file}
 
 The \sfilename{status} file contains the names and changeset hashes of