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