hgbook
annotate en/mq-ref.tex @ 171:8c1703a98266
Add a dependency on htlatex to HTML targets, even though we don't call it.
If the files it ships with aren't present, we can't build HTML.
If the files it ships with aren't present, we can't build HTML.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Mon Mar 26 23:57:58 2007 -0700 (2007-03-26) |
parents | |
children | 34943a3d50d6 |
rev | line source |
---|---|
bos@104 | 1 \chapter{Mercurial Queues reference} |
bos@104 | 2 |
bos@104 | 3 \section{MQ command reference} |
bos@104 | 4 \label{sec:mq:cmdref} |
bos@104 | 5 |
bos@104 | 6 For an overview of the commands provided by MQ, use the command |
bos@104 | 7 \hgcmdargs{help}{mq}. |
bos@104 | 8 |
bos@104 | 9 \subsection{\hgcmd{qapplied}---print applied patches} |
bos@104 | 10 |
bos@104 | 11 The \hgcmd{qapplied} command prints the current stack of applied |
bos@104 | 12 patches. Patches are printed in oldest-to-newest order, so the last |
bos@104 | 13 patch in the list is the ``top'' patch. |
bos@104 | 14 |
bos@104 | 15 \subsection{\hgcmd{qcommit}---commit changes in the queue repository} |
bos@104 | 16 |
bos@104 | 17 The \hgcmd{qcommit} command commits any outstanding changes in the |
bos@104 | 18 \sdirname{.hg/patches} repository. This command only works if the |
bos@104 | 19 \sdirname{.hg/patches} directory is a repository, i.e.~you created the |
bos@104 | 20 directory using \hgcmdargs{qinit}{\hgopt{qinit}{-c}} or ran |
bos@104 | 21 \hgcmd{init} in the directory after running \hgcmd{qinit}. |
bos@104 | 22 |
bos@104 | 23 This command is shorthand for \hgcmdargs{commit}{--cwd .hg/patches}. |
bos@104 | 24 |
bos@104 | 25 \subsection{\hgcmd{qdelete}---delete a patch from the |
bos@104 | 26 \sfilename{series} file} |
bos@104 | 27 |
bos@104 | 28 The \hgcmd{qdelete} command removes the entry for a patch from the |
bos@104 | 29 \sfilename{series} file in the \sdirname{.hg/patches} directory. It |
bos@104 | 30 does not pop the patch if the patch is already applied. By default, |
bos@104 | 31 it does not delete the patch file; use the \hgopt{qdel}{-f} option to |
bos@104 | 32 do that. |
bos@104 | 33 |
bos@104 | 34 Options: |
bos@104 | 35 \begin{itemize} |
bos@104 | 36 \item[\hgopt{qdel}{-f}] Delete the patch file. |
bos@104 | 37 \end{itemize} |
bos@104 | 38 |
bos@104 | 39 \subsection{\hgcmd{qdiff}---print a diff of the topmost applied patch} |
bos@104 | 40 |
bos@104 | 41 The \hgcmd{qdiff} command prints a diff of the topmost applied patch. |
bos@104 | 42 It is equivalent to \hgcmdargs{diff}{-r-2:-1}. |
bos@104 | 43 |
bos@104 | 44 \subsection{\hgcmd{qfold}---merge (``fold'') several patches into one} |
bos@104 | 45 |
bos@104 | 46 The \hgcmd{qfold} command merges multiple patches into the topmost |
bos@104 | 47 applied patch, so that the topmost applied patch makes the union of |
bos@104 | 48 all of the changes in the patches in question. |
bos@104 | 49 |
bos@104 | 50 The patches to fold must not be applied; \hgcmd{qfold} will exit with |
bos@104 | 51 an error if any is. The order in which patches are folded is |
bos@104 | 52 significant; \hgcmdargs{qfold}{a b} means ``apply the current topmost |
bos@104 | 53 patch, followed by \texttt{a}, followed by \texttt{b}''. |
bos@104 | 54 |
bos@104 | 55 The comments from the folded patches are appended to the comments of |
bos@104 | 56 the destination patch, with each block of comments separated by three |
bos@104 | 57 asterisk (``\texttt{*}'') characters. Use the \hgopt{qfold}{-e} |
bos@104 | 58 option to edit the commit message for the combined patch/changeset |
bos@104 | 59 after the folding has completed. |
bos@104 | 60 |
bos@104 | 61 Options: |
bos@104 | 62 \begin{itemize} |
bos@104 | 63 \item[\hgopt{qfold}{-e}] Edit the commit message and patch description |
bos@104 | 64 for the newly folded patch. |
bos@104 | 65 \item[\hgopt{qfold}{-l}] Use the contents of the given file as the new |
bos@104 | 66 commit message and patch description for the folded patch. |
bos@104 | 67 \item[\hgopt{qfold}{-m}] Use the given text as the new commit message |
bos@104 | 68 and patch description for the folded patch. |
bos@104 | 69 \end{itemize} |
bos@104 | 70 |
bos@104 | 71 \subsection{\hgcmd{qheader}---display the header/description of a patch} |
bos@104 | 72 |
bos@104 | 73 The \hgcmd{qheader} command prints the header, or description, of a |
bos@104 | 74 patch. By default, it prints the header of the topmost applied patch. |
bos@104 | 75 Given an argument, it prints the header of the named patch. |
bos@104 | 76 |
bos@104 | 77 \subsection{\hgcmd{qimport}---import a third-party patch into the queue} |
bos@104 | 78 |
bos@104 | 79 The \hgcmd{qimport} command adds an entry for an external patch to the |
bos@104 | 80 \sfilename{series} file, and copies the patch into the |
bos@104 | 81 \sdirname{.hg/patches} directory. It adds the entry immediately after |
bos@104 | 82 the topmost applied patch, but does not push the patch. |
bos@104 | 83 |
bos@104 | 84 If the \sdirname{.hg/patches} directory is a repository, |
bos@104 | 85 \hgcmd{qimport} automatically does an \hgcmd{add} of the imported |
bos@104 | 86 patch. |
bos@104 | 87 |
bos@104 | 88 \subsection{\hgcmd{qinit}---prepare a repository to work with MQ} |
bos@104 | 89 |
bos@104 | 90 The \hgcmd{qinit} command prepares a repository to work with MQ. It |
bos@104 | 91 creates a directory called \sdirname{.hg/patches}. |
bos@104 | 92 |
bos@104 | 93 Options: |
bos@104 | 94 \begin{itemize} |
bos@104 | 95 \item[\hgopt{qinit}{-c}] Create \sdirname{.hg/patches} as a repository |
bos@104 | 96 in its own right. Also creates a \sfilename{.hgignore} file that |
bos@104 | 97 will ignore the \sfilename{status} file. |
bos@104 | 98 \end{itemize} |
bos@104 | 99 |
bos@104 | 100 When the \sdirname{.hg/patches} directory is a repository, the |
bos@104 | 101 \hgcmd{qimport} and \hgcmd{qnew} commands automatically \hgcmd{add} |
bos@104 | 102 new patches. |
bos@104 | 103 |
bos@104 | 104 \subsection{\hgcmd{qnew}---create a new patch} |
bos@104 | 105 |
bos@104 | 106 The \hgcmd{qnew} command creates a new patch. It takes one mandatory |
bos@104 | 107 argument, the name to use for the patch file. The newly created patch |
bos@104 | 108 is created empty by default. It is added to the \sfilename{series} |
bos@104 | 109 file after the current topmost applied patch, and is immediately |
bos@104 | 110 pushed on top of that patch. |
bos@104 | 111 |
bos@104 | 112 If \hgcmd{qnew} finds modified files in the working directory, it will |
bos@104 | 113 refuse to create a new patch unless the \hgopt{qnew}{-f} option is |
bos@104 | 114 used (see below). This behaviour allows you to \hgcmd{qrefresh} your |
bos@104 | 115 topmost applied patch before you apply a new patch on top of it. |
bos@104 | 116 |
bos@104 | 117 Options: |
bos@104 | 118 \begin{itemize} |
bos@104 | 119 \item[\hgopt{qnew}{-f}] Create a new patch if the contents of the |
bos@104 | 120 working directory are modified. Any outstanding modifications are |
bos@104 | 121 added to the newly created patch, so after this command completes, |
bos@104 | 122 the working directory will no longer be modified. |
bos@104 | 123 \item[\hgopt{qnew}{-m}] Use the given text as the commit message. |
bos@104 | 124 This text will be stored at the beginning of the patch file, before |
bos@104 | 125 the patch data. |
bos@104 | 126 \end{itemize} |
bos@104 | 127 |
bos@104 | 128 \subsection{\hgcmd{qnext}---print the name of the next patch} |
bos@104 | 129 |
bos@104 | 130 The \hgcmd{qnext} command prints the name name of the next patch in |
bos@104 | 131 the \sfilename{series} file after the topmost applied patch. This |
bos@104 | 132 patch will become the topmost applied patch if you run \hgcmd{qpush}. |
bos@104 | 133 |
bos@104 | 134 \subsection{\hgcmd{qpop}---pop patches off the stack} |
bos@104 | 135 |
bos@104 | 136 The \hgcmd{qpop} command removes applied patches from the top of the |
bos@104 | 137 stack of applied patches. By default, it removes only one patch. |
bos@104 | 138 |
bos@104 | 139 This command removes the changesets that represent the popped patches |
bos@104 | 140 from the repository, and updates the working directory to undo the |
bos@104 | 141 effects of the patches. |
bos@104 | 142 |
bos@104 | 143 This command takes an optional argument, which it uses as the name or |
bos@104 | 144 index of the patch to pop to. If given a name, it will pop patches |
bos@104 | 145 until the named patch is the topmost applied patch. If given a |
bos@104 | 146 number, \hgcmd{qpop} treats the number as an index into the entries in |
bos@104 | 147 the series file, counting from zero (empty lines and lines containing |
bos@104 | 148 only comments do not count). It pops patches until the patch |
bos@104 | 149 identified by the given index is the topmost applied patch. |
bos@104 | 150 |
bos@104 | 151 The \hgcmd{qpop} command does not read or write patches or the |
bos@104 | 152 \sfilename{series} file. It is thus safe to \hgcmd{qpop} a patch that |
bos@104 | 153 you have removed from the \sfilename{series} file, or a patch that you |
bos@104 | 154 have renamed or deleted entirely. In the latter two cases, use the |
bos@104 | 155 name of the patch as it was when you applied it. |
bos@104 | 156 |
bos@104 | 157 By default, the \hgcmd{qpop} command will not pop any patches if the |
bos@104 | 158 working directory has been modified. You can override this behaviour |
bos@104 | 159 using the \hgopt{qpop}{-f} option, which reverts all modifications in |
bos@104 | 160 the working directory. |
bos@104 | 161 |
bos@104 | 162 Options: |
bos@104 | 163 \begin{itemize} |
bos@104 | 164 \item[\hgopt{qpop}{-a}] Pop all applied patches. This returns the |
bos@104 | 165 repository to its state before you applied any patches. |
bos@104 | 166 \item[\hgopt{qpop}{-f}] Forcibly revert any modifications to the |
bos@104 | 167 working directory when popping. |
bos@104 | 168 \item[\hgopt{qpop}{-n}] Pop a patch from the named queue. |
bos@104 | 169 \end{itemize} |
bos@104 | 170 |
bos@104 | 171 The \hgcmd{qpop} command removes one line from the end of the |
bos@104 | 172 \sfilename{status} file for each patch that it pops. |
bos@104 | 173 |
bos@104 | 174 \subsection{\hgcmd{qprev}---print the name of the previous patch} |
bos@104 | 175 |
bos@104 | 176 The \hgcmd{qprev} command prints the name of the patch in the |
bos@104 | 177 \sfilename{series} file that comes before the topmost applied patch. |
bos@104 | 178 This will become the topmost applied patch if you run \hgcmd{qpop}. |
bos@104 | 179 |
bos@104 | 180 \subsection{\hgcmd{qpush}---push patches onto the stack} |
bos@104 | 181 \label{sec:mq:cmd:qpush} |
bos@104 | 182 |
bos@104 | 183 The \hgcmd{qpush} command adds patches onto the applied stack. By |
bos@104 | 184 default, it adds only one patch. |
bos@104 | 185 |
bos@104 | 186 This command creates a new changeset to represent each applied patch, |
bos@104 | 187 and updates the working directory to apply the effects of the patches. |
bos@104 | 188 |
bos@104 | 189 The default data used when creating a changeset are as follows: |
bos@104 | 190 \begin{itemize} |
bos@104 | 191 \item The commit date and time zone are the current date and time |
bos@104 | 192 zone. Because these data are used to compute the identity of a |
bos@104 | 193 changeset, this means that if you \hgcmd{qpop} a patch and |
bos@104 | 194 \hgcmd{qpush} it again, the changeset that you push will have a |
bos@104 | 195 different identity than the changeset you popped. |
bos@104 | 196 \item The author is the same as the default used by the \hgcmd{commit} |
bos@104 | 197 command. |
bos@104 | 198 \item The commit message is any text from the patch file that comes |
bos@104 | 199 before the first diff header. If there is no such text, a default |
bos@104 | 200 commit message is used that identifies the name of the patch. |
bos@104 | 201 \end{itemize} |
bos@104 | 202 If a patch contains a Mercurial patch header (XXX add link), the |
bos@104 | 203 information in the patch header overrides these defaults. |
bos@104 | 204 |
bos@104 | 205 Options: |
bos@104 | 206 \begin{itemize} |
bos@104 | 207 \item[\hgopt{qpush}{-a}] Push all unapplied patches from the |
bos@104 | 208 \sfilename{series} file until there are none left to push. |
bos@104 | 209 \item[\hgopt{qpush}{-l}] Add the name of the patch to the end |
bos@104 | 210 of the commit message. |
bos@104 | 211 \item[\hgopt{qpush}{-m}] If a patch fails to apply cleanly, use the |
bos@104 | 212 entry for the patch in another saved queue to compute the parameters |
bos@104 | 213 for a three-way merge, and perform a three-way merge using the |
bos@104 | 214 normal Mercurial merge machinery. Use the resolution of the merge |
bos@104 | 215 as the new patch content. |
bos@104 | 216 \item[\hgopt{qpush}{-n}] Use the named queue if merging while pushing. |
bos@104 | 217 \end{itemize} |
bos@104 | 218 |
bos@104 | 219 The \hgcmd{qpush} command reads, but does not modify, the |
bos@104 | 220 \sfilename{series} file. It appends one line to the \hgcmd{status} |
bos@104 | 221 file for each patch that it pushes. |
bos@104 | 222 |
bos@104 | 223 \subsection{\hgcmd{qrefresh}---update the topmost applied patch} |
bos@104 | 224 |
bos@104 | 225 The \hgcmd{qrefresh} command updates the topmost applied patch. It |
bos@104 | 226 modifies the patch, removes the old changeset that represented the |
bos@104 | 227 patch, and creates a new changeset to represent the modified patch. |
bos@104 | 228 |
bos@104 | 229 The \hgcmd{qrefresh} command looks for the following modifications: |
bos@104 | 230 \begin{itemize} |
bos@104 | 231 \item Changes to the commit message, i.e.~the text before the first |
bos@104 | 232 diff header in the patch file, are reflected in the new changeset |
bos@104 | 233 that represents the patch. |
bos@104 | 234 \item Modifications to tracked files in the working directory are |
bos@104 | 235 added to the patch. |
bos@104 | 236 \item Changes to the files tracked using \hgcmd{add}, \hgcmd{copy}, |
bos@104 | 237 \hgcmd{remove}, or \hgcmd{rename}. Added files and copy and rename |
bos@104 | 238 destinations are added to the patch, while removed files and rename |
bos@104 | 239 sources are removed. |
bos@104 | 240 \end{itemize} |
bos@104 | 241 |
bos@104 | 242 Even if \hgcmd{qrefresh} detects no changes, it still recreates the |
bos@104 | 243 changeset that represents the patch. This causes the identity of the |
bos@104 | 244 changeset to differ from the previous changeset that identified the |
bos@104 | 245 patch. |
bos@104 | 246 |
bos@104 | 247 Options: |
bos@104 | 248 \begin{itemize} |
bos@104 | 249 \item[\hgopt{qrefresh}{-e}] Modify the commit and patch description, |
bos@104 | 250 using the preferred text editor. |
bos@104 | 251 \item[\hgopt{qrefresh}{-m}] Modify the commit message and patch |
bos@104 | 252 description, using the given text. |
bos@104 | 253 \item[\hgopt{qrefresh}{-l}] Modify the commit message and patch |
bos@104 | 254 description, using text from the given file. |
bos@104 | 255 \end{itemize} |
bos@104 | 256 |
bos@104 | 257 \subsection{\hgcmd{qrename}---rename a patch} |
bos@104 | 258 |
bos@104 | 259 The \hgcmd{qrename} command renames a patch, and changes the entry for |
bos@104 | 260 the patch in the \sfilename{series} file. |
bos@104 | 261 |
bos@104 | 262 With a single argument, \hgcmd{qrename} renames the topmost applied |
bos@104 | 263 patch. With two arguments, it renames its first argument to its |
bos@104 | 264 second. |
bos@104 | 265 |
bos@104 | 266 \subsection{\hgcmd{qrestore}---restore saved queue state} |
bos@104 | 267 |
bos@104 | 268 XXX No idea what this does. |
bos@104 | 269 |
bos@104 | 270 \subsection{\hgcmd{qsave}---save current queue state} |
bos@104 | 271 |
bos@104 | 272 XXX Likewise. |
bos@104 | 273 |
bos@104 | 274 \subsection{\hgcmd{qseries}---print the entire patch series} |
bos@104 | 275 |
bos@104 | 276 The \hgcmd{qseries} command prints the entire patch series from the |
bos@104 | 277 \sfilename{series} file. It prints only patch names, not empty lines |
bos@104 | 278 or comments. It prints in order from first to be applied to last. |
bos@104 | 279 |
bos@104 | 280 \subsection{\hgcmd{qtop}---print the name of the current patch} |
bos@104 | 281 |
bos@104 | 282 The \hgcmd{qtop} prints the name of the topmost currently applied |
bos@104 | 283 patch. |
bos@104 | 284 |
bos@104 | 285 \subsection{\hgcmd{qunapplied}---print patches not yet applied} |
bos@104 | 286 |
bos@104 | 287 The \hgcmd{qunapplied} command prints the names of patches from the |
bos@104 | 288 \sfilename{series} file that are not yet applied. It prints them in |
bos@104 | 289 order from the next patch that will be pushed to the last. |
bos@104 | 290 |
bos@104 | 291 \subsection{\hgcmd{qversion}} |
bos@104 | 292 |
bos@104 | 293 The \hgcmd{qversion} command prints the version of MQ that is in use. |
bos@104 | 294 |
bos@104 | 295 \subsection{\hgcmd{strip}---remove a revision and descendants} |
bos@104 | 296 |
bos@104 | 297 The \hgcmd{strip} command removes a revision, and all of its |
bos@104 | 298 descendants, from the repository. It undoes the effects of the |
bos@104 | 299 removed revisions from the repository, and updates the working |
bos@104 | 300 directory to the first parent of the removed revision. |
bos@104 | 301 |
bos@104 | 302 The \hgcmd{strip} command saves a backup of the removed changesets in |
bos@104 | 303 a bundle, so that they can be reapplied if removed in error. |
bos@104 | 304 |
bos@104 | 305 Options: |
bos@104 | 306 \begin{itemize} |
bos@104 | 307 \item[\hgopt{strip}{-b}] Save unrelated changesets that are intermixed |
bos@104 | 308 with the stripped changesets in the backup bundle. |
bos@104 | 309 \item[\hgopt{strip}{-f}] If a branch has multiple heads, remove all |
bos@104 | 310 heads. XXX This should be renamed, and use \texttt{-f} to strip revs |
bos@104 | 311 when there are pending changes. |
bos@104 | 312 \item[\hgopt{strip}{-n}] Do not save a backup bundle. |
bos@104 | 313 \end{itemize} |
bos@104 | 314 |
bos@104 | 315 \section{MQ file reference} |
bos@104 | 316 |
bos@104 | 317 \subsection{The \sfilename{series} file} |
bos@104 | 318 |
bos@104 | 319 The \sfilename{series} file contains a list of the names of all |
bos@104 | 320 patches that MQ can apply. It is represented as a list of names, with |
bos@104 | 321 one name saved per line. Leading and trailing white space in each |
bos@104 | 322 line are ignored. |
bos@104 | 323 |
bos@104 | 324 Lines may contain comments. A comment begins with the ``\texttt{\#}'' |
bos@104 | 325 character, and extends to the end of the line. Empty lines, and lines |
bos@104 | 326 that contain only comments, are ignored. |
bos@104 | 327 |
bos@104 | 328 You will often need to edit the \sfilename{series} file by hand, hence |
bos@104 | 329 the support for comments and empty lines noted above. For example, |
bos@104 | 330 you can comment out a patch temporarily, and \hgcmd{qpush} will skip |
bos@104 | 331 over that patch when applying patches. You can also change the order |
bos@104 | 332 in which patches are applied by reordering their entries in the |
bos@104 | 333 \sfilename{series} file. |
bos@104 | 334 |
bos@104 | 335 Placing the \sfilename{series} file under revision control is also |
bos@104 | 336 supported; it is a good idea to place all of the patches that it |
bos@104 | 337 refers to under revision control, as well. If you create a patch |
bos@104 | 338 directory using the \hgopt{qinit}{-c} option to \hgcmd{qinit}, this |
bos@104 | 339 will be done for you automatically. |
bos@104 | 340 |
bos@104 | 341 \subsection{The \sfilename{status} file} |
bos@104 | 342 |
bos@104 | 343 The \sfilename{status} file contains the names and changeset hashes of |
bos@104 | 344 all patches that MQ currently has applied. Unlike the |
bos@104 | 345 \sfilename{series} file, this file is not intended for editing. You |
bos@104 | 346 should not place this file under revision control, or modify it in any |
bos@104 | 347 way. It is used by MQ strictly for internal book-keeping. |
bos@104 | 348 |
bos@104 | 349 %%% Local Variables: |
bos@104 | 350 %%% mode: latex |
bos@104 | 351 %%% TeX-master: "00book" |
bos@104 | 352 %%% End: |