hgbook
diff en/mq.tex @ 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 | 81a2f7a639ed |
children | 9cbc5d0db542 |
line diff
1.1 --- a/en/mq.tex Mon Aug 07 05:20:07 2006 -0700 1.2 +++ b/en/mq.tex Fri Oct 20 16:56:20 2006 -0700 1.3 @@ -838,6 +838,7 @@ 1.4 into the \sdirname{.hg/patches} directory at any time and run 1.5 \hgcmd{init}. Don't forget to add an entry for the 1.6 \sfilename{status} file to the \sfilename{.hgignore} file, though 1.7 + 1.8 (\hgcmdargs{qinit}{\hgopt{qinit}{-c}} does this for you 1.9 automatically); you \emph{really} don't want to manage the 1.10 \sfilename{status} file. 1.11 @@ -1019,352 +1020,6 @@ 1.12 \hgcmd{remove} commands. There is no MQ equivalent of the quilt 1.13 \texttt{edit} command. 1.14 1.15 -\section{MQ command reference} 1.16 -\label{sec:mq:cmdref} 1.17 - 1.18 -For an overview of the commands provided by MQ, use the command 1.19 -\hgcmdargs{help}{mq}. 1.20 - 1.21 -\subsection{\hgcmd{qapplied}---print applied patches} 1.22 - 1.23 -The \hgcmd{qapplied} command prints the current stack of applied 1.24 -patches. Patches are printed in oldest-to-newest order, so the last 1.25 -patch in the list is the ``top'' patch. 1.26 - 1.27 -\subsection{\hgcmd{qcommit}---commit changes in the queue repository} 1.28 - 1.29 -The \hgcmd{qcommit} command commits any outstanding changes in the 1.30 -\sdirname{.hg/patches} repository. This command only works if the 1.31 -\sdirname{.hg/patches} directory is a repository, i.e.~you created the 1.32 -directory using \hgcmdargs{qinit}{\hgopt{qinit}{-c}} or ran 1.33 -\hgcmd{init} in the directory after running \hgcmd{qinit}. 1.34 - 1.35 -This command is shorthand for \hgcmdargs{commit}{--cwd .hg/patches}. 1.36 - 1.37 -\subsection{\hgcmd{qdelete}---delete a patch from the 1.38 - \sfilename{series} file} 1.39 - 1.40 -The \hgcmd{qdelete} command removes the entry for a patch from the 1.41 -\sfilename{series} file in the \sdirname{.hg/patches} directory. It 1.42 -does not pop the patch if the patch is already applied. By default, 1.43 -it does not delete the patch file; use the \hgopt{qdel}{-f} option to 1.44 -do that. 1.45 - 1.46 -Options: 1.47 -\begin{itemize} 1.48 -\item[\hgopt{qdel}{-f}] Delete the patch file. 1.49 -\end{itemize} 1.50 - 1.51 -\subsection{\hgcmd{qdiff}---print a diff of the topmost applied patch} 1.52 - 1.53 -The \hgcmd{qdiff} command prints a diff of the topmost applied patch. 1.54 -It is equivalent to \hgcmdargs{diff}{-r-2:-1}. 1.55 - 1.56 -\subsection{\hgcmd{qfold}---merge (``fold'') several patches into one} 1.57 - 1.58 -The \hgcmd{qfold} command merges multiple patches into the topmost 1.59 -applied patch, so that the topmost applied patch makes the union of 1.60 -all of the changes in the patches in question. 1.61 - 1.62 -The patches to fold must not be applied; \hgcmd{qfold} will exit with 1.63 -an error if any is. The order in which patches are folded is 1.64 -significant; \hgcmdargs{qfold}{a b} means ``apply the current topmost 1.65 -patch, followed by \texttt{a}, followed by \texttt{b}''. 1.66 - 1.67 -The comments from the folded patches are appended to the comments of 1.68 -the destination patch, with each block of comments separated by three 1.69 -asterisk (``\texttt{*}'') characters. Use the \hgopt{qfold}{-e} 1.70 -option to edit the commit message for the combined patch/changeset 1.71 -after the folding has completed. 1.72 - 1.73 -Options: 1.74 -\begin{itemize} 1.75 -\item[\hgopt{qfold}{-e}] Edit the commit message and patch description 1.76 - for the newly folded patch. 1.77 -\item[\hgopt{qfold}{-l}] Use the contents of the given file as the new 1.78 - commit message and patch description for the folded patch. 1.79 -\item[\hgopt{qfold}{-m}] Use the given text as the new commit message 1.80 - and patch description for the folded patch. 1.81 -\end{itemize} 1.82 - 1.83 -\subsection{\hgcmd{qheader}---display the header/description of a patch} 1.84 - 1.85 -The \hgcmd{qheader} command prints the header, or description, of a 1.86 -patch. By default, it prints the header of the topmost applied patch. 1.87 -Given an argument, it prints the header of the named patch. 1.88 - 1.89 -\subsection{\hgcmd{qimport}---import a third-party patch into the queue} 1.90 - 1.91 -The \hgcmd{qimport} command adds an entry for an external patch to the 1.92 -\sfilename{series} file, and copies the patch into the 1.93 -\sdirname{.hg/patches} directory. It adds the entry immediately after 1.94 -the topmost applied patch, but does not push the patch. 1.95 - 1.96 -If the \sdirname{.hg/patches} directory is a repository, 1.97 -\hgcmd{qimport} automatically does an \hgcmd{add} of the imported 1.98 -patch. 1.99 - 1.100 -\subsection{\hgcmd{qinit}---prepare a repository to work with MQ} 1.101 - 1.102 -The \hgcmd{qinit} command prepares a repository to work with MQ. It 1.103 -creates a directory called \sdirname{.hg/patches}. 1.104 - 1.105 -Options: 1.106 -\begin{itemize} 1.107 -\item[\hgopt{qinit}{-c}] Create \sdirname{.hg/patches} as a repository 1.108 - in its own right. Also creates a \sfilename{.hgignore} file that 1.109 - will ignore the \sfilename{status} file. 1.110 -\end{itemize} 1.111 - 1.112 -When the \sdirname{.hg/patches} directory is a repository, the 1.113 -\hgcmd{qimport} and \hgcmd{qnew} commands automatically \hgcmd{add} 1.114 -new patches. 1.115 - 1.116 -\subsection{\hgcmd{qnew}---create a new patch} 1.117 - 1.118 -The \hgcmd{qnew} command creates a new patch. It takes one mandatory 1.119 -argument, the name to use for the patch file. The newly created patch 1.120 -is created empty by default. It is added to the \sfilename{series} 1.121 -file after the current topmost applied patch, and is immediately 1.122 -pushed on top of that patch. 1.123 - 1.124 -If \hgcmd{qnew} finds modified files in the working directory, it will 1.125 -refuse to create a new patch unless the \hgopt{qnew}{-f} option is 1.126 -used (see below). This behaviour allows you to \hgcmd{qrefresh} your 1.127 -topmost applied patch before you apply a new patch on top of it. 1.128 - 1.129 -Options: 1.130 -\begin{itemize} 1.131 -\item[\hgopt{qnew}{-f}] Create a new patch if the contents of the 1.132 - working directory are modified. Any outstanding modifications are 1.133 - added to the newly created patch, so after this command completes, 1.134 - the working directory will no longer be modified. 1.135 -\item[\hgopt{qnew}{-m}] Use the given text as the commit message. 1.136 - This text will be stored at the beginning of the patch file, before 1.137 - the patch data. 1.138 -\end{itemize} 1.139 - 1.140 -\subsection{\hgcmd{qnext}---print the name of the next patch} 1.141 - 1.142 -The \hgcmd{qnext} command prints the name name of the next patch in 1.143 -the \sfilename{series} file after the topmost applied patch. This 1.144 -patch will become the topmost applied patch if you run \hgcmd{qpush}. 1.145 - 1.146 -\subsection{\hgcmd{qpop}---pop patches off the stack} 1.147 - 1.148 -The \hgcmd{qpop} command removes applied patches from the top of the 1.149 -stack of applied patches. By default, it removes only one patch. 1.150 - 1.151 -This command removes the changesets that represent the popped patches 1.152 -from the repository, and updates the working directory to undo the 1.153 -effects of the patches. 1.154 - 1.155 -This command takes an optional argument, which it uses as the name or 1.156 -index of the patch to pop to. If given a name, it will pop patches 1.157 -until the named patch is the topmost applied patch. If given a 1.158 -number, \hgcmd{qpop} treats the number as an index into the entries in 1.159 -the series file, counting from zero (empty lines and lines containing 1.160 -only comments do not count). It pops patches until the patch 1.161 -identified by the given index is the topmost applied patch. 1.162 - 1.163 -The \hgcmd{qpop} command does not read or write patches or the 1.164 -\sfilename{series} file. It is thus safe to \hgcmd{qpop} a patch that 1.165 -you have removed from the \sfilename{series} file, or a patch that you 1.166 -have renamed or deleted entirely. In the latter two cases, use the 1.167 -name of the patch as it was when you applied it. 1.168 - 1.169 -By default, the \hgcmd{qpop} command will not pop any patches if the 1.170 -working directory has been modified. You can override this behaviour 1.171 -using the \hgopt{qpop}{-f} option, which reverts all modifications in 1.172 -the working directory. 1.173 - 1.174 -Options: 1.175 -\begin{itemize} 1.176 -\item[\hgopt{qpop}{-a}] Pop all applied patches. This returns the 1.177 - repository to its state before you applied any patches. 1.178 -\item[\hgopt{qpop}{-f}] Forcibly revert any modifications to the 1.179 - working directory when popping. 1.180 -\item[\hgopt{qpop}{-n}] Pop a patch from the named queue. 1.181 -\end{itemize} 1.182 - 1.183 -The \hgcmd{qpop} command removes one line from the end of the 1.184 -\sfilename{status} file for each patch that it pops. 1.185 - 1.186 -\subsection{\hgcmd{qprev}---print the name of the previous patch} 1.187 - 1.188 -The \hgcmd{qprev} command prints the name of the patch in the 1.189 -\sfilename{series} file that comes before the topmost applied patch. 1.190 -This will become the topmost applied patch if you run \hgcmd{qpop}. 1.191 - 1.192 -\subsection{\hgcmd{qpush}---push patches onto the stack} 1.193 -\label{sec:mq:cmd:qpush} 1.194 - 1.195 -The \hgcmd{qpush} command adds patches onto the applied stack. By 1.196 -default, it adds only one patch. 1.197 - 1.198 -This command creates a new changeset to represent each applied patch, 1.199 -and updates the working directory to apply the effects of the patches. 1.200 - 1.201 -The default data used when creating a changeset are as follows: 1.202 -\begin{itemize} 1.203 -\item The commit date and time zone are the current date and time 1.204 - zone. Because these data are used to compute the identity of a 1.205 - changeset, this means that if you \hgcmd{qpop} a patch and 1.206 - \hgcmd{qpush} it again, the changeset that you push will have a 1.207 - different identity than the changeset you popped. 1.208 -\item The author is the same as the default used by the \hgcmd{commit} 1.209 - command. 1.210 -\item The commit message is any text from the patch file that comes 1.211 - before the first diff header. If there is no such text, a default 1.212 - commit message is used that identifies the name of the patch. 1.213 -\end{itemize} 1.214 -If a patch contains a Mercurial patch header (XXX add link), the 1.215 -information in the patch header overrides these defaults. 1.216 - 1.217 -Options: 1.218 -\begin{itemize} 1.219 -\item[\hgopt{qpush}{-a}] Push all unapplied patches from the 1.220 - \sfilename{series} file until there are none left to push. 1.221 -\item[\hgopt{qpush}{-l}] Add the name of the patch to the end 1.222 - of the commit message. 1.223 -\item[\hgopt{qpush}{-m}] If a patch fails to apply cleanly, use the 1.224 - entry for the patch in another saved queue to compute the parameters 1.225 - for a three-way merge, and perform a three-way merge using the 1.226 - normal Mercurial merge machinery. Use the resolution of the merge 1.227 - as the new patch content. 1.228 -\item[\hgopt{qpush}{-n}] Use the named queue if merging while pushing. 1.229 -\end{itemize} 1.230 - 1.231 -The \hgcmd{qpush} command reads, but does not modify, the 1.232 -\sfilename{series} file. It appends one line to the \hgcmd{status} 1.233 -file for each patch that it pushes. 1.234 - 1.235 -\subsection{\hgcmd{qrefresh}---update the topmost applied patch} 1.236 - 1.237 -The \hgcmd{qrefresh} command updates the topmost applied patch. It 1.238 -modifies the patch, removes the old changeset that represented the 1.239 -patch, and creates a new changeset to represent the modified patch. 1.240 - 1.241 -The \hgcmd{qrefresh} command looks for the following modifications: 1.242 -\begin{itemize} 1.243 -\item Changes to the commit message, i.e.~the text before the first 1.244 - diff header in the patch file, are reflected in the new changeset 1.245 - that represents the patch. 1.246 -\item Modifications to tracked files in the working directory are 1.247 - added to the patch. 1.248 -\item Changes to the files tracked using \hgcmd{add}, \hgcmd{copy}, 1.249 - \hgcmd{remove}, or \hgcmd{rename}. Added files and copy and rename 1.250 - destinations are added to the patch, while removed files and rename 1.251 - sources are removed. 1.252 -\end{itemize} 1.253 - 1.254 -Even if \hgcmd{qrefresh} detects no changes, it still recreates the 1.255 -changeset that represents the patch. This causes the identity of the 1.256 -changeset to differ from the previous changeset that identified the 1.257 -patch. 1.258 - 1.259 -Options: 1.260 -\begin{itemize} 1.261 -\item[\hgopt{qrefresh}{-e}] Modify the commit and patch description, 1.262 - using the preferred text editor. 1.263 -\item[\hgopt{qrefresh}{-m}] Modify the commit message and patch 1.264 - description, using the given text. 1.265 -\item[\hgopt{qrefresh}{-l}] Modify the commit message and patch 1.266 - description, using text from the given file. 1.267 -\end{itemize} 1.268 - 1.269 -\subsection{\hgcmd{qrename}---rename a patch} 1.270 - 1.271 -The \hgcmd{qrename} command renames a patch, and changes the entry for 1.272 -the patch in the \sfilename{series} file. 1.273 - 1.274 -With a single argument, \hgcmd{qrename} renames the topmost applied 1.275 -patch. With two arguments, it renames its first argument to its 1.276 -second. 1.277 - 1.278 -\subsection{\hgcmd{qrestore}---restore saved queue state} 1.279 - 1.280 -XXX No idea what this does. 1.281 - 1.282 -\subsection{\hgcmd{qsave}---save current queue state} 1.283 - 1.284 -XXX Likewise. 1.285 - 1.286 -\subsection{\hgcmd{qseries}---print the entire patch series} 1.287 - 1.288 -The \hgcmd{qseries} command prints the entire patch series from the 1.289 -\sfilename{series} file. It prints only patch names, not empty lines 1.290 -or comments. It prints in order from first to be applied to last. 1.291 - 1.292 -\subsection{\hgcmd{qtop}---print the name of the current patch} 1.293 - 1.294 -The \hgcmd{qtop} prints the name of the topmost currently applied 1.295 -patch. 1.296 - 1.297 -\subsection{\hgcmd{qunapplied}---print patches not yet applied} 1.298 - 1.299 -The \hgcmd{qunapplied} command prints the names of patches from the 1.300 -\sfilename{series} file that are not yet applied. It prints them in 1.301 -order from the next patch that will be pushed to the last. 1.302 - 1.303 -\subsection{\hgcmd{qversion}} 1.304 - 1.305 -The \hgcmd{qversion} command prints the version of MQ that is in use. 1.306 - 1.307 -\subsection{\hgcmd{strip}---remove a revision and descendants} 1.308 - 1.309 -The \hgcmd{strip} command removes a revision, and all of its 1.310 -descendants, from the repository. It undoes the effects of the 1.311 -removed revisions from the repository, and updates the working 1.312 -directory to the first parent of the removed revision. 1.313 - 1.314 -The \hgcmd{strip} command saves a backup of the removed changesets in 1.315 -a bundle, so that they can be reapplied if removed in error. 1.316 - 1.317 -Options: 1.318 -\begin{itemize} 1.319 -\item[\hgopt{strip}{-b}] Save unrelated changesets that are intermixed 1.320 - with the stripped changesets in the backup bundle. 1.321 -\item[\hgopt{strip}{-f}] If a branch has multiple heads, remove all 1.322 - heads. XXX This should be renamed, and use \texttt{-f} to strip revs 1.323 - when there are pending changes. 1.324 -\item[\hgopt{strip}{-n}] Do not save a backup bundle. 1.325 -\end{itemize} 1.326 - 1.327 -\section{MQ file reference} 1.328 - 1.329 -\subsection{The \sfilename{series} file} 1.330 - 1.331 -The \sfilename{series} file contains a list of the names of all 1.332 -patches that MQ can apply. It is represented as a list of names, with 1.333 -one name saved per line. Leading and trailing white space in each 1.334 -line are ignored. 1.335 - 1.336 -Lines may contain comments. A comment begins with the ``\texttt{\#}'' 1.337 -character, and extends to the end of the line. Empty lines, and lines 1.338 -that contain only comments, are ignored. 1.339 - 1.340 -You will often need to edit the \sfilename{series} file by hand, hence 1.341 -the support for comments and empty lines noted above. For example, 1.342 -you can comment out a patch temporarily, and \hgcmd{qpush} will skip 1.343 -over that patch when applying patches. You can also change the order 1.344 -in which patches are applied by reordering their entries in the 1.345 -\sfilename{series} file. 1.346 - 1.347 -Placing the \sfilename{series} file under revision control is also 1.348 -supported; it is a good idea to place all of the patches that it 1.349 -refers to under revision control, as well. If you create a patch 1.350 -directory using the \hgopt{qinit}{-c} option to \hgcmd{qinit}, this 1.351 -will be done for you automatically. 1.352 - 1.353 -\subsection{The \sfilename{status} file} 1.354 - 1.355 -The \sfilename{status} file contains the names and changeset hashes of 1.356 -all patches that MQ currently has applied. Unlike the 1.357 -\sfilename{series} file, this file is not intended for editing. You 1.358 -should not place this file under revision control, or modify it in any 1.359 -way. It is used by MQ strictly for internal book-keeping. 1.360 - 1.361 %%% Local Variables: 1.362 %%% mode: latex 1.363 %%% TeX-master: "00book"