hgbook
changeset 50:8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Thu Jul 27 10:20:55 2006 -0700 (2006-07-27) |
parents | 18210d46491f |
children | 497aa3c9d4ce |
files | en/99defs.tex en/Makefile en/examples/mq.id en/mq.tex |
line diff
1.1 --- a/en/99defs.tex Tue Jul 25 00:18:31 2006 -0700 1.2 +++ b/en/99defs.tex Thu Jul 27 10:20:55 2006 -0700 1.3 @@ -70,9 +70,6 @@ 1.4 % Python module. 1.5 \newcommand{\pymod}[1]{\index{\texttt{#1} module}\texttt{#1}} 1.6 1.7 -% Bundled extension. 1.8 -\newcommand{\hgext}[1]{\index{\texttt{#1} extension}\texttt{#1}} 1.9 - 1.10 % Python class in a module. 1.11 \newcommand{\pymodclass}[2]{\index{\texttt{#1} module!\texttt{#2} 1.12 class}\texttt{#1.#2}}
2.1 --- a/en/Makefile Tue Jul 25 00:18:31 2006 -0700 2.2 +++ b/en/Makefile Thu Jul 27 10:20:55 2006 -0700 2.3 @@ -23,6 +23,7 @@ 2.4 examples/hook.ws \ 2.5 examples/mq.qinit-help \ 2.6 examples/mq.dodiff \ 2.7 + examples/mq.id \ 2.8 examples/mq.tarball \ 2.9 examples/mq.tools \ 2.10 examples/mq.tutorial
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 3.2 +++ b/en/examples/mq.id Thu Jul 27 10:20:55 2006 -0700 3.3 @@ -0,0 +1,22 @@ 3.4 +#!/bin/sh 3.5 + 3.6 +hg init a 3.7 +cd a 3.8 +hg qinit 3.9 +echo 'int x;' > test.c 3.10 +hg ci -Ama 3.11 + 3.12 +hg qnew first.patch 3.13 +echo 'float c;' >> test.c 3.14 +hg qrefresh 3.15 + 3.16 +hg qnew second.patch 3.17 +echo 'double u;' > other.c 3.18 +hg add other.c 3.19 +hg qrefresh 3.20 + 3.21 +#$ name: out 3.22 + 3.23 +hg qapplied 3.24 +hg log -r qbase:qtip 3.25 +hg export second.patch
4.1 --- a/en/mq.tex Tue Jul 25 00:18:31 2006 -0700 4.2 +++ b/en/mq.tex Thu Jul 27 10:20:55 2006 -0700 4.3 @@ -69,7 +69,6 @@ 4.4 \subsection{A patchwork quilt} 4.5 \label{sec:mq:quilt} 4.6 4.7 - 4.8 In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the 4.9 approach of Andrew's scripts and published a tool called ``patchwork 4.10 quilt''~\cite{web:quilt}, or simply ``quilt'' 4.11 @@ -114,19 +113,45 @@ 4.12 Mercurial. Each patch that you push is represented as a Mercurial 4.13 changeset. Pop a patch, and the changeset goes away. 4.14 4.15 -This integration makes understanding patches and debugging their 4.16 -effects \emph{enormously} easier. Since every applied patch has an 4.17 -associated changeset, you can use \hgcmdargs{log}{\emph{filename}} to 4.18 -see which changesets and patches affected a file. You can use the 4.19 -\hgext{bisect} extension to binary-search through all changesets and 4.20 -applied patches to see where a bug got introduced or fixed. You can 4.21 -use the \hgcmd{annotate} command to see which changeset or patch 4.22 -modified a particular line of a source file. And so on. 4.23 - 4.24 Because quilt does not care about revision control tools, it is still 4.25 a tremendously useful piece of software to know about for situations 4.26 where you cannot use Mercurial and MQ. 4.27 4.28 +\section{The huge advantage of MQ} 4.29 + 4.30 +I cannot overstate the value that MQ offers through the unification of 4.31 +patches and revision control. 4.32 + 4.33 +A major reaon that patches have persisted in the free software and 4.34 +open source world---in spite of the availability of increasingly 4.35 +capable revision control tools over the years---is the \emph{agility} 4.36 +they offer. 4.37 + 4.38 +Traditional revision control tools make a permanent, irreversible 4.39 +record of everything that you do. While this has great value, it's 4.40 +also somewhat stifling. If you want to perform a wild-eyed 4.41 +experiment, you have to be careful in how you go about it, or you risk 4.42 +leaving unneeded---or worse, misleading or destabilising---traces of 4.43 +your missteps and errors in the permanent revision record. 4.44 + 4.45 +By contrast, MQ's marriage of distributed revision control with 4.46 +patches makes it much easier to isolate your work. Your patches live 4.47 +on top of normal revision history, and you can make them disappear or 4.48 +reappear at will. If you don't like a patch, you can drop it. If a 4.49 +patch isn't quite as you want it to be, simply fix it---as many times 4.50 +as you need to, until you have refined it into the form you desire. 4.51 + 4.52 +As an example, the integration of patches with revision control makes 4.53 +understanding patches and debugging their effects---and their 4.54 +interplay with the code they're based on---\emph{enormously} easier. 4.55 +Since every applied patch has an associated changeset, you can use 4.56 +\hgcmdargs{log}{\emph{filename}} to see which changesets and patches 4.57 +affected a file. You can use the \hgext{bisect} extension to 4.58 +binary-search through all changesets and applied patches to see where 4.59 +a bug got introduced or fixed. You can use the \hgcmd{annotate} 4.60 +command to see which changeset or patch modified a particular line of 4.61 +a source file. And so on. 4.62 + 4.63 \section{Understanding patches} 4.64 \label{sec:mq:patch} 4.65 4.66 @@ -596,7 +621,8 @@ 4.67 4.68 On my old, slow laptop, I was able to 4.69 \hgcmdargs{qpush}{\hgopt{qpush}{-a}} all 1,738 patches in 3.5 minutes, 4.70 -and \hgcmdargs{qpop}{\hgopt{qpop}{-a}} them all in 30 seconds. I 4.71 +and \hgcmdargs{qpop}{\hgopt{qpop}{-a}} them all in 30 seconds. (On a 4.72 +newer laptop, the time to push all patches dropped to two minutes.) I 4.73 could \hgcmd{qrefresh} one of the biggest patches (which made 22,779 4.74 lines of changes to 287 files) in 6.6 seconds. 4.75 4.76 @@ -615,8 +641,7 @@ 4.77 patch'' that you want to end up at. When you \hgcmd{qpush} with a 4.78 destination specified, it will push patches until that patch is at the 4.79 top of the applied stack. When you \hgcmd{qpop} to a destination, MQ 4.80 -will pop patches until the destination patch \emph{is no longer} 4.81 -applied. 4.82 +will pop patches until the destination patch is at the top. 4.83 4.84 You can identify a destination patch using either the name of the 4.85 patch, or by number. If you use numeric addressing, patches are 4.86 @@ -692,6 +717,60 @@ 4.87 or \hgcmd{strip}. You can delete \sdirname{.hg/patches.\emph{N}} once 4.88 you are sure that you no longer need it as a backup. 4.89 4.90 +\section{Identifying patches} 4.91 + 4.92 +MQ commands that work with patches let you refer to a patch either by 4.93 +using its name or by a number. By name is obvious enough; pass the 4.94 +name \filename{foo.patch} to \hgcmd{qpush}, for example, and it will 4.95 +push patches until \filename{foo.patch} is applied. 4.96 + 4.97 +Referring to a patch by index isn't much different. The first patch 4.98 +printed in the output of \hgcmd{qseries} is patch zero (yes, it's one 4.99 +of those start-at-zero counting systems); the second is patch one; and 4.100 +so on 4.101 + 4.102 +MQ also makes it easy to work with patches when you are using normal 4.103 +Mercurial commands. Every command that accepts a changeset ID will 4.104 +also accept the name of an applied patch. MQ augments the tags 4.105 +normally in the repository with an eponymous one for each applied 4.106 +patch. In addition, the special tags \index{tags!special tag 4.107 + names!\texttt{qbase}}\texttt{qbase} and \index{tags!special tag 4.108 + names!\texttt{qtip}}\texttt{qtip} identify the ``bottom-most'' and 4.109 +topmost applied patches, respectively. 4.110 + 4.111 +These additions to Mercurial's normal tagging capabilities make 4.112 +dealing with patches even more of a breeze. 4.113 +\begin{itemize} 4.114 +\item Want to patchbomb a mailing list with your latest series of 4.115 + changes? 4.116 + \begin{codesample4} 4.117 + hg email qbase:qtip 4.118 + \end{codesample4} 4.119 +\item Need to see all of the patches since \texttt{foo.patch} that 4.120 + have touched files in a subdirectory of your tree? 4.121 + \begin{codesample4} 4.122 + hg log -r foo.patch:qtip \emph{subdir} 4.123 + \end{codesample4} 4.124 +\end{itemize} 4.125 + 4.126 +Because MQ makes the names of patches available to the rest of 4.127 +Mercurial through its normal internal tag machinery, you don't need to 4.128 +type in the entire name of a patch when you want to identify it by 4.129 +name. 4.130 + 4.131 +\begin{figure}[ht] 4.132 + \interaction{mq.id.out} 4.133 + \caption{Using MQ's tag features to work with patches} 4.134 + \label{ex:mq:id} 4.135 +\end{figure} 4.136 + 4.137 +Another nice consequence of representing patch names as tags is that 4.138 +when you run the \hgcmd{log} command, it will display a patch's name 4.139 +as a tag, simply as part of its normal output. This makes it easy to 4.140 +visually distinguish applied patches from underlying ``normal'' 4.141 +revisions. Figure~\ref{ex:mq:id} shows a few normal Mercurial 4.142 +commands in use with applied patches. 4.143 + 4.144 \section{Useful things to know about} 4.145 4.146 There are a number of aspects of MQ usage that don't fit tidily into 4.147 @@ -710,6 +789,7 @@ 4.148 patch stack. If you try to do this, it will appear to succeed, but 4.149 MQ will become confused. 4.150 \end{itemize} 4.151 + 4.152 \section{Managing patches in a repository} 4.153 4.154 Because MQ's \sdirname{.hg/patches} directory resides outside a 4.155 @@ -935,6 +1015,7 @@ 4.156 counterparts for which are the normal Mercurial \hgcmd{add} and 4.157 \hgcmd{remove} commands. There is no MQ equivalent of the quilt 4.158 \texttt{edit} command. 4.159 + 4.160 \section{MQ command reference} 4.161 \label{sec:mq:cmdref} 4.162 4.163 @@ -1038,11 +1119,11 @@ 4.164 4.165 This command takes an optional argument, which it uses as the name or 4.166 index of the patch to pop to. If given a name, it will pop patches 4.167 -until the named patch is no longer applied. If given a number, 4.168 -\hgcmd{qpop} treats the number as an index into the entries in the 4.169 -series file, counting from zero (empty lines and lines containing only 4.170 -comments do not count). It pops patches until the patch identified by 4.171 -the given index is no longer applied. 4.172 +until the named patch is the topmost applied patch. If given a 4.173 +number, \hgcmd{qpop} treats the number as an index into the entries in 4.174 +the series file, counting from zero (empty lines and lines containing 4.175 +only comments do not count). It pops patches until the patch 4.176 +identified by the given index is the topmost applied patch. 4.177 4.178 The \hgcmd{qpop} command does not read or write patches or the 4.179 \sfilename{series} file. It is thus safe to \hgcmd{qpop} a patch that 4.180 @@ -1066,6 +1147,7 @@ 4.181 4.182 The \hgcmd{qpop} command removes one line from the end of the 4.183 \sfilename{status} file for each patch that it pops. 4.184 + 4.185 \subsection{\hgcmd{qprev}---print the name of the previous patch} 4.186 4.187 The \hgcmd{qprev} command prints the name of the patch in the