hgbook
changeset 104:32bf9a5f22c0
Refactor MQ chapter into three.
Start text on guards.
Start text on guards.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Fri Oct 20 16:56:20 2006 -0700 (2006-10-20) |
parents | 5b80c922ebdd |
children | ecacb6b4c9fd |
files | en/00book.tex en/Makefile en/examples/mq.guards en/mq-collab.tex en/mq-ref.tex en/mq.tex |
line diff
1.1 --- a/en/00book.tex Thu Oct 19 15:18:07 2006 -0700 1.2 +++ b/en/00book.tex Fri Oct 20 16:56:20 2006 -0700 1.3 @@ -44,6 +44,8 @@ 1.4 \include{hook} 1.5 \include{template} 1.6 \include{mq} 1.7 +\include{mq-collab} 1.8 +\include{mq-ref} 1.9 1.10 \appendix 1.11 \include{srcinstall}
2.1 --- a/en/Makefile Thu Oct 19 15:18:07 2006 -0700 2.2 +++ b/en/Makefile Fri Oct 20 16:56:20 2006 -0700 2.3 @@ -12,6 +12,8 @@ 2.4 hook.tex \ 2.5 intro.tex \ 2.6 mq.tex \ 2.7 + mq-collab.tex \ 2.8 + mq-ref.tex \ 2.9 preface.tex \ 2.10 srcinstall.tex \ 2.11 template.tex \ 2.12 @@ -34,6 +36,7 @@ 2.13 hook.msglen \ 2.14 hook.simple \ 2.15 hook.ws \ 2.16 + mq.guards \ 2.17 mq.qinit-help \ 2.18 mq.dodiff \ 2.19 mq.id \
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 3.2 +++ b/en/examples/mq.guards Fri Oct 20 16:56:20 2006 -0700 3.3 @@ -0,0 +1,67 @@ 3.4 +#!/bin/bash 3.5 + 3.6 +echo '[extensions]' >> $HGRC 3.7 +echo 'hgext.mq =' >> $HGRC 3.8 + 3.9 +hg init a 3.10 +cd a 3.11 + 3.12 +#$ name: init 3.13 + 3.14 +hg qinit 3.15 +hg qnew hello.patch 3.16 +echo hello > hello 3.17 +hg add hello 3.18 +hg qrefresh 3.19 +hg qnew goodbye.patch 3.20 +echo goodbye > goodbye 3.21 +hg add goodbye 3.22 +hg qrefresh 3.23 + 3.24 +#$ name: qguard 3.25 + 3.26 +hg qguard 3.27 + 3.28 +#$ name: qguard.pos 3.29 + 3.30 +hg qguard +foo 3.31 +hg qguard 3.32 + 3.33 +#$ name: qguard.neg 3.34 + 3.35 +hg qguard hello.patch -quux 3.36 +hg qguard hello.patch 3.37 + 3.38 +#$ name: series 3.39 + 3.40 +cat .hg/patches/series 3.41 + 3.42 +#$ name: qselect.foo 3.43 + 3.44 +hg qpop -a 3.45 +hg qselect 3.46 +hg qselect foo 3.47 +hg qselect 3.48 + 3.49 +#$ name: qselect.cat 3.50 + 3.51 +cat .hg/patches/guards 3.52 + 3.53 +#$ name: qselect.qpush 3.54 +hg qpush -a 3.55 + 3.56 +#$ name: qselect.error 3.57 + 3.58 +hg qselect +foo 3.59 + 3.60 +#$ name: qselect.quux 3.61 + 3.62 +hg qselect quux 3.63 +hg qpop -a 3.64 +hg qpush -a 3.65 + 3.66 +#$ name: qselect.foobar 3.67 + 3.68 +hg qselect foo bar 3.69 +hg qpop -a 3.70 +hg qpush -a
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 4.2 +++ b/en/mq-collab.tex Fri Oct 20 16:56:20 2006 -0700 4.3 @@ -0,0 +1,164 @@ 4.4 +\chapter{Advanced uses of Mercurial Queues} 4.5 + 4.6 +While it's easy to pick up straightforward uses of Mercurial Queues, 4.7 +use of a little discipline and some of MQ's less frequently used 4.8 +capabilities makes it possible to work in complicated development 4.9 +environments. 4.10 + 4.11 +In this chapter, I will discuss a technique I have developed to manage 4.12 +the development of an Infiniband device driver for the Linux kernel. 4.13 +The driver in question is large (at least as drivers go), with 25,000 4.14 +lines of code spread across 35 source files. It is maintained by a 4.15 +small team of developers. 4.16 + 4.17 +While much of the material in this chapter is specific to Linux, the 4.18 +same principles apply to any code base for which you're not the 4.19 +primary owner, and upon which you need to do a lot of development. 4.20 + 4.21 +\section{The problem of many targets} 4.22 + 4.23 +The Linux kernel changes rapidly, and has never been internally 4.24 +stable; developers frequently make drastic changes between releases. 4.25 +This means that a version of the driver that works well with a 4.26 +particular released version of the kernel will not even \emph{compile} 4.27 +correctly against, typically, any other version. 4.28 + 4.29 +To maintain a driver, we have to keep a number of distinct versions of 4.30 +Linux in mind. 4.31 +\begin{itemize} 4.32 +\item One target is the main Linux kernel development tree. 4.33 + Maintenance of the code is in this case partly shared by other 4.34 + developers in the kernel community, who make ``drive-by'' 4.35 + modifications to the driver as they develop and refine kernel 4.36 + subsystems. 4.37 +\item We also maintain a number of ``backports'' to older versions of 4.38 + the Linux kernel, to support the needs of customers who are running 4.39 + older Linux distributions that do not incorporate our drivers. 4.40 +\item Finally, we make software releases on a schedule that is 4.41 + necessarily not aligned with those used by Linux distributors and 4.42 + kernel developers, so that we can deliver new features to customers 4.43 + without forcing them to upgrade their entire kernels or 4.44 + distributions. 4.45 +\end{itemize} 4.46 + 4.47 +\subsection{Tempting approaches that don't work well} 4.48 + 4.49 +There are two ``standard'' ways to maintain a piece of software that 4.50 +has to target many different environments. 4.51 + 4.52 +The first is to maintain a number of branches, each intended for a 4.53 +single target. The trouble with this approach is that you must 4.54 +maintain iron discipline in the flow of changes between repositories. 4.55 +A new feature or bug fix must start life in a ``pristine'' repository, 4.56 +then percolate out to every backport repository. Backport changes are 4.57 +more limited in the branches they should propagate to; a backport 4.58 +change that is applied to a branch where it doesn't belong will 4.59 +probably stop the driver from compiling. 4.60 + 4.61 +The second is to maintain a single source tree filled with conditional 4.62 +statements that turn chunks of code on or off depending on the 4.63 +intended target. Because these ``ifdefs'' are not allowed in the 4.64 +Linux kernel tree, a manual or automatic process must be followed to 4.65 +strip them out and yield a clean tree. A code base maintained in this 4.66 +fashion rapidly becomes a rat's nest of conditional blocks that are 4.67 +difficult to understand and maintain. 4.68 + 4.69 +Neither of these approaches is well suited to a situation where you 4.70 +don't ``own'' the canonical copy of a source tree. In the case of a 4.71 +Linux driver that is distributed with the standard kernel, Linus's 4.72 +tree contains the copy of the code that will be treated by the world 4.73 +as canonical. The upstream version of ``my'' driver can be modified 4.74 +by people I don't know, without me even finding out about it until 4.75 +after the changes show up in Linus's tree. 4.76 + 4.77 +These approaches have the added weakness of making it difficult to 4.78 +generate well-formed patches to submit upstream. 4.79 + 4.80 +In principle, Mercurial Queues seems like a good candidate to manage a 4.81 +development scenario such as the above. While this is indeed the 4.82 +case, MQ contains a few added features that make the job more 4.83 +pleasant. 4.84 + 4.85 +\section{Conditionally applying patches with guards} 4.86 + 4.87 +Perhaps the best way to maintain sanity with so many targets is to be 4.88 +able to choose specific patches to apply for a given situation. MQ 4.89 +provides a feature called ``guards'' (which originates with quilt's 4.90 +\texttt{guards} command) that does just this. To start off, let's 4.91 +create a simple repository for experimenting in. 4.92 +\interaction{mq.guards.init} 4.93 +This gives us a tiny repository that contains two patches that don't 4.94 +have any dependencies on each other, because they touch different files. 4.95 + 4.96 +The idea behind conditional application is that you can ``tag'' a 4.97 +patch with a \emph{guard}, which is simply a text string of your 4.98 +choosing, then tell MQ to select specific guards to use when applying 4.99 +patches. MQ will then either apply, or skip over, a guarded patch, 4.100 +depending on the guards that you have selected. 4.101 + 4.102 +A patch can have an arbitrary number of guards; 4.103 +each one is \emph{positive} (``apply this patch if this guard is 4.104 +selected'') or \emph{negative} (``skip this patch if this guard is 4.105 +selected''). A patch with no guards is always applied. 4.106 + 4.107 +\section{Controlling the guards on a patch} 4.108 + 4.109 +The \hgcmd{qguard} command lets you determine which guards should 4.110 +apply to a patch, or display the guards that are already in effect. 4.111 +Without any arguments, it displays the guards on the current topmost 4.112 +patch. 4.113 +\interaction{mq.guards.qguard} 4.114 +To set a positive guard on a patch, prefix the name of the guard with 4.115 +a ``\texttt{+}''. 4.116 +\interaction{mq.guards.qguard.pos} 4.117 +To set a negative guard on a patch, prefix the name of the guard with 4.118 +a ``\texttt{-}''. 4.119 +\interaction{mq.guards.qguard.neg} 4.120 + 4.121 +\begin{note} 4.122 + The \hgcmd{qguard} command \emph{sets} the guards on a patch; it 4.123 + doesn't \emph{modify} them. What this means is that if you run 4.124 + \hgcmdargs{qguard}{+a +b} on a patch, then \hgcmdargs{qguard}{+c} on 4.125 + the same patch, the \emph{only} guard that will be set on it 4.126 + afterwards is \texttt{+c}. 4.127 +\end{note} 4.128 + 4.129 +Mercurial stores guards in the \sfilename{series} file; the form in 4.130 +which they are stored is easy both to understand and to edit by hand. 4.131 +(In other words, you don't have to use the \hgcmd{qguard} command if 4.132 +you don't want to; it's okay to simply edit the \sfilename{series} 4.133 +file.) 4.134 +\interaction{mq.guards.series} 4.135 + 4.136 +\section{Selecting the guards to use} 4.137 + 4.138 +The \hgcmd{qselect} command determines which guards are active at a 4.139 +given time. The effect of this is to determine which patches MQ will 4.140 +apply the next time you run \hgcmd{qpush}. It has no other effect; in 4.141 +particular, it doesn't do anything to patches that are already 4.142 +applied. 4.143 + 4.144 +With no arguments, the \hgcmd{qselect} command lists the guards 4.145 +currently in effect, one per line of output. Each argument is treated 4.146 +as the name of a guard to apply. 4.147 +\interaction{mq.guards.qselect.foo} 4.148 +In case you're interested, the currently selected guards are stored in 4.149 +the \sfilename{guards} file. 4.150 +\interaction{mq.guards.qselect.cat} 4.151 +We can see the effect the selected guards have when we run 4.152 +\hgcmd{qpush}. 4.153 +\interaction{mq.guards.qselect.qpush} 4.154 + 4.155 +A guard cannot start with a ``\texttt{+}'' or ``\texttt{-}'' 4.156 +character. 4.157 +\interaction{mq.guards.qselect.error} 4.158 +Changing the selected guards changes the patches that are applied. 4.159 +\interaction{mq.guards.qselect.quux} 4.160 +You can see here that negative guards take precedence over positive 4.161 +guards. 4.162 +\interaction{mq.guards.qselect.foobar} 4.163 + 4.164 +%%% Local Variables: 4.165 +%%% mode: latex 4.166 +%%% TeX-master: "00book" 4.167 +%%% End:
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 5.2 +++ b/en/mq-ref.tex Fri Oct 20 16:56:20 2006 -0700 5.3 @@ -0,0 +1,352 @@ 5.4 +\chapter{Mercurial Queues reference} 5.5 + 5.6 +\section{MQ command reference} 5.7 +\label{sec:mq:cmdref} 5.8 + 5.9 +For an overview of the commands provided by MQ, use the command 5.10 +\hgcmdargs{help}{mq}. 5.11 + 5.12 +\subsection{\hgcmd{qapplied}---print applied patches} 5.13 + 5.14 +The \hgcmd{qapplied} command prints the current stack of applied 5.15 +patches. Patches are printed in oldest-to-newest order, so the last 5.16 +patch in the list is the ``top'' patch. 5.17 + 5.18 +\subsection{\hgcmd{qcommit}---commit changes in the queue repository} 5.19 + 5.20 +The \hgcmd{qcommit} command commits any outstanding changes in the 5.21 +\sdirname{.hg/patches} repository. This command only works if the 5.22 +\sdirname{.hg/patches} directory is a repository, i.e.~you created the 5.23 +directory using \hgcmdargs{qinit}{\hgopt{qinit}{-c}} or ran 5.24 +\hgcmd{init} in the directory after running \hgcmd{qinit}. 5.25 + 5.26 +This command is shorthand for \hgcmdargs{commit}{--cwd .hg/patches}. 5.27 + 5.28 +\subsection{\hgcmd{qdelete}---delete a patch from the 5.29 + \sfilename{series} file} 5.30 + 5.31 +The \hgcmd{qdelete} command removes the entry for a patch from the 5.32 +\sfilename{series} file in the \sdirname{.hg/patches} directory. It 5.33 +does not pop the patch if the patch is already applied. By default, 5.34 +it does not delete the patch file; use the \hgopt{qdel}{-f} option to 5.35 +do that. 5.36 + 5.37 +Options: 5.38 +\begin{itemize} 5.39 +\item[\hgopt{qdel}{-f}] Delete the patch file. 5.40 +\end{itemize} 5.41 + 5.42 +\subsection{\hgcmd{qdiff}---print a diff of the topmost applied patch} 5.43 + 5.44 +The \hgcmd{qdiff} command prints a diff of the topmost applied patch. 5.45 +It is equivalent to \hgcmdargs{diff}{-r-2:-1}. 5.46 + 5.47 +\subsection{\hgcmd{qfold}---merge (``fold'') several patches into one} 5.48 + 5.49 +The \hgcmd{qfold} command merges multiple patches into the topmost 5.50 +applied patch, so that the topmost applied patch makes the union of 5.51 +all of the changes in the patches in question. 5.52 + 5.53 +The patches to fold must not be applied; \hgcmd{qfold} will exit with 5.54 +an error if any is. The order in which patches are folded is 5.55 +significant; \hgcmdargs{qfold}{a b} means ``apply the current topmost 5.56 +patch, followed by \texttt{a}, followed by \texttt{b}''. 5.57 + 5.58 +The comments from the folded patches are appended to the comments of 5.59 +the destination patch, with each block of comments separated by three 5.60 +asterisk (``\texttt{*}'') characters. Use the \hgopt{qfold}{-e} 5.61 +option to edit the commit message for the combined patch/changeset 5.62 +after the folding has completed. 5.63 + 5.64 +Options: 5.65 +\begin{itemize} 5.66 +\item[\hgopt{qfold}{-e}] Edit the commit message and patch description 5.67 + for the newly folded patch. 5.68 +\item[\hgopt{qfold}{-l}] Use the contents of the given file as the new 5.69 + commit message and patch description for the folded patch. 5.70 +\item[\hgopt{qfold}{-m}] Use the given text as the new commit message 5.71 + and patch description for the folded patch. 5.72 +\end{itemize} 5.73 + 5.74 +\subsection{\hgcmd{qheader}---display the header/description of a patch} 5.75 + 5.76 +The \hgcmd{qheader} command prints the header, or description, of a 5.77 +patch. By default, it prints the header of the topmost applied patch. 5.78 +Given an argument, it prints the header of the named patch. 5.79 + 5.80 +\subsection{\hgcmd{qimport}---import a third-party patch into the queue} 5.81 + 5.82 +The \hgcmd{qimport} command adds an entry for an external patch to the 5.83 +\sfilename{series} file, and copies the patch into the 5.84 +\sdirname{.hg/patches} directory. It adds the entry immediately after 5.85 +the topmost applied patch, but does not push the patch. 5.86 + 5.87 +If the \sdirname{.hg/patches} directory is a repository, 5.88 +\hgcmd{qimport} automatically does an \hgcmd{add} of the imported 5.89 +patch. 5.90 + 5.91 +\subsection{\hgcmd{qinit}---prepare a repository to work with MQ} 5.92 + 5.93 +The \hgcmd{qinit} command prepares a repository to work with MQ. It 5.94 +creates a directory called \sdirname{.hg/patches}. 5.95 + 5.96 +Options: 5.97 +\begin{itemize} 5.98 +\item[\hgopt{qinit}{-c}] Create \sdirname{.hg/patches} as a repository 5.99 + in its own right. Also creates a \sfilename{.hgignore} file that 5.100 + will ignore the \sfilename{status} file. 5.101 +\end{itemize} 5.102 + 5.103 +When the \sdirname{.hg/patches} directory is a repository, the 5.104 +\hgcmd{qimport} and \hgcmd{qnew} commands automatically \hgcmd{add} 5.105 +new patches. 5.106 + 5.107 +\subsection{\hgcmd{qnew}---create a new patch} 5.108 + 5.109 +The \hgcmd{qnew} command creates a new patch. It takes one mandatory 5.110 +argument, the name to use for the patch file. The newly created patch 5.111 +is created empty by default. It is added to the \sfilename{series} 5.112 +file after the current topmost applied patch, and is immediately 5.113 +pushed on top of that patch. 5.114 + 5.115 +If \hgcmd{qnew} finds modified files in the working directory, it will 5.116 +refuse to create a new patch unless the \hgopt{qnew}{-f} option is 5.117 +used (see below). This behaviour allows you to \hgcmd{qrefresh} your 5.118 +topmost applied patch before you apply a new patch on top of it. 5.119 + 5.120 +Options: 5.121 +\begin{itemize} 5.122 +\item[\hgopt{qnew}{-f}] Create a new patch if the contents of the 5.123 + working directory are modified. Any outstanding modifications are 5.124 + added to the newly created patch, so after this command completes, 5.125 + the working directory will no longer be modified. 5.126 +\item[\hgopt{qnew}{-m}] Use the given text as the commit message. 5.127 + This text will be stored at the beginning of the patch file, before 5.128 + the patch data. 5.129 +\end{itemize} 5.130 + 5.131 +\subsection{\hgcmd{qnext}---print the name of the next patch} 5.132 + 5.133 +The \hgcmd{qnext} command prints the name name of the next patch in 5.134 +the \sfilename{series} file after the topmost applied patch. This 5.135 +patch will become the topmost applied patch if you run \hgcmd{qpush}. 5.136 + 5.137 +\subsection{\hgcmd{qpop}---pop patches off the stack} 5.138 + 5.139 +The \hgcmd{qpop} command removes applied patches from the top of the 5.140 +stack of applied patches. By default, it removes only one patch. 5.141 + 5.142 +This command removes the changesets that represent the popped patches 5.143 +from the repository, and updates the working directory to undo the 5.144 +effects of the patches. 5.145 + 5.146 +This command takes an optional argument, which it uses as the name or 5.147 +index of the patch to pop to. If given a name, it will pop patches 5.148 +until the named patch is the topmost applied patch. If given a 5.149 +number, \hgcmd{qpop} treats the number as an index into the entries in 5.150 +the series file, counting from zero (empty lines and lines containing 5.151 +only comments do not count). It pops patches until the patch 5.152 +identified by the given index is the topmost applied patch. 5.153 + 5.154 +The \hgcmd{qpop} command does not read or write patches or the 5.155 +\sfilename{series} file. It is thus safe to \hgcmd{qpop} a patch that 5.156 +you have removed from the \sfilename{series} file, or a patch that you 5.157 +have renamed or deleted entirely. In the latter two cases, use the 5.158 +name of the patch as it was when you applied it. 5.159 + 5.160 +By default, the \hgcmd{qpop} command will not pop any patches if the 5.161 +working directory has been modified. You can override this behaviour 5.162 +using the \hgopt{qpop}{-f} option, which reverts all modifications in 5.163 +the working directory. 5.164 + 5.165 +Options: 5.166 +\begin{itemize} 5.167 +\item[\hgopt{qpop}{-a}] Pop all applied patches. This returns the 5.168 + repository to its state before you applied any patches. 5.169 +\item[\hgopt{qpop}{-f}] Forcibly revert any modifications to the 5.170 + working directory when popping. 5.171 +\item[\hgopt{qpop}{-n}] Pop a patch from the named queue. 5.172 +\end{itemize} 5.173 + 5.174 +The \hgcmd{qpop} command removes one line from the end of the 5.175 +\sfilename{status} file for each patch that it pops. 5.176 + 5.177 +\subsection{\hgcmd{qprev}---print the name of the previous patch} 5.178 + 5.179 +The \hgcmd{qprev} command prints the name of the patch in the 5.180 +\sfilename{series} file that comes before the topmost applied patch. 5.181 +This will become the topmost applied patch if you run \hgcmd{qpop}. 5.182 + 5.183 +\subsection{\hgcmd{qpush}---push patches onto the stack} 5.184 +\label{sec:mq:cmd:qpush} 5.185 + 5.186 +The \hgcmd{qpush} command adds patches onto the applied stack. By 5.187 +default, it adds only one patch. 5.188 + 5.189 +This command creates a new changeset to represent each applied patch, 5.190 +and updates the working directory to apply the effects of the patches. 5.191 + 5.192 +The default data used when creating a changeset are as follows: 5.193 +\begin{itemize} 5.194 +\item The commit date and time zone are the current date and time 5.195 + zone. Because these data are used to compute the identity of a 5.196 + changeset, this means that if you \hgcmd{qpop} a patch and 5.197 + \hgcmd{qpush} it again, the changeset that you push will have a 5.198 + different identity than the changeset you popped. 5.199 +\item The author is the same as the default used by the \hgcmd{commit} 5.200 + command. 5.201 +\item The commit message is any text from the patch file that comes 5.202 + before the first diff header. If there is no such text, a default 5.203 + commit message is used that identifies the name of the patch. 5.204 +\end{itemize} 5.205 +If a patch contains a Mercurial patch header (XXX add link), the 5.206 +information in the patch header overrides these defaults. 5.207 + 5.208 +Options: 5.209 +\begin{itemize} 5.210 +\item[\hgopt{qpush}{-a}] Push all unapplied patches from the 5.211 + \sfilename{series} file until there are none left to push. 5.212 +\item[\hgopt{qpush}{-l}] Add the name of the patch to the end 5.213 + of the commit message. 5.214 +\item[\hgopt{qpush}{-m}] If a patch fails to apply cleanly, use the 5.215 + entry for the patch in another saved queue to compute the parameters 5.216 + for a three-way merge, and perform a three-way merge using the 5.217 + normal Mercurial merge machinery. Use the resolution of the merge 5.218 + as the new patch content. 5.219 +\item[\hgopt{qpush}{-n}] Use the named queue if merging while pushing. 5.220 +\end{itemize} 5.221 + 5.222 +The \hgcmd{qpush} command reads, but does not modify, the 5.223 +\sfilename{series} file. It appends one line to the \hgcmd{status} 5.224 +file for each patch that it pushes. 5.225 + 5.226 +\subsection{\hgcmd{qrefresh}---update the topmost applied patch} 5.227 + 5.228 +The \hgcmd{qrefresh} command updates the topmost applied patch. It 5.229 +modifies the patch, removes the old changeset that represented the 5.230 +patch, and creates a new changeset to represent the modified patch. 5.231 + 5.232 +The \hgcmd{qrefresh} command looks for the following modifications: 5.233 +\begin{itemize} 5.234 +\item Changes to the commit message, i.e.~the text before the first 5.235 + diff header in the patch file, are reflected in the new changeset 5.236 + that represents the patch. 5.237 +\item Modifications to tracked files in the working directory are 5.238 + added to the patch. 5.239 +\item Changes to the files tracked using \hgcmd{add}, \hgcmd{copy}, 5.240 + \hgcmd{remove}, or \hgcmd{rename}. Added files and copy and rename 5.241 + destinations are added to the patch, while removed files and rename 5.242 + sources are removed. 5.243 +\end{itemize} 5.244 + 5.245 +Even if \hgcmd{qrefresh} detects no changes, it still recreates the 5.246 +changeset that represents the patch. This causes the identity of the 5.247 +changeset to differ from the previous changeset that identified the 5.248 +patch. 5.249 + 5.250 +Options: 5.251 +\begin{itemize} 5.252 +\item[\hgopt{qrefresh}{-e}] Modify the commit and patch description, 5.253 + using the preferred text editor. 5.254 +\item[\hgopt{qrefresh}{-m}] Modify the commit message and patch 5.255 + description, using the given text. 5.256 +\item[\hgopt{qrefresh}{-l}] Modify the commit message and patch 5.257 + description, using text from the given file. 5.258 +\end{itemize} 5.259 + 5.260 +\subsection{\hgcmd{qrename}---rename a patch} 5.261 + 5.262 +The \hgcmd{qrename} command renames a patch, and changes the entry for 5.263 +the patch in the \sfilename{series} file. 5.264 + 5.265 +With a single argument, \hgcmd{qrename} renames the topmost applied 5.266 +patch. With two arguments, it renames its first argument to its 5.267 +second. 5.268 + 5.269 +\subsection{\hgcmd{qrestore}---restore saved queue state} 5.270 + 5.271 +XXX No idea what this does. 5.272 + 5.273 +\subsection{\hgcmd{qsave}---save current queue state} 5.274 + 5.275 +XXX Likewise. 5.276 + 5.277 +\subsection{\hgcmd{qseries}---print the entire patch series} 5.278 + 5.279 +The \hgcmd{qseries} command prints the entire patch series from the 5.280 +\sfilename{series} file. It prints only patch names, not empty lines 5.281 +or comments. It prints in order from first to be applied to last. 5.282 + 5.283 +\subsection{\hgcmd{qtop}---print the name of the current patch} 5.284 + 5.285 +The \hgcmd{qtop} prints the name of the topmost currently applied 5.286 +patch. 5.287 + 5.288 +\subsection{\hgcmd{qunapplied}---print patches not yet applied} 5.289 + 5.290 +The \hgcmd{qunapplied} command prints the names of patches from the 5.291 +\sfilename{series} file that are not yet applied. It prints them in 5.292 +order from the next patch that will be pushed to the last. 5.293 + 5.294 +\subsection{\hgcmd{qversion}} 5.295 + 5.296 +The \hgcmd{qversion} command prints the version of MQ that is in use. 5.297 + 5.298 +\subsection{\hgcmd{strip}---remove a revision and descendants} 5.299 + 5.300 +The \hgcmd{strip} command removes a revision, and all of its 5.301 +descendants, from the repository. It undoes the effects of the 5.302 +removed revisions from the repository, and updates the working 5.303 +directory to the first parent of the removed revision. 5.304 + 5.305 +The \hgcmd{strip} command saves a backup of the removed changesets in 5.306 +a bundle, so that they can be reapplied if removed in error. 5.307 + 5.308 +Options: 5.309 +\begin{itemize} 5.310 +\item[\hgopt{strip}{-b}] Save unrelated changesets that are intermixed 5.311 + with the stripped changesets in the backup bundle. 5.312 +\item[\hgopt{strip}{-f}] If a branch has multiple heads, remove all 5.313 + heads. XXX This should be renamed, and use \texttt{-f} to strip revs 5.314 + when there are pending changes. 5.315 +\item[\hgopt{strip}{-n}] Do not save a backup bundle. 5.316 +\end{itemize} 5.317 + 5.318 +\section{MQ file reference} 5.319 + 5.320 +\subsection{The \sfilename{series} file} 5.321 + 5.322 +The \sfilename{series} file contains a list of the names of all 5.323 +patches that MQ can apply. It is represented as a list of names, with 5.324 +one name saved per line. Leading and trailing white space in each 5.325 +line are ignored. 5.326 + 5.327 +Lines may contain comments. A comment begins with the ``\texttt{\#}'' 5.328 +character, and extends to the end of the line. Empty lines, and lines 5.329 +that contain only comments, are ignored. 5.330 + 5.331 +You will often need to edit the \sfilename{series} file by hand, hence 5.332 +the support for comments and empty lines noted above. For example, 5.333 +you can comment out a patch temporarily, and \hgcmd{qpush} will skip 5.334 +over that patch when applying patches. You can also change the order 5.335 +in which patches are applied by reordering their entries in the 5.336 +\sfilename{series} file. 5.337 + 5.338 +Placing the \sfilename{series} file under revision control is also 5.339 +supported; it is a good idea to place all of the patches that it 5.340 +refers to under revision control, as well. If you create a patch 5.341 +directory using the \hgopt{qinit}{-c} option to \hgcmd{qinit}, this 5.342 +will be done for you automatically. 5.343 + 5.344 +\subsection{The \sfilename{status} file} 5.345 + 5.346 +The \sfilename{status} file contains the names and changeset hashes of 5.347 +all patches that MQ currently has applied. Unlike the 5.348 +\sfilename{series} file, this file is not intended for editing. You 5.349 +should not place this file under revision control, or modify it in any 5.350 +way. It is used by MQ strictly for internal book-keeping. 5.351 + 5.352 +%%% Local Variables: 5.353 +%%% mode: latex 5.354 +%%% TeX-master: "00book" 5.355 +%%% End:
6.1 --- a/en/mq.tex Thu Oct 19 15:18:07 2006 -0700 6.2 +++ b/en/mq.tex Fri Oct 20 16:56:20 2006 -0700 6.3 @@ -838,6 +838,7 @@ 6.4 into the \sdirname{.hg/patches} directory at any time and run 6.5 \hgcmd{init}. Don't forget to add an entry for the 6.6 \sfilename{status} file to the \sfilename{.hgignore} file, though 6.7 + 6.8 (\hgcmdargs{qinit}{\hgopt{qinit}{-c}} does this for you 6.9 automatically); you \emph{really} don't want to manage the 6.10 \sfilename{status} file. 6.11 @@ -1019,352 +1020,6 @@ 6.12 \hgcmd{remove} commands. There is no MQ equivalent of the quilt 6.13 \texttt{edit} command. 6.14 6.15 -\section{MQ command reference} 6.16 -\label{sec:mq:cmdref} 6.17 - 6.18 -For an overview of the commands provided by MQ, use the command 6.19 -\hgcmdargs{help}{mq}. 6.20 - 6.21 -\subsection{\hgcmd{qapplied}---print applied patches} 6.22 - 6.23 -The \hgcmd{qapplied} command prints the current stack of applied 6.24 -patches. Patches are printed in oldest-to-newest order, so the last 6.25 -patch in the list is the ``top'' patch. 6.26 - 6.27 -\subsection{\hgcmd{qcommit}---commit changes in the queue repository} 6.28 - 6.29 -The \hgcmd{qcommit} command commits any outstanding changes in the 6.30 -\sdirname{.hg/patches} repository. This command only works if the 6.31 -\sdirname{.hg/patches} directory is a repository, i.e.~you created the 6.32 -directory using \hgcmdargs{qinit}{\hgopt{qinit}{-c}} or ran 6.33 -\hgcmd{init} in the directory after running \hgcmd{qinit}. 6.34 - 6.35 -This command is shorthand for \hgcmdargs{commit}{--cwd .hg/patches}. 6.36 - 6.37 -\subsection{\hgcmd{qdelete}---delete a patch from the 6.38 - \sfilename{series} file} 6.39 - 6.40 -The \hgcmd{qdelete} command removes the entry for a patch from the 6.41 -\sfilename{series} file in the \sdirname{.hg/patches} directory. It 6.42 -does not pop the patch if the patch is already applied. By default, 6.43 -it does not delete the patch file; use the \hgopt{qdel}{-f} option to 6.44 -do that. 6.45 - 6.46 -Options: 6.47 -\begin{itemize} 6.48 -\item[\hgopt{qdel}{-f}] Delete the patch file. 6.49 -\end{itemize} 6.50 - 6.51 -\subsection{\hgcmd{qdiff}---print a diff of the topmost applied patch} 6.52 - 6.53 -The \hgcmd{qdiff} command prints a diff of the topmost applied patch. 6.54 -It is equivalent to \hgcmdargs{diff}{-r-2:-1}. 6.55 - 6.56 -\subsection{\hgcmd{qfold}---merge (``fold'') several patches into one} 6.57 - 6.58 -The \hgcmd{qfold} command merges multiple patches into the topmost 6.59 -applied patch, so that the topmost applied patch makes the union of 6.60 -all of the changes in the patches in question. 6.61 - 6.62 -The patches to fold must not be applied; \hgcmd{qfold} will exit with 6.63 -an error if any is. The order in which patches are folded is 6.64 -significant; \hgcmdargs{qfold}{a b} means ``apply the current topmost 6.65 -patch, followed by \texttt{a}, followed by \texttt{b}''. 6.66 - 6.67 -The comments from the folded patches are appended to the comments of 6.68 -the destination patch, with each block of comments separated by three 6.69 -asterisk (``\texttt{*}'') characters. Use the \hgopt{qfold}{-e} 6.70 -option to edit the commit message for the combined patch/changeset 6.71 -after the folding has completed. 6.72 - 6.73 -Options: 6.74 -\begin{itemize} 6.75 -\item[\hgopt{qfold}{-e}] Edit the commit message and patch description 6.76 - for the newly folded patch. 6.77 -\item[\hgopt{qfold}{-l}] Use the contents of the given file as the new 6.78 - commit message and patch description for the folded patch. 6.79 -\item[\hgopt{qfold}{-m}] Use the given text as the new commit message 6.80 - and patch description for the folded patch. 6.81 -\end{itemize} 6.82 - 6.83 -\subsection{\hgcmd{qheader}---display the header/description of a patch} 6.84 - 6.85 -The \hgcmd{qheader} command prints the header, or description, of a 6.86 -patch. By default, it prints the header of the topmost applied patch. 6.87 -Given an argument, it prints the header of the named patch. 6.88 - 6.89 -\subsection{\hgcmd{qimport}---import a third-party patch into the queue} 6.90 - 6.91 -The \hgcmd{qimport} command adds an entry for an external patch to the 6.92 -\sfilename{series} file, and copies the patch into the 6.93 -\sdirname{.hg/patches} directory. It adds the entry immediately after 6.94 -the topmost applied patch, but does not push the patch. 6.95 - 6.96 -If the \sdirname{.hg/patches} directory is a repository, 6.97 -\hgcmd{qimport} automatically does an \hgcmd{add} of the imported 6.98 -patch. 6.99 - 6.100 -\subsection{\hgcmd{qinit}---prepare a repository to work with MQ} 6.101 - 6.102 -The \hgcmd{qinit} command prepares a repository to work with MQ. It 6.103 -creates a directory called \sdirname{.hg/patches}. 6.104 - 6.105 -Options: 6.106 -\begin{itemize} 6.107 -\item[\hgopt{qinit}{-c}] Create \sdirname{.hg/patches} as a repository 6.108 - in its own right. Also creates a \sfilename{.hgignore} file that 6.109 - will ignore the \sfilename{status} file. 6.110 -\end{itemize} 6.111 - 6.112 -When the \sdirname{.hg/patches} directory is a repository, the 6.113 -\hgcmd{qimport} and \hgcmd{qnew} commands automatically \hgcmd{add} 6.114 -new patches. 6.115 - 6.116 -\subsection{\hgcmd{qnew}---create a new patch} 6.117 - 6.118 -The \hgcmd{qnew} command creates a new patch. It takes one mandatory 6.119 -argument, the name to use for the patch file. The newly created patch 6.120 -is created empty by default. It is added to the \sfilename{series} 6.121 -file after the current topmost applied patch, and is immediately 6.122 -pushed on top of that patch. 6.123 - 6.124 -If \hgcmd{qnew} finds modified files in the working directory, it will 6.125 -refuse to create a new patch unless the \hgopt{qnew}{-f} option is 6.126 -used (see below). This behaviour allows you to \hgcmd{qrefresh} your 6.127 -topmost applied patch before you apply a new patch on top of it. 6.128 - 6.129 -Options: 6.130 -\begin{itemize} 6.131 -\item[\hgopt{qnew}{-f}] Create a new patch if the contents of the 6.132 - working directory are modified. Any outstanding modifications are 6.133 - added to the newly created patch, so after this command completes, 6.134 - the working directory will no longer be modified. 6.135 -\item[\hgopt{qnew}{-m}] Use the given text as the commit message. 6.136 - This text will be stored at the beginning of the patch file, before 6.137 - the patch data. 6.138 -\end{itemize} 6.139 - 6.140 -\subsection{\hgcmd{qnext}---print the name of the next patch} 6.141 - 6.142 -The \hgcmd{qnext} command prints the name name of the next patch in 6.143 -the \sfilename{series} file after the topmost applied patch. This 6.144 -patch will become the topmost applied patch if you run \hgcmd{qpush}. 6.145 - 6.146 -\subsection{\hgcmd{qpop}---pop patches off the stack} 6.147 - 6.148 -The \hgcmd{qpop} command removes applied patches from the top of the 6.149 -stack of applied patches. By default, it removes only one patch. 6.150 - 6.151 -This command removes the changesets that represent the popped patches 6.152 -from the repository, and updates the working directory to undo the 6.153 -effects of the patches. 6.154 - 6.155 -This command takes an optional argument, which it uses as the name or 6.156 -index of the patch to pop to. If given a name, it will pop patches 6.157 -until the named patch is the topmost applied patch. If given a 6.158 -number, \hgcmd{qpop} treats the number as an index into the entries in 6.159 -the series file, counting from zero (empty lines and lines containing 6.160 -only comments do not count). It pops patches until the patch 6.161 -identified by the given index is the topmost applied patch. 6.162 - 6.163 -The \hgcmd{qpop} command does not read or write patches or the 6.164 -\sfilename{series} file. It is thus safe to \hgcmd{qpop} a patch that 6.165 -you have removed from the \sfilename{series} file, or a patch that you 6.166 -have renamed or deleted entirely. In the latter two cases, use the 6.167 -name of the patch as it was when you applied it. 6.168 - 6.169 -By default, the \hgcmd{qpop} command will not pop any patches if the 6.170 -working directory has been modified. You can override this behaviour 6.171 -using the \hgopt{qpop}{-f} option, which reverts all modifications in 6.172 -the working directory. 6.173 - 6.174 -Options: 6.175 -\begin{itemize} 6.176 -\item[\hgopt{qpop}{-a}] Pop all applied patches. This returns the 6.177 - repository to its state before you applied any patches. 6.178 -\item[\hgopt{qpop}{-f}] Forcibly revert any modifications to the 6.179 - working directory when popping. 6.180 -\item[\hgopt{qpop}{-n}] Pop a patch from the named queue. 6.181 -\end{itemize} 6.182 - 6.183 -The \hgcmd{qpop} command removes one line from the end of the 6.184 -\sfilename{status} file for each patch that it pops. 6.185 - 6.186 -\subsection{\hgcmd{qprev}---print the name of the previous patch} 6.187 - 6.188 -The \hgcmd{qprev} command prints the name of the patch in the 6.189 -\sfilename{series} file that comes before the topmost applied patch. 6.190 -This will become the topmost applied patch if you run \hgcmd{qpop}. 6.191 - 6.192 -\subsection{\hgcmd{qpush}---push patches onto the stack} 6.193 -\label{sec:mq:cmd:qpush} 6.194 - 6.195 -The \hgcmd{qpush} command adds patches onto the applied stack. By 6.196 -default, it adds only one patch. 6.197 - 6.198 -This command creates a new changeset to represent each applied patch, 6.199 -and updates the working directory to apply the effects of the patches. 6.200 - 6.201 -The default data used when creating a changeset are as follows: 6.202 -\begin{itemize} 6.203 -\item The commit date and time zone are the current date and time 6.204 - zone. Because these data are used to compute the identity of a 6.205 - changeset, this means that if you \hgcmd{qpop} a patch and 6.206 - \hgcmd{qpush} it again, the changeset that you push will have a 6.207 - different identity than the changeset you popped. 6.208 -\item The author is the same as the default used by the \hgcmd{commit} 6.209 - command. 6.210 -\item The commit message is any text from the patch file that comes 6.211 - before the first diff header. If there is no such text, a default 6.212 - commit message is used that identifies the name of the patch. 6.213 -\end{itemize} 6.214 -If a patch contains a Mercurial patch header (XXX add link), the 6.215 -information in the patch header overrides these defaults. 6.216 - 6.217 -Options: 6.218 -\begin{itemize} 6.219 -\item[\hgopt{qpush}{-a}] Push all unapplied patches from the 6.220 - \sfilename{series} file until there are none left to push. 6.221 -\item[\hgopt{qpush}{-l}] Add the name of the patch to the end 6.222 - of the commit message. 6.223 -\item[\hgopt{qpush}{-m}] If a patch fails to apply cleanly, use the 6.224 - entry for the patch in another saved queue to compute the parameters 6.225 - for a three-way merge, and perform a three-way merge using the 6.226 - normal Mercurial merge machinery. Use the resolution of the merge 6.227 - as the new patch content. 6.228 -\item[\hgopt{qpush}{-n}] Use the named queue if merging while pushing. 6.229 -\end{itemize} 6.230 - 6.231 -The \hgcmd{qpush} command reads, but does not modify, the 6.232 -\sfilename{series} file. It appends one line to the \hgcmd{status} 6.233 -file for each patch that it pushes. 6.234 - 6.235 -\subsection{\hgcmd{qrefresh}---update the topmost applied patch} 6.236 - 6.237 -The \hgcmd{qrefresh} command updates the topmost applied patch. It 6.238 -modifies the patch, removes the old changeset that represented the 6.239 -patch, and creates a new changeset to represent the modified patch. 6.240 - 6.241 -The \hgcmd{qrefresh} command looks for the following modifications: 6.242 -\begin{itemize} 6.243 -\item Changes to the commit message, i.e.~the text before the first 6.244 - diff header in the patch file, are reflected in the new changeset 6.245 - that represents the patch. 6.246 -\item Modifications to tracked files in the working directory are 6.247 - added to the patch. 6.248 -\item Changes to the files tracked using \hgcmd{add}, \hgcmd{copy}, 6.249 - \hgcmd{remove}, or \hgcmd{rename}. Added files and copy and rename 6.250 - destinations are added to the patch, while removed files and rename 6.251 - sources are removed. 6.252 -\end{itemize} 6.253 - 6.254 -Even if \hgcmd{qrefresh} detects no changes, it still recreates the 6.255 -changeset that represents the patch. This causes the identity of the 6.256 -changeset to differ from the previous changeset that identified the 6.257 -patch. 6.258 - 6.259 -Options: 6.260 -\begin{itemize} 6.261 -\item[\hgopt{qrefresh}{-e}] Modify the commit and patch description, 6.262 - using the preferred text editor. 6.263 -\item[\hgopt{qrefresh}{-m}] Modify the commit message and patch 6.264 - description, using the given text. 6.265 -\item[\hgopt{qrefresh}{-l}] Modify the commit message and patch 6.266 - description, using text from the given file. 6.267 -\end{itemize} 6.268 - 6.269 -\subsection{\hgcmd{qrename}---rename a patch} 6.270 - 6.271 -The \hgcmd{qrename} command renames a patch, and changes the entry for 6.272 -the patch in the \sfilename{series} file. 6.273 - 6.274 -With a single argument, \hgcmd{qrename} renames the topmost applied 6.275 -patch. With two arguments, it renames its first argument to its 6.276 -second. 6.277 - 6.278 -\subsection{\hgcmd{qrestore}---restore saved queue state} 6.279 - 6.280 -XXX No idea what this does. 6.281 - 6.282 -\subsection{\hgcmd{qsave}---save current queue state} 6.283 - 6.284 -XXX Likewise. 6.285 - 6.286 -\subsection{\hgcmd{qseries}---print the entire patch series} 6.287 - 6.288 -The \hgcmd{qseries} command prints the entire patch series from the 6.289 -\sfilename{series} file. It prints only patch names, not empty lines 6.290 -or comments. It prints in order from first to be applied to last. 6.291 - 6.292 -\subsection{\hgcmd{qtop}---print the name of the current patch} 6.293 - 6.294 -The \hgcmd{qtop} prints the name of the topmost currently applied 6.295 -patch. 6.296 - 6.297 -\subsection{\hgcmd{qunapplied}---print patches not yet applied} 6.298 - 6.299 -The \hgcmd{qunapplied} command prints the names of patches from the 6.300 -\sfilename{series} file that are not yet applied. It prints them in 6.301 -order from the next patch that will be pushed to the last. 6.302 - 6.303 -\subsection{\hgcmd{qversion}} 6.304 - 6.305 -The \hgcmd{qversion} command prints the version of MQ that is in use. 6.306 - 6.307 -\subsection{\hgcmd{strip}---remove a revision and descendants} 6.308 - 6.309 -The \hgcmd{strip} command removes a revision, and all of its 6.310 -descendants, from the repository. It undoes the effects of the 6.311 -removed revisions from the repository, and updates the working 6.312 -directory to the first parent of the removed revision. 6.313 - 6.314 -The \hgcmd{strip} command saves a backup of the removed changesets in 6.315 -a bundle, so that they can be reapplied if removed in error. 6.316 - 6.317 -Options: 6.318 -\begin{itemize} 6.319 -\item[\hgopt{strip}{-b}] Save unrelated changesets that are intermixed 6.320 - with the stripped changesets in the backup bundle. 6.321 -\item[\hgopt{strip}{-f}] If a branch has multiple heads, remove all 6.322 - heads. XXX This should be renamed, and use \texttt{-f} to strip revs 6.323 - when there are pending changes. 6.324 -\item[\hgopt{strip}{-n}] Do not save a backup bundle. 6.325 -\end{itemize} 6.326 - 6.327 -\section{MQ file reference} 6.328 - 6.329 -\subsection{The \sfilename{series} file} 6.330 - 6.331 -The \sfilename{series} file contains a list of the names of all 6.332 -patches that MQ can apply. It is represented as a list of names, with 6.333 -one name saved per line. Leading and trailing white space in each 6.334 -line are ignored. 6.335 - 6.336 -Lines may contain comments. A comment begins with the ``\texttt{\#}'' 6.337 -character, and extends to the end of the line. Empty lines, and lines 6.338 -that contain only comments, are ignored. 6.339 - 6.340 -You will often need to edit the \sfilename{series} file by hand, hence 6.341 -the support for comments and empty lines noted above. For example, 6.342 -you can comment out a patch temporarily, and \hgcmd{qpush} will skip 6.343 -over that patch when applying patches. You can also change the order 6.344 -in which patches are applied by reordering their entries in the 6.345 -\sfilename{series} file. 6.346 - 6.347 -Placing the \sfilename{series} file under revision control is also 6.348 -supported; it is a good idea to place all of the patches that it 6.349 -refers to under revision control, as well. If you create a patch 6.350 -directory using the \hgopt{qinit}{-c} option to \hgcmd{qinit}, this 6.351 -will be done for you automatically. 6.352 - 6.353 -\subsection{The \sfilename{status} file} 6.354 - 6.355 -The \sfilename{status} file contains the names and changeset hashes of 6.356 -all patches that MQ currently has applied. Unlike the 6.357 -\sfilename{series} file, this file is not intended for editing. You 6.358 -should not place this file under revision control, or modify it in any 6.359 -way. It is used by MQ strictly for internal book-keeping. 6.360 - 6.361 %%% Local Variables: 6.362 %%% mode: latex 6.363 %%% TeX-master: "00book"