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