hgbook

annotate en/mq-ref.tex @ 171:8c1703a98266

find changesets by author, revision, files, or words in the commit message
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.
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: