hgbook
diff en/mq.tex @ 26:1bc6c1f0192a
More MQ content.
Skeletal preface.
Skeletal preface.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Tue Jul 11 23:48:25 2006 -0700 (2006-07-11) |
parents | 9d5b6d303ef5 |
children | 535e87792eb1 |
line diff
1.1 --- a/en/mq.tex Sun Jul 09 23:18:39 2006 -0700 1.2 +++ b/en/mq.tex Tue Jul 11 23:48:25 2006 -0700 1.3 @@ -128,6 +128,7 @@ 1.4 where you cannot use Mercurial and MQ. 1.5 1.6 \section{Understanding patches} 1.7 +\label{sec:mq:patch} 1.8 1.9 Because MQ doesn't hide its patch-oriented nature, it is helpful to 1.10 understand what patches are, and a little about the tools that work 1.11 @@ -179,7 +180,7 @@ 1.12 deletion and one insertion. 1.13 1.14 We will return to ome of the more subtle aspects of patches later (in 1.15 -section~\ref{ex:mq:adv-patch}), but you should have enough information 1.16 +section~\ref{sec:mq:adv-patch}), but you should have enough information 1.17 now to use MQ. 1.18 1.19 \section{Getting started with Mercurial Queues} 1.20 @@ -380,8 +381,58 @@ 1.21 \label{sec:mq:adv-patch} 1.22 1.23 MQ uses the GNU \command{patch} command to apply patches, so it's 1.24 -helpful to know about a few more detailed aspects of how 1.25 -\command{patch} works. 1.26 +helpful to know a few more detailed aspects of how \command{patch} 1.27 +works, and about patches themselves. 1.28 + 1.29 +\subsection{The strip count} 1.30 + 1.31 +If you look at the file headers in a patch, you will notice that the 1.32 +pathnames usually have an extra component on the front that isn't 1.33 +present in the actual path name. This is a holdover from the way that 1.34 +people used to generate patches (people still do this, but it's 1.35 +somewhat rare with modern revision control tools). 1.36 + 1.37 +Alice would unpack a tarball, edit her files, then decide that she 1.38 +wanted to create a patch. So she'd rename her working directory, 1.39 +unpack the tarball again (hence the need for the rename), and use the 1.40 +\cmdopt{diff}{-r} and \cmdopt{diff}{-N} options to \command{diff} to 1.41 +recursively generate a patch between the unmodified directory and the 1.42 +modified one. The result would be that the name of the unmodified 1.43 +directory would be at the front of the left-hand path in every file 1.44 +header, and the name of the modified directory would be at the front 1.45 +of the right-hand path. 1.46 + 1.47 +Since someone receiving a patch from the Alices of the net would be 1.48 +unlikely to have unmodified and modified directories with exactly the 1.49 +same names, the \command{patch} command has a \cmdopt{patch}{-p} 1.50 +option that indicates the number of leading path name components to 1.51 +strip when trying to apply a patch. This number is called the 1.52 +\emph{strip count}. 1.53 + 1.54 +An option of ``\texttt{-p1}'' means ``use a strip count of one''. If 1.55 +\command{patch} sees a file name \filename{foo/bar/baz} in a file 1.56 +header, it will strip \filename{foo} and try to patch a file named 1.57 +\filename{bar/baz}. (Strictly speaking, the strip count refers to the 1.58 +number of \emph{path separators} (and the components that go with them 1.59 +) to strip. A strip count of one will turn \filename{foo/bar} into 1.60 +\filename{bar}, but \filename{/foo/bar} (notice the extra leading 1.61 +slash) into \filename{foo/bar}.) 1.62 + 1.63 +The ``standard'' strip count for patches is one; almost all patches 1.64 +contain one leading path name component that needs to be stripped. 1.65 +Mercurial's \hgcmd{diff} command generates path names in this form, 1.66 +and the \hgcmd{import} command and MQ expect patches to have a strip 1.67 +count of one. 1.68 + 1.69 +If you receive a patch from someone that you want to add to your patch 1.70 +queue, and the patch needs a strip count other than one, you cannot 1.71 +just \hgcmd{qimport} the patch, because \hgcmd{qimport} does not yet 1.72 +have a \texttt{-p} option (see~\bug{311}). Your best bet is to 1.73 +\hgcmd{qnew} a patch of your own, then use \cmdargs{patch}{-p\emph{N}} 1.74 +to apply their patch, followed by \hgcmd{addremove} to pick up any 1.75 +files added or removed by the patch, followed by \hgcmd{qrefresh}. 1.76 +This complexity may become unnecessary; see~\bug{311} for details. 1.77 +\subsection{Strategies for applying a patch} 1.78 1.79 When \command{patch} applies a hunk, it tries a handful of 1.80 successively less accurate strategies to try to make the hunk apply. 1.81 @@ -604,6 +655,24 @@ 1.82 or \hgcmd{strip}. You can delete \sdirname{.hg/patches.\emph{N}} once 1.83 you are sure that you no longer need it as a backup. 1.84 1.85 +\section{Useful things to know about} 1.86 + 1.87 +There are a number of aspects of MQ usage that don't fit tidily into 1.88 +sections of their own, but that are good to know. Here they are, in 1.89 +one place. 1.90 + 1.91 +\begin{itemize} 1.92 +\item Normally, when you \hgcmd{qpop} a patch and \hgcmd{qpush} it 1.93 + again, the changeset that represents the patch after the pop/push 1.94 + will have a \emph{different identity} than the changeset that 1.95 + represented the hash beforehand. See section~\ref{sec:mq:cmd:qpush} 1.96 + for information as to why this is. 1.97 +\item It's not a good idea to \hgcmd{merge} changes from another 1.98 + branch with a patch changeset, at least if you want to maintain the 1.99 + ``patchiness'' of that changeset and changesets below it on the 1.100 + patch stack. If you try to do this, it will appear to succeed, but 1.101 + MQ will become confused. 1.102 +\end{itemize} 1.103 \section{Managing patches in a repository} 1.104 1.105 Because MQ's \sdirname{.hg/patches} directory resides outside a 1.106 @@ -617,14 +686,14 @@ 1.107 the patch. This lets you ``roll back'' to that version of the patch 1.108 later on. 1.109 1.110 -In addition, you can then share different versions of the same patch 1.111 -stack among multiple underlying repositories. I use this when I am 1.112 -developing a Linux kernel feature. I have a pristine copy of my 1.113 -kernel sources for each of several CPU architectures, and a cloned 1.114 -repository under each that contains the patches I am working on. When 1.115 -I want to test a change on a different architecture, I push my current 1.116 -patches to the patch repository associated with that kernel tree, pop 1.117 -and push all of my patches, and build and test that kernel. 1.118 +You can then share different versions of the same patch stack among 1.119 +multiple underlying repositories. I use this when I am developing a 1.120 +Linux kernel feature. I have a pristine copy of my kernel sources for 1.121 +each of several CPU architectures, and a cloned repository under each 1.122 +that contains the patches I am working on. When I want to test a 1.123 +change on a different architecture, I push my current patches to the 1.124 +patch repository associated with that kernel tree, pop and push all of 1.125 +my patches, and build and test that kernel. 1.126 1.127 Managing patches in a repository makes it possible for multiple 1.128 developers to work on the same patch series without colliding with 1.129 @@ -669,7 +738,7 @@ 1.130 see those changes show up there. If you forget to do this, you can 1.131 confuse MQ's idea of which patches are applied. 1.132 1.133 -\section{Commands for working with patches} 1.134 +\section{Third party tools for working with patches} 1.135 \label{sec:mq:tools} 1.136 1.137 Once you've been working with patches for a while, you'll find 1.138 @@ -801,9 +870,11 @@ 1.139 1.140 This command prints three different kinds of number: 1.141 \begin{itemize} 1.142 -\item a \emph{file number} to identify each file modified in the patch; 1.143 -\item the line number within a modified file that a hunk starts at; and 1.144 -\item a \emph{hunk number} to identify that hunk. 1.145 +\item (in the first column) a \emph{file number} to identify each file 1.146 + modified in the patch; 1.147 +\item (on the next line, indented) the line number within a modified 1.148 + file where a hunk starts; and 1.149 +\item (on the same line) a \emph{hunk number} to identify that hunk. 1.150 \end{itemize} 1.151 1.152 You'll have to use some visual inspection, and reading of the patch, 1.153 @@ -815,6 +886,18 @@ 1.154 Once you have this hunk, you can concatenate it onto the end of your 1.155 destination patch and continue with the remainder of 1.156 section~\ref{sec:mq:combine}. 1.157 + 1.158 +\section{Differences between quilt and MQ} 1.159 + 1.160 +If you are already familiar with quilt, MQ provides a similar command 1.161 +set. There are a few differences in the way that it works. 1.162 + 1.163 +You will already have noticed that most quilt commands have MQ 1.164 +counterparts that simply begin with a ``\texttt{q}''. The exceptions 1.165 +are quilt's \texttt{add} and \texttt{remove} commands, the 1.166 +counterparts for which are the normal Mercurial \hgcmd{add} and 1.167 +\hgcmd{remove} commands. There is no MQ equivalent of the quilt 1.168 +\texttt{edit} command. 1.169 \section{MQ command reference} 1.170 \label{sec:mq:cmdref} 1.171 1.172 @@ -953,6 +1036,7 @@ 1.173 This will become the topmost applied patch if you run \hgcmd{qpop}. 1.174 1.175 \subsection{\hgcmd{qpush}---push patches onto the stack} 1.176 +\label{sec:mq:cmd:qpush} 1.177 1.178 The \hgcmd{qpush} command adds patches onto the applied stack. By 1.179 default, it adds only one patch. 1.180 @@ -960,7 +1044,7 @@ 1.181 This command creates a new changeset to represent each applied patch, 1.182 and updates the working directory to apply the effects of the patches. 1.183 1.184 -The data used when creating a changeset are as follows: 1.185 +The default data used when creating a changeset are as follows: 1.186 \begin{itemize} 1.187 \item The commit date and time zone are the current date and time 1.188 zone. Because these data are used to compute the identity of a 1.189 @@ -973,6 +1057,8 @@ 1.190 before the first diff header. If there is no such text, a default 1.191 commit message is used that identifies the name of the patch. 1.192 \end{itemize} 1.193 +If a patch contains a Mercurial patch header (XXX add link), the 1.194 +information in the patch header overrides these defaults. 1.195 1.196 Options: 1.197 \begin{itemize} 1.198 @@ -1016,15 +1102,87 @@ 1.199 changeset to differ from the previous changeset that identified the 1.200 patch. 1.201 1.202 +\subsection{\hgcmd{qrestore}---restore saved queue state} 1.203 + 1.204 +XXX No idea what this does. 1.205 + 1.206 +\subsection{\hgcmd{qsave}---save current queue state} 1.207 + 1.208 +XXX Likewise. 1.209 + 1.210 +\subsection{\hgcmd{qseries}---print the entire patch series} 1.211 + 1.212 +The \hgcmd{qseries} command prints the entire patch series from the 1.213 +\sfilename{series} file. It prints only patch names, not empty lines 1.214 +or comments. It prints in order from first to be applied to last. 1.215 + 1.216 +\subsection{\hgcmd{qtop}---print the name of the current patch} 1.217 + 1.218 +The \hgcmd{qtop} prints the name of the topmost currently applied 1.219 +patch. 1.220 + 1.221 +\subsection{\hgcmd{qunapplied}---print patches not yet applied} 1.222 + 1.223 +The \hgcmd{qunapplied} command prints the names of patches from the 1.224 +\sfilename{series} file that are not yet applied. It prints them in 1.225 +order from the next patch that will be pushed to the last. 1.226 + 1.227 +\subsection{\hgcmd{qversion}} 1.228 + 1.229 +The \hgcmd{qversion} command prints the version of MQ that is in use. 1.230 + 1.231 +\subsection{\hgcmd{strip}---remove a revision and descendants} 1.232 + 1.233 +The \hgcmd{strip} command removes a revision, and all of its 1.234 +descendants, from the repository. It undoes the effects of the 1.235 +removed revisions from the repository, and updates the working 1.236 +directory to the first parent of the removed revision. 1.237 + 1.238 +The \hgcmd{strip} command saves a backup of the removed changesets in 1.239 +a bundle, so that they can be reapplied if removed in error. 1.240 + 1.241 +Options: 1.242 +\begin{itemize} 1.243 +\item[\hgopt{strip}{-b}] Save unrelated changesets that are intermixed 1.244 + with the stripped changesets in the backup bundle. 1.245 +\item[\hgopt{strip}{-f}] If a branch has multiple heads, remove all 1.246 + heads. XXX This should be renamed, and use \texttt{-f} to strip revs 1.247 + when there are pending changes. 1.248 +\item[\hgopt{strip}{-n}] Do not save a backup bundle. 1.249 +\end{itemize} 1.250 \section{MQ file reference} 1.251 1.252 1.253 \subsection{The \sfilename{series} file} 1.254 1.255 - 1.256 +The \sfilename{series} file contains a list of the names of all 1.257 +patches that MQ can apply. It is represented as a list of names, with 1.258 +one name saved per line. Leading and trailing white space in each 1.259 +line are ignored. 1.260 + 1.261 +Lines may contain comments. A comment begins with the ``\texttt{\#}'' 1.262 +character, and extends to the end of the line. Empty lines, and lines 1.263 +that contain only comments, are ignored. 1.264 + 1.265 +You will often need to edit the \sfilename{series} file by hand, hence 1.266 +the support for comments and empty lines noted above. For example, 1.267 +you can comment out a patch temporarily, and \hgcmd{qpush} will skip 1.268 +over that patch when applying patches. You can also change the order 1.269 +in which patches are applied by reordering their entries in the 1.270 +\sfilename{series} file. 1.271 + 1.272 +Placing the \sfilename{series} file under revision control is also 1.273 +supported; it is a good idea to place all of the patches that it 1.274 +refers to under revision control, as well. If you create a patch 1.275 +directory using the \hgopt{qinit}{-c} option to \hgcmd{qinit}, this 1.276 +will be done for you automatically. 1.277 \subsection{The \sfilename{status} file} 1.278 1.279 - 1.280 +The \sfilename{status} file contains the names and changeset hashes of 1.281 +all patches that MQ currently has applied. Unlike the 1.282 +\sfilename{series} file, this file is not intended for editing. You 1.283 +should not place this file under revision control, or modify it in any 1.284 +way. It is used by MQ strictly for internal book-keeping. 1.285 1.286 %%% Local Variables: 1.287 %%% mode: latex