hgbook

annotate en/mq-ref.tex @ 251:2e73abddad21

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