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