Debian Codegraph @

doc/hg.1.html

raw
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4 <head>
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6 <meta name="generator" content="Docutils 0.21.2: https://docutils.sourceforge.io/" />
7 <meta name="author" content="Olivia Mackall &lt;olivia&#64;selenic.com&gt;" />
8 <meta name="organization" content="Mercurial" />
9 <title>hg</title>
10 <link rel="stylesheet" href="style.css" type="text/css" />
11 </head>
12 <body>
13 <div class="document" id="hg">
14 <span id="hg-1"></span>
15 <h1 class="title">hg</h1>
16 <h2 class="subtitle" id="mercurial-source-code-management-system">Mercurial source code management system</h2>
17 <table class="docinfo" frame="void" rules="none">
18 <col class="docinfo-name" />
19 <col class="docinfo-content" />
20 <tbody valign="top">
21 <tr><th class="docinfo-name">Author:</th>
22 <td>Olivia Mackall &lt;<a class="reference external" href="mailto:olivia&#64;selenic.com">olivia&#64;selenic.com</a>&gt;</td></tr>
23 <tr><th class="docinfo-name">Organization:</th>
24 <td>Mercurial</td></tr>
25 <tr class="manual-section field"><th class="docinfo-name">Manual section:</th><td class="field-body">1</td>
26 </tr>
27 <tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">Mercurial Manual</td>
28 </tr>
29 </tbody>
30 </table>
31 <div class="contents htmlonly topic" id="contents">
32 <p class="topic-title"><a class="reference internal" href="#top">Contents</a></p>
33 <ul class="simple">
34 <li><a class="reference internal" href="#synopsis" id="toc-entry-1">Synopsis</a></li>
35 <li><a class="reference internal" href="#description" id="toc-entry-2">Description</a></li>
36 <li><a class="reference internal" href="#command-elements" id="toc-entry-3">Command Elements</a></li>
37 <li><a class="reference internal" href="#options" id="toc-entry-4">Options</a></li>
38 <li><a class="reference internal" href="#commands" id="toc-entry-5">Commands</a></li>
39 <li><a class="reference internal" href="#bundle-file-formats" id="toc-entry-6">Bundle File Formats</a></li>
40 <li><a class="reference internal" href="#colorizing-outputs" id="toc-entry-7">Colorizing Outputs</a></li>
41 <li><a class="reference internal" href="#date-formats" id="toc-entry-8">Date Formats</a></li>
42 <li><a class="reference internal" href="#deprecated-features" id="toc-entry-9">Deprecated Features</a></li>
43 <li><a class="reference internal" href="#diff-formats" id="toc-entry-10">Diff Formats</a></li>
44 <li><a class="reference internal" href="#environment-variables" id="toc-entry-11">Environment Variables</a></li>
45 <li><a class="reference internal" href="#safely-rewriting-history-experimental" id="toc-entry-12">Safely rewriting history (EXPERIMENTAL)</a></li>
46 <li><a class="reference internal" href="#using-additional-features" id="toc-entry-13">Using Additional Features</a></li>
47 <li><a class="reference internal" href="#specifying-file-sets" id="toc-entry-14">Specifying File Sets</a></li>
48 <li><a class="reference internal" href="#command-line-flags" id="toc-entry-15">Command-line flags</a></li>
49 <li><a class="reference internal" href="#glossary-1" id="toc-entry-16">Glossary</a></li>
50 <li><a class="reference internal" href="#syntax-for-mercurial-ignore-files" id="toc-entry-17">Syntax for Mercurial Ignore Files</a></li>
51 <li><a class="reference internal" href="#configuring-hgweb" id="toc-entry-18">Configuring hgweb</a></li>
52 <li><a class="reference internal" href="#technical-implementation-topics" id="toc-entry-19">Technical implementation topics</a></li>
53 <li><a class="reference internal" href="#merge-tools-1" id="toc-entry-20">Merge Tools</a></li>
54 <li><a class="reference internal" href="#pager-support" id="toc-entry-21">Pager Support</a></li>
55 <li><a class="reference internal" href="#file-name-patterns" id="toc-entry-22">File Name Patterns</a></li>
56 <li><a class="reference internal" href="#working-with-phases" id="toc-entry-23">Working with Phases</a></li>
57 <li><a class="reference internal" href="#specifying-revisions" id="toc-entry-24">Specifying Revisions</a></li>
58 <li><a class="reference internal" href="#rust-in-mercurial" id="toc-entry-25">Rust in Mercurial</a></li>
59 <li><a class="reference internal" href="#using-mercurial-from-scripts-and-automation" id="toc-entry-26">Using Mercurial from scripts and automation</a></li>
60 <li><a class="reference internal" href="#subrepositories" id="toc-entry-27">Subrepositories</a></li>
61 <li><a class="reference internal" href="#template-usage" id="toc-entry-28">Template Usage</a></li>
62 <li><a class="reference internal" href="#url-paths" id="toc-entry-29">URL Paths</a></li>
63 <li><a class="reference internal" href="#extensions-1" id="toc-entry-30">Extensions</a></li>
64 <li><a class="reference internal" href="#files-1" id="toc-entry-31">Files</a></li>
65 <li><a class="reference internal" href="#bugs" id="toc-entry-32">Bugs</a></li>
66 <li><a class="reference internal" href="#see-also" id="toc-entry-33">See Also</a></li>
67 <li><a class="reference internal" href="#author" id="toc-entry-34">Author</a></li>
68 <li><a class="reference internal" href="#resources" id="toc-entry-35">Resources</a></li>
69 <li><a class="reference internal" href="#copying" id="toc-entry-36">Copying</a></li>
70 </ul>
71 </div>
72 <div class="section" id="synopsis">
73 <h1><a class="toc-backref" href="#contents">Synopsis</a></h1>
74 <p><strong>hg</strong> <em>command</em> [<em>option</em>]... [<em>argument</em>]...</p>
75 </div>
76 <div class="section" id="description">
77 <h1><a class="toc-backref" href="#contents">Description</a></h1>
78 <p>The <strong>hg</strong> command provides a command line interface to the Mercurial
79 system.</p>
80 </div>
81 <div class="section" id="command-elements">
82 <h1><a class="toc-backref" href="#contents">Command Elements</a></h1>
83 <dl class="docutils">
84 <dt>files...</dt>
85 <dd>indicates one or more filename or relative path filenames; see
86 <a class="reference internal" href="#file-name-patterns">File Name Patterns</a> for information on pattern matching</dd>
87 <dt>path</dt>
88 <dd>indicates a path on the local machine</dd>
89 <dt>revision</dt>
90 <dd>indicates a changeset which can be specified as a changeset
91 revision number, a tag, or a unique substring of the changeset
92 hash value</dd>
93 <dt>repository path</dt>
94 <dd>either the pathname of a local repository or the URI of a remote
95 repository.</dd>
96 </dl>
97 </div>
98 <div class="section" id="options">
99 <h1><a class="toc-backref" href="#contents">Options</a></h1>
100 <table class="docutils option-list" frame="void" rules="none">
101 <col class="option" />
102 <col class="description" />
103 <tbody valign="top">
104 <tr><td class="option-group" colspan="2">
105 <kbd><span class="option">-R</span>, <span class="option">--repository <var>&lt;REPO&gt;</var></span></kbd></td>
106 </tr>
107 <tr><td>&nbsp;</td><td>repository root directory or name of overlay bundle file</td></tr>
108 <tr><td class="option-group">
109 <kbd><span class="option">--cwd <var>&lt;DIR&gt;</var></span></kbd></td>
110 <td>change working directory</td></tr>
111 <tr><td class="option-group" colspan="2">
112 <kbd><span class="option">-y</span>, <span class="option">--noninteractive</span></kbd></td>
113 </tr>
114 <tr><td>&nbsp;</td><td>do not prompt, automatically pick the first choice for all prompts</td></tr>
115 <tr><td class="option-group">
116 <kbd><span class="option">-q</span>, <span class="option">--quiet</span></kbd></td>
117 <td>suppress output</td></tr>
118 <tr><td class="option-group">
119 <kbd><span class="option">-v</span>, <span class="option">--verbose</span></kbd></td>
120 <td>enable additional output</td></tr>
121 <tr><td class="option-group">
122 <kbd><span class="option">--color <var>&lt;TYPE&gt;</var></span></kbd></td>
123 <td>when to colorize (boolean, always, auto, never, or debug)</td></tr>
124 <tr><td class="option-group" colspan="2">
125 <kbd><span class="option">--config <var>&lt;CONFIG[+]&gt;</var></span></kbd></td>
126 </tr>
127 <tr><td>&nbsp;</td><td>set/override config option (use 'section.name=value')</td></tr>
128 <tr><td class="option-group" colspan="2">
129 <kbd><span class="option">--config-file <var>&lt;HGRC[+]&gt;</var></span></kbd></td>
130 </tr>
131 <tr><td>&nbsp;</td><td>load config file to set/override config options</td></tr>
132 <tr><td class="option-group">
133 <kbd><span class="option">--debug</span></kbd></td>
134 <td>enable debugging output</td></tr>
135 <tr><td class="option-group">
136 <kbd><span class="option">--debugger</span></kbd></td>
137 <td>start debugger</td></tr>
138 <tr><td class="option-group" colspan="2">
139 <kbd><span class="option">--encoding <var>&lt;ENCODE&gt;</var></span></kbd></td>
140 </tr>
141 <tr><td>&nbsp;</td><td>set the charset encoding (default: UTF-8)</td></tr>
142 <tr><td class="option-group" colspan="2">
143 <kbd><span class="option">--encodingmode <var>&lt;MODE&gt;</var></span></kbd></td>
144 </tr>
145 <tr><td>&nbsp;</td><td>set the charset encoding mode (default: strict)</td></tr>
146 <tr><td class="option-group">
147 <kbd><span class="option">--traceback</span></kbd></td>
148 <td>always print a traceback on exception</td></tr>
149 <tr><td class="option-group">
150 <kbd><span class="option">--time</span></kbd></td>
151 <td>time how long the command takes</td></tr>
152 <tr><td class="option-group">
153 <kbd><span class="option">--profile</span></kbd></td>
154 <td>print command execution profile</td></tr>
155 <tr><td class="option-group">
156 <kbd><span class="option">--version</span></kbd></td>
157 <td>output version information and exit</td></tr>
158 <tr><td class="option-group">
159 <kbd><span class="option">-h</span>, <span class="option">--help</span></kbd></td>
160 <td>display help and exit</td></tr>
161 <tr><td class="option-group">
162 <kbd><span class="option">--hidden</span></kbd></td>
163 <td>consider hidden changesets</td></tr>
164 <tr><td class="option-group">
165 <kbd><span class="option">--pager <var>&lt;TYPE&gt;</var></span></kbd></td>
166 <td>when to paginate (boolean, always, auto, or never) (default: auto)</td></tr>
167 </tbody>
168 </table>
169 <p>[+] marked option can be specified multiple times</p>
170 </div>
171 <div class="section" id="commands">
172 <h1><a class="toc-backref" href="#contents">Commands</a></h1>
173 <div class="section" id="repository-creation">
174 <h2>Repository creation</h2>
175 <div class="section" id="clone">
176 <h3>clone</h3>
177 <p>make a copy of an existing repository:</p>
178 <pre class="literal-block">
179 hg clone [OPTION]... SOURCE [DEST]
180 </pre>
181 <p>Create a copy of an existing repository in a new directory.</p>
182 <p>If no destination directory name is specified, it defaults to the
183 basename of the source.</p>
184 <p>The location of the source is added to the new repository's
185 <tt class="docutils literal">.hg/hgrc</tt> file, as the default to be used for future pulls.</p>
186 <p>Only local paths and <tt class="docutils literal"><span class="pre">ssh://</span></tt> URLs are supported as
187 destinations. For <tt class="docutils literal"><span class="pre">ssh://</span></tt> destinations, no working directory or
188 <tt class="docutils literal">.hg/hgrc</tt> will be created on the remote side.</p>
189 <p>If the source repository has a bookmark called '&#64;' set, that
190 revision will be checked out in the new repository by default.</p>
191 <p>To check out a particular version, use -u/--update, or
192 -U/--noupdate to create a clone with no working directory.</p>
193 <p>To pull only a subset of changesets, specify one or more revisions
194 identifiers with -r/--rev or branches with -b/--branch. The
195 resulting clone will contain only the specified changesets and
196 their ancestors. These options (or 'clone src#rev dest') imply
197 --pull, even for local source repositories.</p>
198 <p>In normal clone mode, the remote normalizes repository data into a common
199 exchange format and the receiving end translates this data into its local
200 storage format. --stream activates a different clone mode that essentially
201 copies repository files from the remote with minimal data processing. This
202 significantly reduces the CPU cost of a clone both remotely and locally.
203 However, it often increases the transferred data size by 30-40%. This can
204 result in substantially faster clones where I/O throughput is plentiful,
205 especially for larger repositories. A side-effect of --stream clones is
206 that storage settings and requirements on the remote are applied locally:
207 a modern client may inherit legacy or inefficient storage used by the
208 remote or a legacy Mercurial client may not be able to clone from a
209 modern Mercurial remote.</p>
210 <div class="admonition note">
211 <p class="first admonition-title">Note</p>
212 <p class="last">Specifying a tag will include the tagged changeset but not the
213 changeset containing the tag.</p>
214 </div>
215 <div class="verbose docutils container">
216 <p>For efficiency, hardlinks are used for cloning whenever the
217 source and destination are on the same filesystem (note this
218 applies only to the repository data, not to the working
219 directory). Some filesystems, such as AFS, implement hardlinking
220 incorrectly, but do not report errors. In these cases, use the
221 --pull option to avoid hardlinking.</p>
222 <p>Mercurial will update the working directory to the first applicable
223 revision from this list:</p>
224 <ol class="loweralpha simple">
225 <li>null if -U or the source repository has no changesets</li>
226 <li>if -u . and the source repository is local, the first parent of
227 the source repository's working directory</li>
228 <li>the changeset specified with -u (if a branch name, this means the
229 latest head of that branch)</li>
230 <li>the changeset specified with -r</li>
231 <li>the tipmost head specified with -b</li>
232 <li>the tipmost head specified with the url#branch source syntax</li>
233 <li>the revision marked with the '&#64;' bookmark, if present</li>
234 <li>the tipmost head of the default branch</li>
235 <li>tip</li>
236 </ol>
237 <p>When cloning from servers that support it, Mercurial may fetch
238 pre-generated data from a server-advertised URL or inline from the
239 same stream. When this is done, hooks operating on incoming changesets
240 and changegroups may fire more than once, once for each pre-generated
241 bundle and as well as for any additional remaining data. In addition,
242 if an error occurs, the repository may be rolled back to a partial
243 clone. This behavior may change in future releases.
244 See <a class="reference external" href="hg.1.html#-e"><tt class="docutils literal">hg help <span class="pre">-e</span> clonebundles</tt></a> for more.</p>
245 <p>Examples:</p>
246 <ul>
247 <li><p class="first">clone a remote repository to a new directory named hg/:</p>
248 <pre class="literal-block">
249 hg clone https://www.mercurial-scm.org/repo/hg/
250 </pre>
251 </li>
252 <li><p class="first">create a lightweight local clone:</p>
253 <pre class="literal-block">
254 hg clone project/ project-feature/
255 </pre>
256 </li>
257 <li><p class="first">clone from an absolute path on an ssh server (note double-slash):</p>
258 <pre class="literal-block">
259 hg clone ssh://user&#64;server//home/projects/alpha/
260 </pre>
261 </li>
262 <li><p class="first">do a streaming clone while checking out a specified version:</p>
263 <pre class="literal-block">
264 hg clone --stream http://server/repo -u 1.5
265 </pre>
266 </li>
267 <li><p class="first">create a repository without changesets after a particular revision:</p>
268 <pre class="literal-block">
269 hg clone -r 04e544 experimental/ good/
270 </pre>
271 </li>
272 <li><p class="first">clone (and track) a particular named branch:</p>
273 <pre class="literal-block">
274 hg clone https://www.mercurial-scm.org/repo/hg/#stable
275 </pre>
276 </li>
277 </ul>
278 </div>
279 <p>See <a class="reference external" href="hg.1.html#urls"><tt class="docutils literal">hg help urls</tt></a> for details on specifying URLs.</p>
280 <p>Returns 0 on success.</p>
281 <p>Options:</p>
282 <table class="docutils option-list" frame="void" rules="none">
283 <col class="option" />
284 <col class="description" />
285 <tbody valign="top">
286 <tr><td class="option-group">
287 <kbd><span class="option">-U</span>, <span class="option">--noupdate</span></kbd></td>
288 <td>the clone will include an empty working directory (only a repository)</td></tr>
289 <tr><td class="option-group" colspan="2">
290 <kbd><span class="option">-u</span>, <span class="option">--updaterev <var>&lt;REV&gt;</var></span></kbd></td>
291 </tr>
292 <tr><td>&nbsp;</td><td>revision, tag, or branch to check out</td></tr>
293 <tr><td class="option-group" colspan="2">
294 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
295 </tr>
296 <tr><td>&nbsp;</td><td>do not clone everything, but include this changeset and its ancestors</td></tr>
297 <tr><td class="option-group" colspan="2">
298 <kbd><span class="option">-b</span>, <span class="option">--branch <var>&lt;BRANCH[+]&gt;</var></span></kbd></td>
299 </tr>
300 <tr><td>&nbsp;</td><td>do not clone everything, but include this branch's changesets and their ancestors</td></tr>
301 <tr><td class="option-group">
302 <kbd><span class="option">--pull</span></kbd></td>
303 <td>use pull protocol to copy metadata</td></tr>
304 <tr><td class="option-group">
305 <kbd><span class="option">--uncompressed</span></kbd></td>
306 <td>an alias to --stream (DEPRECATED)</td></tr>
307 <tr><td class="option-group">
308 <kbd><span class="option">--stream</span></kbd></td>
309 <td>clone with minimal data processing</td></tr>
310 <tr><td class="option-group" colspan="2">
311 <kbd><span class="option">-e</span>, <span class="option">--ssh <var>&lt;CMD&gt;</var></span></kbd></td>
312 </tr>
313 <tr><td>&nbsp;</td><td>specify ssh command to use</td></tr>
314 <tr><td class="option-group" colspan="2">
315 <kbd><span class="option">--remotecmd <var>&lt;CMD&gt;</var></span></kbd></td>
316 </tr>
317 <tr><td>&nbsp;</td><td>specify hg command to run on the remote side</td></tr>
318 <tr><td class="option-group">
319 <kbd><span class="option">--insecure</span></kbd></td>
320 <td>do not verify server certificate (ignoring web.cacerts config)</td></tr>
321 </tbody>
322 </table>
323 <p>[+] marked option can be specified multiple times</p>
324 </div>
325 <div class="section" id="init">
326 <h3>init</h3>
327 <p>create a new repository in the given directory:</p>
328 <pre class="literal-block">
329 hg init [-e CMD] [--remotecmd CMD] [DEST]
330 </pre>
331 <p>Initialize a new repository in the given directory. If the given
332 directory does not exist, it will be created.</p>
333 <p>If no directory is given, the current directory is used.</p>
334 <p>It is possible to specify an <tt class="docutils literal"><span class="pre">ssh://</span></tt> URL as the destination.
335 See <a class="reference external" href="hg.1.html#urls"><tt class="docutils literal">hg help urls</tt></a> for more information.</p>
336 <p>Returns 0 on success.</p>
337 <p>Options:</p>
338 <table class="docutils option-list" frame="void" rules="none">
339 <col class="option" />
340 <col class="description" />
341 <tbody valign="top">
342 <tr><td class="option-group" colspan="2">
343 <kbd><span class="option">-e</span>, <span class="option">--ssh <var>&lt;CMD&gt;</var></span></kbd></td>
344 </tr>
345 <tr><td>&nbsp;</td><td>specify ssh command to use</td></tr>
346 <tr><td class="option-group" colspan="2">
347 <kbd><span class="option">--remotecmd <var>&lt;CMD&gt;</var></span></kbd></td>
348 </tr>
349 <tr><td>&nbsp;</td><td>specify hg command to run on the remote side</td></tr>
350 <tr><td class="option-group">
351 <kbd><span class="option">--insecure</span></kbd></td>
352 <td>do not verify server certificate (ignoring web.cacerts config)</td></tr>
353 </tbody>
354 </table>
355 </div>
356 </div>
357 <div class="section" id="remote-repository-management">
358 <h2>Remote repository management</h2>
359 <div class="section" id="incoming">
360 <h3>incoming</h3>
361 <p>show new changesets found in source:</p>
362 <pre class="literal-block">
363 hg incoming [-p] [-n] [-M] [-f] [-r REV]... [--bundle FILENAME] [SOURCE]
364 </pre>
365 <p>Show new changesets found in the specified path/URL or the default
366 pull location. These are the changesets that would have been pulled
367 by <a class="reference external" href="hg.1.html#pull"><tt class="docutils literal">hg pull</tt></a> at the time you issued this command.</p>
368 <p>See pull for valid source format details.</p>
369 <div class="verbose docutils container">
370 <p>With -B/--bookmarks, the result of bookmark comparison between
371 local and remote repositories is displayed. With -v/--verbose,
372 status is also displayed for each bookmark like below:</p>
373 <pre class="literal-block">
374 BM1 01234567890a added
375 BM2 1234567890ab advanced
376 BM3 234567890abc diverged
377 BM4 34567890abcd changed
378 </pre>
379 <p>The action taken locally when pulling depends on the
380 status of each bookmark:</p>
381 <table class="docutils field-list" frame="void" rules="none">
382 <col class="field-name" />
383 <col class="field-body" />
384 <tbody valign="top">
385 <tr class="field"><th class="field-name"><tt class="docutils literal">added</tt>:</th><td class="field-body">pull will create it</td>
386 </tr>
387 <tr class="field"><th class="field-name"><tt class="docutils literal">advanced</tt>:</th><td class="field-body">pull will update it</td>
388 </tr>
389 <tr class="field"><th class="field-name"><tt class="docutils literal">diverged</tt>:</th><td class="field-body">pull will create a divergent bookmark</td>
390 </tr>
391 <tr class="field"><th class="field-name"><tt class="docutils literal">changed</tt>:</th><td class="field-body">result depends on remote changesets</td>
392 </tr>
393 </tbody>
394 </table>
395 <p>From the point of view of pulling behavior, bookmark
396 existing only in the remote repository are treated as <tt class="docutils literal">added</tt>,
397 even if it is in fact locally deleted.</p>
398 </div>
399 <div class="verbose docutils container">
400 <p>For remote repository, using --bundle avoids downloading the
401 changesets twice if the incoming is followed by a pull.</p>
402 <p>Examples:</p>
403 <ul>
404 <li><p class="first">show incoming changes with patches and full description:</p>
405 <pre class="literal-block">
406 hg incoming -vp
407 </pre>
408 </li>
409 <li><p class="first">show incoming changes excluding merges, store a bundle:</p>
410 <pre class="literal-block">
411 hg in -vpM --bundle incoming.hg
412 hg pull incoming.hg
413 </pre>
414 </li>
415 <li><p class="first">briefly list changes inside a bundle:</p>
416 <pre class="literal-block">
417 hg in changes.hg -T &quot;{desc|firstline}\n&quot;
418 </pre>
419 </li>
420 </ul>
421 </div>
422 <p>Returns 0 if there are incoming changes, 1 otherwise.</p>
423 <p>Options:</p>
424 <table class="docutils option-list" frame="void" rules="none">
425 <col class="option" />
426 <col class="description" />
427 <tbody valign="top">
428 <tr><td class="option-group">
429 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
430 <td>run even if remote repository is unrelated</td></tr>
431 <tr><td class="option-group" colspan="2">
432 <kbd><span class="option">-n</span>, <span class="option">--newest-first</span></kbd></td>
433 </tr>
434 <tr><td>&nbsp;</td><td>show newest record first</td></tr>
435 <tr><td class="option-group" colspan="2">
436 <kbd><span class="option">--bundle <var>&lt;FILE&gt;</var></span></kbd></td>
437 </tr>
438 <tr><td>&nbsp;</td><td>file to store the bundles into</td></tr>
439 <tr><td class="option-group" colspan="2">
440 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
441 </tr>
442 <tr><td>&nbsp;</td><td>a remote changeset intended to be added</td></tr>
443 <tr><td class="option-group" colspan="2">
444 <kbd><span class="option">-B</span>, <span class="option">--bookmarks</span></kbd></td>
445 </tr>
446 <tr><td>&nbsp;</td><td>compare bookmarks</td></tr>
447 <tr><td class="option-group" colspan="2">
448 <kbd><span class="option">-b</span>, <span class="option">--branch <var>&lt;BRANCH[+]&gt;</var></span></kbd></td>
449 </tr>
450 <tr><td>&nbsp;</td><td>a specific branch you would like to pull</td></tr>
451 <tr><td class="option-group" colspan="2">
452 <kbd><span class="option">--remote-hidden</span></kbd></td>
453 </tr>
454 <tr><td>&nbsp;</td><td>include changesets hidden on the remote (EXPERIMENTAL)</td></tr>
455 <tr><td class="option-group">
456 <kbd><span class="option">-p</span>, <span class="option">--patch</span></kbd></td>
457 <td>show patch</td></tr>
458 <tr><td class="option-group">
459 <kbd><span class="option">-g</span>, <span class="option">--git</span></kbd></td>
460 <td>use git extended diff format</td></tr>
461 <tr><td class="option-group" colspan="2">
462 <kbd><span class="option">-l</span>, <span class="option">--limit <var>&lt;NUM&gt;</var></span></kbd></td>
463 </tr>
464 <tr><td>&nbsp;</td><td>limit number of changes displayed</td></tr>
465 <tr><td class="option-group" colspan="2">
466 <kbd><span class="option">-M</span>, <span class="option">--no-merges</span></kbd></td>
467 </tr>
468 <tr><td>&nbsp;</td><td>do not show merges</td></tr>
469 <tr><td class="option-group">
470 <kbd><span class="option">--stat</span></kbd></td>
471 <td>output diffstat-style summary of changes</td></tr>
472 <tr><td class="option-group">
473 <kbd><span class="option">-G</span>, <span class="option">--graph</span></kbd></td>
474 <td>show the revision DAG</td></tr>
475 <tr><td class="option-group" colspan="2">
476 <kbd><span class="option">--style <var>&lt;STYLE&gt;</var></span></kbd></td>
477 </tr>
478 <tr><td>&nbsp;</td><td>display using template map file (DEPRECATED)</td></tr>
479 <tr><td class="option-group" colspan="2">
480 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
481 </tr>
482 <tr><td>&nbsp;</td><td>display with template</td></tr>
483 <tr><td class="option-group" colspan="2">
484 <kbd><span class="option">-e</span>, <span class="option">--ssh <var>&lt;CMD&gt;</var></span></kbd></td>
485 </tr>
486 <tr><td>&nbsp;</td><td>specify ssh command to use</td></tr>
487 <tr><td class="option-group" colspan="2">
488 <kbd><span class="option">--remotecmd <var>&lt;CMD&gt;</var></span></kbd></td>
489 </tr>
490 <tr><td>&nbsp;</td><td>specify hg command to run on the remote side</td></tr>
491 <tr><td class="option-group">
492 <kbd><span class="option">--insecure</span></kbd></td>
493 <td>do not verify server certificate (ignoring web.cacerts config)</td></tr>
494 <tr><td class="option-group">
495 <kbd><span class="option">-S</span>, <span class="option">--subrepos</span></kbd></td>
496 <td>recurse into subrepositories</td></tr>
497 </tbody>
498 </table>
499 <p>[+] marked option can be specified multiple times</p>
500 <!-- -->
501 <blockquote>
502 aliases: in</blockquote>
503 </div>
504 <div class="section" id="outgoing">
505 <h3>outgoing</h3>
506 <p>show changesets not found in the destination:</p>
507 <pre class="literal-block">
508 hg outgoing [-M] [-p] [-n] [-f] [-r REV]... [DEST]...
509 </pre>
510 <p>Show changesets not found in the specified destination repository
511 or the default push location. These are the changesets that would
512 be pushed if a push was requested.</p>
513 <p>See pull for details of valid destination formats.</p>
514 <div class="verbose docutils container">
515 <p>With -B/--bookmarks, the result of bookmark comparison between
516 local and remote repositories is displayed. With -v/--verbose,
517 status is also displayed for each bookmark like below:</p>
518 <pre class="literal-block">
519 BM1 01234567890a added
520 BM2 deleted
521 BM3 234567890abc advanced
522 BM4 34567890abcd diverged
523 BM5 4567890abcde changed
524 </pre>
525 <p>The action taken when pushing depends on the
526 status of each bookmark:</p>
527 <table class="docutils field-list" frame="void" rules="none">
528 <col class="field-name" />
529 <col class="field-body" />
530 <tbody valign="top">
531 <tr class="field"><th class="field-name"><tt class="docutils literal">added</tt>:</th><td class="field-body">push with <tt class="docutils literal"><span class="pre">-B</span></tt> will create it</td>
532 </tr>
533 <tr class="field"><th class="field-name"><tt class="docutils literal">deleted</tt>:</th><td class="field-body">push with <tt class="docutils literal"><span class="pre">-B</span></tt> will delete it</td>
534 </tr>
535 <tr class="field"><th class="field-name"><tt class="docutils literal">advanced</tt>:</th><td class="field-body">push will update it</td>
536 </tr>
537 <tr class="field"><th class="field-name"><tt class="docutils literal">diverged</tt>:</th><td class="field-body">push with <tt class="docutils literal"><span class="pre">-B</span></tt> will update it</td>
538 </tr>
539 <tr class="field"><th class="field-name"><tt class="docutils literal">changed</tt>:</th><td class="field-body">push with <tt class="docutils literal"><span class="pre">-B</span></tt> will update it</td>
540 </tr>
541 </tbody>
542 </table>
543 <p>From the point of view of pushing behavior, bookmarks
544 existing only in the remote repository are treated as
545 <tt class="docutils literal">deleted</tt>, even if it is in fact added remotely.</p>
546 </div>
547 <p>Returns 0 if there are outgoing changes, 1 otherwise.</p>
548 <p>Options:</p>
549 <table class="docutils option-list" frame="void" rules="none">
550 <col class="option" />
551 <col class="description" />
552 <tbody valign="top">
553 <tr><td class="option-group">
554 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
555 <td>run even when the destination is unrelated</td></tr>
556 <tr><td class="option-group" colspan="2">
557 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
558 </tr>
559 <tr><td>&nbsp;</td><td>a changeset intended to be included in the destination</td></tr>
560 <tr><td class="option-group" colspan="2">
561 <kbd><span class="option">-n</span>, <span class="option">--newest-first</span></kbd></td>
562 </tr>
563 <tr><td>&nbsp;</td><td>show newest record first</td></tr>
564 <tr><td class="option-group" colspan="2">
565 <kbd><span class="option">-B</span>, <span class="option">--bookmarks</span></kbd></td>
566 </tr>
567 <tr><td>&nbsp;</td><td>compare bookmarks</td></tr>
568 <tr><td class="option-group" colspan="2">
569 <kbd><span class="option">-b</span>, <span class="option">--branch <var>&lt;BRANCH[+]&gt;</var></span></kbd></td>
570 </tr>
571 <tr><td>&nbsp;</td><td>a specific branch you would like to push</td></tr>
572 <tr><td class="option-group">
573 <kbd><span class="option">-p</span>, <span class="option">--patch</span></kbd></td>
574 <td>show patch</td></tr>
575 <tr><td class="option-group">
576 <kbd><span class="option">-g</span>, <span class="option">--git</span></kbd></td>
577 <td>use git extended diff format</td></tr>
578 <tr><td class="option-group" colspan="2">
579 <kbd><span class="option">-l</span>, <span class="option">--limit <var>&lt;NUM&gt;</var></span></kbd></td>
580 </tr>
581 <tr><td>&nbsp;</td><td>limit number of changes displayed</td></tr>
582 <tr><td class="option-group" colspan="2">
583 <kbd><span class="option">-M</span>, <span class="option">--no-merges</span></kbd></td>
584 </tr>
585 <tr><td>&nbsp;</td><td>do not show merges</td></tr>
586 <tr><td class="option-group">
587 <kbd><span class="option">--stat</span></kbd></td>
588 <td>output diffstat-style summary of changes</td></tr>
589 <tr><td class="option-group">
590 <kbd><span class="option">-G</span>, <span class="option">--graph</span></kbd></td>
591 <td>show the revision DAG</td></tr>
592 <tr><td class="option-group" colspan="2">
593 <kbd><span class="option">--style <var>&lt;STYLE&gt;</var></span></kbd></td>
594 </tr>
595 <tr><td>&nbsp;</td><td>display using template map file (DEPRECATED)</td></tr>
596 <tr><td class="option-group" colspan="2">
597 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
598 </tr>
599 <tr><td>&nbsp;</td><td>display with template</td></tr>
600 <tr><td class="option-group" colspan="2">
601 <kbd><span class="option">-e</span>, <span class="option">--ssh <var>&lt;CMD&gt;</var></span></kbd></td>
602 </tr>
603 <tr><td>&nbsp;</td><td>specify ssh command to use</td></tr>
604 <tr><td class="option-group" colspan="2">
605 <kbd><span class="option">--remotecmd <var>&lt;CMD&gt;</var></span></kbd></td>
606 </tr>
607 <tr><td>&nbsp;</td><td>specify hg command to run on the remote side</td></tr>
608 <tr><td class="option-group">
609 <kbd><span class="option">--insecure</span></kbd></td>
610 <td>do not verify server certificate (ignoring web.cacerts config)</td></tr>
611 <tr><td class="option-group">
612 <kbd><span class="option">-S</span>, <span class="option">--subrepos</span></kbd></td>
613 <td>recurse into subrepositories</td></tr>
614 </tbody>
615 </table>
616 <p>[+] marked option can be specified multiple times</p>
617 <!-- -->
618 <blockquote>
619 aliases: out</blockquote>
620 </div>
621 <div class="section" id="paths">
622 <h3>paths</h3>
623 <p>show aliases for remote repositories:</p>
624 <pre class="literal-block">
625 hg paths [NAME]
626 </pre>
627 <p>Show definition of symbolic path name NAME. If no name is given,
628 show definition of all available names.</p>
629 <p>Option -q/--quiet suppresses all output when searching for NAME
630 and shows only the path names when listing all definitions.</p>
631 <p>Path names are defined in the [paths] section of your
632 configuration file and in <tt class="docutils literal">/etc/mercurial/hgrc</tt>. If run inside a
633 repository, <tt class="docutils literal">.hg/hgrc</tt> is used, too.</p>
634 <p>The path names <tt class="docutils literal">default</tt> and <tt class="docutils literal"><span class="pre">default-push</span></tt> have a special
635 meaning. When performing a push or pull operation, they are used
636 as fallbacks if no location is specified on the command-line.
637 When <tt class="docutils literal"><span class="pre">default-push</span></tt> is set, it will be used for push and
638 <tt class="docutils literal">default</tt> will be used for pull; otherwise <tt class="docutils literal">default</tt> is used
639 as the fallback for both. When cloning a repository, the clone
640 source is written as <tt class="docutils literal">default</tt> in <tt class="docutils literal">.hg/hgrc</tt>.</p>
641 <div class="admonition note">
642 <p class="first admonition-title">Note</p>
643 <p class="last"><tt class="docutils literal">default</tt> and <tt class="docutils literal"><span class="pre">default-push</span></tt> apply to all inbound (e.g.
644 <a class="reference external" href="hg.1.html#incoming"><tt class="docutils literal">hg incoming</tt></a>) and outbound (e.g. <a class="reference external" href="hg.1.html#outgoing"><tt class="docutils literal">hg outgoing</tt></a>, <a class="reference external" href="hg.1.html#email"><tt class="docutils literal">hg email</tt></a>
645 and <a class="reference external" href="hg.1.html#bundle"><tt class="docutils literal">hg bundle</tt></a>) operations.</p>
646 </div>
647 <p>See <a class="reference external" href="hg.1.html#urls"><tt class="docutils literal">hg help urls</tt></a> for more information.</p>
648 <div class="verbose docutils container">
649 <p>Template:</p>
650 <p>The following keywords are supported. See also <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help templates</tt></a>.</p>
651 <table class="docutils field-list" frame="void" rules="none">
652 <col class="field-name" />
653 <col class="field-body" />
654 <tbody valign="top">
655 <tr class="field"><th class="field-name">name:</th><td class="field-body">String. Symbolic name of the path alias.</td>
656 </tr>
657 <tr class="field"><th class="field-name">pushurl:</th><td class="field-body">String. URL for push operations.</td>
658 </tr>
659 <tr class="field"><th class="field-name">url:</th><td class="field-body">String. URL or directory path for the other operations.</td>
660 </tr>
661 </tbody>
662 </table>
663 </div>
664 <p>Returns 0 on success.</p>
665 <p>Options:</p>
666 <table class="docutils option-list" frame="void" rules="none">
667 <col class="option" />
668 <col class="description" />
669 <tbody valign="top">
670 <tr><td class="option-group" colspan="2">
671 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
672 </tr>
673 <tr><td>&nbsp;</td><td>display with template</td></tr>
674 </tbody>
675 </table>
676 </div>
677 <div class="section" id="pull">
678 <h3>pull</h3>
679 <p>pull changes from the specified source:</p>
680 <pre class="literal-block">
681 hg pull [-u] [-f] [-r REV]... [-e CMD] [--remotecmd CMD] [SOURCE]...
682 </pre>
683 <p>Pull changes from a remote repository to a local one.</p>
684 <p>This finds all changes from the repository at the specified path
685 or URL and adds them to a local repository (the current one unless
686 -R is specified). By default, this does not update the copy of the
687 project in the working directory.</p>
688 <p>When cloning from servers that support it, Mercurial may fetch
689 pre-generated data. When this is done, hooks operating on incoming
690 changesets and changegroups may fire more than once, once for each
691 pre-generated bundle and as well as for any additional remaining
692 data. See <a class="reference external" href="hg.1.html#-e"><tt class="docutils literal">hg help <span class="pre">-e</span> clonebundles</tt></a> for more.</p>
693 <p>Use <a class="reference external" href="hg.1.html#incoming"><tt class="docutils literal">hg incoming</tt></a> if you want to see what would have been added
694 by a pull at the time you issued this command. If you then decide
695 to add those changes to the repository, you should use <a class="reference external" href="hg.1.html#pull"><tt class="docutils literal">hg pull
696 <span class="pre">-r</span> X</tt></a> where <tt class="docutils literal">X</tt> is the last changeset listed by <a class="reference external" href="hg.1.html#incoming"><tt class="docutils literal">hg incoming</tt></a>.</p>
697 <p>If SOURCE is omitted, the 'default' path will be used.
698 See <a class="reference external" href="hg.1.html#urls"><tt class="docutils literal">hg help urls</tt></a> for more information.</p>
699 <p>If multiple sources are specified, they will be pulled sequentially as if
700 the command was run multiple times. If --update is specified, the command
701 will stop at the first failed --update.</p>
702 <p>Specifying bookmark as <tt class="docutils literal">.</tt> is equivalent to specifying the active
703 bookmark's name.</p>
704 <div class="verbose docutils container">
705 One can use the <cite>--remote-hidden</cite> flag to pull changesets
706 hidden on the remote. This flag is &quot;best effort&quot;, and will only
707 work if the server supports the feature and is configured to
708 allow the user to access hidden changesets. This option is
709 experimental and backwards compatibility is not guaranteed.</div>
710 <p>Returns 0 on success, 1 if an update had unresolved files.</p>
711 <p>Options:</p>
712 <table class="docutils option-list" frame="void" rules="none">
713 <col class="option" />
714 <col class="description" />
715 <tbody valign="top">
716 <tr><td class="option-group">
717 <kbd><span class="option">-u</span>, <span class="option">--update</span></kbd></td>
718 <td>update to new branch head if new descendants were pulled</td></tr>
719 <tr><td class="option-group">
720 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
721 <td>run even when remote repository is unrelated</td></tr>
722 <tr><td class="option-group">
723 <kbd><span class="option">--confirm</span></kbd></td>
724 <td>confirm pull before applying changes</td></tr>
725 <tr><td class="option-group" colspan="2">
726 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
727 </tr>
728 <tr><td>&nbsp;</td><td>a remote changeset intended to be added</td></tr>
729 <tr><td class="option-group" colspan="2">
730 <kbd><span class="option">-B</span>, <span class="option">--bookmark <var>&lt;BOOKMARK[+]&gt;</var></span></kbd></td>
731 </tr>
732 <tr><td>&nbsp;</td><td>bookmark to pull</td></tr>
733 <tr><td class="option-group" colspan="2">
734 <kbd><span class="option">-b</span>, <span class="option">--branch <var>&lt;BRANCH[+]&gt;</var></span></kbd></td>
735 </tr>
736 <tr><td>&nbsp;</td><td>a specific branch you would like to pull</td></tr>
737 <tr><td class="option-group" colspan="2">
738 <kbd><span class="option">--remote-hidden</span></kbd></td>
739 </tr>
740 <tr><td>&nbsp;</td><td>include changesets hidden on the remote (EXPERIMENTAL)</td></tr>
741 <tr><td class="option-group" colspan="2">
742 <kbd><span class="option">-e</span>, <span class="option">--ssh <var>&lt;CMD&gt;</var></span></kbd></td>
743 </tr>
744 <tr><td>&nbsp;</td><td>specify ssh command to use</td></tr>
745 <tr><td class="option-group" colspan="2">
746 <kbd><span class="option">--remotecmd <var>&lt;CMD&gt;</var></span></kbd></td>
747 </tr>
748 <tr><td>&nbsp;</td><td>specify hg command to run on the remote side</td></tr>
749 <tr><td class="option-group">
750 <kbd><span class="option">--insecure</span></kbd></td>
751 <td>do not verify server certificate (ignoring web.cacerts config)</td></tr>
752 </tbody>
753 </table>
754 <p>[+] marked option can be specified multiple times</p>
755 </div>
756 <div class="section" id="push">
757 <h3>push</h3>
758 <p>push changes to the specified destination:</p>
759 <pre class="literal-block">
760 hg push [-f] [-r REV]... [-e CMD] [--remotecmd CMD] [DEST]...
761 </pre>
762 <p>Push changesets from the local repository to the specified
763 destination.</p>
764 <p>This operation is symmetrical to pull: it is identical to a pull
765 in the destination repository from the current one.</p>
766 <p>By default, push will not allow creation of new heads at the
767 destination, since multiple heads would make it unclear which head
768 to use. In this situation, it is recommended to pull and merge
769 before pushing.</p>
770 <p>Use --new-branch if you want to allow push to create a new named
771 branch that is not present at the destination. This allows you to
772 only create a new branch without forcing other changes.</p>
773 <div class="admonition note">
774 <p class="first admonition-title">Note</p>
775 <p class="last">Extra care should be taken with the -f/--force option,
776 which will push all new heads on all branches, an action which will
777 almost always cause confusion for collaborators.</p>
778 </div>
779 <p>If -r/--rev is used, the specified revision and all its ancestors
780 will be pushed to the remote repository.</p>
781 <p>If -B/--bookmark is used, the specified bookmarked revision, its
782 ancestors, and the bookmark will be pushed to the remote
783 repository. Specifying <tt class="docutils literal">.</tt> is equivalent to specifying the active
784 bookmark's name. Use the --all-bookmarks option for pushing all
785 current bookmarks.</p>
786 <p>Please see <a class="reference external" href="hg.1.html#urls"><tt class="docutils literal">hg help urls</tt></a> for important details about <tt class="docutils literal"><span class="pre">ssh://</span></tt>
787 URLs. If DESTINATION is omitted, a default path will be used.</p>
788 <p>When passed multiple destinations, push will process them one after the
789 other, but stop should an error occur.</p>
790 <div class="verbose docutils container">
791 <p>The --pushvars option sends strings to the server that become
792 environment variables prepended with <tt class="docutils literal">HG_USERVAR_</tt>. For example,
793 <tt class="docutils literal"><span class="pre">--pushvars</span> ENABLE_FEATURE=true</tt>, provides the server side hooks with
794 <tt class="docutils literal">HG_USERVAR_ENABLE_FEATURE=true</tt> as part of their environment.</p>
795 <p>pushvars can provide for user-overridable hooks as well as set debug
796 levels. One example is having a hook that blocks commits containing
797 conflict markers, but enables the user to override the hook if the file
798 is using conflict markers for testing purposes or the file format has
799 strings that look like conflict markers.</p>
800 <p>By default, servers will ignore <cite>--pushvars</cite>. To enable it add the
801 following to your configuration file:</p>
802 <pre class="literal-block">
803 [push]
804 pushvars.server = true
805 </pre>
806 </div>
807 <p>Returns 0 if push was successful, 1 if nothing to push.</p>
808 <p>Options:</p>
809 <table class="docutils option-list" frame="void" rules="none">
810 <col class="option" />
811 <col class="description" />
812 <tbody valign="top">
813 <tr><td class="option-group">
814 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
815 <td>force push</td></tr>
816 <tr><td class="option-group" colspan="2">
817 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
818 </tr>
819 <tr><td>&nbsp;</td><td>a changeset intended to be included in the destination</td></tr>
820 <tr><td class="option-group" colspan="2">
821 <kbd><span class="option">-B</span>, <span class="option">--bookmark <var>&lt;BOOKMARK[+]&gt;</var></span></kbd></td>
822 </tr>
823 <tr><td>&nbsp;</td><td>bookmark to push</td></tr>
824 <tr><td class="option-group" colspan="2">
825 <kbd><span class="option">--all-bookmarks</span></kbd></td>
826 </tr>
827 <tr><td>&nbsp;</td><td>push all bookmarks (EXPERIMENTAL)</td></tr>
828 <tr><td class="option-group" colspan="2">
829 <kbd><span class="option">-b</span>, <span class="option">--branch <var>&lt;BRANCH[+]&gt;</var></span></kbd></td>
830 </tr>
831 <tr><td>&nbsp;</td><td>a specific branch you would like to push</td></tr>
832 <tr><td class="option-group">
833 <kbd><span class="option">--new-branch</span></kbd></td>
834 <td>allow pushing a new branch</td></tr>
835 <tr><td class="option-group" colspan="2">
836 <kbd><span class="option">--pushvars <var>&lt;VALUE[+]&gt;</var></span></kbd></td>
837 </tr>
838 <tr><td>&nbsp;</td><td>variables that can be sent to server (ADVANCED)</td></tr>
839 <tr><td class="option-group">
840 <kbd><span class="option">--publish</span></kbd></td>
841 <td>push the changeset as public (EXPERIMENTAL)</td></tr>
842 <tr><td class="option-group" colspan="2">
843 <kbd><span class="option">-e</span>, <span class="option">--ssh <var>&lt;CMD&gt;</var></span></kbd></td>
844 </tr>
845 <tr><td>&nbsp;</td><td>specify ssh command to use</td></tr>
846 <tr><td class="option-group" colspan="2">
847 <kbd><span class="option">--remotecmd <var>&lt;CMD&gt;</var></span></kbd></td>
848 </tr>
849 <tr><td>&nbsp;</td><td>specify hg command to run on the remote side</td></tr>
850 <tr><td class="option-group">
851 <kbd><span class="option">--insecure</span></kbd></td>
852 <td>do not verify server certificate (ignoring web.cacerts config)</td></tr>
853 </tbody>
854 </table>
855 <p>[+] marked option can be specified multiple times</p>
856 </div>
857 <div class="section" id="serve">
858 <h3>serve</h3>
859 <p>start stand-alone webserver:</p>
860 <pre class="literal-block">
861 hg serve [OPTION]...
862 </pre>
863 <p>Start a local HTTP repository browser and pull server. You can use
864 this for ad-hoc sharing and browsing of repositories. It is
865 recommended to use a real web server to serve a repository for
866 longer periods of time.</p>
867 <p>Please note that the server does not implement access control.
868 This means that, by default, anybody can read from the server and
869 nobody can write to it by default. Set the <tt class="docutils literal"><span class="pre">web.allow-push</span></tt>
870 option to <tt class="docutils literal">*</tt> to allow everybody to push to the server. You
871 should use a real web server if you need to authenticate users.</p>
872 <p>By default, the server logs accesses to stdout and errors to
873 stderr. Use the -A/--accesslog and -E/--errorlog options to log to
874 files.</p>
875 <p>To have the server choose a free port number to listen on, specify
876 a port number of 0; in this case, the server will print the port
877 number it uses.</p>
878 <p>Returns 0 on success.</p>
879 <p>Options:</p>
880 <table class="docutils option-list" frame="void" rules="none">
881 <col class="option" />
882 <col class="description" />
883 <tbody valign="top">
884 <tr><td class="option-group" colspan="2">
885 <kbd><span class="option">-A</span>, <span class="option">--accesslog <var>&lt;FILE&gt;</var></span></kbd></td>
886 </tr>
887 <tr><td>&nbsp;</td><td>name of access log file to write to</td></tr>
888 <tr><td class="option-group">
889 <kbd><span class="option">-d</span>, <span class="option">--daemon</span></kbd></td>
890 <td>run server in background</td></tr>
891 <tr><td class="option-group" colspan="2">
892 <kbd><span class="option">--daemon-postexec <var>&lt;VALUE[+]&gt;</var></span></kbd></td>
893 </tr>
894 <tr><td>&nbsp;</td><td>used internally by daemon mode</td></tr>
895 <tr><td class="option-group" colspan="2">
896 <kbd><span class="option">-E</span>, <span class="option">--errorlog <var>&lt;FILE&gt;</var></span></kbd></td>
897 </tr>
898 <tr><td>&nbsp;</td><td>name of error log file to write to</td></tr>
899 <tr><td class="option-group" colspan="2">
900 <kbd><span class="option">-p</span>, <span class="option">--port <var>&lt;PORT&gt;</var></span></kbd></td>
901 </tr>
902 <tr><td>&nbsp;</td><td>port to listen on (default: 8000)</td></tr>
903 <tr><td class="option-group" colspan="2">
904 <kbd><span class="option">-a</span>, <span class="option">--address <var>&lt;ADDR&gt;</var></span></kbd></td>
905 </tr>
906 <tr><td>&nbsp;</td><td>address to listen on (default: all interfaces)</td></tr>
907 <tr><td class="option-group" colspan="2">
908 <kbd><span class="option">--prefix <var>&lt;PREFIX&gt;</var></span></kbd></td>
909 </tr>
910 <tr><td>&nbsp;</td><td>prefix path to serve from (default: server root)</td></tr>
911 <tr><td class="option-group" colspan="2">
912 <kbd><span class="option">-n</span>, <span class="option">--name <var>&lt;NAME&gt;</var></span></kbd></td>
913 </tr>
914 <tr><td>&nbsp;</td><td>name to show in web pages (default: working directory)</td></tr>
915 <tr><td class="option-group" colspan="2">
916 <kbd><span class="option">--web-conf <var>&lt;FILE&gt;</var></span></kbd></td>
917 </tr>
918 <tr><td>&nbsp;</td><td>name of the hgweb config file (see 'hg help hgweb')</td></tr>
919 <tr><td class="option-group" colspan="2">
920 <kbd><span class="option">--webdir-conf <var>&lt;FILE&gt;</var></span></kbd></td>
921 </tr>
922 <tr><td>&nbsp;</td><td>name of the hgweb config file (DEPRECATED)</td></tr>
923 <tr><td class="option-group" colspan="2">
924 <kbd><span class="option">--pid-file <var>&lt;FILE&gt;</var></span></kbd></td>
925 </tr>
926 <tr><td>&nbsp;</td><td>name of file to write process ID to</td></tr>
927 <tr><td class="option-group">
928 <kbd><span class="option">--stdio</span></kbd></td>
929 <td>for remote clients (ADVANCED)</td></tr>
930 <tr><td class="option-group" colspan="2">
931 <kbd><span class="option">--cmdserver <var>&lt;MODE&gt;</var></span></kbd></td>
932 </tr>
933 <tr><td>&nbsp;</td><td>for remote clients (ADVANCED)</td></tr>
934 <tr><td class="option-group" colspan="2">
935 <kbd><span class="option">-t</span>, <span class="option">--templates <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
936 </tr>
937 <tr><td>&nbsp;</td><td>web templates to use</td></tr>
938 <tr><td class="option-group" colspan="2">
939 <kbd><span class="option">--style <var>&lt;STYLE&gt;</var></span></kbd></td>
940 </tr>
941 <tr><td>&nbsp;</td><td>template style to use</td></tr>
942 <tr><td class="option-group">
943 <kbd><span class="option">-6</span>, <span class="option">--ipv6</span></kbd></td>
944 <td>use IPv6 instead of IPv4</td></tr>
945 <tr><td class="option-group" colspan="2">
946 <kbd><span class="option">--certificate <var>&lt;FILE&gt;</var></span></kbd></td>
947 </tr>
948 <tr><td>&nbsp;</td><td>SSL certificate file</td></tr>
949 <tr><td class="option-group">
950 <kbd><span class="option">--print-url</span></kbd></td>
951 <td>start and print only the URL</td></tr>
952 <tr><td class="option-group">
953 <kbd><span class="option">-S</span>, <span class="option">--subrepos</span></kbd></td>
954 <td>recurse into subrepositories</td></tr>
955 </tbody>
956 </table>
957 <p>[+] marked option can be specified multiple times</p>
958 </div>
959 </div>
960 <div class="section" id="change-creation">
961 <h2>Change creation</h2>
962 <div class="section" id="commit">
963 <h3>commit</h3>
964 <p>commit the specified files or all outstanding changes:</p>
965 <pre class="literal-block">
966 hg commit [OPTION]... [FILE]...
967 </pre>
968 <p>Commit changes to the given files into the repository. Unlike a
969 centralized SCM, this operation is a local operation. See
970 <a class="reference external" href="hg.1.html#push"><tt class="docutils literal">hg push</tt></a> for a way to actively distribute your changes.</p>
971 <p>If a list of files is omitted, all changes reported by <a class="reference external" href="hg.1.html#status"><tt class="docutils literal">hg status</tt></a>
972 will be committed.</p>
973 <p>If you are committing the result of a merge, do not provide any
974 filenames or -I/-X filters.</p>
975 <p>If no commit message is specified, Mercurial starts your
976 configured editor where you can enter a message. In case your
977 commit fails, you will find a backup of your message in
978 <tt class="docutils literal"><span class="pre">.hg/last-message.txt</span></tt>.</p>
979 <p>The --close-branch flag can be used to mark the current branch
980 head closed. When all heads of a branch are closed, the branch
981 will be considered closed and no longer listed.</p>
982 <p>The --amend flag can be used to amend the parent of the
983 working directory with a new commit that contains the changes
984 in the parent in addition to those currently reported by <a class="reference external" href="hg.1.html#status"><tt class="docutils literal">hg status</tt></a>,
985 if there are any. The old commit is stored in a backup bundle in
986 <tt class="docutils literal"><span class="pre">.hg/strip-backup</span></tt> (see <a class="reference external" href="hg.1.html#bundle"><tt class="docutils literal">hg help bundle</tt></a> and <a class="reference external" href="hg.1.html#unbundle"><tt class="docutils literal">hg help unbundle</tt></a>
987 on how to restore it).</p>
988 <p>Message, user and date are taken from the amended commit unless
989 specified. When a message isn't specified on the command line,
990 the editor will open with the message of the amended commit.</p>
991 <p>It is not possible to amend public changesets (see <a class="reference external" href="hg.1.html#phases"><tt class="docutils literal">hg help phases</tt></a>)
992 or changesets that have children.</p>
993 <p>See <a class="reference external" href="hg.1.html#dates"><tt class="docutils literal">hg help dates</tt></a> for a list of formats valid for -d/--date.</p>
994 <p>Returns 0 on success, 1 if nothing changed.</p>
995 <div class="verbose docutils container">
996 <p>Examples:</p>
997 <ul>
998 <li><p class="first">commit all files ending in .py:</p>
999 <pre class="literal-block">
1000 hg commit --include &quot;set:**.py&quot;
1001 </pre>
1002 </li>
1003 <li><p class="first">commit all non-binary files:</p>
1004 <pre class="literal-block">
1005 hg commit --exclude &quot;set:binary()&quot;
1006 </pre>
1007 </li>
1008 <li><p class="first">amend the current commit and set the date to now:</p>
1009 <pre class="literal-block">
1010 hg commit --amend --date now
1011 </pre>
1012 </li>
1013 </ul>
1014 </div>
1015 <p>Options:</p>
1016 <table class="docutils option-list" frame="void" rules="none">
1017 <col class="option" />
1018 <col class="description" />
1019 <tbody valign="top">
1020 <tr><td class="option-group" colspan="2">
1021 <kbd><span class="option">-A</span>, <span class="option">--addremove</span></kbd></td>
1022 </tr>
1023 <tr><td>&nbsp;</td><td>mark new/missing files as added/removed before committing</td></tr>
1024 <tr><td class="option-group">
1025 <kbd><span class="option">--close-branch</span></kbd></td>
1026 <td>mark a branch head as closed</td></tr>
1027 <tr><td class="option-group">
1028 <kbd><span class="option">--amend</span></kbd></td>
1029 <td>amend the parent of the working directory</td></tr>
1030 <tr><td class="option-group">
1031 <kbd><span class="option">-s</span>, <span class="option">--secret</span></kbd></td>
1032 <td>use the secret phase for committing</td></tr>
1033 <tr><td class="option-group">
1034 <kbd><span class="option">--draft</span></kbd></td>
1035 <td>use the draft phase for committing</td></tr>
1036 <tr><td class="option-group">
1037 <kbd><span class="option">-e</span>, <span class="option">--edit</span></kbd></td>
1038 <td>invoke editor on commit messages</td></tr>
1039 <tr><td class="option-group" colspan="2">
1040 <kbd><span class="option">--force-close-branch</span></kbd></td>
1041 </tr>
1042 <tr><td>&nbsp;</td><td>forcibly close branch from a non-head changeset (ADVANCED)</td></tr>
1043 <tr><td class="option-group" colspan="2">
1044 <kbd><span class="option">-i</span>, <span class="option">--interactive</span></kbd></td>
1045 </tr>
1046 <tr><td>&nbsp;</td><td>use interactive mode</td></tr>
1047 <tr><td class="option-group" colspan="2">
1048 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
1049 </tr>
1050 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
1051 <tr><td class="option-group" colspan="2">
1052 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
1053 </tr>
1054 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
1055 <tr><td class="option-group" colspan="2">
1056 <kbd><span class="option">-m</span>, <span class="option">--message <var>&lt;TEXT&gt;</var></span></kbd></td>
1057 </tr>
1058 <tr><td>&nbsp;</td><td>use text as commit message</td></tr>
1059 <tr><td class="option-group" colspan="2">
1060 <kbd><span class="option">-l</span>, <span class="option">--logfile <var>&lt;FILE&gt;</var></span></kbd></td>
1061 </tr>
1062 <tr><td>&nbsp;</td><td>read commit message from file</td></tr>
1063 <tr><td class="option-group" colspan="2">
1064 <kbd><span class="option">-d</span>, <span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
1065 </tr>
1066 <tr><td>&nbsp;</td><td>record the specified date as commit date</td></tr>
1067 <tr><td class="option-group" colspan="2">
1068 <kbd><span class="option">-u</span>, <span class="option">--user <var>&lt;USER&gt;</var></span></kbd></td>
1069 </tr>
1070 <tr><td>&nbsp;</td><td>record the specified user as committer</td></tr>
1071 <tr><td class="option-group">
1072 <kbd><span class="option">-S</span>, <span class="option">--subrepos</span></kbd></td>
1073 <td>recurse into subrepositories</td></tr>
1074 </tbody>
1075 </table>
1076 <p>[+] marked option can be specified multiple times</p>
1077 <!-- -->
1078 <blockquote>
1079 aliases: ci</blockquote>
1080 </div>
1081 </div>
1082 <div class="section" id="change-manipulation">
1083 <h2>Change manipulation</h2>
1084 <div class="section" id="abort">
1085 <h3>abort</h3>
1086 <p>abort an unfinished operation (EXPERIMENTAL):</p>
1087 <pre class="literal-block">
1088 hg abort
1089 </pre>
1090 <p>Aborts a multistep operation like graft, histedit, rebase, merge,
1091 and unshelve if they are in an unfinished state.</p>
1092 <p>use --dry-run/-n to dry run the command.</p>
1093 <p>Options:</p>
1094 <table class="docutils option-list" frame="void" rules="none">
1095 <col class="option" />
1096 <col class="description" />
1097 <tbody valign="top">
1098 <tr><td class="option-group">
1099 <kbd><span class="option">-n</span>, <span class="option">--dry-run</span></kbd></td>
1100 <td>do not perform actions, just print output</td></tr>
1101 </tbody>
1102 </table>
1103 </div>
1104 <div class="section" id="backout">
1105 <h3>backout</h3>
1106 <p>reverse effect of earlier changeset:</p>
1107 <pre class="literal-block">
1108 hg backout [OPTION]... [-r] REV
1109 </pre>
1110 <p>Prepare a new changeset with the effect of REV undone in the
1111 current working directory. If no conflicts were encountered,
1112 it will be committed immediately.</p>
1113 <p>If REV is the parent of the working directory, then this new changeset
1114 is committed automatically (unless --no-commit is specified).</p>
1115 <div class="admonition note">
1116 <p class="first admonition-title">Note</p>
1117 <p class="last"><a class="reference external" href="hg.1.html#backout"><tt class="docutils literal">hg backout</tt></a> cannot be used to fix either an unwanted or
1118 incorrect merge.</p>
1119 </div>
1120 <div class="verbose docutils container">
1121 <p>Examples:</p>
1122 <ul>
1123 <li><p class="first">Reverse the effect of the parent of the working directory.
1124 This backout will be committed immediately:</p>
1125 <pre class="literal-block">
1126 hg backout -r .
1127 </pre>
1128 </li>
1129 <li><p class="first">Reverse the effect of previous bad revision 23:</p>
1130 <pre class="literal-block">
1131 hg backout -r 23
1132 </pre>
1133 </li>
1134 <li><p class="first">Reverse the effect of previous bad revision 23 and
1135 leave changes uncommitted:</p>
1136 <pre class="literal-block">
1137 hg backout -r 23 --no-commit
1138 hg commit -m &quot;Backout revision 23&quot;
1139 </pre>
1140 </li>
1141 </ul>
1142 <p>By default, the pending changeset will have one parent,
1143 maintaining a linear history. With --merge, the pending
1144 changeset will instead have two parents: the old parent of the
1145 working directory and a new child of REV that simply undoes REV.</p>
1146 <p>Before version 1.7, the behavior without --merge was equivalent
1147 to specifying --merge followed by <a class="reference external" href="hg.1.html#update"><tt class="docutils literal">hg update <span class="pre">--clean</span> .</tt></a> to
1148 cancel the merge and leave the child of REV as a head to be
1149 merged separately.</p>
1150 </div>
1151 <p>See <a class="reference external" href="hg.1.html#dates"><tt class="docutils literal">hg help dates</tt></a> for a list of formats valid for -d/--date.</p>
1152 <p>See <a class="reference external" href="hg.1.html#revert"><tt class="docutils literal">hg help revert</tt></a> for a way to restore files to the state
1153 of another revision.</p>
1154 <p>Returns 0 on success, 1 if nothing to backout or there are unresolved
1155 files.</p>
1156 <p>Options:</p>
1157 <table class="docutils option-list" frame="void" rules="none">
1158 <col class="option" />
1159 <col class="description" />
1160 <tbody valign="top">
1161 <tr><td class="option-group">
1162 <kbd><span class="option">--merge</span></kbd></td>
1163 <td>merge with old dirstate parent after backout</td></tr>
1164 <tr><td class="option-group">
1165 <kbd><span class="option">--commit</span></kbd></td>
1166 <td>commit if no conflicts were encountered (DEPRECATED)</td></tr>
1167 <tr><td class="option-group">
1168 <kbd><span class="option">--no-commit</span></kbd></td>
1169 <td>do not commit</td></tr>
1170 <tr><td class="option-group">
1171 <kbd><span class="option">--parent <var>&lt;REV&gt;</var></span></kbd></td>
1172 <td>parent to choose when backing out merge (DEPRECATED)</td></tr>
1173 <tr><td class="option-group" colspan="2">
1174 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV&gt;</var></span></kbd></td>
1175 </tr>
1176 <tr><td>&nbsp;</td><td>revision to backout</td></tr>
1177 <tr><td class="option-group">
1178 <kbd><span class="option">-e</span>, <span class="option">--edit</span></kbd></td>
1179 <td>invoke editor on commit messages</td></tr>
1180 <tr><td class="option-group" colspan="2">
1181 <kbd><span class="option">-t</span>, <span class="option">--tool <var>&lt;TOOL&gt;</var></span></kbd></td>
1182 </tr>
1183 <tr><td>&nbsp;</td><td>specify merge tool</td></tr>
1184 <tr><td class="option-group" colspan="2">
1185 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
1186 </tr>
1187 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
1188 <tr><td class="option-group" colspan="2">
1189 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
1190 </tr>
1191 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
1192 <tr><td class="option-group" colspan="2">
1193 <kbd><span class="option">-m</span>, <span class="option">--message <var>&lt;TEXT&gt;</var></span></kbd></td>
1194 </tr>
1195 <tr><td>&nbsp;</td><td>use text as commit message</td></tr>
1196 <tr><td class="option-group" colspan="2">
1197 <kbd><span class="option">-l</span>, <span class="option">--logfile <var>&lt;FILE&gt;</var></span></kbd></td>
1198 </tr>
1199 <tr><td>&nbsp;</td><td>read commit message from file</td></tr>
1200 <tr><td class="option-group" colspan="2">
1201 <kbd><span class="option">-d</span>, <span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
1202 </tr>
1203 <tr><td>&nbsp;</td><td>record the specified date as commit date</td></tr>
1204 <tr><td class="option-group" colspan="2">
1205 <kbd><span class="option">-u</span>, <span class="option">--user <var>&lt;USER&gt;</var></span></kbd></td>
1206 </tr>
1207 <tr><td>&nbsp;</td><td>record the specified user as committer</td></tr>
1208 </tbody>
1209 </table>
1210 <p>[+] marked option can be specified multiple times</p>
1211 </div>
1212 <div class="section" id="continue">
1213 <h3>continue</h3>
1214 <p>resumes an interrupted operation (EXPERIMENTAL):</p>
1215 <pre class="literal-block">
1216 hg continue
1217 </pre>
1218 <p>Finishes a multistep operation like graft, histedit, rebase, merge,
1219 and unshelve if they are in an interrupted state.</p>
1220 <p>use --dry-run/-n to dry run the command.</p>
1221 <p>Options:</p>
1222 <table class="docutils option-list" frame="void" rules="none">
1223 <col class="option" />
1224 <col class="description" />
1225 <tbody valign="top">
1226 <tr><td class="option-group">
1227 <kbd><span class="option">-n</span>, <span class="option">--dry-run</span></kbd></td>
1228 <td>do not perform actions, just print output</td></tr>
1229 </tbody>
1230 </table>
1231 </div>
1232 <div class="section" id="graft">
1233 <h3>graft</h3>
1234 <p>copy changes from other branches onto the current branch:</p>
1235 <pre class="literal-block">
1236 hg graft [OPTION]... [-r REV]... REV...
1237 </pre>
1238 <p>This command uses Mercurial's merge logic to copy individual
1239 changes from other branches without merging branches in the
1240 history graph. This is sometimes known as 'backporting' or
1241 'cherry-picking'. By default, graft will copy user, date, and
1242 description from the source changesets.</p>
1243 <p>Changesets that are ancestors of the current revision, that have
1244 already been grafted, or that are merges will be skipped.</p>
1245 <p>If --log is specified, log messages will have a comment appended
1246 of the form:</p>
1247 <pre class="literal-block">
1248 (grafted from CHANGESETHASH)
1249 </pre>
1250 <p>If --force is specified, revisions will be grafted even if they
1251 are already ancestors of, or have been grafted to, the destination.
1252 This is useful when the revisions have since been backed out.</p>
1253 <p>If a graft merge results in conflicts, the graft process is
1254 interrupted so that the current merge can be manually resolved.
1255 Once all conflicts are addressed, the graft process can be
1256 continued with the -c/--continue option.</p>
1257 <p>The -c/--continue option reapplies all the earlier options.</p>
1258 <div class="verbose docutils container">
1259 <p>The --base option exposes more of how graft internally uses merge with a
1260 custom base revision. --base can be used to specify another ancestor than
1261 the first and only parent.</p>
1262 <p>The command:</p>
1263 <pre class="literal-block">
1264 hg graft -r 345 --base 234
1265 </pre>
1266 <p>is thus pretty much the same as:</p>
1267 <pre class="literal-block">
1268 hg diff --from 234 --to 345 | hg import
1269 </pre>
1270 <p>but using merge to resolve conflicts and track moved files.</p>
1271 <p>The result of a merge can thus be backported as a single commit by
1272 specifying one of the merge parents as base, and thus effectively
1273 grafting the changes from the other side.</p>
1274 <p>It is also possible to collapse multiple changesets and clean up history
1275 by specifying another ancestor as base, much like rebase --collapse
1276 --keep.</p>
1277 <p>The commit message can be tweaked after the fact using commit --amend .</p>
1278 <p>For using non-ancestors as the base to backout changes, see the backout
1279 command and the hidden --parent option.</p>
1280 </div>
1281 <div class="verbose docutils container">
1282 <p>The experimental --to option allows grafting a revision in-memory,
1283 independent of the working copy. Merge conflicts are not currently
1284 supported, and the operation will be aborted if the configured tool
1285 cannot handle the conflicts that might be encountered.</p>
1286 <p>As the operation is performed in-memory, the on-disk files will not be
1287 modified, and some hooks might not be run.</p>
1288 </div>
1289 <div class="verbose docutils container">
1290 <p>Examples:</p>
1291 <ul>
1292 <li><p class="first">copy a single change to the stable branch and edit its description:</p>
1293 <pre class="literal-block">
1294 hg update stable
1295 hg graft --edit 9393
1296 </pre>
1297 </li>
1298 <li><p class="first">graft a range of changesets with one exception, updating dates:</p>
1299 <pre class="literal-block">
1300 hg graft -D &quot;2085::2093 and not 2091&quot;
1301 </pre>
1302 </li>
1303 <li><p class="first">continue a graft after resolving conflicts:</p>
1304 <pre class="literal-block">
1305 hg graft -c
1306 </pre>
1307 </li>
1308 <li><p class="first">show the source of a grafted changeset:</p>
1309 <pre class="literal-block">
1310 hg log --debug -r .
1311 </pre>
1312 </li>
1313 <li><p class="first">show revisions sorted by date:</p>
1314 <pre class="literal-block">
1315 hg log -r &quot;sort(all(), date)&quot;
1316 </pre>
1317 </li>
1318 <li><p class="first">backport the result of a merge as a single commit:</p>
1319 <pre class="literal-block">
1320 hg graft -r 123 --base 123^
1321 </pre>
1322 </li>
1323 <li><p class="first">land a feature branch as one changeset:</p>
1324 <pre class="literal-block">
1325 hg up -cr default
1326 hg graft -r featureX --base &quot;ancestor('featureX', 'default')&quot;
1327 </pre>
1328 </li>
1329 </ul>
1330 </div>
1331 <p>See <a class="reference external" href="hg.1.html#revisions"><tt class="docutils literal">hg help revisions</tt></a> for more about specifying revisions.</p>
1332 <p>Returns 0 on successful completion, 1 if there are unresolved files.</p>
1333 <p>Options:</p>
1334 <table class="docutils option-list" frame="void" rules="none">
1335 <col class="option" />
1336 <col class="description" />
1337 <tbody valign="top">
1338 <tr><td class="option-group" colspan="2">
1339 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
1340 </tr>
1341 <tr><td>&nbsp;</td><td>revisions to graft</td></tr>
1342 <tr><td class="option-group">
1343 <kbd><span class="option">--base <var>&lt;REV&gt;</var></span></kbd></td>
1344 <td>base revision when doing the graft merge (ADVANCED)</td></tr>
1345 <tr><td class="option-group">
1346 <kbd><span class="option">--to <var>&lt;VALUE&gt;</var></span></kbd></td>
1347 <td>graft to this destination, in-memory (EXPERIMENTAL)</td></tr>
1348 <tr><td class="option-group">
1349 <kbd><span class="option">-c</span>, <span class="option">--continue</span></kbd></td>
1350 <td>resume interrupted graft</td></tr>
1351 <tr><td class="option-group">
1352 <kbd><span class="option">--stop</span></kbd></td>
1353 <td>stop interrupted graft</td></tr>
1354 <tr><td class="option-group">
1355 <kbd><span class="option">--abort</span></kbd></td>
1356 <td>abort interrupted graft</td></tr>
1357 <tr><td class="option-group">
1358 <kbd><span class="option">-e</span>, <span class="option">--edit</span></kbd></td>
1359 <td>invoke editor on commit messages</td></tr>
1360 <tr><td class="option-group">
1361 <kbd><span class="option">--log</span></kbd></td>
1362 <td>append graft info to log message</td></tr>
1363 <tr><td class="option-group">
1364 <kbd><span class="option">--no-commit</span></kbd></td>
1365 <td>don't commit, just apply the changes in working directory</td></tr>
1366 <tr><td class="option-group">
1367 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
1368 <td>force graft</td></tr>
1369 <tr><td class="option-group" colspan="2">
1370 <kbd><span class="option">-D</span>, <span class="option">--currentdate</span></kbd></td>
1371 </tr>
1372 <tr><td>&nbsp;</td><td>record the current date as commit date</td></tr>
1373 <tr><td class="option-group" colspan="2">
1374 <kbd><span class="option">-U</span>, <span class="option">--currentuser</span></kbd></td>
1375 </tr>
1376 <tr><td>&nbsp;</td><td>record the current user as committer</td></tr>
1377 <tr><td class="option-group" colspan="2">
1378 <kbd><span class="option">-d</span>, <span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
1379 </tr>
1380 <tr><td>&nbsp;</td><td>record the specified date as commit date</td></tr>
1381 <tr><td class="option-group" colspan="2">
1382 <kbd><span class="option">-u</span>, <span class="option">--user <var>&lt;USER&gt;</var></span></kbd></td>
1383 </tr>
1384 <tr><td>&nbsp;</td><td>record the specified user as committer</td></tr>
1385 <tr><td class="option-group" colspan="2">
1386 <kbd><span class="option">-t</span>, <span class="option">--tool <var>&lt;TOOL&gt;</var></span></kbd></td>
1387 </tr>
1388 <tr><td>&nbsp;</td><td>specify merge tool</td></tr>
1389 <tr><td class="option-group">
1390 <kbd><span class="option">-n</span>, <span class="option">--dry-run</span></kbd></td>
1391 <td>do not perform actions, just print output</td></tr>
1392 </tbody>
1393 </table>
1394 <p>[+] marked option can be specified multiple times</p>
1395 </div>
1396 <div class="section" id="merge">
1397 <h3>merge</h3>
1398 <p>merge another revision into working directory:</p>
1399 <pre class="literal-block">
1400 hg merge [-P] [[-r] REV]
1401 </pre>
1402 <p>The current working directory is updated with all changes made in
1403 the requested revision since the last common predecessor revision.</p>
1404 <p>Files that changed between either parent are marked as changed for
1405 the next commit and a commit must be performed before any further
1406 updates to the repository are allowed. The next commit will have
1407 two parents.</p>
1408 <p><tt class="docutils literal"><span class="pre">--tool</span></tt> can be used to specify the merge tool used for file
1409 merges. It overrides the HGMERGE environment variable and your
1410 configuration files. See <a class="reference external" href="hg.1.html#merge-tools"><tt class="docutils literal">hg help <span class="pre">merge-tools</span></tt></a> for options.</p>
1411 <p>If no revision is specified, the working directory's parent is a
1412 head revision, and the current branch contains exactly one other
1413 head, the other head is merged with by default. Otherwise, an
1414 explicit revision with which to merge must be provided.</p>
1415 <p>See <a class="reference external" href="hg.1.html#resolve"><tt class="docutils literal">hg help resolve</tt></a> for information on handling file conflicts.</p>
1416 <p>To undo an uncommitted merge, use <a class="reference external" href="hg.1.html#merge"><tt class="docutils literal">hg merge <span class="pre">--abort</span></tt></a> which
1417 will check out a clean copy of the original merge parent, losing
1418 all changes.</p>
1419 <p>Returns 0 on success, 1 if there are unresolved files.</p>
1420 <p>Options:</p>
1421 <table class="docutils option-list" frame="void" rules="none">
1422 <col class="option" />
1423 <col class="description" />
1424 <tbody valign="top">
1425 <tr><td class="option-group">
1426 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
1427 <td>force a merge including outstanding changes (DEPRECATED)</td></tr>
1428 <tr><td class="option-group" colspan="2">
1429 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV&gt;</var></span></kbd></td>
1430 </tr>
1431 <tr><td>&nbsp;</td><td>revision to merge</td></tr>
1432 <tr><td class="option-group">
1433 <kbd><span class="option">-P</span>, <span class="option">--preview</span></kbd></td>
1434 <td>review revisions to merge (no merge is performed)</td></tr>
1435 <tr><td class="option-group">
1436 <kbd><span class="option">--abort</span></kbd></td>
1437 <td>abort the ongoing merge</td></tr>
1438 <tr><td class="option-group" colspan="2">
1439 <kbd><span class="option">-t</span>, <span class="option">--tool <var>&lt;TOOL&gt;</var></span></kbd></td>
1440 </tr>
1441 <tr><td>&nbsp;</td><td>specify merge tool</td></tr>
1442 </tbody>
1443 </table>
1444 </div>
1445 </div>
1446 <div class="section" id="change-organization">
1447 <h2>Change organization</h2>
1448 <div class="section" id="bookmarks">
1449 <h3>bookmarks</h3>
1450 <p>create a new bookmark or list existing bookmarks:</p>
1451 <pre class="literal-block">
1452 hg bookmarks [OPTIONS]... [NAME]...
1453 </pre>
1454 <p>Bookmarks are labels on changesets to help track lines of development.
1455 Bookmarks are unversioned and can be moved, renamed and deleted.
1456 Deleting or moving a bookmark has no effect on the associated changesets.</p>
1457 <p>Creating or updating to a bookmark causes it to be marked as 'active'.
1458 The active bookmark is indicated with a '*'.
1459 When a commit is made, the active bookmark will advance to the new commit.
1460 A plain <a class="reference external" href="hg.1.html#update"><tt class="docutils literal">hg update</tt></a> will also advance an active bookmark, if possible.
1461 Updating away from a bookmark will cause it to be deactivated.</p>
1462 <p>Bookmarks can be pushed and pulled between repositories (see
1463 <a class="reference external" href="hg.1.html#push"><tt class="docutils literal">hg help push</tt></a> and <a class="reference external" href="hg.1.html#pull"><tt class="docutils literal">hg help pull</tt></a>). If a shared bookmark has
1464 diverged, a new 'divergent bookmark' of the form <a class="reference external" href="mailto:'name&#64;path">'name&#64;path</a>' will
1465 be created. Using <a class="reference external" href="hg.1.html#merge"><tt class="docutils literal">hg merge</tt></a> will resolve the divergence.</p>
1466 <p>Specifying bookmark as '.' to -m/-d/-l options is equivalent to specifying
1467 the active bookmark's name.</p>
1468 <p>A bookmark named '&#64;' has the special property that <a class="reference external" href="hg.1.html#clone"><tt class="docutils literal">hg clone</tt></a> will
1469 check it out by default if it exists.</p>
1470 <div class="verbose docutils container">
1471 <p>Template:</p>
1472 <p>The following keywords are supported in addition to the common template
1473 keywords and functions such as <tt class="docutils literal">{bookmark}</tt>. See also
1474 <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help templates</tt></a>.</p>
1475 <table class="docutils field-list" frame="void" rules="none">
1476 <col class="field-name" />
1477 <col class="field-body" />
1478 <tbody valign="top">
1479 <tr class="field"><th class="field-name">active:</th><td class="field-body">Boolean. True if the bookmark is active.</td>
1480 </tr>
1481 </tbody>
1482 </table>
1483 <p>Examples:</p>
1484 <ul>
1485 <li><p class="first">create an active bookmark for a new line of development:</p>
1486 <pre class="literal-block">
1487 hg book new-feature
1488 </pre>
1489 </li>
1490 <li><p class="first">create an inactive bookmark as a place marker:</p>
1491 <pre class="literal-block">
1492 hg book -i reviewed
1493 </pre>
1494 </li>
1495 <li><p class="first">create an inactive bookmark on another changeset:</p>
1496 <pre class="literal-block">
1497 hg book -r .^ tested
1498 </pre>
1499 </li>
1500 <li><p class="first">rename bookmark turkey to dinner:</p>
1501 <pre class="literal-block">
1502 hg book -m turkey dinner
1503 </pre>
1504 </li>
1505 <li><p class="first">move the '&#64;' bookmark from another branch:</p>
1506 <pre class="literal-block">
1507 hg book -f &#64;
1508 </pre>
1509 </li>
1510 <li><p class="first">print only the active bookmark name:</p>
1511 <pre class="literal-block">
1512 hg book -ql .
1513 </pre>
1514 </li>
1515 </ul>
1516 </div>
1517 <p>Options:</p>
1518 <table class="docutils option-list" frame="void" rules="none">
1519 <col class="option" />
1520 <col class="description" />
1521 <tbody valign="top">
1522 <tr><td class="option-group">
1523 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
1524 <td>force</td></tr>
1525 <tr><td class="option-group" colspan="2">
1526 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV&gt;</var></span></kbd></td>
1527 </tr>
1528 <tr><td>&nbsp;</td><td>revision for bookmark action</td></tr>
1529 <tr><td class="option-group">
1530 <kbd><span class="option">-d</span>, <span class="option">--delete</span></kbd></td>
1531 <td>delete a given bookmark</td></tr>
1532 <tr><td class="option-group" colspan="2">
1533 <kbd><span class="option">-m</span>, <span class="option">--rename <var>&lt;OLD&gt;</var></span></kbd></td>
1534 </tr>
1535 <tr><td>&nbsp;</td><td>rename a given bookmark</td></tr>
1536 <tr><td class="option-group">
1537 <kbd><span class="option">-i</span>, <span class="option">--inactive</span></kbd></td>
1538 <td>mark a bookmark inactive</td></tr>
1539 <tr><td class="option-group">
1540 <kbd><span class="option">-l</span>, <span class="option">--list</span></kbd></td>
1541 <td>list existing bookmarks</td></tr>
1542 <tr><td class="option-group" colspan="2">
1543 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
1544 </tr>
1545 <tr><td>&nbsp;</td><td>display with template</td></tr>
1546 </tbody>
1547 </table>
1548 <!-- -->
1549 <blockquote>
1550 aliases: bookmark</blockquote>
1551 </div>
1552 <div class="section" id="branch">
1553 <h3>branch</h3>
1554 <p>set or show the current branch name:</p>
1555 <pre class="literal-block">
1556 hg branch [-fC] [NAME]
1557 </pre>
1558 <div class="admonition note">
1559 <p class="first admonition-title">Note</p>
1560 <p class="last">Branch names are permanent and global. Use <a class="reference external" href="hg.1.html#bookmark"><tt class="docutils literal">hg bookmark</tt></a> to create a
1561 light-weight bookmark instead. See <a class="reference external" href="hg.1.html#glossary"><tt class="docutils literal">hg help glossary</tt></a> for more
1562 information about named branches and bookmarks.</p>
1563 </div>
1564 <p>With no argument, show the current branch name. With one argument,
1565 set the working directory branch name (the branch will not exist
1566 in the repository until the next commit). Standard practice
1567 recommends that primary development take place on the 'default'
1568 branch.</p>
1569 <p>Unless -f/--force is specified, branch will not let you set a
1570 branch name that already exists.</p>
1571 <p>Use -C/--clean to reset the working directory branch to that of
1572 the parent of the working directory, negating a previous branch
1573 change.</p>
1574 <p>Use the command <a class="reference external" href="hg.1.html#update"><tt class="docutils literal">hg update</tt></a> to switch to an existing branch. Use
1575 <a class="reference external" href="hg.1.html#commit"><tt class="docutils literal">hg commit <span class="pre">--close-branch</span></tt></a> to mark this branch head as closed.
1576 When all heads of a branch are closed, the branch will be
1577 considered closed.</p>
1578 <p>Returns 0 on success.</p>
1579 <p>Options:</p>
1580 <table class="docutils option-list" frame="void" rules="none">
1581 <col class="option" />
1582 <col class="description" />
1583 <tbody valign="top">
1584 <tr><td class="option-group">
1585 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
1586 <td>set branch name even if it shadows an existing branch</td></tr>
1587 <tr><td class="option-group">
1588 <kbd><span class="option">-C</span>, <span class="option">--clean</span></kbd></td>
1589 <td>reset branch name to parent branch name</td></tr>
1590 <tr><td class="option-group" colspan="2">
1591 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;VALUE[+]&gt;</var></span></kbd></td>
1592 </tr>
1593 <tr><td>&nbsp;</td><td>change branches of the given revs (EXPERIMENTAL)</td></tr>
1594 </tbody>
1595 </table>
1596 <p>[+] marked option can be specified multiple times</p>
1597 </div>
1598 <div class="section" id="branches">
1599 <h3>branches</h3>
1600 <p>list repository named branches:</p>
1601 <pre class="literal-block">
1602 hg branches [-c]
1603 </pre>
1604 <p>List the repository's named branches, indicating which ones are
1605 inactive. If -c/--closed is specified, also list branches which have
1606 been marked closed (see <a class="reference external" href="hg.1.html#commit"><tt class="docutils literal">hg commit <span class="pre">--close-branch</span></tt></a>).</p>
1607 <p>Use the command <a class="reference external" href="hg.1.html#update"><tt class="docutils literal">hg update</tt></a> to switch to an existing branch.</p>
1608 <div class="verbose docutils container">
1609 <p>Template:</p>
1610 <p>The following keywords are supported in addition to the common template
1611 keywords and functions such as <tt class="docutils literal">{branch}</tt>. See also
1612 <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help templates</tt></a>.</p>
1613 <table class="docutils field-list" frame="void" rules="none">
1614 <col class="field-name" />
1615 <col class="field-body" />
1616 <tbody valign="top">
1617 <tr class="field"><th class="field-name">active:</th><td class="field-body">Boolean. True if the branch is active.</td>
1618 </tr>
1619 <tr class="field"><th class="field-name">closed:</th><td class="field-body">Boolean. True if the branch is closed.</td>
1620 </tr>
1621 <tr class="field"><th class="field-name">current:</th><td class="field-body">Boolean. True if it is the current branch.</td>
1622 </tr>
1623 </tbody>
1624 </table>
1625 </div>
1626 <p>Returns 0.</p>
1627 <p>Options:</p>
1628 <table class="docutils option-list" frame="void" rules="none">
1629 <col class="option" />
1630 <col class="description" />
1631 <tbody valign="top">
1632 <tr><td class="option-group">
1633 <kbd><span class="option">-a</span>, <span class="option">--active</span></kbd></td>
1634 <td>show only branches that have unmerged heads (DEPRECATED)</td></tr>
1635 <tr><td class="option-group">
1636 <kbd><span class="option">-c</span>, <span class="option">--closed</span></kbd></td>
1637 <td>show normal and closed branches</td></tr>
1638 <tr><td class="option-group" colspan="2">
1639 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;VALUE[+]&gt;</var></span></kbd></td>
1640 </tr>
1641 <tr><td>&nbsp;</td><td>show branch name(s) of the given rev</td></tr>
1642 <tr><td class="option-group" colspan="2">
1643 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
1644 </tr>
1645 <tr><td>&nbsp;</td><td>display with template</td></tr>
1646 </tbody>
1647 </table>
1648 <p>[+] marked option can be specified multiple times</p>
1649 </div>
1650 <div class="section" id="phase">
1651 <h3>phase</h3>
1652 <p>set or show the current phase name:</p>
1653 <pre class="literal-block">
1654 hg phase [-p|-d|-s] [-f] [-r] [REV...]
1655 </pre>
1656 <p>With no argument, show the phase name of the current revision(s).</p>
1657 <p>With one of -p/--public, -d/--draft or -s/--secret, change the
1658 phase value of the specified revisions.</p>
1659 <p>Unless -f/--force is specified, <a class="reference external" href="hg.1.html#phase"><tt class="docutils literal">hg phase</tt></a> won't move changesets from a
1660 lower phase to a higher phase. Phases are ordered as follows:</p>
1661 <pre class="literal-block">
1662 public &lt; draft &lt; secret
1663 </pre>
1664 <p>Returns 0 on success, 1 if some phases could not be changed.</p>
1665 <p>(For more information about the phases concept, see <a class="reference external" href="hg.1.html#phases"><tt class="docutils literal">hg help phases</tt></a>.)</p>
1666 <p>Options:</p>
1667 <table class="docutils option-list" frame="void" rules="none">
1668 <col class="option" />
1669 <col class="description" />
1670 <tbody valign="top">
1671 <tr><td class="option-group">
1672 <kbd><span class="option">-p</span>, <span class="option">--public</span></kbd></td>
1673 <td>set changeset phase to public</td></tr>
1674 <tr><td class="option-group">
1675 <kbd><span class="option">-d</span>, <span class="option">--draft</span></kbd></td>
1676 <td>set changeset phase to draft</td></tr>
1677 <tr><td class="option-group">
1678 <kbd><span class="option">-s</span>, <span class="option">--secret</span></kbd></td>
1679 <td>set changeset phase to secret</td></tr>
1680 <tr><td class="option-group">
1681 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
1682 <td>allow to move boundary backward</td></tr>
1683 <tr><td class="option-group" colspan="2">
1684 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
1685 </tr>
1686 <tr><td>&nbsp;</td><td>target revision</td></tr>
1687 </tbody>
1688 </table>
1689 <p>[+] marked option can be specified multiple times</p>
1690 </div>
1691 <div class="section" id="tag">
1692 <h3>tag</h3>
1693 <p>add one or more tags for the current or given revision:</p>
1694 <pre class="literal-block">
1695 hg tag [-f] [-l] [-m TEXT] [-d DATE] [-u USER] [-r REV] NAME...
1696 </pre>
1697 <p>Name a particular revision using &lt;name&gt;.</p>
1698 <p>Tags are used to name particular revisions of the repository and are
1699 very useful to compare different revisions, to go back to significant
1700 earlier versions or to mark branch points as releases, etc. Changing
1701 an existing tag is normally disallowed; use -f/--force to override.</p>
1702 <p>If no revision is given, the parent of the working directory is
1703 used.</p>
1704 <p>To facilitate version control, distribution, and merging of tags,
1705 they are stored as a file named &quot;.hgtags&quot; which is managed similarly
1706 to other project files and can be hand-edited if necessary. This
1707 also means that tagging creates a new commit. The file
1708 &quot;.hg/localtags&quot; is used for local tags (not shared among
1709 repositories).</p>
1710 <p>Tag commits are usually made at the head of a branch. If the parent
1711 of the working directory is not a branch head, <a class="reference external" href="hg.1.html#tag"><tt class="docutils literal">hg tag</tt></a> aborts; use
1712 -f/--force to force the tag commit to be based on a non-head
1713 changeset.</p>
1714 <p>See <a class="reference external" href="hg.1.html#dates"><tt class="docutils literal">hg help dates</tt></a> for a list of formats valid for -d/--date.</p>
1715 <p>Since tag names have priority over branch names during revision
1716 lookup, using an existing branch name as a tag name is discouraged.</p>
1717 <p>Returns 0 on success.</p>
1718 <p>Options:</p>
1719 <table class="docutils option-list" frame="void" rules="none">
1720 <col class="option" />
1721 <col class="description" />
1722 <tbody valign="top">
1723 <tr><td class="option-group">
1724 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
1725 <td>force tag</td></tr>
1726 <tr><td class="option-group">
1727 <kbd><span class="option">-l</span>, <span class="option">--local</span></kbd></td>
1728 <td>make the tag local</td></tr>
1729 <tr><td class="option-group" colspan="2">
1730 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV&gt;</var></span></kbd></td>
1731 </tr>
1732 <tr><td>&nbsp;</td><td>revision to tag</td></tr>
1733 <tr><td class="option-group">
1734 <kbd><span class="option">--remove</span></kbd></td>
1735 <td>remove a tag</td></tr>
1736 <tr><td class="option-group">
1737 <kbd><span class="option">-e</span>, <span class="option">--edit</span></kbd></td>
1738 <td>invoke editor on commit messages</td></tr>
1739 <tr><td class="option-group" colspan="2">
1740 <kbd><span class="option">-m</span>, <span class="option">--message <var>&lt;TEXT&gt;</var></span></kbd></td>
1741 </tr>
1742 <tr><td>&nbsp;</td><td>use text as commit message</td></tr>
1743 <tr><td class="option-group" colspan="2">
1744 <kbd><span class="option">-d</span>, <span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
1745 </tr>
1746 <tr><td>&nbsp;</td><td>record the specified date as commit date</td></tr>
1747 <tr><td class="option-group" colspan="2">
1748 <kbd><span class="option">-u</span>, <span class="option">--user <var>&lt;USER&gt;</var></span></kbd></td>
1749 </tr>
1750 <tr><td>&nbsp;</td><td>record the specified user as committer</td></tr>
1751 </tbody>
1752 </table>
1753 </div>
1754 <div class="section" id="tags">
1755 <h3>tags</h3>
1756 <p>list repository tags:</p>
1757 <pre class="literal-block">
1758 hg tags
1759 </pre>
1760 <p>This lists both regular and local tags. When the -v/--verbose
1761 switch is used, a third column &quot;local&quot; is printed for local tags.
1762 When the -q/--quiet switch is used, only the tag name is printed.</p>
1763 <div class="verbose docutils container">
1764 <p>Template:</p>
1765 <p>The following keywords are supported in addition to the common template
1766 keywords and functions such as <tt class="docutils literal">{tag}</tt>. See also
1767 <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help templates</tt></a>.</p>
1768 <table class="docutils field-list" frame="void" rules="none">
1769 <col class="field-name" />
1770 <col class="field-body" />
1771 <tbody valign="top">
1772 <tr class="field"><th class="field-name">type:</th><td class="field-body">String. <tt class="docutils literal">local</tt> for local tags.</td>
1773 </tr>
1774 </tbody>
1775 </table>
1776 </div>
1777 <p>Returns 0 on success.</p>
1778 <p>Options:</p>
1779 <table class="docutils option-list" frame="void" rules="none">
1780 <col class="option" />
1781 <col class="description" />
1782 <tbody valign="top">
1783 <tr><td class="option-group" colspan="2">
1784 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
1785 </tr>
1786 <tr><td>&nbsp;</td><td>display with template</td></tr>
1787 </tbody>
1788 </table>
1789 </div>
1790 </div>
1791 <div class="section" id="file-content-management">
1792 <h2>File content management</h2>
1793 <div class="section" id="annotate">
1794 <h3>annotate</h3>
1795 <p>show changeset information by line for each file:</p>
1796 <pre class="literal-block">
1797 hg annotate [-r REV] [-f] [-a] [-u] [-d] [-n] [-c] [-l] FILE...
1798 </pre>
1799 <p>List changes in files, showing the revision id responsible for
1800 each line.</p>
1801 <p>This command is useful for discovering when a change was made and
1802 by whom.</p>
1803 <p>If you include --file, --user, or --date, the revision number is
1804 suppressed unless you also include --number.</p>
1805 <p>Without the -a/--text option, annotate will avoid processing files
1806 it detects as binary. With -a, annotate will annotate the file
1807 anyway, although the results will probably be neither useful
1808 nor desirable.</p>
1809 <div class="verbose docutils container">
1810 Use -L/--line-range FILE,M:N options to filter the output to the lines
1811 from M to N in FILE. This option is incompatible with --no-follow and
1812 cannot be combined with file pattern arguments. When combined with --rev
1813 the line ranges refer to the state of the file at the requested revision.</div>
1814 <div class="verbose docutils container">
1815 <p>Template:</p>
1816 <p>The following keywords are supported in addition to the common template
1817 keywords and functions. See also <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help templates</tt></a>.</p>
1818 <table class="docutils field-list" frame="void" rules="none">
1819 <col class="field-name" />
1820 <col class="field-body" />
1821 <tbody valign="top">
1822 <tr class="field"><th class="field-name">lines:</th><td class="field-body">List of lines with annotation data.</td>
1823 </tr>
1824 <tr class="field"><th class="field-name">path:</th><td class="field-body">String. Repository-absolute path of the specified file.</td>
1825 </tr>
1826 </tbody>
1827 </table>
1828 <p>And each entry of <tt class="docutils literal">{lines}</tt> provides the following sub-keywords in
1829 addition to <tt class="docutils literal">{date}</tt>, <tt class="docutils literal">{node}</tt>, <tt class="docutils literal">{rev}</tt>, <tt class="docutils literal">{user}</tt>, etc.</p>
1830 <table class="docutils field-list" frame="void" rules="none">
1831 <col class="field-name" />
1832 <col class="field-body" />
1833 <tbody valign="top">
1834 <tr class="field"><th class="field-name">line:</th><td class="field-body">String. Line content.</td>
1835 </tr>
1836 <tr class="field"><th class="field-name">lineno:</th><td class="field-body">Integer. Line number at that revision.</td>
1837 </tr>
1838 <tr class="field"><th class="field-name">path:</th><td class="field-body">String. Repository-absolute path of the file at that revision.</td>
1839 </tr>
1840 </tbody>
1841 </table>
1842 <p>See <a class="reference external" href="hg.1.html#templates.operators"><tt class="docutils literal">hg help templates.operators</tt></a> for the list expansion syntax.</p>
1843 </div>
1844 <p>Returns 0 on success.</p>
1845 <p>Options:</p>
1846 <table class="docutils option-list" frame="void" rules="none">
1847 <col class="option" />
1848 <col class="description" />
1849 <tbody valign="top">
1850 <tr><td class="option-group" colspan="2">
1851 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV&gt;</var></span></kbd></td>
1852 </tr>
1853 <tr><td>&nbsp;</td><td>annotate the specified revision</td></tr>
1854 <tr><td class="option-group">
1855 <kbd><span class="option">--follow</span></kbd></td>
1856 <td>follow copies/renames and list the filename (DEPRECATED)</td></tr>
1857 <tr><td class="option-group">
1858 <kbd><span class="option">--no-follow</span></kbd></td>
1859 <td>don't follow copies and renames</td></tr>
1860 <tr><td class="option-group">
1861 <kbd><span class="option">-a</span>, <span class="option">--text</span></kbd></td>
1862 <td>treat all files as text</td></tr>
1863 <tr><td class="option-group">
1864 <kbd><span class="option">-u</span>, <span class="option">--user</span></kbd></td>
1865 <td>list the author (long with -v)</td></tr>
1866 <tr><td class="option-group">
1867 <kbd><span class="option">-f</span>, <span class="option">--file</span></kbd></td>
1868 <td>list the filename</td></tr>
1869 <tr><td class="option-group">
1870 <kbd><span class="option">-d</span>, <span class="option">--date</span></kbd></td>
1871 <td>list the date (short with -q)</td></tr>
1872 <tr><td class="option-group">
1873 <kbd><span class="option">-n</span>, <span class="option">--number</span></kbd></td>
1874 <td>list the revision number (default)</td></tr>
1875 <tr><td class="option-group" colspan="2">
1876 <kbd><span class="option">-c</span>, <span class="option">--changeset</span></kbd></td>
1877 </tr>
1878 <tr><td>&nbsp;</td><td>list the changeset</td></tr>
1879 <tr><td class="option-group" colspan="2">
1880 <kbd><span class="option">-l</span>, <span class="option">--line-number</span></kbd></td>
1881 </tr>
1882 <tr><td>&nbsp;</td><td>show line number at the first appearance</td></tr>
1883 <tr><td class="option-group" colspan="2">
1884 <kbd><span class="option">--skip <var>&lt;REV[+]&gt;</var></span></kbd></td>
1885 </tr>
1886 <tr><td>&nbsp;</td><td>revset to not display (EXPERIMENTAL)</td></tr>
1887 <tr><td class="option-group" colspan="2">
1888 <kbd><span class="option">-L</span>, <span class="option">--line-range <var>&lt;FILE,RANGE[+]&gt;</var></span></kbd></td>
1889 </tr>
1890 <tr><td>&nbsp;</td><td>follow line range of specified file (EXPERIMENTAL)</td></tr>
1891 <tr><td class="option-group" colspan="2">
1892 <kbd><span class="option">-w</span>, <span class="option">--ignore-all-space</span></kbd></td>
1893 </tr>
1894 <tr><td>&nbsp;</td><td>ignore white space when comparing lines</td></tr>
1895 <tr><td class="option-group" colspan="2">
1896 <kbd><span class="option">-b</span>, <span class="option">--ignore-space-change</span></kbd></td>
1897 </tr>
1898 <tr><td>&nbsp;</td><td>ignore changes in the amount of white space</td></tr>
1899 <tr><td class="option-group" colspan="2">
1900 <kbd><span class="option">-B</span>, <span class="option">--ignore-blank-lines</span></kbd></td>
1901 </tr>
1902 <tr><td>&nbsp;</td><td>ignore changes whose lines are all blank</td></tr>
1903 <tr><td class="option-group" colspan="2">
1904 <kbd><span class="option">-Z</span>, <span class="option">--ignore-space-at-eol</span></kbd></td>
1905 </tr>
1906 <tr><td>&nbsp;</td><td>ignore changes in whitespace at EOL</td></tr>
1907 <tr><td class="option-group" colspan="2">
1908 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
1909 </tr>
1910 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
1911 <tr><td class="option-group" colspan="2">
1912 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
1913 </tr>
1914 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
1915 <tr><td class="option-group" colspan="2">
1916 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
1917 </tr>
1918 <tr><td>&nbsp;</td><td>display with template</td></tr>
1919 </tbody>
1920 </table>
1921 <p>[+] marked option can be specified multiple times</p>
1922 <!-- -->
1923 <blockquote>
1924 aliases: blame</blockquote>
1925 </div>
1926 <div class="section" id="cat">
1927 <h3>cat</h3>
1928 <p>output the current or given revision of files:</p>
1929 <pre class="literal-block">
1930 hg cat [OPTION]... FILE...
1931 </pre>
1932 <p>Print the specified files as they were at the given revision. If
1933 no revision is given, the parent of the working directory is used.</p>
1934 <p>Output may be to a file, in which case the name of the file is
1935 given using a template string. See <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help templates</tt></a>. In addition
1936 to the common template keywords, the following formatting rules are
1937 supported:</p>
1938 <table class="docutils field-list" frame="void" rules="none">
1939 <col class="field-name" />
1940 <col class="field-body" />
1941 <tbody valign="top">
1942 <tr class="field"><th class="field-name"><tt class="docutils literal">%%</tt>:</th><td class="field-body">literal &quot;%&quot; character</td>
1943 </tr>
1944 <tr class="field"><th class="field-name"><tt class="docutils literal">%s</tt>:</th><td class="field-body">basename of file being printed</td>
1945 </tr>
1946 <tr class="field"><th class="field-name"><tt class="docutils literal">%d</tt>:</th><td class="field-body">dirname of file being printed, or '.' if in repository root</td>
1947 </tr>
1948 <tr class="field"><th class="field-name"><tt class="docutils literal">%p</tt>:</th><td class="field-body">root-relative path name of file being printed</td>
1949 </tr>
1950 <tr class="field"><th class="field-name"><tt class="docutils literal">%H</tt>:</th><td class="field-body">changeset hash (40 hexadecimal digits)</td>
1951 </tr>
1952 <tr class="field"><th class="field-name"><tt class="docutils literal">%R</tt>:</th><td class="field-body">changeset revision number</td>
1953 </tr>
1954 <tr class="field"><th class="field-name"><tt class="docutils literal">%h</tt>:</th><td class="field-body">short-form changeset hash (12 hexadecimal digits)</td>
1955 </tr>
1956 <tr class="field"><th class="field-name"><tt class="docutils literal">%r</tt>:</th><td class="field-body">zero-padded changeset revision number</td>
1957 </tr>
1958 <tr class="field"><th class="field-name"><tt class="docutils literal">%b</tt>:</th><td class="field-body">basename of the exporting repository</td>
1959 </tr>
1960 <tr class="field"><th class="field-name"><tt class="docutils literal">\</tt>:</th><td class="field-body">literal &quot;&quot; character</td>
1961 </tr>
1962 </tbody>
1963 </table>
1964 <div class="verbose docutils container">
1965 <p>Template:</p>
1966 <p>The following keywords are supported in addition to the common template
1967 keywords and functions. See also <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help templates</tt></a>.</p>
1968 <table class="docutils field-list" frame="void" rules="none">
1969 <col class="field-name" />
1970 <col class="field-body" />
1971 <tbody valign="top">
1972 <tr class="field"><th class="field-name">data:</th><td class="field-body">String. File content.</td>
1973 </tr>
1974 <tr class="field"><th class="field-name">path:</th><td class="field-body">String. Repository-absolute path of the file.</td>
1975 </tr>
1976 </tbody>
1977 </table>
1978 </div>
1979 <p>Returns 0 on success.</p>
1980 <p>Options:</p>
1981 <table class="docutils option-list" frame="void" rules="none">
1982 <col class="option" />
1983 <col class="description" />
1984 <tbody valign="top">
1985 <tr><td class="option-group" colspan="2">
1986 <kbd><span class="option">-o</span>, <span class="option">--output <var>&lt;FORMAT&gt;</var></span></kbd></td>
1987 </tr>
1988 <tr><td>&nbsp;</td><td>print output to file with formatted name</td></tr>
1989 <tr><td class="option-group" colspan="2">
1990 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV&gt;</var></span></kbd></td>
1991 </tr>
1992 <tr><td>&nbsp;</td><td>print the given revision</td></tr>
1993 <tr><td class="option-group">
1994 <kbd><span class="option">--decode</span></kbd></td>
1995 <td>apply any matching decode filter</td></tr>
1996 <tr><td class="option-group" colspan="2">
1997 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
1998 </tr>
1999 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
2000 <tr><td class="option-group" colspan="2">
2001 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
2002 </tr>
2003 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
2004 <tr><td class="option-group" colspan="2">
2005 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
2006 </tr>
2007 <tr><td>&nbsp;</td><td>display with template</td></tr>
2008 </tbody>
2009 </table>
2010 <p>[+] marked option can be specified multiple times</p>
2011 </div>
2012 <div class="section" id="copy">
2013 <h3>copy</h3>
2014 <p>mark files as copied for the next commit:</p>
2015 <pre class="literal-block">
2016 hg copy [OPTION]... (SOURCE... DEST | --forget DEST...)
2017 </pre>
2018 <p>Mark dest as having copies of source files. If dest is a
2019 directory, copies are put in that directory. If dest is a file,
2020 the source must be a single file.</p>
2021 <p>By default, this command copies the contents of files as they
2022 exist in the working directory. If invoked with -A/--after, the
2023 operation is recorded, but no copying is performed.</p>
2024 <p>To undo marking a destination file as copied, use --forget. With that
2025 option, all given (positional) arguments are unmarked as copies. The
2026 destination file(s) will be left in place (still tracked). Note that
2027 <a class="reference external" href="hg.1.html#copy"><tt class="docutils literal">hg copy <span class="pre">--forget</span></tt></a> behaves the same way as <a class="reference external" href="hg.1.html#rename"><tt class="docutils literal">hg rename <span class="pre">--forget</span></tt></a>.</p>
2028 <p>This command takes effect with the next commit by default.</p>
2029 <p>Returns 0 on success, 1 if errors are encountered.</p>
2030 <p>Options:</p>
2031 <table class="docutils option-list" frame="void" rules="none">
2032 <col class="option" />
2033 <col class="description" />
2034 <tbody valign="top">
2035 <tr><td class="option-group">
2036 <kbd><span class="option">--forget</span></kbd></td>
2037 <td>unmark a destination file as copied</td></tr>
2038 <tr><td class="option-group">
2039 <kbd><span class="option">-A</span>, <span class="option">--after</span></kbd></td>
2040 <td>record a copy that has already occurred</td></tr>
2041 <tr><td class="option-group">
2042 <kbd><span class="option">--at-rev <var>&lt;REV&gt;</var></span></kbd></td>
2043 <td>(un)mark copies in the given revision (EXPERIMENTAL)</td></tr>
2044 <tr><td class="option-group">
2045 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
2046 <td>forcibly copy over an existing managed file</td></tr>
2047 <tr><td class="option-group" colspan="2">
2048 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
2049 </tr>
2050 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
2051 <tr><td class="option-group" colspan="2">
2052 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
2053 </tr>
2054 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
2055 <tr><td class="option-group">
2056 <kbd><span class="option">-n</span>, <span class="option">--dry-run</span></kbd></td>
2057 <td>do not perform actions, just print output</td></tr>
2058 </tbody>
2059 </table>
2060 <p>[+] marked option can be specified multiple times</p>
2061 <!-- -->
2062 <blockquote>
2063 aliases: cp</blockquote>
2064 </div>
2065 <div class="section" id="diff">
2066 <h3>diff</h3>
2067 <p>diff repository (or selected files):</p>
2068 <pre class="literal-block">
2069 hg diff [OPTION]... ([-c REV] | [--from REV1] [--to REV2]) [FILE]...
2070 </pre>
2071 <p>Show differences between revisions for the specified files.</p>
2072 <p>Differences between files are shown using the unified diff format.</p>
2073 <div class="admonition note">
2074 <p class="first admonition-title">Note</p>
2075 <p class="last"><a class="reference external" href="hg.1.html#diff"><tt class="docutils literal">hg diff</tt></a> may generate unexpected results for merges, as it will
2076 default to comparing against the working directory's first
2077 parent changeset if no revisions are specified. To diff against the
2078 conflict regions, you can use <cite>--config diff.merge=yes</cite>.</p>
2079 </div>
2080 <p>By default, the working directory files are compared to its first parent. To
2081 see the differences from another revision, use --from. To see the difference
2082 to another revision, use --to. For example, <a class="reference external" href="hg.1.html#diff"><tt class="docutils literal">hg diff <span class="pre">--from</span> .^</tt></a> will show
2083 the differences from the working copy's grandparent to the working copy,
2084 <a class="reference external" href="hg.1.html#diff"><tt class="docutils literal">hg diff <span class="pre">--to</span> .</tt></a> will show the diff from the working copy to its parent
2085 (i.e. the reverse of the default), and <a class="reference external" href="hg.1.html#diff"><tt class="docutils literal">hg diff <span class="pre">--from</span> 1.0 <span class="pre">--to</span> 1.2</tt></a> will
2086 show the diff between those two revisions.</p>
2087 <p>Alternatively you can specify -c/--change with a revision to see the changes
2088 in that changeset relative to its first parent (i.e. <a class="reference external" href="hg.1.html#diff"><tt class="docutils literal">hg diff <span class="pre">-c</span> 42</tt></a> is
2089 equivalent to <a class="reference external" href="hg.1.html#diff"><tt class="docutils literal">hg diff <span class="pre">--from</span> 42^ <span class="pre">--to</span> 42</tt></a>)</p>
2090 <p>Without the -a/--text option, diff will avoid generating diffs of
2091 files it detects as binary. With -a, diff will generate a diff
2092 anyway, probably with undesirable results.</p>
2093 <p>Use the -g/--git option to generate diffs in the git extended diff
2094 format. For more information, read <a class="reference external" href="hg.1.html#diffs"><tt class="docutils literal">hg help diffs</tt></a>.</p>
2095 <div class="verbose docutils container">
2096 <p>Examples:</p>
2097 <ul>
2098 <li><p class="first">compare a file in the current working directory to its parent:</p>
2099 <pre class="literal-block">
2100 hg diff foo.c
2101 </pre>
2102 </li>
2103 <li><p class="first">compare two historical versions of a directory, with rename info:</p>
2104 <pre class="literal-block">
2105 hg diff --git --from 1.0 --to 1.2 lib/
2106 </pre>
2107 </li>
2108 <li><p class="first">get change stats relative to the last change on some date:</p>
2109 <pre class="literal-block">
2110 hg diff --stat --from &quot;date('may 2')&quot;
2111 </pre>
2112 </li>
2113 <li><p class="first">diff all newly-added files that contain a keyword:</p>
2114 <pre class="literal-block">
2115 hg diff &quot;set:added() and grep(GNU)&quot;
2116 </pre>
2117 </li>
2118 <li><p class="first">compare a revision and its parents:</p>
2119 <pre class="literal-block">
2120 hg diff -c 9353 # compare against first parent
2121 hg diff --from 9353^ --to 9353 # same using revset syntax
2122 hg diff --from 9353^2 --to 9353 # compare against the second parent
2123 </pre>
2124 </li>
2125 </ul>
2126 </div>
2127 <p>Returns 0 on success.</p>
2128 <p>Options:</p>
2129 <table class="docutils option-list" frame="void" rules="none">
2130 <col class="option" />
2131 <col class="description" />
2132 <tbody valign="top">
2133 <tr><td class="option-group" colspan="2">
2134 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
2135 </tr>
2136 <tr><td>&nbsp;</td><td>revision (DEPRECATED)</td></tr>
2137 <tr><td class="option-group">
2138 <kbd><span class="option">--from <var>&lt;REV1&gt;</var></span></kbd></td>
2139 <td>revision to diff from</td></tr>
2140 <tr><td class="option-group">
2141 <kbd><span class="option">--to <var>&lt;REV2&gt;</var></span></kbd></td>
2142 <td>revision to diff to</td></tr>
2143 <tr><td class="option-group" colspan="2">
2144 <kbd><span class="option">-c</span>, <span class="option">--change <var>&lt;REV&gt;</var></span></kbd></td>
2145 </tr>
2146 <tr><td>&nbsp;</td><td>change made by revision</td></tr>
2147 <tr><td class="option-group" colspan="2">
2148 <kbd><span class="option">--ignore-changes-from-ancestors</span></kbd></td>
2149 </tr>
2150 <tr><td>&nbsp;</td><td>only compare the change made by the selected revision (EXPERIMENTAL)</td></tr>
2151 <tr><td class="option-group">
2152 <kbd><span class="option">-a</span>, <span class="option">--text</span></kbd></td>
2153 <td>treat all files as text</td></tr>
2154 <tr><td class="option-group">
2155 <kbd><span class="option">-g</span>, <span class="option">--git</span></kbd></td>
2156 <td>use git extended diff format (DEFAULT: diff.git)</td></tr>
2157 <tr><td class="option-group">
2158 <kbd><span class="option">--binary</span></kbd></td>
2159 <td>generate binary diffs in git mode (default)</td></tr>
2160 <tr><td class="option-group">
2161 <kbd><span class="option">--nodates</span></kbd></td>
2162 <td>omit dates from diff headers</td></tr>
2163 <tr><td class="option-group">
2164 <kbd><span class="option">--noprefix</span></kbd></td>
2165 <td>omit a/ and b/ prefixes from filenames</td></tr>
2166 <tr><td class="option-group" colspan="2">
2167 <kbd><span class="option">-p</span>, <span class="option">--show-function</span></kbd></td>
2168 </tr>
2169 <tr><td>&nbsp;</td><td>show which function each change is in (DEFAULT: diff.showfunc)</td></tr>
2170 <tr><td class="option-group">
2171 <kbd><span class="option">--reverse</span></kbd></td>
2172 <td>produce a diff that undoes the changes</td></tr>
2173 <tr><td class="option-group" colspan="2">
2174 <kbd><span class="option">-w</span>, <span class="option">--ignore-all-space</span></kbd></td>
2175 </tr>
2176 <tr><td>&nbsp;</td><td>ignore white space when comparing lines</td></tr>
2177 <tr><td class="option-group" colspan="2">
2178 <kbd><span class="option">-b</span>, <span class="option">--ignore-space-change</span></kbd></td>
2179 </tr>
2180 <tr><td>&nbsp;</td><td>ignore changes in the amount of white space</td></tr>
2181 <tr><td class="option-group" colspan="2">
2182 <kbd><span class="option">-B</span>, <span class="option">--ignore-blank-lines</span></kbd></td>
2183 </tr>
2184 <tr><td>&nbsp;</td><td>ignore changes whose lines are all blank</td></tr>
2185 <tr><td class="option-group" colspan="2">
2186 <kbd><span class="option">-Z</span>, <span class="option">--ignore-space-at-eol</span></kbd></td>
2187 </tr>
2188 <tr><td>&nbsp;</td><td>ignore changes in whitespace at EOL</td></tr>
2189 <tr><td class="option-group" colspan="2">
2190 <kbd><span class="option">-U</span>, <span class="option">--unified <var>&lt;NUM&gt;</var></span></kbd></td>
2191 </tr>
2192 <tr><td>&nbsp;</td><td>number of lines of context to show</td></tr>
2193 <tr><td class="option-group">
2194 <kbd><span class="option">--stat</span></kbd></td>
2195 <td>output diffstat-style summary of changes</td></tr>
2196 <tr><td class="option-group">
2197 <kbd><span class="option">--root <var>&lt;DIR&gt;</var></span></kbd></td>
2198 <td>produce diffs relative to subdirectory</td></tr>
2199 <tr><td class="option-group" colspan="2">
2200 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
2201 </tr>
2202 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
2203 <tr><td class="option-group" colspan="2">
2204 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
2205 </tr>
2206 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
2207 <tr><td class="option-group">
2208 <kbd><span class="option">-S</span>, <span class="option">--subrepos</span></kbd></td>
2209 <td>recurse into subrepositories</td></tr>
2210 </tbody>
2211 </table>
2212 <p>[+] marked option can be specified multiple times</p>
2213 </div>
2214 <div class="section" id="grep">
2215 <h3>grep</h3>
2216 <p>search for a pattern in specified files:</p>
2217 <pre class="literal-block">
2218 hg grep [--diff] [OPTION]... PATTERN [FILE]...
2219 </pre>
2220 <p>Search the working directory or revision history for a regular
2221 expression in the specified files for the entire repository.</p>
2222 <p>By default, grep searches the repository files in the working
2223 directory and prints the files where it finds a match. To specify
2224 historical revisions instead of the working directory, use the
2225 --rev flag.</p>
2226 <p>To search instead historical revision differences that contains a
2227 change in match status (&quot;-&quot; for a match that becomes a non-match,
2228 or &quot;+&quot; for a non-match that becomes a match), use the --diff flag.</p>
2229 <p>PATTERN can be any Python (roughly Perl-compatible) regular
2230 expression.</p>
2231 <p>If no FILEs are specified and the --rev flag isn't supplied, all
2232 files in the working directory are searched. When using the --rev
2233 flag and specifying FILEs, use the --follow argument to also
2234 follow the specified FILEs across renames and copies.</p>
2235 <div class="verbose docutils container">
2236 <p>Template:</p>
2237 <p>The following keywords are supported in addition to the common template
2238 keywords and functions. See also <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help templates</tt></a>.</p>
2239 <table class="docutils field-list" frame="void" rules="none">
2240 <col class="field-name" />
2241 <col class="field-body" />
2242 <tbody valign="top">
2243 <tr class="field"><th class="field-name">change:</th><td class="field-body">String. Character denoting insertion <tt class="docutils literal">+</tt> or removal <tt class="docutils literal">-</tt>.
2244 Available if <tt class="docutils literal"><span class="pre">--diff</span></tt> is specified.</td>
2245 </tr>
2246 <tr class="field"><th class="field-name">lineno:</th><td class="field-body">Integer. Line number of the match.</td>
2247 </tr>
2248 <tr class="field"><th class="field-name">path:</th><td class="field-body">String. Repository-absolute path of the file.</td>
2249 </tr>
2250 <tr class="field"><th class="field-name">texts:</th><td class="field-body">List of text chunks.</td>
2251 </tr>
2252 </tbody>
2253 </table>
2254 <p>And each entry of <tt class="docutils literal">{texts}</tt> provides the following sub-keywords.</p>
2255 <table class="docutils field-list" frame="void" rules="none">
2256 <col class="field-name" />
2257 <col class="field-body" />
2258 <tbody valign="top">
2259 <tr class="field"><th class="field-name">matched:</th><td class="field-body">Boolean. True if the chunk matches the specified pattern.</td>
2260 </tr>
2261 <tr class="field"><th class="field-name">text:</th><td class="field-body">String. Chunk content.</td>
2262 </tr>
2263 </tbody>
2264 </table>
2265 <p>See <a class="reference external" href="hg.1.html#templates.operators"><tt class="docutils literal">hg help templates.operators</tt></a> for the list expansion syntax.</p>
2266 </div>
2267 <p>Returns 0 if a match is found, 1 otherwise.</p>
2268 <p>Options:</p>
2269 <table class="docutils option-list" frame="void" rules="none">
2270 <col class="option" />
2271 <col class="description" />
2272 <tbody valign="top">
2273 <tr><td class="option-group">
2274 <kbd><span class="option">-0</span>, <span class="option">--print0</span></kbd></td>
2275 <td>end fields with NUL</td></tr>
2276 <tr><td class="option-group">
2277 <kbd><span class="option">--all</span></kbd></td>
2278 <td>an alias to --diff (DEPRECATED)</td></tr>
2279 <tr><td class="option-group">
2280 <kbd><span class="option">--diff</span></kbd></td>
2281 <td>search revision differences for when the pattern was added or removed</td></tr>
2282 <tr><td class="option-group">
2283 <kbd><span class="option">-a</span>, <span class="option">--text</span></kbd></td>
2284 <td>treat all files as text</td></tr>
2285 <tr><td class="option-group">
2286 <kbd><span class="option">-f</span>, <span class="option">--follow</span></kbd></td>
2287 <td>follow changeset history, or file history across copies and renames</td></tr>
2288 <tr><td class="option-group" colspan="2">
2289 <kbd><span class="option">-i</span>, <span class="option">--ignore-case</span></kbd></td>
2290 </tr>
2291 <tr><td>&nbsp;</td><td>ignore case when matching</td></tr>
2292 <tr><td class="option-group" colspan="2">
2293 <kbd><span class="option">-l</span>, <span class="option">--files-with-matches</span></kbd></td>
2294 </tr>
2295 <tr><td>&nbsp;</td><td>print only filenames and revisions that match</td></tr>
2296 <tr><td class="option-group" colspan="2">
2297 <kbd><span class="option">-n</span>, <span class="option">--line-number</span></kbd></td>
2298 </tr>
2299 <tr><td>&nbsp;</td><td>print matching line numbers</td></tr>
2300 <tr><td class="option-group" colspan="2">
2301 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
2302 </tr>
2303 <tr><td>&nbsp;</td><td>search files changed within revision range</td></tr>
2304 <tr><td class="option-group">
2305 <kbd><span class="option">--all-files</span></kbd></td>
2306 <td>include all files in the changeset while grepping (DEPRECATED)</td></tr>
2307 <tr><td class="option-group">
2308 <kbd><span class="option">-u</span>, <span class="option">--user</span></kbd></td>
2309 <td>list the author (long with -v)</td></tr>
2310 <tr><td class="option-group">
2311 <kbd><span class="option">-d</span>, <span class="option">--date</span></kbd></td>
2312 <td>list the date (short with -q)</td></tr>
2313 <tr><td class="option-group" colspan="2">
2314 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
2315 </tr>
2316 <tr><td>&nbsp;</td><td>display with template</td></tr>
2317 <tr><td class="option-group" colspan="2">
2318 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
2319 </tr>
2320 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
2321 <tr><td class="option-group" colspan="2">
2322 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
2323 </tr>
2324 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
2325 </tbody>
2326 </table>
2327 <p>[+] marked option can be specified multiple times</p>
2328 </div>
2329 </div>
2330 <div class="section" id="change-navigation">
2331 <h2>Change navigation</h2>
2332 <div class="section" id="bisect">
2333 <h3>bisect</h3>
2334 <p>subdivision search of changesets:</p>
2335 <pre class="literal-block">
2336 hg bisect [-gbsr] [-U] [-c CMD] [REV]
2337 </pre>
2338 <p>This command helps to find changesets which introduce problems. To
2339 use, mark the earliest changeset you know exhibits the problem as
2340 bad, then mark the latest changeset which is free from the problem
2341 as good. Bisect will update your working directory to a revision
2342 for testing (unless the -U/--noupdate option is specified). Once
2343 you have performed tests, mark the working directory as good or
2344 bad, and bisect will either update to another candidate changeset
2345 or announce that it has found the bad revision.</p>
2346 <p>As a shortcut, you can also use the revision argument to mark a
2347 revision as good or bad without checking it out first.</p>
2348 <p>If you supply a command, it will be used for automatic bisection.
2349 The environment variable HG_NODE will contain the ID of the
2350 changeset being tested. The exit status of the command will be
2351 used to mark revisions as good or bad: status 0 means good, 125
2352 means to skip the revision, 127 (command not found) will abort the
2353 bisection, and any other non-zero exit status means the revision
2354 is bad.</p>
2355 <div class="verbose docutils container">
2356 <p>Some examples:</p>
2357 <ul>
2358 <li><p class="first">start a bisection with known bad revision 34, and good revision 12:</p>
2359 <pre class="literal-block">
2360 hg bisect --bad 34
2361 hg bisect --good 12
2362 </pre>
2363 </li>
2364 <li><p class="first">advance the current bisection by marking current revision as good or
2365 bad:</p>
2366 <pre class="literal-block">
2367 hg bisect --good
2368 hg bisect --bad
2369 </pre>
2370 </li>
2371 <li><p class="first">mark the current revision, or a known revision, to be skipped (e.g. if
2372 that revision is not usable because of another issue):</p>
2373 <pre class="literal-block">
2374 hg bisect --skip
2375 hg bisect --skip 23
2376 </pre>
2377 </li>
2378 <li><p class="first">skip all revisions that do not touch directories <tt class="docutils literal">foo</tt> or <tt class="docutils literal">bar</tt>:</p>
2379 <pre class="literal-block">
2380 hg bisect --skip &quot;!( file('path:foo') &amp; file('path:bar') )&quot;
2381 </pre>
2382 </li>
2383 <li><p class="first">forget the current bisection:</p>
2384 <pre class="literal-block">
2385 hg bisect --reset
2386 </pre>
2387 </li>
2388 <li><p class="first">use 'make &amp;&amp; make tests' to automatically find the first broken
2389 revision:</p>
2390 <pre class="literal-block">
2391 hg bisect --reset
2392 hg bisect --bad 34
2393 hg bisect --good 12
2394 hg bisect --command &quot;make &amp;&amp; make tests&quot;
2395 </pre>
2396 </li>
2397 <li><p class="first">see all changesets whose states are already known in the current
2398 bisection:</p>
2399 <pre class="literal-block">
2400 hg log -r &quot;bisect(pruned)&quot;
2401 </pre>
2402 </li>
2403 <li><p class="first">see the changeset currently being bisected (especially useful
2404 if running with -U/--noupdate):</p>
2405 <pre class="literal-block">
2406 hg log -r &quot;bisect(current)&quot;
2407 </pre>
2408 </li>
2409 <li><p class="first">see all changesets that took part in the current bisection:</p>
2410 <pre class="literal-block">
2411 hg log -r &quot;bisect(range)&quot;
2412 </pre>
2413 </li>
2414 <li><p class="first">you can even get a nice graph:</p>
2415 <pre class="literal-block">
2416 hg log --graph -r &quot;bisect(range)&quot;
2417 </pre>
2418 </li>
2419 </ul>
2420 <p>See <a class="reference external" href="hg.1.html#revisions.bisect"><tt class="docutils literal">hg help revisions.bisect</tt></a> for more about the <cite>bisect()</cite> predicate.</p>
2421 </div>
2422 <p>Returns 0 on success.</p>
2423 <p>Options:</p>
2424 <table class="docutils option-list" frame="void" rules="none">
2425 <col class="option" />
2426 <col class="description" />
2427 <tbody valign="top">
2428 <tr><td class="option-group">
2429 <kbd><span class="option">-r</span>, <span class="option">--reset</span></kbd></td>
2430 <td>reset bisect state</td></tr>
2431 <tr><td class="option-group">
2432 <kbd><span class="option">-g</span>, <span class="option">--good</span></kbd></td>
2433 <td>mark changeset good</td></tr>
2434 <tr><td class="option-group">
2435 <kbd><span class="option">-b</span>, <span class="option">--bad</span></kbd></td>
2436 <td>mark changeset bad</td></tr>
2437 <tr><td class="option-group">
2438 <kbd><span class="option">-s</span>, <span class="option">--skip</span></kbd></td>
2439 <td>skip testing changeset</td></tr>
2440 <tr><td class="option-group">
2441 <kbd><span class="option">-e</span>, <span class="option">--extend</span></kbd></td>
2442 <td>extend the bisect range</td></tr>
2443 <tr><td class="option-group" colspan="2">
2444 <kbd><span class="option">-c</span>, <span class="option">--command <var>&lt;CMD&gt;</var></span></kbd></td>
2445 </tr>
2446 <tr><td>&nbsp;</td><td>use command to check changeset state</td></tr>
2447 <tr><td class="option-group">
2448 <kbd><span class="option">-U</span>, <span class="option">--noupdate</span></kbd></td>
2449 <td>do not update to target</td></tr>
2450 </tbody>
2451 </table>
2452 </div>
2453 <div class="section" id="heads">
2454 <h3>heads</h3>
2455 <p>show branch heads:</p>
2456 <pre class="literal-block">
2457 hg heads [-ct] [-r STARTREV] [REV]...
2458 </pre>
2459 <p>With no arguments, show all open branch heads in the repository.
2460 Branch heads are changesets that have no descendants on the
2461 same branch. They are where development generally takes place and
2462 are the usual targets for update and merge operations.</p>
2463 <p>If one or more REVs are given, only open branch heads on the
2464 branches associated with the specified changesets are shown. This
2465 means that you can use <a class="reference external" href="hg.1.html#heads"><tt class="docutils literal">hg heads .</tt></a> to see the heads on the
2466 currently checked-out branch.</p>
2467 <p>If -c/--closed is specified, also show branch heads marked closed
2468 (see <a class="reference external" href="hg.1.html#commit"><tt class="docutils literal">hg commit <span class="pre">--close-branch</span></tt></a>).</p>
2469 <p>If STARTREV is specified, only those heads that are descendants of
2470 STARTREV will be displayed.</p>
2471 <p>If -t/--topo is specified, named branch mechanics will be ignored and only
2472 topological heads (changesets with no children) will be shown.</p>
2473 <p>Returns 0 if matching heads are found, 1 if not.</p>
2474 <p>Options:</p>
2475 <table class="docutils option-list" frame="void" rules="none">
2476 <col class="option" />
2477 <col class="description" />
2478 <tbody valign="top">
2479 <tr><td class="option-group" colspan="2">
2480 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;STARTREV&gt;</var></span></kbd></td>
2481 </tr>
2482 <tr><td>&nbsp;</td><td>show only heads which are descendants of STARTREV</td></tr>
2483 <tr><td class="option-group">
2484 <kbd><span class="option">-t</span>, <span class="option">--topo</span></kbd></td>
2485 <td>show topological heads only</td></tr>
2486 <tr><td class="option-group">
2487 <kbd><span class="option">-a</span>, <span class="option">--active</span></kbd></td>
2488 <td>show active branchheads only (DEPRECATED)</td></tr>
2489 <tr><td class="option-group">
2490 <kbd><span class="option">-c</span>, <span class="option">--closed</span></kbd></td>
2491 <td>show normal and closed branch heads</td></tr>
2492 <tr><td class="option-group" colspan="2">
2493 <kbd><span class="option">--style <var>&lt;STYLE&gt;</var></span></kbd></td>
2494 </tr>
2495 <tr><td>&nbsp;</td><td>display using template map file (DEPRECATED)</td></tr>
2496 <tr><td class="option-group" colspan="2">
2497 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
2498 </tr>
2499 <tr><td>&nbsp;</td><td>display with template</td></tr>
2500 </tbody>
2501 </table>
2502 </div>
2503 <div class="section" id="identify">
2504 <h3>identify</h3>
2505 <p>identify the working directory or specified revision:</p>
2506 <pre class="literal-block">
2507 hg identify [-nibtB] [-r REV] [SOURCE]
2508 </pre>
2509 <p>Print a summary identifying the repository state at REV using one or
2510 two parent hash identifiers, followed by a &quot;+&quot; if the working
2511 directory has uncommitted changes, the branch name (if not default),
2512 a list of tags, and a list of bookmarks.</p>
2513 <p>When REV is not given, print a summary of the current state of the
2514 repository including the working directory. Specify -r. to get information
2515 of the working directory parent without scanning uncommitted changes.</p>
2516 <p>Specifying a path to a repository root or Mercurial bundle will
2517 cause lookup to operate on that repository/bundle.</p>
2518 <div class="verbose docutils container">
2519 <p>Template:</p>
2520 <p>The following keywords are supported in addition to the common template
2521 keywords and functions. See also <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help templates</tt></a>.</p>
2522 <table class="docutils field-list" frame="void" rules="none">
2523 <col class="field-name" />
2524 <col class="field-body" />
2525 <tbody valign="top">
2526 <tr class="field"><th class="field-name">dirty:</th><td class="field-body">String. Character <tt class="docutils literal">+</tt> denoting if the working directory has
2527 uncommitted changes.</td>
2528 </tr>
2529 <tr class="field"><th class="field-name">id:</th><td class="field-body">String. One or two nodes, optionally followed by <tt class="docutils literal">+</tt>.</td>
2530 </tr>
2531 <tr class="field"><th class="field-name">parents:</th><td class="field-body">List of strings. Parent nodes of the changeset.</td>
2532 </tr>
2533 </tbody>
2534 </table>
2535 <p>Examples:</p>
2536 <ul>
2537 <li><p class="first">generate a build identifier for the working directory:</p>
2538 <pre class="literal-block">
2539 hg id --id &gt; build-id.dat
2540 </pre>
2541 </li>
2542 <li><p class="first">find the revision corresponding to a tag:</p>
2543 <pre class="literal-block">
2544 hg id -n -r 1.3
2545 </pre>
2546 </li>
2547 <li><p class="first">check the most recent revision of a remote repository:</p>
2548 <pre class="literal-block">
2549 hg id -r tip https://www.mercurial-scm.org/repo/hg/
2550 </pre>
2551 </li>
2552 </ul>
2553 </div>
2554 <p>See <a class="reference external" href="hg.1.html#log"><tt class="docutils literal">hg log</tt></a> for generating more information about specific revisions,
2555 including full hash identifiers.</p>
2556 <p>Returns 0 if successful.</p>
2557 <p>Options:</p>
2558 <table class="docutils option-list" frame="void" rules="none">
2559 <col class="option" />
2560 <col class="description" />
2561 <tbody valign="top">
2562 <tr><td class="option-group" colspan="2">
2563 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV&gt;</var></span></kbd></td>
2564 </tr>
2565 <tr><td>&nbsp;</td><td>identify the specified revision</td></tr>
2566 <tr><td class="option-group">
2567 <kbd><span class="option">-n</span>, <span class="option">--num</span></kbd></td>
2568 <td>show local revision number</td></tr>
2569 <tr><td class="option-group">
2570 <kbd><span class="option">-i</span>, <span class="option">--id</span></kbd></td>
2571 <td>show global revision id</td></tr>
2572 <tr><td class="option-group">
2573 <kbd><span class="option">-b</span>, <span class="option">--branch</span></kbd></td>
2574 <td>show branch</td></tr>
2575 <tr><td class="option-group">
2576 <kbd><span class="option">-t</span>, <span class="option">--tags</span></kbd></td>
2577 <td>show tags</td></tr>
2578 <tr><td class="option-group" colspan="2">
2579 <kbd><span class="option">-B</span>, <span class="option">--bookmarks</span></kbd></td>
2580 </tr>
2581 <tr><td>&nbsp;</td><td>show bookmarks</td></tr>
2582 <tr><td class="option-group" colspan="2">
2583 <kbd><span class="option">-e</span>, <span class="option">--ssh <var>&lt;CMD&gt;</var></span></kbd></td>
2584 </tr>
2585 <tr><td>&nbsp;</td><td>specify ssh command to use</td></tr>
2586 <tr><td class="option-group" colspan="2">
2587 <kbd><span class="option">--remotecmd <var>&lt;CMD&gt;</var></span></kbd></td>
2588 </tr>
2589 <tr><td>&nbsp;</td><td>specify hg command to run on the remote side</td></tr>
2590 <tr><td class="option-group">
2591 <kbd><span class="option">--insecure</span></kbd></td>
2592 <td>do not verify server certificate (ignoring web.cacerts config)</td></tr>
2593 <tr><td class="option-group" colspan="2">
2594 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
2595 </tr>
2596 <tr><td>&nbsp;</td><td>display with template</td></tr>
2597 </tbody>
2598 </table>
2599 <!-- -->
2600 <blockquote>
2601 aliases: id</blockquote>
2602 </div>
2603 <div class="section" id="log">
2604 <h3>log</h3>
2605 <p>show revision history of entire repository or files:</p>
2606 <pre class="literal-block">
2607 hg log [OPTION]... [FILE]
2608 </pre>
2609 <p>Print the revision history of the specified files or the entire
2610 project.</p>
2611 <p>If no revision range is specified, the default is <tt class="docutils literal">tip:0</tt> unless
2612 --follow is set.</p>
2613 <p>File history is shown without following rename or copy history of
2614 files. Use -f/--follow with a filename to follow history across
2615 renames and copies. --follow without a filename will only show
2616 ancestors of the starting revisions. The starting revisions can be
2617 specified by -r/--rev, which default to the working directory parent.</p>
2618 <p>By default this command prints revision number and changeset id,
2619 tags, non-trivial parents, user, date and time, and a summary for
2620 each commit. When the -v/--verbose switch is used, the list of
2621 changed files and full commit message are shown.</p>
2622 <p>With --graph the revisions are shown as an ASCII art DAG with the most
2623 recent changeset at the top.
2624 'o' is a changeset, '&#64;' is a working directory parent, '%' is a changeset
2625 involved in an unresolved merge conflict, '_' closes a branch,
2626 'x' is obsolete, '*' is unstable, and '+' represents a fork where the
2627 changeset from the lines below is a parent of the 'o' merge on the same
2628 line.
2629 Paths in the DAG are represented with '|', '/' and so forth. ':' in place
2630 of a '|' indicates one or more revisions in a path are omitted.</p>
2631 <div class="verbose docutils container">
2632 Use -L/--line-range FILE,M:N options to follow the history of lines
2633 from M to N in FILE. With -p/--patch only diff hunks affecting
2634 specified line range will be shown. This option requires --follow;
2635 it can be specified multiple times. Currently, this option is not
2636 compatible with --graph. This option is experimental.</div>
2637 <div class="admonition note">
2638 <p class="first admonition-title">Note</p>
2639 <p class="last"><a class="reference external" href="hg.1.html#log"><tt class="docutils literal">hg log <span class="pre">--patch</span></tt></a> may generate unexpected diff output for merge
2640 changesets, as it will only compare the merge changeset against
2641 its first parent. Also, only files different from BOTH parents
2642 will appear in files:.</p>
2643 </div>
2644 <div class="admonition note">
2645 <p class="first admonition-title">Note</p>
2646 <p class="last">For performance reasons, <a class="reference external" href="hg.1.html#log"><tt class="docutils literal">hg log FILE</tt></a> may omit duplicate changes
2647 made on branches and will not show removals or mode changes. To
2648 see all such changes, use the --removed switch.</p>
2649 </div>
2650 <div class="verbose docutils container">
2651 <div class="admonition note">
2652 <p class="first admonition-title">Note</p>
2653 <p class="last">The history resulting from -L/--line-range options depends on diff
2654 options; for instance if white-spaces are ignored, respective changes
2655 with only white-spaces in specified line range will not be listed.</p>
2656 </div>
2657 </div>
2658 <div class="verbose docutils container">
2659 <p>Some examples:</p>
2660 <ul>
2661 <li><p class="first">changesets with full descriptions and file lists:</p>
2662 <pre class="literal-block">
2663 hg log -v
2664 </pre>
2665 </li>
2666 <li><p class="first">changesets ancestral to the working directory:</p>
2667 <pre class="literal-block">
2668 hg log -f
2669 </pre>
2670 </li>
2671 <li><p class="first">last 10 commits on the current branch:</p>
2672 <pre class="literal-block">
2673 hg log -l 10 -b .
2674 </pre>
2675 </li>
2676 <li><p class="first">changesets showing all modifications of a file, including removals:</p>
2677 <pre class="literal-block">
2678 hg log --removed file.c
2679 </pre>
2680 </li>
2681 <li><p class="first">all changesets that touch a directory, with diffs, excluding merges:</p>
2682 <pre class="literal-block">
2683 hg log -Mp lib/
2684 </pre>
2685 </li>
2686 <li><p class="first">all revision numbers that match a keyword:</p>
2687 <pre class="literal-block">
2688 hg log -k bug --template &quot;{rev}\n&quot;
2689 </pre>
2690 </li>
2691 <li><p class="first">the full hash identifier of the working directory parent:</p>
2692 <pre class="literal-block">
2693 hg log -r . --template &quot;{node}\n&quot;
2694 </pre>
2695 </li>
2696 <li><p class="first">list available log templates:</p>
2697 <pre class="literal-block">
2698 hg log -T list
2699 </pre>
2700 </li>
2701 <li><p class="first">check if a given changeset is included in a tagged release:</p>
2702 <pre class="literal-block">
2703 hg log -r &quot;a21ccf and ancestor(1.9)&quot;
2704 </pre>
2705 </li>
2706 <li><p class="first">find all changesets by some user in a date range:</p>
2707 <pre class="literal-block">
2708 hg log -k alice -d &quot;may 2008 to jul 2008&quot;
2709 </pre>
2710 </li>
2711 <li><p class="first">summary of all changesets after the last tag:</p>
2712 <pre class="literal-block">
2713 hg log -r &quot;last(tagged())::&quot; --template &quot;{desc|firstline}\n&quot;
2714 </pre>
2715 </li>
2716 <li><p class="first">changesets touching lines 13 to 23 for file.c:</p>
2717 <pre class="literal-block">
2718 hg log -L file.c,13:23
2719 </pre>
2720 </li>
2721 <li><p class="first">changesets touching lines 13 to 23 for file.c and lines 2 to 6 of
2722 main.c with patch:</p>
2723 <pre class="literal-block">
2724 hg log -L file.c,13:23 -L main.c,2:6 -p
2725 </pre>
2726 </li>
2727 </ul>
2728 </div>
2729 <p>See <a class="reference external" href="hg.1.html#dates"><tt class="docutils literal">hg help dates</tt></a> for a list of formats valid for -d/--date.</p>
2730 <p>See <a class="reference external" href="hg.1.html#revisions"><tt class="docutils literal">hg help revisions</tt></a> for more about specifying and ordering
2731 revisions.</p>
2732 <p>See <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help templates</tt></a> for more about pre-packaged styles and
2733 specifying custom templates. The default template used by the log
2734 command can be customized via the <tt class="docutils literal"><span class="pre">command-templates.log</span></tt> configuration
2735 setting.</p>
2736 <p>Returns 0 on success.</p>
2737 <p>Options:</p>
2738 <table class="docutils option-list" frame="void" rules="none">
2739 <col class="option" />
2740 <col class="description" />
2741 <tbody valign="top">
2742 <tr><td class="option-group">
2743 <kbd><span class="option">-f</span>, <span class="option">--follow</span></kbd></td>
2744 <td>follow changeset history, or file history across copies and renames</td></tr>
2745 <tr><td class="option-group">
2746 <kbd><span class="option">--follow-first</span></kbd></td>
2747 <td>only follow the first parent of merge changesets (DEPRECATED)</td></tr>
2748 <tr><td class="option-group" colspan="2">
2749 <kbd><span class="option">-d</span>, <span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
2750 </tr>
2751 <tr><td>&nbsp;</td><td>show revisions matching date spec</td></tr>
2752 <tr><td class="option-group">
2753 <kbd><span class="option">-C</span>, <span class="option">--copies</span></kbd></td>
2754 <td>show copied files</td></tr>
2755 <tr><td class="option-group" colspan="2">
2756 <kbd><span class="option">-k</span>, <span class="option">--keyword <var>&lt;TEXT[+]&gt;</var></span></kbd></td>
2757 </tr>
2758 <tr><td>&nbsp;</td><td>do case-insensitive search for a given text</td></tr>
2759 <tr><td class="option-group" colspan="2">
2760 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
2761 </tr>
2762 <tr><td>&nbsp;</td><td>revisions to select or follow from</td></tr>
2763 <tr><td class="option-group" colspan="2">
2764 <kbd><span class="option">-L</span>, <span class="option">--line-range <var>&lt;FILE,RANGE[+]&gt;</var></span></kbd></td>
2765 </tr>
2766 <tr><td>&nbsp;</td><td>follow line range of specified file (EXPERIMENTAL)</td></tr>
2767 <tr><td class="option-group">
2768 <kbd><span class="option">--removed</span></kbd></td>
2769 <td>include revisions where files were removed</td></tr>
2770 <tr><td class="option-group" colspan="2">
2771 <kbd><span class="option">-m</span>, <span class="option">--only-merges</span></kbd></td>
2772 </tr>
2773 <tr><td>&nbsp;</td><td>show only merges (DEPRECATED) (use -r &quot;merge()&quot; instead)</td></tr>
2774 <tr><td class="option-group" colspan="2">
2775 <kbd><span class="option">-u</span>, <span class="option">--user <var>&lt;USER[+]&gt;</var></span></kbd></td>
2776 </tr>
2777 <tr><td>&nbsp;</td><td>revisions committed by user</td></tr>
2778 <tr><td class="option-group" colspan="2">
2779 <kbd><span class="option">--only-branch <var>&lt;BRANCH[+]&gt;</var></span></kbd></td>
2780 </tr>
2781 <tr><td>&nbsp;</td><td>show only changesets within the given named branch (DEPRECATED)</td></tr>
2782 <tr><td class="option-group" colspan="2">
2783 <kbd><span class="option">-b</span>, <span class="option">--branch <var>&lt;BRANCH[+]&gt;</var></span></kbd></td>
2784 </tr>
2785 <tr><td>&nbsp;</td><td>show changesets within the given named branch</td></tr>
2786 <tr><td class="option-group" colspan="2">
2787 <kbd><span class="option">-B</span>, <span class="option">--bookmark <var>&lt;BOOKMARK[+]&gt;</var></span></kbd></td>
2788 </tr>
2789 <tr><td>&nbsp;</td><td>show changesets within the given bookmark</td></tr>
2790 <tr><td class="option-group" colspan="2">
2791 <kbd><span class="option">-P</span>, <span class="option">--prune <var>&lt;REV[+]&gt;</var></span></kbd></td>
2792 </tr>
2793 <tr><td>&nbsp;</td><td>do not display revision or any of its ancestors</td></tr>
2794 <tr><td class="option-group">
2795 <kbd><span class="option">-p</span>, <span class="option">--patch</span></kbd></td>
2796 <td>show patch</td></tr>
2797 <tr><td class="option-group">
2798 <kbd><span class="option">-g</span>, <span class="option">--git</span></kbd></td>
2799 <td>use git extended diff format</td></tr>
2800 <tr><td class="option-group" colspan="2">
2801 <kbd><span class="option">-l</span>, <span class="option">--limit <var>&lt;NUM&gt;</var></span></kbd></td>
2802 </tr>
2803 <tr><td>&nbsp;</td><td>limit number of changes displayed</td></tr>
2804 <tr><td class="option-group" colspan="2">
2805 <kbd><span class="option">-M</span>, <span class="option">--no-merges</span></kbd></td>
2806 </tr>
2807 <tr><td>&nbsp;</td><td>do not show merges</td></tr>
2808 <tr><td class="option-group">
2809 <kbd><span class="option">--stat</span></kbd></td>
2810 <td>output diffstat-style summary of changes</td></tr>
2811 <tr><td class="option-group">
2812 <kbd><span class="option">-G</span>, <span class="option">--graph</span></kbd></td>
2813 <td>show the revision DAG</td></tr>
2814 <tr><td class="option-group" colspan="2">
2815 <kbd><span class="option">--style <var>&lt;STYLE&gt;</var></span></kbd></td>
2816 </tr>
2817 <tr><td>&nbsp;</td><td>display using template map file (DEPRECATED)</td></tr>
2818 <tr><td class="option-group" colspan="2">
2819 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
2820 </tr>
2821 <tr><td>&nbsp;</td><td>display with template</td></tr>
2822 <tr><td class="option-group" colspan="2">
2823 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
2824 </tr>
2825 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
2826 <tr><td class="option-group" colspan="2">
2827 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
2828 </tr>
2829 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
2830 </tbody>
2831 </table>
2832 <p>[+] marked option can be specified multiple times</p>
2833 <!-- -->
2834 <blockquote>
2835 aliases: history</blockquote>
2836 </div>
2837 <div class="section" id="parents">
2838 <h3>parents</h3>
2839 <p>show the parents of the working directory or revision (DEPRECATED):</p>
2840 <pre class="literal-block">
2841 hg parents [-r REV] [FILE]
2842 </pre>
2843 <p>Print the working directory's parent revisions. If a revision is
2844 given via -r/--rev, the parent of that revision will be printed.
2845 If a file argument is given, the revision in which the file was
2846 last changed (before the working directory revision or the
2847 argument to --rev if given) is printed.</p>
2848 <p>This command is equivalent to:</p>
2849 <pre class="literal-block">
2850 hg log -r &quot;p1()+p2()&quot; or
2851 hg log -r &quot;p1(REV)+p2(REV)&quot; or
2852 hg log -r &quot;max(::p1() and file(FILE))+max(::p2() and file(FILE))&quot; or
2853 hg log -r &quot;max(::p1(REV) and file(FILE))+max(::p2(REV) and file(FILE))&quot;
2854 </pre>
2855 <p>See <a class="reference external" href="hg.1.html#summary"><tt class="docutils literal">hg summary</tt></a> and <a class="reference external" href="hg.1.html#revsets"><tt class="docutils literal">hg help revsets</tt></a> for related information.</p>
2856 <p>Returns 0 on success.</p>
2857 <p>Options:</p>
2858 <table class="docutils option-list" frame="void" rules="none">
2859 <col class="option" />
2860 <col class="description" />
2861 <tbody valign="top">
2862 <tr><td class="option-group" colspan="2">
2863 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV&gt;</var></span></kbd></td>
2864 </tr>
2865 <tr><td>&nbsp;</td><td>show parents of the specified revision</td></tr>
2866 <tr><td class="option-group" colspan="2">
2867 <kbd><span class="option">--style <var>&lt;STYLE&gt;</var></span></kbd></td>
2868 </tr>
2869 <tr><td>&nbsp;</td><td>display using template map file (DEPRECATED)</td></tr>
2870 <tr><td class="option-group" colspan="2">
2871 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
2872 </tr>
2873 <tr><td>&nbsp;</td><td>display with template</td></tr>
2874 </tbody>
2875 </table>
2876 </div>
2877 <div class="section" id="tip">
2878 <h3>tip</h3>
2879 <p>show the tip revision (DEPRECATED):</p>
2880 <pre class="literal-block">
2881 hg tip [-p] [-g]
2882 </pre>
2883 <p>The tip revision (usually just called the tip) is the changeset
2884 most recently added to the repository (and therefore the most
2885 recently changed head).</p>
2886 <p>If you have just made a commit, that commit will be the tip. If
2887 you have just pulled changes from another repository, the tip of
2888 that repository becomes the current tip. The &quot;tip&quot; tag is special
2889 and cannot be renamed or assigned to a different changeset.</p>
2890 <p>This command is deprecated, please use <a class="reference external" href="hg.1.html#heads"><tt class="docutils literal">hg heads</tt></a> instead.</p>
2891 <p>Returns 0 on success.</p>
2892 <p>Options:</p>
2893 <table class="docutils option-list" frame="void" rules="none">
2894 <col class="option" />
2895 <col class="description" />
2896 <tbody valign="top">
2897 <tr><td class="option-group">
2898 <kbd><span class="option">-p</span>, <span class="option">--patch</span></kbd></td>
2899 <td>show patch</td></tr>
2900 <tr><td class="option-group">
2901 <kbd><span class="option">-g</span>, <span class="option">--git</span></kbd></td>
2902 <td>use git extended diff format</td></tr>
2903 <tr><td class="option-group" colspan="2">
2904 <kbd><span class="option">--style <var>&lt;STYLE&gt;</var></span></kbd></td>
2905 </tr>
2906 <tr><td>&nbsp;</td><td>display using template map file (DEPRECATED)</td></tr>
2907 <tr><td class="option-group" colspan="2">
2908 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
2909 </tr>
2910 <tr><td>&nbsp;</td><td>display with template</td></tr>
2911 </tbody>
2912 </table>
2913 </div>
2914 </div>
2915 <div class="section" id="working-directory-management">
2916 <h2>Working directory management</h2>
2917 <div class="section" id="add">
2918 <h3>add</h3>
2919 <p>add the specified files on the next commit:</p>
2920 <pre class="literal-block">
2921 hg add [OPTION]... [FILE]...
2922 </pre>
2923 <p>Schedule files to be version controlled and added to the
2924 repository.</p>
2925 <p>The files will be added to the repository at the next commit. To
2926 undo an add before that, see <a class="reference external" href="hg.1.html#forget"><tt class="docutils literal">hg forget</tt></a>.</p>
2927 <p>If no names are given, add all files to the repository (except
2928 files matching <tt class="docutils literal">.hgignore</tt>).</p>
2929 <div class="verbose docutils container">
2930 <p>Examples:</p>
2931 <blockquote>
2932 <ul>
2933 <li><p class="first">New (unknown) files are added
2934 automatically by <a class="reference external" href="hg.1.html#add"><tt class="docutils literal">hg add</tt></a>:</p>
2935 <pre class="literal-block">
2936 $ ls
2937 foo.c
2938 $ hg status
2939 ? foo.c
2940 $ hg add
2941 adding foo.c
2942 $ hg status
2943 A foo.c
2944 </pre>
2945 </li>
2946 <li><p class="first">Specific files to be added can be specified:</p>
2947 <pre class="literal-block">
2948 $ ls
2949 bar.c foo.c
2950 $ hg status
2951 ? bar.c
2952 ? foo.c
2953 $ hg add bar.c
2954 $ hg status
2955 A bar.c
2956 ? foo.c
2957 </pre>
2958 </li>
2959 </ul>
2960 </blockquote>
2961 </div>
2962 <p>Returns 0 if all files are successfully added.</p>
2963 <p>Options:</p>
2964 <table class="docutils option-list" frame="void" rules="none">
2965 <col class="option" />
2966 <col class="description" />
2967 <tbody valign="top">
2968 <tr><td class="option-group" colspan="2">
2969 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
2970 </tr>
2971 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
2972 <tr><td class="option-group" colspan="2">
2973 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
2974 </tr>
2975 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
2976 <tr><td class="option-group">
2977 <kbd><span class="option">-S</span>, <span class="option">--subrepos</span></kbd></td>
2978 <td>recurse into subrepositories</td></tr>
2979 <tr><td class="option-group">
2980 <kbd><span class="option">-n</span>, <span class="option">--dry-run</span></kbd></td>
2981 <td>do not perform actions, just print output</td></tr>
2982 </tbody>
2983 </table>
2984 <p>[+] marked option can be specified multiple times</p>
2985 </div>
2986 <div class="section" id="addremove">
2987 <h3>addremove</h3>
2988 <p>add all new files, delete all missing files:</p>
2989 <pre class="literal-block">
2990 hg addremove [OPTION]... [FILE]...
2991 </pre>
2992 <p>Add all new files and remove all missing files from the
2993 repository.</p>
2994 <p>Unless names are given, new files are ignored if they match any of
2995 the patterns in <tt class="docutils literal">.hgignore</tt>. As with add, these changes take
2996 effect at the next commit.</p>
2997 <p>Use the -s/--similarity option to detect renamed files. This
2998 option takes a percentage between 0 (disabled) and 100 (files must
2999 be identical) as its parameter. With a parameter greater than 0,
3000 this compares every removed file with every added file and records
3001 those similar enough as renames. Detecting renamed files this way
3002 can be expensive. After using this option, <a class="reference external" href="hg.1.html#status"><tt class="docutils literal">hg status <span class="pre">-C</span></tt></a> can be
3003 used to check which files were identified as moved or renamed. If
3004 not specified, -s/--similarity defaults to 100 and only renames of
3005 identical files are detected.</p>
3006 <div class="verbose docutils container">
3007 <p>Examples:</p>
3008 <blockquote>
3009 <ul>
3010 <li><p class="first">A number of files (bar.c and foo.c) are new,
3011 while foobar.c has been removed (without using <a class="reference external" href="hg.1.html#remove"><tt class="docutils literal">hg remove</tt></a>)
3012 from the repository:</p>
3013 <pre class="literal-block">
3014 $ ls
3015 bar.c foo.c
3016 $ hg status
3017 ! foobar.c
3018 ? bar.c
3019 ? foo.c
3020 $ hg addremove
3021 adding bar.c
3022 adding foo.c
3023 removing foobar.c
3024 $ hg status
3025 A bar.c
3026 A foo.c
3027 R foobar.c
3028 </pre>
3029 </li>
3030 <li><p class="first">A file foobar.c was moved to foo.c without using <a class="reference external" href="hg.1.html#rename"><tt class="docutils literal">hg rename</tt></a>.
3031 Afterwards, it was edited slightly:</p>
3032 <pre class="literal-block">
3033 $ ls
3034 foo.c
3035 $ hg status
3036 ! foobar.c
3037 ? foo.c
3038 $ hg addremove --similarity 90
3039 removing foobar.c
3040 adding foo.c
3041 recording removal of foobar.c as rename to foo.c (94% similar)
3042 $ hg status -C
3043 A foo.c
3044 foobar.c
3045 R foobar.c
3046 </pre>
3047 </li>
3048 </ul>
3049 </blockquote>
3050 </div>
3051 <p>Returns 0 if all files are successfully added.</p>
3052 <p>Options:</p>
3053 <table class="docutils option-list" frame="void" rules="none">
3054 <col class="option" />
3055 <col class="description" />
3056 <tbody valign="top">
3057 <tr><td class="option-group" colspan="2">
3058 <kbd><span class="option">-s</span>, <span class="option">--similarity <var>&lt;SIMILARITY&gt;</var></span></kbd></td>
3059 </tr>
3060 <tr><td>&nbsp;</td><td>guess renamed files by similarity (0&lt;=s&lt;=100)</td></tr>
3061 <tr><td class="option-group">
3062 <kbd><span class="option">-S</span>, <span class="option">--subrepos</span></kbd></td>
3063 <td>recurse into subrepositories</td></tr>
3064 <tr><td class="option-group" colspan="2">
3065 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3066 </tr>
3067 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
3068 <tr><td class="option-group" colspan="2">
3069 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3070 </tr>
3071 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
3072 <tr><td class="option-group">
3073 <kbd><span class="option">-n</span>, <span class="option">--dry-run</span></kbd></td>
3074 <td>do not perform actions, just print output</td></tr>
3075 </tbody>
3076 </table>
3077 <p>[+] marked option can be specified multiple times</p>
3078 </div>
3079 <div class="section" id="files">
3080 <h3>files</h3>
3081 <p>list tracked files:</p>
3082 <pre class="literal-block">
3083 hg files [OPTION]... [FILE]...
3084 </pre>
3085 <p>Print files under Mercurial control in the working directory or
3086 specified revision for given files (excluding removed files).
3087 Files can be specified as filenames or filesets.</p>
3088 <p>If no files are given to match, this command prints the names
3089 of all files under Mercurial control.</p>
3090 <div class="verbose docutils container">
3091 <p>Template:</p>
3092 <p>The following keywords are supported in addition to the common template
3093 keywords and functions. See also <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help templates</tt></a>.</p>
3094 <table class="docutils field-list" frame="void" rules="none">
3095 <col class="field-name" />
3096 <col class="field-body" />
3097 <tbody valign="top">
3098 <tr class="field"><th class="field-name">flags:</th><td class="field-body">String. Character denoting file's symlink and executable bits.</td>
3099 </tr>
3100 <tr class="field"><th class="field-name">path:</th><td class="field-body">String. Repository-absolute path of the file.</td>
3101 </tr>
3102 <tr class="field"><th class="field-name">size:</th><td class="field-body">Integer. Size of the file in bytes.</td>
3103 </tr>
3104 </tbody>
3105 </table>
3106 <p>Examples:</p>
3107 <ul>
3108 <li><p class="first">list all files under the current directory:</p>
3109 <pre class="literal-block">
3110 hg files .
3111 </pre>
3112 </li>
3113 <li><p class="first">shows sizes and flags for current revision:</p>
3114 <pre class="literal-block">
3115 hg files -vr .
3116 </pre>
3117 </li>
3118 <li><p class="first">list all files named README:</p>
3119 <pre class="literal-block">
3120 hg files -I &quot;**/README&quot;
3121 </pre>
3122 </li>
3123 <li><p class="first">list all binary files:</p>
3124 <pre class="literal-block">
3125 hg files &quot;set:binary()&quot;
3126 </pre>
3127 </li>
3128 <li><p class="first">find files containing a regular expression:</p>
3129 <pre class="literal-block">
3130 hg files &quot;set:grep('bob')&quot;
3131 </pre>
3132 </li>
3133 <li><p class="first">search tracked file contents with xargs and grep:</p>
3134 <pre class="literal-block">
3135 hg files -0 | xargs -0 grep foo
3136 </pre>
3137 </li>
3138 </ul>
3139 </div>
3140 <p>See <a class="reference external" href="hg.1.html#patterns"><tt class="docutils literal">hg help patterns</tt></a> and <a class="reference external" href="hg.1.html#filesets"><tt class="docutils literal">hg help filesets</tt></a> for more information
3141 on specifying file patterns.</p>
3142 <p>Returns 0 if a match is found, 1 otherwise.</p>
3143 <p>Options:</p>
3144 <table class="docutils option-list" frame="void" rules="none">
3145 <col class="option" />
3146 <col class="description" />
3147 <tbody valign="top">
3148 <tr><td class="option-group" colspan="2">
3149 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV&gt;</var></span></kbd></td>
3150 </tr>
3151 <tr><td>&nbsp;</td><td>search the repository as it is in REV</td></tr>
3152 <tr><td class="option-group">
3153 <kbd><span class="option">-0</span>, <span class="option">--print0</span></kbd></td>
3154 <td>end filenames with NUL, for use with xargs</td></tr>
3155 <tr><td class="option-group" colspan="2">
3156 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3157 </tr>
3158 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
3159 <tr><td class="option-group" colspan="2">
3160 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3161 </tr>
3162 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
3163 <tr><td class="option-group" colspan="2">
3164 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
3165 </tr>
3166 <tr><td>&nbsp;</td><td>display with template</td></tr>
3167 <tr><td class="option-group">
3168 <kbd><span class="option">-S</span>, <span class="option">--subrepos</span></kbd></td>
3169 <td>recurse into subrepositories</td></tr>
3170 </tbody>
3171 </table>
3172 <p>[+] marked option can be specified multiple times</p>
3173 </div>
3174 <div class="section" id="forget">
3175 <h3>forget</h3>
3176 <p>forget the specified files on the next commit:</p>
3177 <pre class="literal-block">
3178 hg forget [OPTION]... FILE...
3179 </pre>
3180 <p>Mark the specified files so they will no longer be tracked
3181 after the next commit.</p>
3182 <p>This only removes files from the current branch, not from the
3183 entire project history, and it does not delete them from the
3184 working directory.</p>
3185 <p>To delete the file from the working directory, see <a class="reference external" href="hg.1.html#remove"><tt class="docutils literal">hg remove</tt></a>.</p>
3186 <p>To undo a forget before the next commit, see <a class="reference external" href="hg.1.html#add"><tt class="docutils literal">hg add</tt></a>.</p>
3187 <div class="verbose docutils container">
3188 <p>Examples:</p>
3189 <ul>
3190 <li><p class="first">forget newly-added binary files:</p>
3191 <pre class="literal-block">
3192 hg forget &quot;set:added() and binary()&quot;
3193 </pre>
3194 </li>
3195 <li><p class="first">forget files that would be excluded by .hgignore:</p>
3196 <pre class="literal-block">
3197 hg forget &quot;set:hgignore()&quot;
3198 </pre>
3199 </li>
3200 </ul>
3201 </div>
3202 <p>Returns 0 on success.</p>
3203 <p>Options:</p>
3204 <table class="docutils option-list" frame="void" rules="none">
3205 <col class="option" />
3206 <col class="description" />
3207 <tbody valign="top">
3208 <tr><td class="option-group" colspan="2">
3209 <kbd><span class="option">-i</span>, <span class="option">--interactive</span></kbd></td>
3210 </tr>
3211 <tr><td>&nbsp;</td><td>use interactive mode</td></tr>
3212 <tr><td class="option-group" colspan="2">
3213 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3214 </tr>
3215 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
3216 <tr><td class="option-group" colspan="2">
3217 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3218 </tr>
3219 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
3220 <tr><td class="option-group">
3221 <kbd><span class="option">-n</span>, <span class="option">--dry-run</span></kbd></td>
3222 <td>do not perform actions, just print output</td></tr>
3223 </tbody>
3224 </table>
3225 <p>[+] marked option can be specified multiple times</p>
3226 </div>
3227 <div class="section" id="locate">
3228 <h3>locate</h3>
3229 <p>locate files matching specific patterns (DEPRECATED):</p>
3230 <pre class="literal-block">
3231 hg locate [OPTION]... [PATTERN]...
3232 </pre>
3233 <p>Print files under Mercurial control in the working directory whose
3234 names match the given patterns.</p>
3235 <p>By default, this command searches all directories in the working
3236 directory. To search just the current directory and its
3237 subdirectories, use &quot;--include .&quot;.</p>
3238 <p>If no patterns are given to match, this command prints the names
3239 of all files under Mercurial control in the working directory.</p>
3240 <p>If you want to feed the output of this command into the &quot;xargs&quot;
3241 command, use the -0 option to both this command and &quot;xargs&quot;. This
3242 will avoid the problem of &quot;xargs&quot; treating single filenames that
3243 contain whitespace as multiple filenames.</p>
3244 <p>See <a class="reference external" href="hg.1.html#files"><tt class="docutils literal">hg help files</tt></a> for a more versatile command.</p>
3245 <p>Returns 0 if a match is found, 1 otherwise.</p>
3246 <p>Options:</p>
3247 <table class="docutils option-list" frame="void" rules="none">
3248 <col class="option" />
3249 <col class="description" />
3250 <tbody valign="top">
3251 <tr><td class="option-group" colspan="2">
3252 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV&gt;</var></span></kbd></td>
3253 </tr>
3254 <tr><td>&nbsp;</td><td>search the repository as it is in REV</td></tr>
3255 <tr><td class="option-group">
3256 <kbd><span class="option">-0</span>, <span class="option">--print0</span></kbd></td>
3257 <td>end filenames with NUL, for use with xargs</td></tr>
3258 <tr><td class="option-group">
3259 <kbd><span class="option">-f</span>, <span class="option">--fullpath</span></kbd></td>
3260 <td>print complete paths from the filesystem root</td></tr>
3261 <tr><td class="option-group" colspan="2">
3262 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3263 </tr>
3264 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
3265 <tr><td class="option-group" colspan="2">
3266 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3267 </tr>
3268 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
3269 </tbody>
3270 </table>
3271 <p>[+] marked option can be specified multiple times</p>
3272 </div>
3273 <div class="section" id="purge">
3274 <h3>purge</h3>
3275 <p>removes files not tracked by Mercurial:</p>
3276 <pre class="literal-block">
3277 hg purge [OPTION]... [DIR]...
3278 </pre>
3279 <p>Delete files not known to Mercurial. This is useful to test local
3280 and uncommitted changes in an otherwise-clean source tree.</p>
3281 <p>This means that purge will delete the following by default:</p>
3282 <ul class="simple">
3283 <li>Unknown files: files marked with &quot;?&quot; by <a class="reference external" href="hg.1.html#status"><tt class="docutils literal">hg status</tt></a></li>
3284 <li>Empty directories: in fact Mercurial ignores directories unless
3285 they contain files under source control management</li>
3286 </ul>
3287 <p>But it will leave untouched:</p>
3288 <ul class="simple">
3289 <li>Modified and unmodified tracked files</li>
3290 <li>Ignored files (unless -i or --all is specified)</li>
3291 <li>New files added to the repository (with <a class="reference external" href="hg.1.html#add"><tt class="docutils literal">hg add</tt></a>)</li>
3292 </ul>
3293 <p>The --files and --dirs options can be used to direct purge to delete
3294 only files, only directories, or both. If neither option is given,
3295 both will be deleted.</p>
3296 <p>If directories are given on the command line, only files in these
3297 directories are considered.</p>
3298 <p>Be careful with purge, as you could irreversibly delete some files
3299 you forgot to add to the repository. If you only want to print the
3300 list of files that this program would delete, use the --print
3301 option.</p>
3302 <p>Options:</p>
3303 <table class="docutils option-list" frame="void" rules="none">
3304 <col class="option" />
3305 <col class="description" />
3306 <tbody valign="top">
3307 <tr><td class="option-group" colspan="2">
3308 <kbd><span class="option">-a</span>, <span class="option">--abort-on-err</span></kbd></td>
3309 </tr>
3310 <tr><td>&nbsp;</td><td>abort if an error occurs</td></tr>
3311 <tr><td class="option-group">
3312 <kbd><span class="option">--all</span></kbd></td>
3313 <td>purge ignored files too</td></tr>
3314 <tr><td class="option-group">
3315 <kbd><span class="option">-i</span>, <span class="option">--ignored</span></kbd></td>
3316 <td>purge only ignored files</td></tr>
3317 <tr><td class="option-group">
3318 <kbd><span class="option">--dirs</span></kbd></td>
3319 <td>purge empty directories</td></tr>
3320 <tr><td class="option-group">
3321 <kbd><span class="option">--files</span></kbd></td>
3322 <td>purge files</td></tr>
3323 <tr><td class="option-group">
3324 <kbd><span class="option">-p</span>, <span class="option">--print</span></kbd></td>
3325 <td>print filenames instead of deleting them</td></tr>
3326 <tr><td class="option-group">
3327 <kbd><span class="option">-0</span>, <span class="option">--print0</span></kbd></td>
3328 <td>end filenames with NUL, for use with xargs (implies -p/--print)</td></tr>
3329 <tr><td class="option-group">
3330 <kbd><span class="option">--confirm</span></kbd></td>
3331 <td>ask before permanently deleting files</td></tr>
3332 <tr><td class="option-group" colspan="2">
3333 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3334 </tr>
3335 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
3336 <tr><td class="option-group" colspan="2">
3337 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3338 </tr>
3339 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
3340 </tbody>
3341 </table>
3342 <p>[+] marked option can be specified multiple times</p>
3343 <!-- -->
3344 <blockquote>
3345 aliases: clean</blockquote>
3346 </div>
3347 <div class="section" id="remove">
3348 <h3>remove</h3>
3349 <p>remove the specified files on the next commit:</p>
3350 <pre class="literal-block">
3351 hg remove [OPTION]... FILE...
3352 </pre>
3353 <p>Schedule the indicated files for removal from the current branch.</p>
3354 <p>This command schedules the files to be removed at the next commit.
3355 To undo a remove before that, see <a class="reference external" href="hg.1.html#revert"><tt class="docutils literal">hg revert</tt></a>. To undo added
3356 files, see <a class="reference external" href="hg.1.html#forget"><tt class="docutils literal">hg forget</tt></a>.</p>
3357 <div class="verbose docutils container">
3358 <p>-A/--after can be used to remove only files that have already
3359 been deleted, -f/--force can be used to force deletion, and -Af
3360 can be used to remove files from the next revision without
3361 deleting them from the working directory.</p>
3362 <p>The following table details the behavior of remove for different
3363 file states (columns) and option combinations (rows). The file
3364 states are Added [A], Clean [C], Modified [M] and Missing [!]
3365 (as reported by <a class="reference external" href="hg.1.html#status"><tt class="docutils literal">hg status</tt></a>). The actions are Warn, Remove
3366 (from branch) and Delete (from disk):</p>
3367 <table border="1" class="docutils">
3368 <colgroup>
3369 <col width="53%" />
3370 <col width="12%" />
3371 <col width="12%" />
3372 <col width="12%" />
3373 <col width="12%" />
3374 </colgroup>
3375 <thead valign="bottom">
3376 <tr><th class="head">opt/state</th>
3377 <th class="head">A</th>
3378 <th class="head">C</th>
3379 <th class="head">M</th>
3380 <th class="head">!</th>
3381 </tr>
3382 </thead>
3383 <tbody valign="top">
3384 <tr><td>none</td>
3385 <td>W</td>
3386 <td>RD</td>
3387 <td>W</td>
3388 <td>R</td>
3389 </tr>
3390 <tr><td>-f</td>
3391 <td>R</td>
3392 <td>RD</td>
3393 <td>RD</td>
3394 <td>R</td>
3395 </tr>
3396 <tr><td>-A</td>
3397 <td>W</td>
3398 <td>W</td>
3399 <td>W</td>
3400 <td>R</td>
3401 </tr>
3402 <tr><td>-Af</td>
3403 <td>R</td>
3404 <td>R</td>
3405 <td>R</td>
3406 <td>R</td>
3407 </tr>
3408 </tbody>
3409 </table>
3410 <div class="admonition note">
3411 <p class="first admonition-title">Note</p>
3412 <p class="last"><a class="reference external" href="hg.1.html#remove"><tt class="docutils literal">hg remove</tt></a> never deletes files in Added [A] state from the
3413 working directory, not even if <tt class="docutils literal"><span class="pre">--force</span></tt> is specified.</p>
3414 </div>
3415 </div>
3416 <p>Returns 0 on success, 1 if any warnings encountered.</p>
3417 <p>Options:</p>
3418 <table class="docutils option-list" frame="void" rules="none">
3419 <col class="option" />
3420 <col class="description" />
3421 <tbody valign="top">
3422 <tr><td class="option-group">
3423 <kbd><span class="option">-A</span>, <span class="option">--after</span></kbd></td>
3424 <td>record delete for missing files</td></tr>
3425 <tr><td class="option-group">
3426 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
3427 <td>forget added files, delete modified files</td></tr>
3428 <tr><td class="option-group">
3429 <kbd><span class="option">-S</span>, <span class="option">--subrepos</span></kbd></td>
3430 <td>recurse into subrepositories</td></tr>
3431 <tr><td class="option-group" colspan="2">
3432 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3433 </tr>
3434 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
3435 <tr><td class="option-group" colspan="2">
3436 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3437 </tr>
3438 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
3439 <tr><td class="option-group">
3440 <kbd><span class="option">-n</span>, <span class="option">--dry-run</span></kbd></td>
3441 <td>do not perform actions, just print output</td></tr>
3442 </tbody>
3443 </table>
3444 <p>[+] marked option can be specified multiple times</p>
3445 <!-- -->
3446 <blockquote>
3447 aliases: rm</blockquote>
3448 </div>
3449 <div class="section" id="rename">
3450 <h3>rename</h3>
3451 <p>rename files; equivalent of copy + remove:</p>
3452 <pre class="literal-block">
3453 hg rename [OPTION]... SOURCE... DEST
3454 </pre>
3455 <p>Mark dest as copies of sources; mark sources for deletion. If dest
3456 is a directory, copies are put in that directory. If dest is a
3457 file, there can only be one source.</p>
3458 <p>By default, this command copies the contents of files as they
3459 exist in the working directory. If invoked with -A/--after, the
3460 operation is recorded, but no copying is performed.</p>
3461 <p>To undo marking a destination file as renamed, use --forget. With that
3462 option, all given (positional) arguments are unmarked as renames. The
3463 destination file(s) will be left in place (still tracked). The source
3464 file(s) will not be restored. Note that <a class="reference external" href="hg.1.html#rename"><tt class="docutils literal">hg rename <span class="pre">--forget</span></tt></a> behaves
3465 the same way as <a class="reference external" href="hg.1.html#copy"><tt class="docutils literal">hg copy <span class="pre">--forget</span></tt></a>.</p>
3466 <p>This command takes effect with the next commit by default.</p>
3467 <p>Returns 0 on success, 1 if errors are encountered.</p>
3468 <p>Options:</p>
3469 <table class="docutils option-list" frame="void" rules="none">
3470 <col class="option" />
3471 <col class="description" />
3472 <tbody valign="top">
3473 <tr><td class="option-group">
3474 <kbd><span class="option">--forget</span></kbd></td>
3475 <td>unmark a destination file as renamed</td></tr>
3476 <tr><td class="option-group">
3477 <kbd><span class="option">-A</span>, <span class="option">--after</span></kbd></td>
3478 <td>record a rename that has already occurred</td></tr>
3479 <tr><td class="option-group">
3480 <kbd><span class="option">--at-rev <var>&lt;REV&gt;</var></span></kbd></td>
3481 <td>(un)mark renames in the given revision (EXPERIMENTAL)</td></tr>
3482 <tr><td class="option-group">
3483 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
3484 <td>forcibly move over an existing managed file</td></tr>
3485 <tr><td class="option-group" colspan="2">
3486 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3487 </tr>
3488 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
3489 <tr><td class="option-group" colspan="2">
3490 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3491 </tr>
3492 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
3493 <tr><td class="option-group">
3494 <kbd><span class="option">-n</span>, <span class="option">--dry-run</span></kbd></td>
3495 <td>do not perform actions, just print output</td></tr>
3496 </tbody>
3497 </table>
3498 <p>[+] marked option can be specified multiple times</p>
3499 <!-- -->
3500 <blockquote>
3501 aliases: move mv</blockquote>
3502 </div>
3503 <div class="section" id="resolve">
3504 <h3>resolve</h3>
3505 <p>redo merges or set/view the merge status of files:</p>
3506 <pre class="literal-block">
3507 hg resolve [OPTION]... [FILE]...
3508 </pre>
3509 <p>Merges with unresolved conflicts are often the result of
3510 non-interactive merging using the <tt class="docutils literal">internal:merge</tt> configuration
3511 setting, or a command-line merge tool like <tt class="docutils literal">diff3</tt>. The resolve
3512 command is used to manage the files involved in a merge, after
3513 <a class="reference external" href="hg.1.html#merge"><tt class="docutils literal">hg merge</tt></a> has been run, and before <a class="reference external" href="hg.1.html#commit"><tt class="docutils literal">hg commit</tt></a> is run (i.e. the
3514 working directory must have two parents). See <a class="reference external" href="hg.1.html#merge-tools"><tt class="docutils literal">hg help
3515 <span class="pre">merge-tools</span></tt></a> for information on configuring merge tools.</p>
3516 <p>The resolve command can be used in the following ways:</p>
3517 <ul class="simple">
3518 <li><a class="reference external" href="hg.1.html#resolve"><tt class="docutils literal">hg resolve <span class="pre">[--re-merge]</span> <span class="pre">[--tool</span> TOOL] <span class="pre">FILE...</span></tt></a>: attempt to re-merge
3519 the specified files, discarding any previous merge attempts. Re-merging
3520 is not performed for files already marked as resolved. Use <tt class="docutils literal"><span class="pre">--all/-a</span></tt>
3521 to select all unresolved files. <tt class="docutils literal"><span class="pre">--tool</span></tt> can be used to specify
3522 the merge tool used for the given files. It overrides the HGMERGE
3523 environment variable and your configuration files. Previous file
3524 contents are saved with a <tt class="docutils literal">.orig</tt> suffix.</li>
3525 <li><a class="reference external" href="hg.1.html#resolve"><tt class="docutils literal">hg resolve <span class="pre">-m</span> [FILE]</tt></a>: mark a file as having been resolved
3526 (e.g. after having manually fixed-up the files). The default is
3527 to mark all unresolved files.</li>
3528 <li><a class="reference external" href="hg.1.html#resolve"><tt class="docutils literal">hg resolve <span class="pre">-u</span> <span class="pre">[FILE]...</span></tt></a>: mark a file as unresolved. The
3529 default is to mark all resolved files.</li>
3530 <li><a class="reference external" href="hg.1.html#resolve"><tt class="docutils literal">hg resolve <span class="pre">-l</span></tt></a>: list files which had or still have conflicts.
3531 In the printed list, <tt class="docutils literal">U</tt> = unresolved and <tt class="docutils literal">R</tt> = resolved.
3532 You can use <tt class="docutils literal">set:unresolved()</tt> or <tt class="docutils literal">set:resolved()</tt> to filter
3533 the list. See <a class="reference external" href="hg.1.html#filesets"><tt class="docutils literal">hg help filesets</tt></a> for details.</li>
3534 </ul>
3535 <div class="admonition note">
3536 <p class="first admonition-title">Note</p>
3537 <p class="last">Mercurial will not let you commit files with unresolved merge
3538 conflicts. You must use <a class="reference external" href="hg.1.html#resolve"><tt class="docutils literal">hg resolve <span class="pre">-m</span> ...</tt></a> before you can
3539 commit after a conflicting merge.</p>
3540 </div>
3541 <div class="verbose docutils container">
3542 <p>Template:</p>
3543 <p>The following keywords are supported in addition to the common template
3544 keywords and functions. See also <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help templates</tt></a>.</p>
3545 <table class="docutils field-list" frame="void" rules="none">
3546 <col class="field-name" />
3547 <col class="field-body" />
3548 <tbody valign="top">
3549 <tr class="field"><th class="field-name">mergestatus:</th><td class="field-body">String. Character denoting merge conflicts, <tt class="docutils literal">U</tt> or <tt class="docutils literal">R</tt>.</td>
3550 </tr>
3551 <tr class="field"><th class="field-name">path:</th><td class="field-body">String. Repository-absolute path of the file.</td>
3552 </tr>
3553 </tbody>
3554 </table>
3555 </div>
3556 <p>Returns 0 on success, 1 if any files fail a resolve attempt.</p>
3557 <p>Options:</p>
3558 <table class="docutils option-list" frame="void" rules="none">
3559 <col class="option" />
3560 <col class="description" />
3561 <tbody valign="top">
3562 <tr><td class="option-group">
3563 <kbd><span class="option">-a</span>, <span class="option">--all</span></kbd></td>
3564 <td>select all unresolved files</td></tr>
3565 <tr><td class="option-group">
3566 <kbd><span class="option">-l</span>, <span class="option">--list</span></kbd></td>
3567 <td>list state of files needing merge</td></tr>
3568 <tr><td class="option-group">
3569 <kbd><span class="option">-m</span>, <span class="option">--mark</span></kbd></td>
3570 <td>mark files as resolved</td></tr>
3571 <tr><td class="option-group">
3572 <kbd><span class="option">-u</span>, <span class="option">--unmark</span></kbd></td>
3573 <td>mark files as unresolved</td></tr>
3574 <tr><td class="option-group" colspan="2">
3575 <kbd><span class="option">-n</span>, <span class="option">--no-status</span></kbd></td>
3576 </tr>
3577 <tr><td>&nbsp;</td><td>hide status prefix</td></tr>
3578 <tr><td class="option-group">
3579 <kbd><span class="option">--re-merge</span></kbd></td>
3580 <td>re-merge files</td></tr>
3581 <tr><td class="option-group" colspan="2">
3582 <kbd><span class="option">-t</span>, <span class="option">--tool <var>&lt;TOOL&gt;</var></span></kbd></td>
3583 </tr>
3584 <tr><td>&nbsp;</td><td>specify merge tool</td></tr>
3585 <tr><td class="option-group" colspan="2">
3586 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3587 </tr>
3588 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
3589 <tr><td class="option-group" colspan="2">
3590 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3591 </tr>
3592 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
3593 <tr><td class="option-group" colspan="2">
3594 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
3595 </tr>
3596 <tr><td>&nbsp;</td><td>display with template</td></tr>
3597 </tbody>
3598 </table>
3599 <p>[+] marked option can be specified multiple times</p>
3600 </div>
3601 <div class="section" id="revert">
3602 <h3>revert</h3>
3603 <p>restore files to their checkout state:</p>
3604 <pre class="literal-block">
3605 hg revert [OPTION]... [-r REV] [NAME]...
3606 </pre>
3607 <div class="admonition note">
3608 <p class="first admonition-title">Note</p>
3609 <p class="last">To check out earlier revisions, you should use <a class="reference external" href="hg.1.html#update"><tt class="docutils literal">hg update REV</tt></a>.
3610 To cancel an uncommitted merge (and lose your changes),
3611 use <a class="reference external" href="hg.1.html#merge"><tt class="docutils literal">hg merge <span class="pre">--abort</span></tt></a>.</p>
3612 </div>
3613 <p>With no revision specified, revert the specified files or directories
3614 to the contents they had in the parent of the working directory.
3615 This restores the contents of files to an unmodified
3616 state and unschedules adds, removes, copies, and renames. If the
3617 working directory has two parents, you must explicitly specify a
3618 revision.</p>
3619 <p>Using the -r/--rev or -d/--date options, revert the given files or
3620 directories to their states as of a specific revision. Because
3621 revert does not change the working directory parents, this will
3622 cause these files to appear modified. This can be helpful to &quot;back
3623 out&quot; some or all of an earlier change. See <a class="reference external" href="hg.1.html#backout"><tt class="docutils literal">hg backout</tt></a> for a
3624 related method.</p>
3625 <p>Modified files are saved with a .orig suffix before reverting.
3626 To disable these backups, use --no-backup. It is possible to store
3627 the backup files in a custom directory relative to the root of the
3628 repository by setting the <tt class="docutils literal">ui.origbackuppath</tt> configuration
3629 option.</p>
3630 <p>See <a class="reference external" href="hg.1.html#dates"><tt class="docutils literal">hg help dates</tt></a> for a list of formats valid for -d/--date.</p>
3631 <p>See <a class="reference external" href="hg.1.html#backout"><tt class="docutils literal">hg help backout</tt></a> for a way to reverse the effect of an
3632 earlier changeset.</p>
3633 <p>Returns 0 on success.</p>
3634 <p>Options:</p>
3635 <table class="docutils option-list" frame="void" rules="none">
3636 <col class="option" />
3637 <col class="description" />
3638 <tbody valign="top">
3639 <tr><td class="option-group">
3640 <kbd><span class="option">-a</span>, <span class="option">--all</span></kbd></td>
3641 <td>revert all changes when no arguments given</td></tr>
3642 <tr><td class="option-group" colspan="2">
3643 <kbd><span class="option">-d</span>, <span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
3644 </tr>
3645 <tr><td>&nbsp;</td><td>tipmost revision matching date</td></tr>
3646 <tr><td class="option-group" colspan="2">
3647 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV&gt;</var></span></kbd></td>
3648 </tr>
3649 <tr><td>&nbsp;</td><td>revert to the specified revision</td></tr>
3650 <tr><td class="option-group" colspan="2">
3651 <kbd><span class="option">-C</span>, <span class="option">--no-backup</span></kbd></td>
3652 </tr>
3653 <tr><td>&nbsp;</td><td>do not save backup copies of files</td></tr>
3654 <tr><td class="option-group" colspan="2">
3655 <kbd><span class="option">-i</span>, <span class="option">--interactive</span></kbd></td>
3656 </tr>
3657 <tr><td>&nbsp;</td><td>interactively select the changes</td></tr>
3658 <tr><td class="option-group" colspan="2">
3659 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3660 </tr>
3661 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
3662 <tr><td class="option-group" colspan="2">
3663 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3664 </tr>
3665 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
3666 <tr><td class="option-group">
3667 <kbd><span class="option">-n</span>, <span class="option">--dry-run</span></kbd></td>
3668 <td>do not perform actions, just print output</td></tr>
3669 </tbody>
3670 </table>
3671 <p>[+] marked option can be specified multiple times</p>
3672 </div>
3673 <div class="section" id="root">
3674 <h3>root</h3>
3675 <p>print the root (top) of the current working directory:</p>
3676 <pre class="literal-block">
3677 hg root
3678 </pre>
3679 <p>Print the root directory of the current repository.</p>
3680 <div class="verbose docutils container">
3681 <p>Template:</p>
3682 <p>The following keywords are supported in addition to the common template
3683 keywords and functions. See also <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help templates</tt></a>.</p>
3684 <table class="docutils field-list" frame="void" rules="none">
3685 <col class="field-name" />
3686 <col class="field-body" />
3687 <tbody valign="top">
3688 <tr class="field"><th class="field-name">hgpath:</th><td class="field-body">String. Path to the .hg directory.</td>
3689 </tr>
3690 <tr class="field"><th class="field-name">storepath:</th><td class="field-body">String. Path to the directory holding versioned data.</td>
3691 </tr>
3692 </tbody>
3693 </table>
3694 </div>
3695 <p>Returns 0 on success.</p>
3696 <p>Options:</p>
3697 <table class="docutils option-list" frame="void" rules="none">
3698 <col class="option" />
3699 <col class="description" />
3700 <tbody valign="top">
3701 <tr><td class="option-group">
3702 <kbd><span class="option">--share-source</span></kbd></td>
3703 <td>print the share source root instead</td></tr>
3704 <tr><td class="option-group" colspan="2">
3705 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
3706 </tr>
3707 <tr><td>&nbsp;</td><td>display with template</td></tr>
3708 </tbody>
3709 </table>
3710 </div>
3711 <div class="section" id="shelve">
3712 <h3>shelve</h3>
3713 <p>save and set aside changes from the working directory:</p>
3714 <pre class="literal-block">
3715 hg shelve [OPTION]... [FILE]...
3716 </pre>
3717 <p>Shelving takes files that &quot;hg status&quot; reports as not clean, saves
3718 the modifications to a bundle (a shelved change), and reverts the
3719 files so that their state in the working directory becomes clean.</p>
3720 <p>To restore these changes to the working directory, using &quot;hg
3721 unshelve&quot;; this will work even if you switch to a different
3722 commit.</p>
3723 <p>When no files are specified, &quot;hg shelve&quot; saves all not-clean
3724 files. If specific files or directories are named, only changes to
3725 those files are shelved.</p>
3726 <p>In bare shelve (when no files are specified, without interactive,
3727 include and exclude option), shelving remembers information if the
3728 working directory was on newly created branch, in other words working
3729 directory was on different branch than its first parent. In this
3730 situation unshelving restores branch information to the working directory.</p>
3731 <p>Each shelved change has a name that makes it easier to find later.
3732 The name of a shelved change defaults to being based on the active
3733 bookmark, or if there is no active bookmark, the current named
3734 branch. To specify a different name, use <tt class="docutils literal"><span class="pre">--name</span></tt>.</p>
3735 <p>To see a list of existing shelved changes, use the <tt class="docutils literal"><span class="pre">--list</span></tt>
3736 option. For each shelved change, this will print its name, age,
3737 and description; use <tt class="docutils literal"><span class="pre">--patch</span></tt> or <tt class="docutils literal"><span class="pre">--stat</span></tt> for more details.</p>
3738 <p>To delete specific shelved changes, use <tt class="docutils literal"><span class="pre">--delete</span></tt>. To delete
3739 all shelved changes, use <tt class="docutils literal"><span class="pre">--cleanup</span></tt>.</p>
3740 <p>Options:</p>
3741 <table class="docutils option-list" frame="void" rules="none">
3742 <col class="option" />
3743 <col class="description" />
3744 <tbody valign="top">
3745 <tr><td class="option-group" colspan="2">
3746 <kbd><span class="option">-A</span>, <span class="option">--addremove</span></kbd></td>
3747 </tr>
3748 <tr><td>&nbsp;</td><td>mark new/missing files as added/removed before shelving</td></tr>
3749 <tr><td class="option-group">
3750 <kbd><span class="option">-u</span>, <span class="option">--unknown</span></kbd></td>
3751 <td>store unknown files in the shelve</td></tr>
3752 <tr><td class="option-group">
3753 <kbd><span class="option">--cleanup</span></kbd></td>
3754 <td>delete all shelved changes</td></tr>
3755 <tr><td class="option-group">
3756 <kbd><span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
3757 <td>shelve with the specified commit date</td></tr>
3758 <tr><td class="option-group">
3759 <kbd><span class="option">-d</span>, <span class="option">--delete</span></kbd></td>
3760 <td>delete the named shelved change(s)</td></tr>
3761 <tr><td class="option-group">
3762 <kbd><span class="option">-e</span>, <span class="option">--edit</span></kbd></td>
3763 <td>invoke editor on commit messages</td></tr>
3764 <tr><td class="option-group">
3765 <kbd><span class="option">-k</span>, <span class="option">--keep</span></kbd></td>
3766 <td>shelve, but keep changes in the working directory</td></tr>
3767 <tr><td class="option-group">
3768 <kbd><span class="option">-l</span>, <span class="option">--list</span></kbd></td>
3769 <td>list current shelves</td></tr>
3770 <tr><td class="option-group" colspan="2">
3771 <kbd><span class="option">-m</span>, <span class="option">--message <var>&lt;TEXT&gt;</var></span></kbd></td>
3772 </tr>
3773 <tr><td>&nbsp;</td><td>use text as shelve message</td></tr>
3774 <tr><td class="option-group" colspan="2">
3775 <kbd><span class="option">-n</span>, <span class="option">--name <var>&lt;NAME&gt;</var></span></kbd></td>
3776 </tr>
3777 <tr><td>&nbsp;</td><td>use the given name for the shelved commit</td></tr>
3778 <tr><td class="option-group">
3779 <kbd><span class="option">-p</span>, <span class="option">--patch</span></kbd></td>
3780 <td>output patches for changes (provide the names of the shelved changes as positional arguments)</td></tr>
3781 <tr><td class="option-group" colspan="2">
3782 <kbd><span class="option">-i</span>, <span class="option">--interactive</span></kbd></td>
3783 </tr>
3784 <tr><td>&nbsp;</td><td>interactive mode</td></tr>
3785 <tr><td class="option-group">
3786 <kbd><span class="option">--stat</span></kbd></td>
3787 <td>output diffstat-style summary of changes (provide the names of the shelved changes as positional arguments)</td></tr>
3788 <tr><td class="option-group" colspan="2">
3789 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3790 </tr>
3791 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
3792 <tr><td class="option-group" colspan="2">
3793 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3794 </tr>
3795 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
3796 </tbody>
3797 </table>
3798 <p>[+] marked option can be specified multiple times</p>
3799 </div>
3800 <div class="section" id="status">
3801 <h3>status</h3>
3802 <p>show changed files in the working directory:</p>
3803 <pre class="literal-block">
3804 hg status [OPTION]... [FILE]...
3805 </pre>
3806 <p>Show status of files in the repository. If names are given, only
3807 files that match are shown. Files that are clean or ignored or
3808 the source of a copy/move operation, are not listed unless
3809 -c/--clean, -i/--ignored, -C/--copies or -A/--all are given.
3810 Unless options described with &quot;show only ...&quot; are given, the
3811 options -mardu are used.</p>
3812 <p>Option -q/--quiet hides untracked (unknown and ignored) files
3813 unless explicitly requested with -u/--unknown or -i/--ignored.</p>
3814 <div class="admonition note">
3815 <p class="first admonition-title">Note</p>
3816 <p class="last"><a class="reference external" href="hg.1.html#status"><tt class="docutils literal">hg status</tt></a> may appear to disagree with diff if permissions have
3817 changed or a merge has occurred. The standard diff format does
3818 not report permission changes and diff only reports changes
3819 relative to one merge parent.</p>
3820 </div>
3821 <p>If one revision is given, it is used as the base revision.
3822 If two revisions are given, the differences between them are
3823 shown. The --change option can also be used as a shortcut to list
3824 the changed files of a revision from its first parent.</p>
3825 <p>The codes used to show the status of files are:</p>
3826 <pre class="literal-block">
3827 M = modified
3828 A = added
3829 R = removed
3830 C = clean
3831 ! = missing (deleted by non-hg command, but still tracked)
3832 ? = not tracked
3833 I = ignored
3834 = origin of the previous file (with --copies)
3835 </pre>
3836 <div class="verbose docutils container">
3837 <p>The -t/--terse option abbreviates the output by showing only the directory
3838 name if all the files in it share the same status. The option takes an
3839 argument indicating the statuses to abbreviate: 'm' for 'modified', 'a'
3840 for 'added', 'r' for 'removed', 'd' for 'deleted', 'u' for 'unknown', 'i'
3841 for 'ignored' and 'c' for clean.</p>
3842 <p>It abbreviates only those statuses which are passed. Note that clean and
3843 ignored files are not displayed with '--terse ic' unless the -c/--clean
3844 and -i/--ignored options are also used.</p>
3845 <p>The -v/--verbose option shows information when the repository is in an
3846 unfinished merge, shelve, rebase state etc. You can have this behavior
3847 turned on by default by enabling the <tt class="docutils literal">commands.status.verbose</tt> option.</p>
3848 <p>You can skip displaying some of these states by setting
3849 <tt class="docutils literal">commands.status.skipstates</tt> to one or more of: 'bisect', 'graft',
3850 'histedit', 'merge', 'rebase', or 'unshelve'.</p>
3851 <p>Template:</p>
3852 <p>The following keywords are supported in addition to the common template
3853 keywords and functions. See also <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help templates</tt></a>.</p>
3854 <table class="docutils field-list" frame="void" rules="none">
3855 <col class="field-name" />
3856 <col class="field-body" />
3857 <tbody valign="top">
3858 <tr class="field"><th class="field-name">path:</th><td class="field-body">String. Repository-absolute path of the file.</td>
3859 </tr>
3860 <tr class="field"><th class="field-name">source:</th><td class="field-body">String. Repository-absolute path of the file originated from.
3861 Available if <tt class="docutils literal"><span class="pre">--copies</span></tt> is specified.</td>
3862 </tr>
3863 <tr class="field"><th class="field-name">status:</th><td class="field-body">String. Character denoting file's status.</td>
3864 </tr>
3865 </tbody>
3866 </table>
3867 <p>Examples:</p>
3868 <ul>
3869 <li><p class="first">show changes in the working directory relative to a
3870 changeset:</p>
3871 <pre class="literal-block">
3872 hg status --rev 9353
3873 </pre>
3874 </li>
3875 <li><p class="first">show changes in the working directory relative to the
3876 current directory (see <a class="reference external" href="hg.1.html#patterns"><tt class="docutils literal">hg help patterns</tt></a> for more information):</p>
3877 <pre class="literal-block">
3878 hg status re:
3879 </pre>
3880 </li>
3881 <li><p class="first">show all changes including copies in an existing changeset:</p>
3882 <pre class="literal-block">
3883 hg status --copies --change 9353
3884 </pre>
3885 </li>
3886 <li><p class="first">get a NUL separated list of added files, suitable for xargs:</p>
3887 <pre class="literal-block">
3888 hg status -an0
3889 </pre>
3890 </li>
3891 <li><p class="first">show more information about the repository status, abbreviating
3892 added, removed, modified, deleted, and untracked paths:</p>
3893 <pre class="literal-block">
3894 hg status -v -t mardu
3895 </pre>
3896 </li>
3897 </ul>
3898 </div>
3899 <p>Returns 0 on success.</p>
3900 <p>Options:</p>
3901 <table class="docutils option-list" frame="void" rules="none">
3902 <col class="option" />
3903 <col class="description" />
3904 <tbody valign="top">
3905 <tr><td class="option-group">
3906 <kbd><span class="option">-A</span>, <span class="option">--all</span></kbd></td>
3907 <td>show status of all files</td></tr>
3908 <tr><td class="option-group">
3909 <kbd><span class="option">-m</span>, <span class="option">--modified</span></kbd></td>
3910 <td>show only modified files</td></tr>
3911 <tr><td class="option-group">
3912 <kbd><span class="option">-a</span>, <span class="option">--added</span></kbd></td>
3913 <td>show only added files</td></tr>
3914 <tr><td class="option-group">
3915 <kbd><span class="option">-r</span>, <span class="option">--removed</span></kbd></td>
3916 <td>show only removed files</td></tr>
3917 <tr><td class="option-group">
3918 <kbd><span class="option">-d</span>, <span class="option">--deleted</span></kbd></td>
3919 <td>show only missing files</td></tr>
3920 <tr><td class="option-group">
3921 <kbd><span class="option">-c</span>, <span class="option">--clean</span></kbd></td>
3922 <td>show only files without changes</td></tr>
3923 <tr><td class="option-group">
3924 <kbd><span class="option">-u</span>, <span class="option">--unknown</span></kbd></td>
3925 <td>show only unknown (not tracked) files</td></tr>
3926 <tr><td class="option-group">
3927 <kbd><span class="option">-i</span>, <span class="option">--ignored</span></kbd></td>
3928 <td>show only ignored files</td></tr>
3929 <tr><td class="option-group" colspan="2">
3930 <kbd><span class="option">-n</span>, <span class="option">--no-status</span></kbd></td>
3931 </tr>
3932 <tr><td>&nbsp;</td><td>hide status prefix</td></tr>
3933 <tr><td class="option-group" colspan="2">
3934 <kbd><span class="option">-t</span>, <span class="option">--terse <var>&lt;VALUE&gt;</var></span></kbd></td>
3935 </tr>
3936 <tr><td>&nbsp;</td><td>show the terse output (EXPERIMENTAL) (default: nothing)</td></tr>
3937 <tr><td class="option-group">
3938 <kbd><span class="option">-C</span>, <span class="option">--copies</span></kbd></td>
3939 <td>show source of copied files (DEFAULT: ui.statuscopies)</td></tr>
3940 <tr><td class="option-group">
3941 <kbd><span class="option">-0</span>, <span class="option">--print0</span></kbd></td>
3942 <td>end filenames with NUL, for use with xargs</td></tr>
3943 <tr><td class="option-group">
3944 <kbd><span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
3945 <td>show difference from revision</td></tr>
3946 <tr><td class="option-group">
3947 <kbd><span class="option">--change <var>&lt;REV&gt;</var></span></kbd></td>
3948 <td>list the changed files of a revision</td></tr>
3949 <tr><td class="option-group" colspan="2">
3950 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3951 </tr>
3952 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
3953 <tr><td class="option-group" colspan="2">
3954 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
3955 </tr>
3956 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
3957 <tr><td class="option-group">
3958 <kbd><span class="option">-S</span>, <span class="option">--subrepos</span></kbd></td>
3959 <td>recurse into subrepositories</td></tr>
3960 <tr><td class="option-group" colspan="2">
3961 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
3962 </tr>
3963 <tr><td>&nbsp;</td><td>display with template</td></tr>
3964 </tbody>
3965 </table>
3966 <p>[+] marked option can be specified multiple times</p>
3967 <!-- -->
3968 <blockquote>
3969 aliases: st</blockquote>
3970 </div>
3971 <div class="section" id="summary">
3972 <h3>summary</h3>
3973 <p>summarize working directory state:</p>
3974 <pre class="literal-block">
3975 hg summary [--remote]
3976 </pre>
3977 <p>This generates a brief summary of the working directory state,
3978 including parents, branch, commit status, phase and available updates.</p>
3979 <p>With the --remote option, this will check the default paths for
3980 incoming and outgoing changes. This can be time-consuming.</p>
3981 <p>Returns 0 on success.</p>
3982 <p>Options:</p>
3983 <table class="docutils option-list" frame="void" rules="none">
3984 <col class="option" />
3985 <col class="description" />
3986 <tbody valign="top">
3987 <tr><td class="option-group">
3988 <kbd><span class="option">--remote</span></kbd></td>
3989 <td>check for push and pull</td></tr>
3990 </tbody>
3991 </table>
3992 <!-- -->
3993 <blockquote>
3994 aliases: sum</blockquote>
3995 </div>
3996 <div class="section" id="unshelve">
3997 <h3>unshelve</h3>
3998 <p>restore a shelved change to the working directory:</p>
3999 <pre class="literal-block">
4000 hg unshelve [OPTION]... [[-n] SHELVED]
4001 </pre>
4002 <p>This command accepts an optional name of a shelved change to
4003 restore. If none is given, the most recent shelved change is used.</p>
4004 <p>If a shelved change is applied successfully, the bundle that
4005 contains the shelved changes is moved to a backup location
4006 (.hg/shelve-backup).</p>
4007 <p>Since you can restore a shelved change on top of an arbitrary
4008 commit, it is possible that unshelving will result in a conflict
4009 between your changes and the commits you are unshelving onto. If
4010 this occurs, you must resolve the conflict, then use
4011 <tt class="docutils literal"><span class="pre">--continue</span></tt> to complete the unshelve operation. (The bundle
4012 will not be moved until you successfully complete the unshelve.)</p>
4013 <p>(Alternatively, you can use <tt class="docutils literal"><span class="pre">--abort</span></tt> to abandon an unshelve
4014 that causes a conflict. This reverts the unshelved changes, and
4015 leaves the bundle in place.)</p>
4016 <p>If bare shelved change (without interactive, include and exclude
4017 option) was done on newly created branch it would restore branch
4018 information to the working directory.</p>
4019 <p>After a successful unshelve, the shelved changes are stored in a
4020 backup directory. Only the N most recent backups are kept. N
4021 defaults to 10 but can be overridden using the <tt class="docutils literal">shelve.maxbackups</tt>
4022 configuration option.</p>
4023 <div class="verbose docutils container">
4024 <p>Timestamp in seconds is used to decide order of backups. More
4025 than <tt class="docutils literal">maxbackups</tt> backups are kept, if same timestamp
4026 prevents from deciding exact order of them, for safety.</p>
4027 <p>Selected changes can be unshelved with <tt class="docutils literal"><span class="pre">--interactive</span></tt> flag.
4028 The working directory is updated with the selected changes, and
4029 only the unselected changes remain shelved.
4030 Note: The whole shelve is applied to working directory first before
4031 running interactively. So, this will bring up all the conflicts between
4032 working directory and the shelve, irrespective of which changes will be
4033 unshelved.</p>
4034 </div>
4035 <p>Options:</p>
4036 <table class="docutils option-list" frame="void" rules="none">
4037 <col class="option" />
4038 <col class="description" />
4039 <tbody valign="top">
4040 <tr><td class="option-group">
4041 <kbd><span class="option">-a</span>, <span class="option">--abort</span></kbd></td>
4042 <td>abort an incomplete unshelve operation</td></tr>
4043 <tr><td class="option-group">
4044 <kbd><span class="option">-c</span>, <span class="option">--continue</span></kbd></td>
4045 <td>continue an incomplete unshelve operation</td></tr>
4046 <tr><td class="option-group" colspan="2">
4047 <kbd><span class="option">-i</span>, <span class="option">--interactive</span></kbd></td>
4048 </tr>
4049 <tr><td>&nbsp;</td><td>use interactive mode (EXPERIMENTAL)</td></tr>
4050 <tr><td class="option-group">
4051 <kbd><span class="option">-k</span>, <span class="option">--keep</span></kbd></td>
4052 <td>keep shelve after unshelving</td></tr>
4053 <tr><td class="option-group" colspan="2">
4054 <kbd><span class="option">-n</span>, <span class="option">--name <var>&lt;NAME&gt;</var></span></kbd></td>
4055 </tr>
4056 <tr><td>&nbsp;</td><td>restore shelved change with given name</td></tr>
4057 <tr><td class="option-group" colspan="2">
4058 <kbd><span class="option">-t</span>, <span class="option">--tool <var>&lt;VALUE&gt;</var></span></kbd></td>
4059 </tr>
4060 <tr><td>&nbsp;</td><td>specify merge tool</td></tr>
4061 <tr><td class="option-group">
4062 <kbd><span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
4063 <td>set date for temporary commits (DEPRECATED)</td></tr>
4064 </tbody>
4065 </table>
4066 </div>
4067 <div class="section" id="update">
4068 <h3>update</h3>
4069 <p>update working directory (or switch revisions):</p>
4070 <pre class="literal-block">
4071 hg update [-C|-c|-m] [-d DATE] [[-r] REV]
4072 </pre>
4073 <p>Update the repository's working directory to the specified
4074 changeset. If no changeset is specified, update to the tip of the
4075 current named branch and move the active bookmark (see <a class="reference external" href="hg.1.html#bookmarks"><tt class="docutils literal">hg help
4076 bookmarks</tt></a>).</p>
4077 <p>Update sets the working directory's parent revision to the specified
4078 changeset (see <a class="reference external" href="hg.1.html#parents"><tt class="docutils literal">hg help parents</tt></a>).</p>
4079 <p>If the changeset is not a descendant or ancestor of the working
4080 directory's parent and there are uncommitted changes, the update is
4081 aborted. With the -c/--check option, the working directory is checked
4082 for uncommitted changes; if none are found, the working directory is
4083 updated to the specified changeset.</p>
4084 <div class="verbose docutils container">
4085 <p>The -C/--clean, -c/--check, and -m/--merge options control what
4086 happens if the working directory contains uncommitted changes.
4087 At most of one of them can be specified.</p>
4088 <ol class="arabic simple">
4089 <li>If no option is specified, and if
4090 the requested changeset is an ancestor or descendant of
4091 the working directory's parent, the uncommitted changes
4092 are merged into the requested changeset and the merged
4093 result is left uncommitted. If the requested changeset is
4094 not an ancestor or descendant (that is, it is on another
4095 branch), the update is aborted and the uncommitted changes
4096 are preserved.</li>
4097 <li>With the -m/--merge option, the update is allowed even if the
4098 requested changeset is not an ancestor or descendant of
4099 the working directory's parent.</li>
4100 <li>With the -c/--check option, the update is aborted and the
4101 uncommitted changes are preserved.</li>
4102 <li>With the -C/--clean option, uncommitted changes are discarded and
4103 the working directory is updated to the requested changeset.</li>
4104 </ol>
4105 </div>
4106 <p>To cancel an uncommitted merge (and lose your changes), use
4107 <a class="reference external" href="hg.1.html#merge"><tt class="docutils literal">hg merge <span class="pre">--abort</span></tt></a>.</p>
4108 <p>Use null as the changeset to remove the working directory (like
4109 <a class="reference external" href="hg.1.html#clone"><tt class="docutils literal">hg clone <span class="pre">-U</span></tt></a>).</p>
4110 <p>If you want to revert just one file to an older revision, use
4111 <a class="reference external" href="hg.1.html#revert"><tt class="docutils literal">hg revert <span class="pre">[-r</span> REV] NAME</tt></a>.</p>
4112 <p>See <a class="reference external" href="hg.1.html#dates"><tt class="docutils literal">hg help dates</tt></a> for a list of formats valid for -d/--date.</p>
4113 <p>Returns 0 on success, 1 if there are unresolved files.</p>
4114 <p>Options:</p>
4115 <table class="docutils option-list" frame="void" rules="none">
4116 <col class="option" />
4117 <col class="description" />
4118 <tbody valign="top">
4119 <tr><td class="option-group">
4120 <kbd><span class="option">-C</span>, <span class="option">--clean</span></kbd></td>
4121 <td>discard uncommitted changes (no backup)</td></tr>
4122 <tr><td class="option-group">
4123 <kbd><span class="option">-c</span>, <span class="option">--check</span></kbd></td>
4124 <td>require clean working directory</td></tr>
4125 <tr><td class="option-group">
4126 <kbd><span class="option">-m</span>, <span class="option">--merge</span></kbd></td>
4127 <td>merge uncommitted changes</td></tr>
4128 <tr><td class="option-group" colspan="2">
4129 <kbd><span class="option">-d</span>, <span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
4130 </tr>
4131 <tr><td>&nbsp;</td><td>tipmost revision matching date</td></tr>
4132 <tr><td class="option-group" colspan="2">
4133 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV&gt;</var></span></kbd></td>
4134 </tr>
4135 <tr><td>&nbsp;</td><td>revision</td></tr>
4136 <tr><td class="option-group" colspan="2">
4137 <kbd><span class="option">-t</span>, <span class="option">--tool <var>&lt;TOOL&gt;</var></span></kbd></td>
4138 </tr>
4139 <tr><td>&nbsp;</td><td>specify merge tool</td></tr>
4140 </tbody>
4141 </table>
4142 <!-- -->
4143 <blockquote>
4144 aliases: up checkout co</blockquote>
4145 </div>
4146 </div>
4147 <div class="section" id="change-import-export">
4148 <h2>Change import/export</h2>
4149 <div class="section" id="archive">
4150 <h3>archive</h3>
4151 <p>create an unversioned archive of a repository revision:</p>
4152 <pre class="literal-block">
4153 hg archive [OPTION]... DEST
4154 </pre>
4155 <p>By default, the revision used is the parent of the working
4156 directory; use -r/--rev to specify a different revision.</p>
4157 <p>The archive type is automatically detected based on file
4158 extension (to override, use -t/--type).</p>
4159 <div class="verbose docutils container">
4160 <p>Examples:</p>
4161 <ul>
4162 <li><p class="first">create a zip file containing the 1.0 release:</p>
4163 <pre class="literal-block">
4164 hg archive -r 1.0 project-1.0.zip
4165 </pre>
4166 </li>
4167 <li><p class="first">create a tarball excluding .hg files:</p>
4168 <pre class="literal-block">
4169 hg archive project.tar.gz -X &quot;.hg*&quot;
4170 </pre>
4171 </li>
4172 </ul>
4173 </div>
4174 <p>Valid types are:</p>
4175 <table class="docutils field-list" frame="void" rules="none">
4176 <col class="field-name" />
4177 <col class="field-body" />
4178 <tbody valign="top">
4179 <tr class="field"><th class="field-name"><tt class="docutils literal">files</tt>:</th><td class="field-body">a directory full of files (default)</td>
4180 </tr>
4181 <tr class="field"><th class="field-name"><tt class="docutils literal">tar</tt>:</th><td class="field-body">tar archive, uncompressed</td>
4182 </tr>
4183 <tr class="field"><th class="field-name"><tt class="docutils literal">tbz2</tt>:</th><td class="field-body">tar archive, compressed using bzip2</td>
4184 </tr>
4185 <tr class="field"><th class="field-name"><tt class="docutils literal">tgz</tt>:</th><td class="field-body">tar archive, compressed using gzip</td>
4186 </tr>
4187 <tr class="field"><th class="field-name"><tt class="docutils literal">txz</tt>:</th><td class="field-body">tar archive, compressed using lzma (only in Python 3)</td>
4188 </tr>
4189 <tr class="field"><th class="field-name"><tt class="docutils literal">uzip</tt>:</th><td class="field-body">zip archive, uncompressed</td>
4190 </tr>
4191 <tr class="field"><th class="field-name"><tt class="docutils literal">zip</tt>:</th><td class="field-body">zip archive, compressed using deflate</td>
4192 </tr>
4193 </tbody>
4194 </table>
4195 <p>The exact name of the destination archive or directory is given
4196 using a format string; see <a class="reference external" href="hg.1.html#export"><tt class="docutils literal">hg help export</tt></a> for details.</p>
4197 <p>Each member added to an archive file has a directory prefix
4198 prepended. Use -p/--prefix to specify a format string for the
4199 prefix. The default is the basename of the archive, with suffixes
4200 removed.</p>
4201 <p>Returns 0 on success.</p>
4202 <p>Options:</p>
4203 <table class="docutils option-list" frame="void" rules="none">
4204 <col class="option" />
4205 <col class="description" />
4206 <tbody valign="top">
4207 <tr><td class="option-group">
4208 <kbd><span class="option">--no-decode</span></kbd></td>
4209 <td>do not pass files through decoders</td></tr>
4210 <tr><td class="option-group" colspan="2">
4211 <kbd><span class="option">-p</span>, <span class="option">--prefix <var>&lt;PREFIX&gt;</var></span></kbd></td>
4212 </tr>
4213 <tr><td>&nbsp;</td><td>directory prefix for files in archive</td></tr>
4214 <tr><td class="option-group" colspan="2">
4215 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV&gt;</var></span></kbd></td>
4216 </tr>
4217 <tr><td>&nbsp;</td><td>revision to distribute</td></tr>
4218 <tr><td class="option-group" colspan="2">
4219 <kbd><span class="option">-t</span>, <span class="option">--type <var>&lt;TYPE&gt;</var></span></kbd></td>
4220 </tr>
4221 <tr><td>&nbsp;</td><td>type of distribution to create</td></tr>
4222 <tr><td class="option-group">
4223 <kbd><span class="option">-S</span>, <span class="option">--subrepos</span></kbd></td>
4224 <td>recurse into subrepositories</td></tr>
4225 <tr><td class="option-group" colspan="2">
4226 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
4227 </tr>
4228 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
4229 <tr><td class="option-group" colspan="2">
4230 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
4231 </tr>
4232 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
4233 </tbody>
4234 </table>
4235 <p>[+] marked option can be specified multiple times</p>
4236 </div>
4237 <div class="section" id="bundle">
4238 <h3>bundle</h3>
4239 <p>create a bundle file:</p>
4240 <pre class="literal-block">
4241 hg bundle [-f] [-t BUNDLESPEC] [-a] [-r REV]... [--base REV]... FILE [DEST]...
4242 </pre>
4243 <p>Generate a bundle file containing data to be transferred to another
4244 repository.</p>
4245 <p>To create a bundle containing all changesets, use -a/--all
4246 (or --base null). Otherwise, hg assumes the destination will have
4247 all the nodes you specify with --base parameters. Otherwise, hg
4248 will assume the repository has all the nodes in destination, or
4249 default-push/default if no destination is specified, where destination
4250 is the repositories you provide through DEST option.</p>
4251 <p>You can change bundle format with the -t/--type option. See
4252 <a class="reference external" href="hg.1.html#bundlespec"><tt class="docutils literal">hg help bundlespec</tt></a> for documentation on this format. By default,
4253 the most appropriate format is used and compression defaults to
4254 bzip2.</p>
4255 <p>The bundle file can then be transferred using conventional means
4256 and applied to another repository with the unbundle or pull
4257 command. This is useful when direct push and pull are not
4258 available or when exporting an entire repository is undesirable.</p>
4259 <p>Applying bundles preserves all changeset contents including
4260 permissions, copy/rename information, and revision history.</p>
4261 <p>Returns 0 on success, 1 if no changes found.</p>
4262 <p>Options:</p>
4263 <table class="docutils option-list" frame="void" rules="none">
4264 <col class="option" />
4265 <col class="description" />
4266 <tbody valign="top">
4267 <tr><td class="option-group">
4268 <kbd><span class="option">--exact</span></kbd></td>
4269 <td>compute the base from the revision specified</td></tr>
4270 <tr><td class="option-group">
4271 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
4272 <td>run even when the destination is unrelated</td></tr>
4273 <tr><td class="option-group" colspan="2">
4274 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
4275 </tr>
4276 <tr><td>&nbsp;</td><td>a changeset intended to be added to the destination</td></tr>
4277 <tr><td class="option-group" colspan="2">
4278 <kbd><span class="option">-b</span>, <span class="option">--branch <var>&lt;BRANCH[+]&gt;</var></span></kbd></td>
4279 </tr>
4280 <tr><td>&nbsp;</td><td>a specific branch you would like to bundle</td></tr>
4281 <tr><td class="option-group" colspan="2">
4282 <kbd><span class="option">--base <var>&lt;REV[+]&gt;</var></span></kbd></td>
4283 </tr>
4284 <tr><td>&nbsp;</td><td>a base changeset assumed to be available at the destination</td></tr>
4285 <tr><td class="option-group">
4286 <kbd><span class="option">-a</span>, <span class="option">--all</span></kbd></td>
4287 <td>bundle all changesets in the repository</td></tr>
4288 <tr><td class="option-group" colspan="2">
4289 <kbd><span class="option">-t</span>, <span class="option">--type <var>&lt;TYPE&gt;</var></span></kbd></td>
4290 </tr>
4291 <tr><td>&nbsp;</td><td>bundle compression type to use (default: bzip2)</td></tr>
4292 <tr><td class="option-group" colspan="2">
4293 <kbd><span class="option">-e</span>, <span class="option">--ssh <var>&lt;CMD&gt;</var></span></kbd></td>
4294 </tr>
4295 <tr><td>&nbsp;</td><td>specify ssh command to use</td></tr>
4296 <tr><td class="option-group" colspan="2">
4297 <kbd><span class="option">--remotecmd <var>&lt;CMD&gt;</var></span></kbd></td>
4298 </tr>
4299 <tr><td>&nbsp;</td><td>specify hg command to run on the remote side</td></tr>
4300 <tr><td class="option-group">
4301 <kbd><span class="option">--insecure</span></kbd></td>
4302 <td>do not verify server certificate (ignoring web.cacerts config)</td></tr>
4303 </tbody>
4304 </table>
4305 <p>[+] marked option can be specified multiple times</p>
4306 </div>
4307 <div class="section" id="export">
4308 <h3>export</h3>
4309 <p>dump the header and diffs for one or more changesets:</p>
4310 <pre class="literal-block">
4311 hg export [OPTION]... [-o OUTFILESPEC] [-r] [REV]...
4312 </pre>
4313 <p>Print the changeset header and diffs for one or more revisions.
4314 If no revision is given, the parent of the working directory is used.</p>
4315 <p>The information shown in the changeset header is: author, date,
4316 branch name (if non-default), changeset hash, parent(s) and commit
4317 comment.</p>
4318 <div class="admonition note">
4319 <p class="first admonition-title">Note</p>
4320 <p class="last"><a class="reference external" href="hg.1.html#export"><tt class="docutils literal">hg export</tt></a> may generate unexpected diff output for merge
4321 changesets, as it will compare the merge changeset against its
4322 first parent only.</p>
4323 </div>
4324 <p>Output may be to a file, in which case the name of the file is
4325 given using a template string. See <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help templates</tt></a>. In addition
4326 to the common template keywords, the following formatting rules are
4327 supported:</p>
4328 <table class="docutils field-list" frame="void" rules="none">
4329 <col class="field-name" />
4330 <col class="field-body" />
4331 <tbody valign="top">
4332 <tr class="field"><th class="field-name"><tt class="docutils literal">%%</tt>:</th><td class="field-body">literal &quot;%&quot; character</td>
4333 </tr>
4334 <tr class="field"><th class="field-name"><tt class="docutils literal">%H</tt>:</th><td class="field-body">changeset hash (40 hexadecimal digits)</td>
4335 </tr>
4336 <tr class="field"><th class="field-name"><tt class="docutils literal">%N</tt>:</th><td class="field-body">number of patches being generated</td>
4337 </tr>
4338 <tr class="field"><th class="field-name"><tt class="docutils literal">%R</tt>:</th><td class="field-body">changeset revision number</td>
4339 </tr>
4340 <tr class="field"><th class="field-name"><tt class="docutils literal">%b</tt>:</th><td class="field-body">basename of the exporting repository</td>
4341 </tr>
4342 <tr class="field"><th class="field-name"><tt class="docutils literal">%h</tt>:</th><td class="field-body">short-form changeset hash (12 hexadecimal digits)</td>
4343 </tr>
4344 <tr class="field"><th class="field-name"><tt class="docutils literal">%m</tt>:</th><td class="field-body">first line of the commit message (only alphanumeric characters)</td>
4345 </tr>
4346 <tr class="field"><th class="field-name"><tt class="docutils literal">%n</tt>:</th><td class="field-body">zero-padded sequence number, starting at 1</td>
4347 </tr>
4348 <tr class="field"><th class="field-name"><tt class="docutils literal">%r</tt>:</th><td class="field-body">zero-padded changeset revision number</td>
4349 </tr>
4350 <tr class="field"><th class="field-name"><tt class="docutils literal">\</tt>:</th><td class="field-body">literal &quot;&quot; character</td>
4351 </tr>
4352 </tbody>
4353 </table>
4354 <p>Without the -a/--text option, export will avoid generating diffs
4355 of files it detects as binary. With -a, export will generate a
4356 diff anyway, probably with undesirable results.</p>
4357 <p>With -B/--bookmark changesets reachable by the given bookmark are
4358 selected.</p>
4359 <p>Use the -g/--git option to generate diffs in the git extended diff
4360 format. See <a class="reference external" href="hg.1.html#diffs"><tt class="docutils literal">hg help diffs</tt></a> for more information.</p>
4361 <p>With the --switch-parent option, the diff will be against the
4362 second parent. It can be useful to review a merge.</p>
4363 <div class="verbose docutils container">
4364 <p>Template:</p>
4365 <p>The following keywords are supported in addition to the common template
4366 keywords and functions. See also <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help templates</tt></a>.</p>
4367 <table class="docutils field-list" frame="void" rules="none">
4368 <col class="field-name" />
4369 <col class="field-body" />
4370 <tbody valign="top">
4371 <tr class="field"><th class="field-name">diff:</th><td class="field-body">String. Diff content.</td>
4372 </tr>
4373 <tr class="field"><th class="field-name">parents:</th><td class="field-body">List of strings. Parent nodes of the changeset.</td>
4374 </tr>
4375 </tbody>
4376 </table>
4377 <p>Examples:</p>
4378 <ul>
4379 <li><p class="first">use export and import to transplant a bugfix to the current
4380 branch:</p>
4381 <pre class="literal-block">
4382 hg export -r 9353 | hg import -
4383 </pre>
4384 </li>
4385 <li><p class="first">export all the changesets between two revisions to a file with
4386 rename information:</p>
4387 <pre class="literal-block">
4388 hg export --git -r 123:150 &gt; changes.txt
4389 </pre>
4390 </li>
4391 <li><p class="first">split outgoing changes into a series of patches with
4392 descriptive names:</p>
4393 <pre class="literal-block">
4394 hg export -r &quot;outgoing()&quot; -o &quot;%n-%m.patch&quot;
4395 </pre>
4396 </li>
4397 </ul>
4398 </div>
4399 <p>Returns 0 on success.</p>
4400 <p>Options:</p>
4401 <table class="docutils option-list" frame="void" rules="none">
4402 <col class="option" />
4403 <col class="description" />
4404 <tbody valign="top">
4405 <tr><td class="option-group" colspan="2">
4406 <kbd><span class="option">-B</span>, <span class="option">--bookmark <var>&lt;BOOKMARK&gt;</var></span></kbd></td>
4407 </tr>
4408 <tr><td>&nbsp;</td><td>export changes only reachable by given bookmark</td></tr>
4409 <tr><td class="option-group" colspan="2">
4410 <kbd><span class="option">-o</span>, <span class="option">--output <var>&lt;FORMAT&gt;</var></span></kbd></td>
4411 </tr>
4412 <tr><td>&nbsp;</td><td>print output to file with formatted name</td></tr>
4413 <tr><td class="option-group" colspan="2">
4414 <kbd><span class="option">--switch-parent</span></kbd></td>
4415 </tr>
4416 <tr><td>&nbsp;</td><td>diff against the second parent</td></tr>
4417 <tr><td class="option-group" colspan="2">
4418 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
4419 </tr>
4420 <tr><td>&nbsp;</td><td>revisions to export</td></tr>
4421 <tr><td class="option-group">
4422 <kbd><span class="option">-a</span>, <span class="option">--text</span></kbd></td>
4423 <td>treat all files as text</td></tr>
4424 <tr><td class="option-group">
4425 <kbd><span class="option">-g</span>, <span class="option">--git</span></kbd></td>
4426 <td>use git extended diff format (DEFAULT: diff.git)</td></tr>
4427 <tr><td class="option-group">
4428 <kbd><span class="option">--binary</span></kbd></td>
4429 <td>generate binary diffs in git mode (default)</td></tr>
4430 <tr><td class="option-group">
4431 <kbd><span class="option">--nodates</span></kbd></td>
4432 <td>omit dates from diff headers</td></tr>
4433 <tr><td class="option-group" colspan="2">
4434 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
4435 </tr>
4436 <tr><td>&nbsp;</td><td>display with template</td></tr>
4437 </tbody>
4438 </table>
4439 <p>[+] marked option can be specified multiple times</p>
4440 </div>
4441 <div class="section" id="import">
4442 <h3>import</h3>
4443 <p>import an ordered set of patches:</p>
4444 <pre class="literal-block">
4445 hg import [OPTION]... PATCH...
4446 </pre>
4447 <p>Import a list of patches and commit them individually (unless
4448 --no-commit is specified).</p>
4449 <p>To read a patch from standard input (stdin), use &quot;-&quot; as the patch
4450 name. If a URL is specified, the patch will be downloaded from
4451 there.</p>
4452 <p>Import first applies changes to the working directory (unless
4453 --bypass is specified), import will abort if there are outstanding
4454 changes.</p>
4455 <p>Use --bypass to apply and commit patches directly to the
4456 repository, without affecting the working directory. Without
4457 --exact, patches will be applied on top of the working directory
4458 parent revision.</p>
4459 <p>You can import a patch straight from a mail message. Even patches
4460 as attachments work (to use the body part, it must have type
4461 text/plain or text/x-patch). From and Subject headers of email
4462 message are used as default committer and commit message. All
4463 text/plain body parts before first diff are added to the commit
4464 message.</p>
4465 <p>If the imported patch was generated by <a class="reference external" href="hg.1.html#export"><tt class="docutils literal">hg export</tt></a>, user and
4466 description from patch override values from message headers and
4467 body. Values given on command line with -m/--message and -u/--user
4468 override these.</p>
4469 <p>If --exact is specified, import will set the working directory to
4470 the parent of each patch before applying it, and will abort if the
4471 resulting changeset has a different ID than the one recorded in
4472 the patch. This will guard against various ways that portable
4473 patch formats and mail systems might fail to transfer Mercurial
4474 data or metadata. See <a class="reference external" href="hg.1.html#bundle"><tt class="docutils literal">hg bundle</tt></a> for lossless transmission.</p>
4475 <p>Use --partial to ensure a changeset will be created from the patch
4476 even if some hunks fail to apply. Hunks that fail to apply will be
4477 written to a &lt;target-file&gt;.rej file. Conflicts can then be resolved
4478 by hand before <a class="reference external" href="hg.1.html#commit"><tt class="docutils literal">hg commit <span class="pre">--amend</span></tt></a> is run to update the created
4479 changeset. This flag exists to let people import patches that
4480 partially apply without losing the associated metadata (author,
4481 date, description, ...).</p>
4482 <div class="admonition note">
4483 <p class="first admonition-title">Note</p>
4484 <p class="last">When no hunks apply cleanly, <a class="reference external" href="hg.1.html#import"><tt class="docutils literal">hg import <span class="pre">--partial</span></tt></a> will create
4485 an empty changeset, importing only the patch metadata.</p>
4486 </div>
4487 <p>With -s/--similarity, hg will attempt to discover renames and
4488 copies in the patch in the same way as <a class="reference external" href="hg.1.html#addremove"><tt class="docutils literal">hg addremove</tt></a>.</p>
4489 <p>It is possible to use external patch programs to perform the patch
4490 by setting the <tt class="docutils literal">ui.patch</tt> configuration option. For the default
4491 internal tool, the fuzz can also be configured via <tt class="docutils literal">patch.fuzz</tt>.
4492 See <a class="reference external" href="hgrc.5.html"><tt class="docutils literal">hg help config</tt></a> for more information about configuration
4493 files and how to use these options.</p>
4494 <p>See <a class="reference external" href="hg.1.html#dates"><tt class="docutils literal">hg help dates</tt></a> for a list of formats valid for -d/--date.</p>
4495 <div class="verbose docutils container">
4496 <p>Examples:</p>
4497 <ul>
4498 <li><p class="first">import a traditional patch from a website and detect renames:</p>
4499 <pre class="literal-block">
4500 hg import -s 80 http://example.com/bugfix.patch
4501 </pre>
4502 </li>
4503 <li><p class="first">import a changeset from an hgweb server:</p>
4504 <pre class="literal-block">
4505 hg import https://www.mercurial-scm.org/repo/hg/rev/5ca8c111e9aa
4506 </pre>
4507 </li>
4508 <li><p class="first">import all the patches in an Unix-style mbox:</p>
4509 <pre class="literal-block">
4510 hg import incoming-patches.mbox
4511 </pre>
4512 </li>
4513 <li><p class="first">import patches from stdin:</p>
4514 <pre class="literal-block">
4515 hg import -
4516 </pre>
4517 </li>
4518 <li><p class="first">attempt to exactly restore an exported changeset (not always
4519 possible):</p>
4520 <pre class="literal-block">
4521 hg import --exact proposed-fix.patch
4522 </pre>
4523 </li>
4524 <li><p class="first">use an external tool to apply a patch which is too fuzzy for
4525 the default internal tool.</p>
4526 <blockquote>
4527 <p>hg import --config ui.patch=&quot;patch --merge&quot; fuzzy.patch</p>
4528 </blockquote>
4529 </li>
4530 <li><p class="first">change the default fuzzing from 2 to a less strict 7</p>
4531 <blockquote>
4532 <p>hg import --config ui.fuzz=7 fuzz.patch</p>
4533 </blockquote>
4534 </li>
4535 </ul>
4536 </div>
4537 <p>Returns 0 on success, 1 on partial success (see --partial).</p>
4538 <p>Options:</p>
4539 <table class="docutils option-list" frame="void" rules="none">
4540 <col class="option" />
4541 <col class="description" />
4542 <tbody valign="top">
4543 <tr><td class="option-group" colspan="2">
4544 <kbd><span class="option">-p</span>, <span class="option">--strip <var>&lt;NUM&gt;</var></span></kbd></td>
4545 </tr>
4546 <tr><td>&nbsp;</td><td>directory strip option for patch. This has the same meaning as the corresponding patch option (default: 1)</td></tr>
4547 <tr><td class="option-group" colspan="2">
4548 <kbd><span class="option">-b</span>, <span class="option">--base <var>&lt;PATH&gt;</var></span></kbd></td>
4549 </tr>
4550 <tr><td>&nbsp;</td><td>base path (DEPRECATED)</td></tr>
4551 <tr><td class="option-group">
4552 <kbd><span class="option">--secret</span></kbd></td>
4553 <td>use the secret phase for committing</td></tr>
4554 <tr><td class="option-group">
4555 <kbd><span class="option">-e</span>, <span class="option">--edit</span></kbd></td>
4556 <td>invoke editor on commit messages</td></tr>
4557 <tr><td class="option-group">
4558 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
4559 <td>skip check for outstanding uncommitted changes (DEPRECATED)</td></tr>
4560 <tr><td class="option-group">
4561 <kbd><span class="option">--no-commit</span></kbd></td>
4562 <td>don't commit, just update the working directory</td></tr>
4563 <tr><td class="option-group">
4564 <kbd><span class="option">--bypass</span></kbd></td>
4565 <td>apply patch without touching the working directory</td></tr>
4566 <tr><td class="option-group">
4567 <kbd><span class="option">--partial</span></kbd></td>
4568 <td>commit even if some hunks fail</td></tr>
4569 <tr><td class="option-group">
4570 <kbd><span class="option">--exact</span></kbd></td>
4571 <td>abort if patch would apply lossily</td></tr>
4572 <tr><td class="option-group">
4573 <kbd><span class="option">--prefix <var>&lt;DIR&gt;</var></span></kbd></td>
4574 <td>apply patch to subdirectory</td></tr>
4575 <tr><td class="option-group" colspan="2">
4576 <kbd><span class="option">--import-branch</span></kbd></td>
4577 </tr>
4578 <tr><td>&nbsp;</td><td>use any branch information in patch (implied by --exact)</td></tr>
4579 <tr><td class="option-group" colspan="2">
4580 <kbd><span class="option">-m</span>, <span class="option">--message <var>&lt;TEXT&gt;</var></span></kbd></td>
4581 </tr>
4582 <tr><td>&nbsp;</td><td>use text as commit message</td></tr>
4583 <tr><td class="option-group" colspan="2">
4584 <kbd><span class="option">-l</span>, <span class="option">--logfile <var>&lt;FILE&gt;</var></span></kbd></td>
4585 </tr>
4586 <tr><td>&nbsp;</td><td>read commit message from file</td></tr>
4587 <tr><td class="option-group" colspan="2">
4588 <kbd><span class="option">-d</span>, <span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
4589 </tr>
4590 <tr><td>&nbsp;</td><td>record the specified date as commit date</td></tr>
4591 <tr><td class="option-group" colspan="2">
4592 <kbd><span class="option">-u</span>, <span class="option">--user <var>&lt;USER&gt;</var></span></kbd></td>
4593 </tr>
4594 <tr><td>&nbsp;</td><td>record the specified user as committer</td></tr>
4595 <tr><td class="option-group" colspan="2">
4596 <kbd><span class="option">-s</span>, <span class="option">--similarity <var>&lt;SIMILARITY&gt;</var></span></kbd></td>
4597 </tr>
4598 <tr><td>&nbsp;</td><td>guess renamed files by similarity (0&lt;=s&lt;=100)</td></tr>
4599 </tbody>
4600 </table>
4601 <!-- -->
4602 <blockquote>
4603 aliases: patch</blockquote>
4604 </div>
4605 <div class="section" id="unbundle">
4606 <h3>unbundle</h3>
4607 <p>apply one or more bundle files:</p>
4608 <pre class="literal-block">
4609 hg unbundle [-u] FILE...
4610 </pre>
4611 <p>Apply one or more bundle files generated by <a class="reference external" href="hg.1.html#bundle"><tt class="docutils literal">hg bundle</tt></a>.</p>
4612 <p>Returns 0 on success, 1 if an update has unresolved files.</p>
4613 <p>Options:</p>
4614 <table class="docutils option-list" frame="void" rules="none">
4615 <col class="option" />
4616 <col class="description" />
4617 <tbody valign="top">
4618 <tr><td class="option-group">
4619 <kbd><span class="option">-u</span>, <span class="option">--update</span></kbd></td>
4620 <td>update to new branch head if changesets were unbundled</td></tr>
4621 </tbody>
4622 </table>
4623 </div>
4624 </div>
4625 <div class="section" id="repository-maintenance">
4626 <h2>Repository maintenance</h2>
4627 <div class="section" id="admin-narrow-client">
4628 <h3>admin::narrow-client</h3>
4629 <p>Narrow-related client administration utils. (EXPERIMENTAL):</p>
4630 <pre class="literal-block">
4631 hg admin::narrow-client
4632 </pre>
4633 <p>This command is experimental and is subject to change.</p>
4634 <p>Options:</p>
4635 <table class="docutils option-list" frame="void" rules="none">
4636 <col class="option" />
4637 <col class="description" />
4638 <tbody valign="top">
4639 <tr><td class="option-group" colspan="2">
4640 <kbd><span class="option">--store-fingerprint</span></kbd></td>
4641 </tr>
4642 <tr><td>&nbsp;</td><td>get the fingerprint for this repo's store narrowspec</td></tr>
4643 </tbody>
4644 </table>
4645 </div>
4646 <div class="section" id="admin-narrow-server">
4647 <h3>admin::narrow-server</h3>
4648 <p>Narrow-related server administration utils. (EXPERIMENTAL):</p>
4649 <pre class="literal-block">
4650 hg admin::narrow-server
4651 </pre>
4652 <p>This command is experimental and is subject to change.</p>
4653 <p>Options:</p>
4654 <table class="docutils option-list" frame="void" rules="none">
4655 <col class="option" />
4656 <col class="description" />
4657 <tbody valign="top">
4658 <tr><td class="option-group" colspan="2">
4659 <kbd><span class="option">--shape-fingerprints</span></kbd></td>
4660 </tr>
4661 <tr><td>&nbsp;</td><td>list the fingerprint for each shape</td></tr>
4662 <tr><td class="option-group" colspan="2">
4663 <kbd><span class="option">--shape-patterns <var>&lt;SHAPE-PATTERNS&gt;</var></span></kbd></td>
4664 </tr>
4665 <tr><td>&nbsp;</td><td>list the path patterns for the given shape</td></tr>
4666 <tr><td class="option-group" colspan="2">
4667 <kbd><span class="option">--shape-narrow-patterns <var>&lt;SHAPE-NARROW-PATTERNS&gt;</var></span></kbd></td>
4668 </tr>
4669 <tr><td>&nbsp;</td><td>list the legacy narrow-style patterns for the given shape</td></tr>
4670 <tr><td class="option-group" colspan="2">
4671 <kbd><span class="option">--shape-files <var>&lt;VALUE&gt;</var></span></kbd></td>
4672 </tr>
4673 <tr><td>&nbsp;</td><td>list the files covered by the given shape</td></tr>
4674 <tr><td class="option-group" colspan="2">
4675 <kbd><span class="option">--shape-files-hidden <var>&lt;VALUE&gt;</var></span></kbd></td>
4676 </tr>
4677 <tr><td>&nbsp;</td><td>list this shape's files that are not in the working copy</td></tr>
4678 <tr><td class="option-group" colspan="2">
4679 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
4680 </tr>
4681 <tr><td>&nbsp;</td><td>display with template</td></tr>
4682 </tbody>
4683 </table>
4684 </div>
4685 <div class="section" id="admin-verify">
4686 <h3>admin::verify</h3>
4687 <p>verify the integrity of the repository:</p>
4688 <pre class="literal-block">
4689 hg admin::verify
4690 </pre>
4691 <p>Alternative UI to <cite>hg verify</cite> with a lot more control over the
4692 verification process and better error reporting.</p>
4693 <p>Options:</p>
4694 <table class="docutils option-list" frame="void" rules="none">
4695 <col class="option" />
4696 <col class="description" />
4697 <tbody valign="top">
4698 <tr><td class="option-group" colspan="2">
4699 <kbd><span class="option">-c</span>, <span class="option">--check <var>&lt;CHECK[+]&gt;</var></span></kbd></td>
4700 </tr>
4701 <tr><td>&nbsp;</td><td>add a check</td></tr>
4702 <tr><td class="option-group" colspan="2">
4703 <kbd><span class="option">-o</span>, <span class="option">--option <var>&lt;OPTION[+]&gt;</var></span></kbd></td>
4704 </tr>
4705 <tr><td>&nbsp;</td><td>pass an option to a check</td></tr>
4706 </tbody>
4707 </table>
4708 <p>[+] marked option can be specified multiple times</p>
4709 </div>
4710 <div class="section" id="manifest">
4711 <h3>manifest</h3>
4712 <p>output the current or given revision of the project manifest:</p>
4713 <pre class="literal-block">
4714 hg manifest [-r REV]
4715 </pre>
4716 <p>Print a list of version controlled files for the given revision.
4717 If no revision is given, the first parent of the working directory
4718 is used, or the null revision if no revision is checked out.</p>
4719 <p>With -v, print file permissions, symlink and executable bits.
4720 With --debug, print file revision hashes.</p>
4721 <p>If option --all is specified, the list of all files from all revisions
4722 is printed. This includes deleted and renamed files.</p>
4723 <p>Returns 0 on success.</p>
4724 <p>Options:</p>
4725 <table class="docutils option-list" frame="void" rules="none">
4726 <col class="option" />
4727 <col class="description" />
4728 <tbody valign="top">
4729 <tr><td class="option-group" colspan="2">
4730 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV&gt;</var></span></kbd></td>
4731 </tr>
4732 <tr><td>&nbsp;</td><td>revision to display</td></tr>
4733 <tr><td class="option-group">
4734 <kbd><span class="option">--all</span></kbd></td>
4735 <td>list files from all revisions</td></tr>
4736 <tr><td class="option-group" colspan="2">
4737 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
4738 </tr>
4739 <tr><td>&nbsp;</td><td>display with template</td></tr>
4740 </tbody>
4741 </table>
4742 </div>
4743 <div class="section" id="recover">
4744 <h3>recover</h3>
4745 <p>roll back an interrupted transaction:</p>
4746 <pre class="literal-block">
4747 hg recover
4748 </pre>
4749 <p>Recover from an interrupted commit or pull.</p>
4750 <p>This command tries to fix the repository status after an
4751 interrupted operation. It should only be necessary when Mercurial
4752 suggests it.</p>
4753 <p>Returns 0 if successful, 1 if nothing to recover or verify fails.</p>
4754 <p>Options:</p>
4755 <table class="docutils option-list" frame="void" rules="none">
4756 <col class="option" />
4757 <col class="description" />
4758 <tbody valign="top">
4759 <tr><td class="option-group">
4760 <kbd><span class="option">--verify</span></kbd></td>
4761 <td>run <cite>hg verify</cite> after successful recover</td></tr>
4762 </tbody>
4763 </table>
4764 </div>
4765 <div class="section" id="rollback">
4766 <h3>rollback</h3>
4767 <p>roll back the last transaction (DANGEROUS) (DEPRECATED):</p>
4768 <pre class="literal-block">
4769 hg rollback
4770 </pre>
4771 <p>Please use <a class="reference external" href="hg.1.html#commit"><tt class="docutils literal">hg commit <span class="pre">--amend</span></tt></a> instead of rollback to correct
4772 mistakes in the last commit.</p>
4773 <p>This command should be used with care. There is only one level of
4774 rollback, and there is no way to undo a rollback. It will also
4775 restore the dirstate at the time of the last transaction, losing
4776 any dirstate changes since that time. This command does not alter
4777 the working directory.</p>
4778 <p>Transactions are used to encapsulate the effects of all commands
4779 that create new changesets or propagate existing changesets into a
4780 repository.</p>
4781 <div class="verbose docutils container">
4782 <p>For example, the following commands are transactional, and their
4783 effects can be rolled back:</p>
4784 <ul class="simple">
4785 <li>commit</li>
4786 <li>import</li>
4787 <li>pull</li>
4788 <li>push (with this repository as the destination)</li>
4789 <li>unbundle</li>
4790 </ul>
4791 <p>To avoid permanent data loss, rollback will refuse to rollback a
4792 commit transaction if it isn't checked out. Use --force to
4793 override this protection.</p>
4794 <p>The rollback command can be entirely disabled by setting the
4795 <tt class="docutils literal">ui.rollback</tt> configuration setting to false. If you're here
4796 because you want to use rollback and it's disabled, you can
4797 re-enable the command by setting <tt class="docutils literal">ui.rollback</tt> to true.</p>
4798 </div>
4799 <p>This command is not intended for use on public repositories. Once
4800 changes are visible for pull by other users, rolling a transaction
4801 back locally is ineffective (someone else may already have pulled
4802 the changes). Furthermore, a race is possible with readers of the
4803 repository; for example an in-progress pull from the repository
4804 may fail if a rollback is performed.</p>
4805 <p>Returns 0 on success, 1 if no rollback data is available.</p>
4806 <p>Options:</p>
4807 <table class="docutils option-list" frame="void" rules="none">
4808 <col class="option" />
4809 <col class="description" />
4810 <tbody valign="top">
4811 <tr><td class="option-group">
4812 <kbd><span class="option">-n</span>, <span class="option">--dry-run</span></kbd></td>
4813 <td>do not perform actions, just print output</td></tr>
4814 <tr><td class="option-group">
4815 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
4816 <td>ignore safety measures</td></tr>
4817 </tbody>
4818 </table>
4819 </div>
4820 <div class="section" id="verify">
4821 <h3>verify</h3>
4822 <p>verify the integrity of the repository:</p>
4823 <pre class="literal-block">
4824 hg verify
4825 </pre>
4826 <p>Verify the integrity of the current repository.</p>
4827 <p>This will perform an extensive check of the repository's
4828 integrity, validating the hashes and checksums of each entry in
4829 the changelog, manifest, and tracked files, as well as the
4830 integrity of their crosslinks and indices.</p>
4831 <p>Please see <a class="reference external" href="https://mercurial-scm.org/wiki/RepositoryCorruption">https://mercurial-scm.org/wiki/RepositoryCorruption</a>
4832 for more information about recovery from corruption of the
4833 repository.</p>
4834 <p>For an alternative UI with a lot more control over the verification
4835 process and better error reporting, try <cite>hg help admin::verify</cite>.</p>
4836 <p>Returns 0 on success, 1 if errors are encountered.</p>
4837 <p>Options:</p>
4838 <table class="docutils option-list" frame="void" rules="none">
4839 <col class="option" />
4840 <col class="description" />
4841 <tbody valign="top">
4842 <tr><td class="option-group">
4843 <kbd><span class="option">--full</span></kbd></td>
4844 <td>perform more checks (EXPERIMENTAL)</td></tr>
4845 </tbody>
4846 </table>
4847 </div>
4848 </div>
4849 <div class="section" id="help">
4850 <h2>Help</h2>
4851 <div class="section" id="config">
4852 <h3>config</h3>
4853 <p>show combined config settings from all hgrc files:</p>
4854 <pre class="literal-block">
4855 hg config [-u] [NAME]...
4856 </pre>
4857 <p>With no arguments, print names and values of all config items.</p>
4858 <p>With one argument of the form section.name, print just the value
4859 of that config item.</p>
4860 <p>With multiple arguments, print names and values of all config
4861 items with matching section names or section.names.</p>
4862 <p>With --edit, start an editor on the user-level config file. With
4863 --global, edit the system-wide config file. With --local, edit the
4864 repository-level config file.</p>
4865 <p>With --source, the source (filename and line number) is printed
4866 for each config item.</p>
4867 <p>See <a class="reference external" href="hgrc.5.html"><tt class="docutils literal">hg help config</tt></a> for more information about config files.</p>
4868 <div class="verbose docutils container">
4869 <p>--non-shared flag is used to edit <cite>.hg/hgrc-not-shared</cite> config file.
4870 This file is not shared across shares when in share-safe mode.</p>
4871 <p>Template:</p>
4872 <p>The following keywords are supported. See also <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help templates</tt></a>.</p>
4873 <table class="docutils field-list" frame="void" rules="none">
4874 <col class="field-name" />
4875 <col class="field-body" />
4876 <tbody valign="top">
4877 <tr class="field"><th class="field-name">name:</th><td class="field-body">String. Config name.</td>
4878 </tr>
4879 <tr class="field"><th class="field-name">source:</th><td class="field-body">String. Filename and line number where the item is defined.</td>
4880 </tr>
4881 <tr class="field"><th class="field-name">value:</th><td class="field-body">String. Config value.</td>
4882 </tr>
4883 </tbody>
4884 </table>
4885 <p>The --shared flag can be used to edit the config file of shared source
4886 repository. It only works when you have shared using the experimental
4887 share safe feature.</p>
4888 </div>
4889 <p>Returns 0 on success, 1 if NAME does not exist.</p>
4890 <p>Options:</p>
4891 <table class="docutils option-list" frame="void" rules="none">
4892 <col class="option" />
4893 <col class="description" />
4894 <tbody valign="top">
4895 <tr><td class="option-group" colspan="2">
4896 <kbd><span class="option">-u</span>, <span class="option">--untrusted</span></kbd></td>
4897 </tr>
4898 <tr><td>&nbsp;</td><td>show untrusted configuration options</td></tr>
4899 <tr><td class="option-group" colspan="2">
4900 <kbd><span class="option">--exp-all-known</span></kbd></td>
4901 </tr>
4902 <tr><td>&nbsp;</td><td>show all known config option (EXPERIMENTAL)</td></tr>
4903 <tr><td class="option-group">
4904 <kbd><span class="option">-e</span>, <span class="option">--edit</span></kbd></td>
4905 <td>edit user config</td></tr>
4906 <tr><td class="option-group">
4907 <kbd><span class="option">-l</span>, <span class="option">--local</span></kbd></td>
4908 <td>edit repository config</td></tr>
4909 <tr><td class="option-group">
4910 <kbd><span class="option">--source</span></kbd></td>
4911 <td>show source of configuration value</td></tr>
4912 <tr><td class="option-group">
4913 <kbd><span class="option">--shared</span></kbd></td>
4914 <td>edit shared source repository config</td></tr>
4915 <tr><td class="option-group">
4916 <kbd><span class="option">--non-shared</span></kbd></td>
4917 <td>edit non shared config</td></tr>
4918 <tr><td class="option-group">
4919 <kbd><span class="option">-g</span>, <span class="option">--global</span></kbd></td>
4920 <td>edit global config</td></tr>
4921 <tr><td class="option-group" colspan="2">
4922 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
4923 </tr>
4924 <tr><td>&nbsp;</td><td>display with template</td></tr>
4925 </tbody>
4926 </table>
4927 <!-- -->
4928 <blockquote>
4929 aliases: showconfig debugconfig</blockquote>
4930 </div>
4931 <div class="section" id="help-1">
4932 <h3>help</h3>
4933 <p>show help for a given topic or a help overview:</p>
4934 <pre class="literal-block">
4935 hg help [-eck] [-s PLATFORM] [TOPIC]
4936 </pre>
4937 <p>With no arguments, print a list of commands with short help messages.</p>
4938 <p>Given a topic, extension, or command name, print help for that
4939 topic.</p>
4940 <p>Returns 0 if successful.</p>
4941 <p>Options:</p>
4942 <table class="docutils option-list" frame="void" rules="none">
4943 <col class="option" />
4944 <col class="description" />
4945 <tbody valign="top">
4946 <tr><td class="option-group" colspan="2">
4947 <kbd><span class="option">-e</span>, <span class="option">--extension</span></kbd></td>
4948 </tr>
4949 <tr><td>&nbsp;</td><td>show only help for extensions</td></tr>
4950 <tr><td class="option-group">
4951 <kbd><span class="option">-c</span>, <span class="option">--command</span></kbd></td>
4952 <td>show only help for commands</td></tr>
4953 <tr><td class="option-group">
4954 <kbd><span class="option">-k</span>, <span class="option">--keyword</span></kbd></td>
4955 <td>show topics matching keyword</td></tr>
4956 <tr><td class="option-group" colspan="2">
4957 <kbd><span class="option">-s</span>, <span class="option">--system <var>&lt;PLATFORM[+]&gt;</var></span></kbd></td>
4958 </tr>
4959 <tr><td>&nbsp;</td><td>show help for specific platform(s)</td></tr>
4960 </tbody>
4961 </table>
4962 <p>[+] marked option can be specified multiple times</p>
4963 </div>
4964 <div class="section" id="version">
4965 <h3>version</h3>
4966 <p>output version and copyright information:</p>
4967 <pre class="literal-block">
4968 hg version
4969 </pre>
4970 <div class="verbose docutils container">
4971 <p>Template:</p>
4972 <p>The following keywords are supported. See also <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help templates</tt></a>.</p>
4973 <table class="docutils field-list" frame="void" rules="none">
4974 <col class="field-name" />
4975 <col class="field-body" />
4976 <tbody valign="top">
4977 <tr class="field"><th class="field-name">extensions:</th><td class="field-body">List of extensions.</td>
4978 </tr>
4979 <tr class="field"><th class="field-name">ver:</th><td class="field-body">String. Version number.</td>
4980 </tr>
4981 </tbody>
4982 </table>
4983 <p>And each entry of <tt class="docutils literal">{extensions}</tt> provides the following sub-keywords
4984 in addition to <tt class="docutils literal">{ver}</tt>.</p>
4985 <table class="docutils field-list" frame="void" rules="none">
4986 <col class="field-name" />
4987 <col class="field-body" />
4988 <tbody valign="top">
4989 <tr class="field"><th class="field-name">bundled:</th><td class="field-body">Boolean. True if included in the release.</td>
4990 </tr>
4991 <tr class="field"><th class="field-name">name:</th><td class="field-body">String. Extension name.</td>
4992 </tr>
4993 </tbody>
4994 </table>
4995 </div>
4996 <p>Options:</p>
4997 <table class="docutils option-list" frame="void" rules="none">
4998 <col class="option" />
4999 <col class="description" />
5000 <tbody valign="top">
5001 <tr><td class="option-group" colspan="2">
5002 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
5003 </tr>
5004 <tr><td>&nbsp;</td><td>display with template</td></tr>
5005 </tbody>
5006 </table>
5007 </div>
5008 </div>
5009 <div class="section" id="uncategorized-commands">
5010 <h2>Uncategorized commands</h2>
5011 <div class="section" id="admin-chainsaw-update">
5012 <h3>admin::chainsaw-update</h3>
5013 <p>pull and update to a given revision, no matter what, (EXPERIMENTAL):</p>
5014 <pre class="literal-block">
5015 hg admin::chainsaw-update [OPTION] --rev REV --source SOURCE --dest DEST
5016 </pre>
5017 <p>Context of application: <em>some</em> Continuous Integration (CI) systems,
5018 packaging or deployment tools.</p>
5019 <p>Wanted end result: local repository at the given REPO_PATH, having the
5020 latest changes to the given revision and with a clean working directory
5021 updated at the given revision.</p>
5022 <p>chainsaw-update pulls from one source, then updates the working directory
5023 to the given revision, overcoming anything that would stand in the way.</p>
5024 <p>By default, it will:</p>
5025 <ul class="simple">
5026 <li>clone if the local repo does not exist yet, <strong>removing any directory
5027 at the given path</strong> that would not be a Mercurial repository.
5028 The initial clone is full by default, so that clonebundles can be
5029 applied. Use the --initial-clone-minimal flag to avoid this.</li>
5030 <li>break locks if needed, leading to possible corruption if there
5031 is a concurrent write access.</li>
5032 <li>perform recovery actions if needed</li>
5033 <li>revert any local modification.</li>
5034 <li>purge unknown and ignored files.</li>
5035 <li>go as far as to reclone if everything else failed (not implemented yet).</li>
5036 </ul>
5037 <p>DO NOT use it for anything else than performing a series
5038 of unattended updates, with full exclusive repository access each time
5039 and without any other local work than running build scripts.
5040 In case the local repository is a share (see <a class="reference external" href="hg.1.html#share"><tt class="docutils literal">hg help share</tt></a>), exclusive
5041 write access to the share source is also mandatory.</p>
5042 <p>It is recommended to run these commands with the <tt class="docutils literal">HGPLAIN</tt> environment
5043 variable (see <a class="reference external" href="hg.1.html#scripting"><tt class="docutils literal">hg scripting</tt></a>).</p>
5044 <p>Motivation: in Continuous Integration and Delivery systems (CI/CD), the
5045 occasional remnant or bogus lock are common sources of waste of time (both
5046 working time and calendar time). CI/CD scripts tend to grow with counter-
5047 measures, often done in urgency. Also, whilst it is neat to keep
5048 repositories from one job to the next (especially with large
5049 repositories), an exceptional recloning is better than missing a release
5050 deadline.</p>
5051 <p>Options:</p>
5052 <table class="docutils option-list" frame="void" rules="none">
5053 <col class="option" />
5054 <col class="description" />
5055 <tbody valign="top">
5056 <tr><td class="option-group" colspan="2">
5057 <kbd><span class="option">--purge-unknown</span></kbd></td>
5058 </tr>
5059 <tr><td>&nbsp;</td><td>Remove unversioned files before update. Disabling this can in some cases interfere with the update.See also <a class="reference external" href="hg.1.html#purge"><tt class="docutils literal">hg purge</tt></a>. (default: True)</td></tr>
5060 <tr><td class="option-group" colspan="2">
5061 <kbd><span class="option">--purge-ignored</span></kbd></td>
5062 </tr>
5063 <tr><td>&nbsp;</td><td>Remove ignored files before update. Disable this for instance to reuse previous compiler object files. See also <a class="reference external" href="hg.1.html#purge"><tt class="docutils literal">hg purge</tt></a>. (default: True)</td></tr>
5064 <tr><td class="option-group">
5065 <kbd><span class="option">--rev <var>&lt;VALUE&gt;</var></span></kbd></td>
5066 <td>revision to update to</td></tr>
5067 <tr><td class="option-group" colspan="2">
5068 <kbd><span class="option">--source <var>&lt;VALUE&gt;</var></span></kbd></td>
5069 </tr>
5070 <tr><td>&nbsp;</td><td>repository to clone from</td></tr>
5071 <tr><td class="option-group">
5072 <kbd><span class="option">--dest <var>&lt;VALUE&gt;</var></span></kbd></td>
5073 <td>repository to update to REV (possibly cloning)</td></tr>
5074 <tr><td class="option-group" colspan="2">
5075 <kbd><span class="option">--initial-clone-minimal</span></kbd></td>
5076 </tr>
5077 <tr><td>&nbsp;</td><td>Pull only the prescribed revision upon initial cloning. This has the side effect of ignoring clone-bundles, which if often slower on the client side and stressful to the server than applying available clone bundles.</td></tr>
5078 </tbody>
5079 </table>
5080 </div>
5081 </div>
5082 </div>
5083 <div class="section" id="bundle-file-formats">
5084 <span id="bundlespec"></span><h1><a class="toc-backref" href="#contents">Bundle File Formats</a></h1>
5085 <p>Mercurial supports generating standalone &quot;bundle&quot; files that hold repository
5086 data. These &quot;bundles&quot; are typically saved locally and used later or exchanged
5087 between different repositories, possibly on different machines. Example
5088 commands using bundles are <a class="reference external" href="hg.1.html#bundle"><tt class="docutils literal">hg bundle</tt></a> and <a class="reference external" href="hg.1.html#unbundle"><tt class="docutils literal">hg unbundle</tt></a>.</p>
5089 <p>Generation of bundle files is controlled by a &quot;bundle specification&quot;
5090 (&quot;bundlespec&quot;) string. This string tells the bundle generation process how
5091 to create the bundle.</p>
5092 <p>A &quot;bundlespec&quot; string is composed of the following elements:</p>
5093 <dl class="docutils">
5094 <dt>type</dt>
5095 <dd>A string denoting the bundle format to use.</dd>
5096 <dt>compression</dt>
5097 <dd>Denotes the compression engine to use compressing the raw bundle data.</dd>
5098 <dt>parameters</dt>
5099 <dd>Arbitrary key-value parameters to further control bundle generation.</dd>
5100 </dl>
5101 <p>A &quot;bundlespec&quot; string has the following formats:</p>
5102 <dl class="docutils">
5103 <dt>&lt;type&gt;</dt>
5104 <dd>The literal bundle format string is used.</dd>
5105 <dt>&lt;compression&gt;-&lt;type&gt;</dt>
5106 <dd>The compression engine and format are delimited by a hyphen (<tt class="docutils literal">-</tt>).</dd>
5107 </dl>
5108 <p>Optional parameters follow the <tt class="docutils literal">&lt;type&gt;</tt>. Parameters are URI escaped
5109 <tt class="docutils literal">key=value</tt> pairs. Each pair is delimited by a semicolon (<tt class="docutils literal">;</tt>). The
5110 first parameter begins after a <tt class="docutils literal">;</tt> immediately following the <tt class="docutils literal">&lt;type&gt;</tt>
5111 value.</p>
5112 <div class="section" id="available-types">
5113 <h2>Available Types</h2>
5114 <p>The following bundle &lt;type&gt; strings are available:</p>
5115 <dl class="docutils">
5116 <dt>v1</dt>
5117 <dd><p class="first">Produces a legacy &quot;changegroup&quot; version 1 bundle.</p>
5118 <p>This format is compatible with nearly all Mercurial clients because it is
5119 the oldest. However, it has some limitations, which is why it is no longer
5120 the default for new repositories.</p>
5121 <p><tt class="docutils literal">v1</tt> bundles can be used with modern repositories using the &quot;generaldelta&quot;
5122 storage format. However, it may take longer to produce the bundle and the
5123 resulting bundle may be significantly larger than a <tt class="docutils literal">v2</tt> bundle.</p>
5124 <p class="last"><tt class="docutils literal">v1</tt> bundles can only use the <tt class="docutils literal">gzip</tt>, <tt class="docutils literal">bzip2</tt>, and <tt class="docutils literal">none</tt> compression
5125 formats.</p>
5126 </dd>
5127 <dt>v2</dt>
5128 <dd><p class="first">Produces a version 2 bundle.</p>
5129 <p>Version 2 bundles are an extensible format that can store additional
5130 repository data (such as bookmarks and phases information) and they can
5131 store data more efficiently, resulting in smaller bundles.</p>
5132 <p class="last">Version 2 bundles can also use modern compression engines, such as
5133 <tt class="docutils literal">zstd</tt>, making them faster to compress and often smaller.</p>
5134 </dd>
5135 </dl>
5136 </div>
5137 <div class="section" id="available-compression-engines">
5138 <h2>Available Compression Engines</h2>
5139 <p>The following bundle &lt;compression&gt; engines can be used:</p>
5140 <dl class="docutils">
5141 <dt><tt class="docutils literal">bzip2</tt></dt>
5142 <dd><p class="first">An algorithm that produces smaller bundles than <tt class="docutils literal">gzip</tt>.</p>
5143 <p>All Mercurial clients should support this format.</p>
5144 <p>This engine will likely produce smaller bundles than <tt class="docutils literal">gzip</tt> but
5145 will be significantly slower, both during compression and
5146 decompression.</p>
5147 <p class="last">If available, the <tt class="docutils literal">zstd</tt> engine can yield similar or better
5148 compression at much higher speeds.</p>
5149 </dd>
5150 <dt><tt class="docutils literal">gzip</tt></dt>
5151 <dd><p class="first">zlib compression using the DEFLATE algorithm.</p>
5152 <p class="last">All Mercurial clients should support this format. The compression
5153 algorithm strikes a reasonable balance between compression ratio
5154 and size.</p>
5155 </dd>
5156 <dt><tt class="docutils literal">none</tt></dt>
5157 <dd><p class="first">No compression is performed.</p>
5158 <p class="last">Use this compression engine to explicitly disable compression.</p>
5159 </dd>
5160 </dl>
5161 <p>The compression engines can be prepended with <tt class="docutils literal">stream</tt> to create a streaming bundle.
5162 These are bundles that are extremely efficient to produce and consume,
5163 but do not have guaranteed compatibility with older clients.</p>
5164 </div>
5165 <div class="section" id="available-options">
5166 <h2>Available Options</h2>
5167 <p>The following options exist:</p>
5168 <dl class="docutils">
5169 <dt>changegroup</dt>
5170 <dd>Include the changegroup data in the bundle (default to True).</dd>
5171 <dt>cg.version</dt>
5172 <dd>Select the version of the changegroup to use. Available options are : 01,
5173 02, 03, or 04. By default it will be automatically selected according to the
5174 current repository format.</dd>
5175 <dt>cg.delta-compression</dt>
5176 <dd><p class="first">Starting with <cite>cg.version</cite> &quot;04&quot;, changegroups can include pre-compressed
5177 deltas that the receiving end might reuse as-is. If this option is omitted,
5178 no such delta will be part of the changegroup. The option accepts a
5179 comma-separated list of accepted compression formats. Supported format are:</p>
5180 <ul class="last simple">
5181 <li><dl class="first docutils">
5182 <dt>none: delta explicitly non-compressed (useful to prevent the receiver from</dt>
5183 <dd>even trying to compress such deltas)</dd>
5184 </dl>
5185 </li>
5186 <li>zlib: zlib-compressed delta</li>
5187 <li>zstd: zstd-compressed delta</li>
5188 </ul>
5189 </dd>
5190 <dt>obsolescence</dt>
5191 <dd>Include obsolescence-markers relevant to the bundled changesets.</dd>
5192 <dt>phases</dt>
5193 <dd>Include phase information relevant to the bundled changesets.</dd>
5194 <dt>revbranchcache</dt>
5195 <dd>Include the &quot;rev-branch&quot; cache inside the bundle.</dd>
5196 <dt>tagsfnodescache</dt>
5197 <dd>Include the &quot;tags-fnodes&quot; cache inside the bundle.</dd>
5198 </dl>
5199 </div>
5200 <div class="section" id="examples">
5201 <h2>Examples</h2>
5202 <dl class="docutils">
5203 <dt><tt class="docutils literal">v2</tt></dt>
5204 <dd>Produce a <tt class="docutils literal">v2</tt> bundle using default options, including compression.</dd>
5205 <dt><tt class="docutils literal"><span class="pre">none-v1</span></tt></dt>
5206 <dd>Produce a <tt class="docutils literal">v1</tt> bundle with no compression.</dd>
5207 <dt><tt class="docutils literal"><span class="pre">zstd-v2</span></tt></dt>
5208 <dd>Produce a <tt class="docutils literal">v2</tt> bundle with zstandard compression using default
5209 settings.</dd>
5210 <dt><tt class="docutils literal"><span class="pre">zstd-v1</span></tt></dt>
5211 <dd>This errors because <tt class="docutils literal">zstd</tt> is not supported for <tt class="docutils literal">v1</tt> types.</dd>
5212 <dt><tt class="docutils literal"><span class="pre">none-streamv2</span></tt></dt>
5213 <dd>Produce a <tt class="docutils literal">v2</tt> streaming bundle with no compression.</dd>
5214 <dt><tt class="docutils literal"><span class="pre">zstd-v2;obsolescence=true;phases=true</span></tt></dt>
5215 <dd>Produce a <tt class="docutils literal">v2</tt> bundle with zstandard compression which includes
5216 obsolescence markers and phases.</dd>
5217 </dl>
5218 </div>
5219 </div>
5220 <div class="section" id="colorizing-outputs">
5221 <span id="color"></span><h1><a class="toc-backref" href="#contents">Colorizing Outputs</a></h1>
5222 <p>Mercurial colorizes output from several commands.</p>
5223 <p>For example, the diff command shows additions in green and deletions
5224 in red, while the status command shows modified files in magenta. Many
5225 other commands have analogous colors. It is possible to customize
5226 these colors.</p>
5227 <p>To enable color (default) whenever possible use:</p>
5228 <pre class="literal-block">
5229 [ui]
5230 color = yes
5231 </pre>
5232 <p>To disable color use:</p>
5233 <pre class="literal-block">
5234 [ui]
5235 color = no
5236 </pre>
5237 <p>See <a class="reference external" href="hgrc.5.html#ui"><tt class="docutils literal">hg help config.ui.color</tt></a> for details.</p>
5238 <div class="windows docutils container">
5239 The default pager on Windows does not support color, so enabling the pager
5240 will effectively disable color. See <a class="reference external" href="hgrc.5.html#ui"><tt class="docutils literal">hg help config.ui.paginate</tt></a> to disable
5241 the pager. Alternately, MSYS and Cygwin shells provide <cite>less</cite> as a pager,
5242 which can be configured to support ANSI color mode. Windows 10 natively
5243 supports ANSI color mode.</div>
5244 <div class="section" id="mode">
5245 <h2>Mode</h2>
5246 <p>Mercurial can use various systems to display color. The supported modes are
5247 <tt class="docutils literal">ansi</tt>, <tt class="docutils literal">win32</tt>, and <tt class="docutils literal">terminfo</tt>. See <a class="reference external" href="hgrc.5.html#color"><tt class="docutils literal">hg help config.color</tt></a> for details
5248 about how to control the mode.</p>
5249 </div>
5250 <div class="section" id="effects">
5251 <h2>Effects</h2>
5252 <p>Other effects in addition to color, like bold and underlined text, are
5253 also available. By default, the terminfo database is used to find the
5254 terminal codes used to change color and effect. If terminfo is not
5255 available, then effects are rendered with the ECMA-48 SGR control
5256 function (aka ANSI escape codes).</p>
5257 <p>The available effects in terminfo mode are 'blink', 'bold', 'dim',
5258 'inverse', 'invisible', 'italic', 'standout', and 'underline'; in
5259 ECMA-48 mode, the options are 'bold', 'inverse', 'italic', and
5260 'underline'. How each is rendered depends on the terminal emulator.
5261 Some may not be available for a given terminal type, and will be
5262 silently ignored.</p>
5263 <p>If the terminfo entry for your terminal is missing codes for an effect
5264 or has the wrong codes, you can add or override those codes in your
5265 configuration:</p>
5266 <pre class="literal-block">
5267 [color]
5268 terminfo.dim = \E[2m
5269 </pre>
5270 <p>where 'E' is substituted with an escape character.</p>
5271 </div>
5272 <div class="section" id="labels">
5273 <h2>Labels</h2>
5274 <p>Text receives color effects depending on the labels that it has. Many
5275 default Mercurial commands emit labelled text. You can also define
5276 your own labels in templates using the label function, see <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help
5277 templates</tt></a>. In order to receive effects, labels must have a dot, such
5278 as <cite>log.secret</cite> or <cite>branch.active</cite>. A single portion of text may have
5279 more than one label. In that case, effects given to the last label
5280 will override any other effects. This includes the special &quot;none&quot;
5281 effect, which nullifies other effects.</p>
5282 <p>Labels are normally invisible. In order to see these labels and their
5283 position in the text, use the global --color=debug option. The same
5284 anchor text may be associated to multiple labels, e.g.</p>
5285 <blockquote>
5286 [log.changeset changeset.secret|changeset: 22611:6f0a53c8f587]</blockquote>
5287 <p>The following are the default effects for some default labels. Default
5288 effects may be overridden from your configuration file:</p>
5289 <pre class="literal-block">
5290 [color]
5291 status.modified = blue bold underline red_background
5292 status.added = green bold
5293 status.removed = red bold blue_background
5294 status.deleted = cyan bold underline
5295 status.unknown = magenta bold underline
5296 status.ignored = black bold
5297
5298 # 'none' turns off all effects
5299 status.clean = none
5300 status.copied = none
5301
5302 qseries.applied = blue bold underline
5303 qseries.unapplied = black bold
5304 qseries.missing = red bold
5305
5306 diff.diffline = bold
5307 diff.extended = cyan bold
5308 diff.file_a = red bold
5309 diff.file_b = green bold
5310 diff.hunk = magenta
5311 diff.deleted = red
5312 diff.inserted = green
5313 diff.changed = white
5314 diff.tab =
5315 diff.trailingwhitespace = bold red_background
5316
5317 # Blank so it inherits the style of the surrounding label
5318 changeset.public =
5319 changeset.draft =
5320 changeset.secret =
5321
5322 resolve.unresolved = red bold
5323 resolve.resolved = green bold
5324
5325 bookmarks.active = green
5326
5327 branches.active = none
5328 branches.closed = black bold
5329 branches.current = green
5330 branches.inactive = none
5331
5332 tags.normal = green
5333 tags.local = black bold
5334
5335 rebase.rebased = blue
5336 rebase.remaining = red bold
5337
5338 shelve.age = cyan
5339 shelve.newest = green bold
5340 shelve.name = blue bold
5341
5342 histedit.remaining = red bold
5343 </pre>
5344 </div>
5345 <div class="section" id="custom-colors">
5346 <h2>Custom colors</h2>
5347 <p>Because there are only eight standard colors, Mercurial allows you
5348 to define color names for other color slots which might be available
5349 for your terminal type, assuming terminfo mode. For instance:</p>
5350 <pre class="literal-block">
5351 color.brightblue = 12
5352 color.pink = 207
5353 color.orange = 202
5354 </pre>
5355 <p>to set 'brightblue' to color slot 12 (useful for 16 color terminals
5356 that have brighter colors defined in the upper eight) and, 'pink' and
5357 'orange' to colors in 256-color xterm's default color cube. These
5358 defined colors may then be used as any of the pre-defined eight,
5359 including appending '_background' to set the background to that color.</p>
5360 </div>
5361 </div>
5362 <div class="section" id="date-formats">
5363 <span id="dates"></span><h1><a class="toc-backref" href="#contents">Date Formats</a></h1>
5364 <p>Some commands allow the user to specify a date, e.g.:</p>
5365 <ul class="simple">
5366 <li>backout, commit, import, tag: Specify the commit date.</li>
5367 <li>log, revert, update: Select revision(s) by date.</li>
5368 </ul>
5369 <p>Many date formats are valid. Here are some examples:</p>
5370 <ul class="simple">
5371 <li><tt class="docutils literal">Wed Dec 6 13:18:29 2006</tt> (local timezone assumed)</li>
5372 <li><tt class="docutils literal">Dec 6 13:18 <span class="pre">-0600</span></tt> (year assumed, time offset provided)</li>
5373 <li><tt class="docutils literal">Dec 6 13:18 UTC</tt> (UTC and GMT are aliases for +0000)</li>
5374 <li><tt class="docutils literal">Dec 6</tt> (midnight)</li>
5375 <li><tt class="docutils literal">13:18</tt> (today assumed)</li>
5376 <li><tt class="docutils literal">3:39</tt> (3:39AM assumed)</li>
5377 <li><tt class="docutils literal">3:39pm</tt> (15:39)</li>
5378 <li><tt class="docutils literal"><span class="pre">2006-12-06</span> 13:18:29</tt> (ISO 8601 format)</li>
5379 <li><tt class="docutils literal"><span class="pre">2006-12-6</span> 13:18</tt></li>
5380 <li><tt class="docutils literal"><span class="pre">2006-12-6</span></tt></li>
5381 <li><tt class="docutils literal"><span class="pre">12-6</span></tt></li>
5382 <li><tt class="docutils literal">12/6</tt></li>
5383 <li><tt class="docutils literal">12/6/6</tt> (Dec 6 2006)</li>
5384 <li><tt class="docutils literal">today</tt> (midnight)</li>
5385 <li><tt class="docutils literal">yesterday</tt> (midnight)</li>
5386 <li><tt class="docutils literal">now</tt> - right now</li>
5387 </ul>
5388 <p>Lastly, there is Mercurial's internal format:</p>
5389 <ul class="simple">
5390 <li><tt class="docutils literal">1165411109 0</tt> (Wed Dec 6 13:18:29 2006 UTC)</li>
5391 </ul>
5392 <p>This is the internal representation format for dates. The first number
5393 is the number of seconds since the epoch (1970-01-01 00:00 UTC). The
5394 second is the offset of the local timezone, in seconds west of UTC
5395 (negative if the timezone is east of UTC).</p>
5396 <p>The log command also accepts date ranges:</p>
5397 <ul class="simple">
5398 <li><tt class="docutils literal">&lt;DATE</tt> - at or before a given date/time</li>
5399 <li><tt class="docutils literal">&gt;DATE</tt> - on or after a given date/time</li>
5400 <li><tt class="docutils literal">DATE to DATE</tt> - a date range, inclusive</li>
5401 <li><tt class="docutils literal"><span class="pre">-DAYS</span></tt> - within a given number of days from today</li>
5402 </ul>
5403 </div>
5404 <div class="section" id="deprecated-features">
5405 <span id="deprecated"></span><h1><a class="toc-backref" href="#contents">Deprecated Features</a></h1>
5406 <p>Mercurial evolves over time, some features, options, commands may be replaced by
5407 better and more secure alternatives. This topic will help you migrating your
5408 existing usage and/or configuration to newer features.</p>
5409 <div class="section" id="commands-1">
5410 <h2>Commands</h2>
5411 <p>The following commands are still available but their use are not recommended:</p>
5412 <p><tt class="docutils literal">locate</tt></p>
5413 <p>This command has been replaced by <cite>hg files</cite>.</p>
5414 <p><tt class="docutils literal">parents</tt></p>
5415 <p>This command can be replaced by <cite>hg summary</cite> or <cite>hg log</cite> with appropriate
5416 revsets. See <cite>hg help revsets</cite> for more information.</p>
5417 <p><tt class="docutils literal">tip</tt></p>
5418 <p>The recommended alternative is <cite>hg heads</cite>.</p>
5419 </div>
5420 <div class="section" id="options-1">
5421 <h2>Options</h2>
5422 <dl class="docutils">
5423 <dt><tt class="docutils literal">web.allowpull</tt></dt>
5424 <dd>Renamed to <cite>allow-pull</cite>.</dd>
5425 <dt><tt class="docutils literal">web.allow_push</tt></dt>
5426 <dd>Renamed to <cite>allow-push</cite>.</dd>
5427 </dl>
5428 </div>
5429 </div>
5430 <div class="section" id="diff-formats">
5431 <span id="diffs"></span><h1><a class="toc-backref" href="#contents">Diff Formats</a></h1>
5432 <p>Mercurial's default format for showing changes between two versions of
5433 a file is compatible with the unified format of GNU diff, which can be
5434 used by GNU patch and many other standard tools.</p>
5435 <p>While this standard format is often enough, it does not encode the
5436 following information:</p>
5437 <ul class="simple">
5438 <li>executable status and other permission bits</li>
5439 <li>copy or rename information</li>
5440 <li>changes in binary files</li>
5441 <li>creation or deletion of empty files</li>
5442 </ul>
5443 <p>Mercurial also supports the extended diff format from the git VCS
5444 which addresses these limitations. The git diff format is not produced
5445 by default because a few widespread tools still do not understand this
5446 format.</p>
5447 <p>This means that when generating diffs from a Mercurial repository
5448 (e.g. with <a class="reference external" href="hg.1.html#export"><tt class="docutils literal">hg export</tt></a>), you should be careful about things like file
5449 copies and renames or other things mentioned above, because when
5450 applying a standard diff to a different repository, this extra
5451 information is lost. Mercurial's internal operations (like push and
5452 pull) are not affected by this, because they use an internal binary
5453 format for communicating changes.</p>
5454 <p>To make Mercurial produce the git extended diff format, use the --git
5455 option available for many commands, or set 'git = True' in the [diff]
5456 section of your configuration file. You do not need to set this option
5457 when importing diffs in this format or using them in the mq extension.</p>
5458 </div>
5459 <div class="section" id="environment-variables">
5460 <span id="env"></span><span id="environment"></span><h1><a class="toc-backref" href="#contents">Environment Variables</a></h1>
5461 <dl class="docutils">
5462 <dt>HG</dt>
5463 <dd>Path to the 'hg' executable, automatically passed when running
5464 hooks, extensions or external tools. If unset or empty, this is
5465 the hg executable's name if it's frozen, or an executable named
5466 'hg' (with %PATHEXT% [defaulting to COM/EXE/BAT/CMD] extensions on
5467 Windows) is searched.</dd>
5468 <dt>HGEDITOR</dt>
5469 <dd><p class="first">This is the name of the editor to run when committing. See EDITOR.</p>
5470 <p class="last">(deprecated, see <a class="reference external" href="hgrc.5.html#ui"><tt class="docutils literal">hg help config.ui.editor</tt></a>)</p>
5471 </dd>
5472 <dt>HGENCODING</dt>
5473 <dd>This overrides the default locale setting detected by Mercurial.
5474 This setting is used to convert data including usernames,
5475 changeset descriptions, tag names, and branches. This setting can
5476 be overridden with the --encoding command-line option.</dd>
5477 <dt>HGENCODINGMODE</dt>
5478 <dd>This sets Mercurial's behavior for handling unknown characters
5479 while transcoding user input. The default is &quot;strict&quot;, which
5480 causes Mercurial to abort if it can't map a character. Other
5481 settings include &quot;replace&quot;, which replaces unknown characters, and
5482 &quot;ignore&quot;, which drops them. This setting can be overridden with
5483 the --encodingmode command-line option.</dd>
5484 <dt>HGENCODINGAMBIGUOUS</dt>
5485 <dd>This sets Mercurial's behavior for handling characters with
5486 &quot;ambiguous&quot; widths like accented Latin characters with East Asian
5487 fonts. By default, Mercurial assumes ambiguous characters are
5488 narrow, set this variable to &quot;wide&quot; if such characters cause
5489 formatting problems.</dd>
5490 <dt>HGMERGE</dt>
5491 <dd><p class="first">An executable to use for resolving merge conflicts. The program
5492 will be executed with three arguments: local file, remote file,
5493 ancestor file.</p>
5494 <p class="last">(deprecated, see <a class="reference external" href="hgrc.5.html#ui"><tt class="docutils literal">hg help config.ui.merge</tt></a>)</p>
5495 </dd>
5496 <dt>HGRCPATH</dt>
5497 <dd><p class="first">A list of files or directories to search for configuration
5498 files. Item separator is &quot;:&quot; on Unix, &quot;;&quot; on Windows. If HGRCPATH
5499 is not set, platform default search path is used. If empty, only
5500 the .hg/hgrc from the current repository is read.</p>
5501 <p>For each element in HGRCPATH:</p>
5502 <ul class="last simple">
5503 <li>if it's a directory, all files ending with .rc are added</li>
5504 <li>otherwise, the file itself will be added</li>
5505 </ul>
5506 </dd>
5507 <dt>HGRCSKIPREPO</dt>
5508 <dd>When set, the .hg/hgrc from repositories are not read.</dd>
5509 <dt>HGPLAIN</dt>
5510 <dd><p class="first">When set, this disables any configuration settings that might
5511 change Mercurial's default output. This includes encoding,
5512 defaults, verbose mode, debug mode, quiet mode, tracebacks, and
5513 localization. This can be useful when scripting against Mercurial
5514 in the face of existing user configuration.</p>
5515 <p>In addition to the features disabled by <tt class="docutils literal">HGPLAIN=</tt>, the following
5516 values can be specified to adjust behavior:</p>
5517 <dl class="docutils">
5518 <dt><tt class="docutils literal">+strictflags</tt></dt>
5519 <dd>Restrict parsing of command line flags.</dd>
5520 </dl>
5521 <p>Equivalent options set via command line flags or environment
5522 variables are not overridden.</p>
5523 <p class="last">See <a class="reference external" href="hg.1.html#scripting"><tt class="docutils literal">hg help scripting</tt></a> for details.</p>
5524 </dd>
5525 <dt>HGPLAINEXCEPT</dt>
5526 <dd><p class="first">This is a comma-separated list of features to preserve when
5527 HGPLAIN is enabled. Currently the following values are supported:</p>
5528 <dl class="docutils">
5529 <dt><tt class="docutils literal">alias</tt></dt>
5530 <dd>Don't remove aliases.</dd>
5531 <dt><tt class="docutils literal">color</tt></dt>
5532 <dd>Don't disable colored output.</dd>
5533 <dt><tt class="docutils literal">i18n</tt></dt>
5534 <dd>Preserve internationalization.</dd>
5535 <dt><tt class="docutils literal">revsetalias</tt></dt>
5536 <dd>Don't remove revset aliases.</dd>
5537 <dt><tt class="docutils literal">templatealias</tt></dt>
5538 <dd>Don't remove template aliases.</dd>
5539 <dt><tt class="docutils literal">progress</tt></dt>
5540 <dd>Don't hide progress output.</dd>
5541 </dl>
5542 <p class="last">Setting HGPLAINEXCEPT to anything (even an empty string) will
5543 enable plain mode.</p>
5544 </dd>
5545 <dt>HGUSER</dt>
5546 <dd><p class="first">This is the string used as the author of a commit. If not set,
5547 available values will be considered in this order:</p>
5548 <ul class="simple">
5549 <li>HGUSER (deprecated)</li>
5550 <li>configuration files from the HGRCPATH</li>
5551 <li>EMAIL</li>
5552 <li>interactive prompt</li>
5553 <li>LOGNAME (with <tt class="docutils literal">&#64;hostname</tt> appended)</li>
5554 </ul>
5555 <p class="last">(deprecated, see <a class="reference external" href="hgrc.5.html#ui"><tt class="docutils literal">hg help config.ui.username</tt></a>)</p>
5556 </dd>
5557 <dt>EMAIL</dt>
5558 <dd>May be used as the author of a commit; see HGUSER.</dd>
5559 <dt>LOGNAME</dt>
5560 <dd>May be used as the author of a commit; see HGUSER.</dd>
5561 <dt>VISUAL</dt>
5562 <dd>This is the name of the editor to use when committing. See EDITOR.</dd>
5563 <dt>EDITOR</dt>
5564 <dd>Sometimes Mercurial needs to open a text file in an editor for a
5565 user to modify, for example when writing commit messages. The
5566 editor it uses is determined by looking at the environment
5567 variables HGEDITOR, VISUAL and EDITOR, in that order. The first
5568 non-empty one is chosen. If all of them are empty, the editor
5569 defaults to 'vi'.</dd>
5570 <dt>PYTHONPATH</dt>
5571 <dd>This is used by Python to find imported modules and may need to be
5572 set appropriately if this Mercurial is not installed system-wide.</dd>
5573 <dt>HGZSTDPOLICY</dt>
5574 <dd><p class="first">Control which zstd implementation will be used for the Python code. This is
5575 a list of options in priority order.</p>
5576 <ul class="simple">
5577 <li>vendored: use the pinned version of python-zstandard shipped in Mercurial</li>
5578 <li>system: use a possibly installed &quot;zstandard&quot; python package</li>
5579 <li>none: don't use zstd (ommiting this will raise an error if the above
5580 fails)</li>
5581 </ul>
5582 <p>Default value is &quot;vendored,system,none&quot;</p>
5583 <p class="last">This variable might be deprecated in the future depending on how zstd wrapper
5584 library and they integration in Mercurial evolves. This config has no
5585 effect on the Rust code.</p>
5586 </dd>
5587 </dl>
5588 </div>
5589 <div class="section" id="safely-rewriting-history-experimental">
5590 <span id="evolution"></span><h1><a class="toc-backref" href="#contents">Safely rewriting history (EXPERIMENTAL)</a></h1>
5591 <p>Obsolescence markers make it possible to mark changesets that have been
5592 deleted or superseded in a new version of the changeset.</p>
5593 <p>Unlike the previous way of handling such changes, by stripping the old
5594 changesets from the repository, obsolescence markers can be propagated
5595 between repositories. This allows for a safe and simple way of exchanging
5596 mutable history and altering it after the fact. Changeset phases are
5597 respected, such that only draft and secret changesets can be altered (see
5598 <a class="reference external" href="hg.1.html#phases"><tt class="docutils literal">hg help phases</tt></a> for details).</p>
5599 <p>Obsolescence is tracked using &quot;obsolescence markers&quot;, a piece of metadata
5600 tracking which changesets have been made obsolete, potential successors for
5601 a given changeset, the moment the changeset was marked as obsolete, and the
5602 user who performed the rewriting operation. The markers are stored
5603 separately from standard changeset data can be exchanged without any of the
5604 precursor changesets, preventing unnecessary exchange of obsolescence data.</p>
5605 <p>The complete set of obsolescence markers describes a history of changeset
5606 modifications that is orthogonal to the repository history of file
5607 modifications. This changeset history allows for detection and automatic
5608 resolution of edge cases arising from multiple users rewriting the same part
5609 of history concurrently.</p>
5610 <div class="section" id="current-feature-status">
5611 <h2>Current feature status</h2>
5612 <p>This feature is still in development.</p>
5613 </div>
5614 <div class="section" id="instability">
5615 <h2>Instability</h2>
5616 <p>Rewriting changesets might introduce instability.</p>
5617 <p>There are two main kinds of instability: orphaning and diverging.</p>
5618 <p>Orphans are changesets left behind when their ancestors are rewritten.
5619 Divergence has two variants:</p>
5620 <ul class="simple">
5621 <li>Content-divergence occurs when independent rewrites of the same changesets
5622 lead to different results.</li>
5623 <li>Phase-divergence occurs when the old (obsolete) version of a changeset
5624 becomes public.</li>
5625 </ul>
5626 <p>It is possible to prevent local creation of orphans by using the following config:</p>
5627 <pre class="literal-block">
5628 [experimental]
5629 evolution.createmarkers = true
5630 evolution.exchange = true
5631 </pre>
5632 <p>You can also enable that option explicitly:</p>
5633 <pre class="literal-block">
5634 [experimental]
5635 evolution.createmarkers = true
5636 evolution.exchange = true
5637 evolution.allowunstable = true
5638 </pre>
5639 </div>
5640 </div>
5641 <div class="section" id="using-additional-features">
5642 <span id="extensions"></span><h1><a class="toc-backref" href="#contents">Using Additional Features</a></h1>
5643 <p>Mercurial has the ability to add new features through the use of
5644 extensions. Extensions may add new commands, add options to
5645 existing commands, change the default behavior of commands, or
5646 implement hooks.</p>
5647 <p>To enable the &quot;foo&quot; extension, either shipped with Mercurial or in the
5648 Python search path, create an entry for it in your configuration file,
5649 like this:</p>
5650 <pre class="literal-block">
5651 [extensions]
5652 foo =
5653 </pre>
5654 <p>You may also specify the full path to an extension:</p>
5655 <pre class="literal-block">
5656 [extensions]
5657 myfeature = ~/.hgext/myfeature.py
5658 </pre>
5659 <p>See <a class="reference external" href="hgrc.5.html"><tt class="docutils literal">hg help config</tt></a> for more information on configuration files.</p>
5660 <p>Extensions are not loaded by default for a variety of reasons:
5661 they can increase startup overhead; they may be meant for advanced
5662 usage only; they may provide potentially dangerous abilities (such
5663 as letting you destroy or modify history); they might not be ready
5664 for prime time; or they may alter some usual behaviors of stock
5665 Mercurial. It is thus up to the user to activate extensions as
5666 needed.</p>
5667 <p>To explicitly disable an extension enabled in a configuration file of
5668 broader scope, prepend its path with !:</p>
5669 <pre class="literal-block">
5670 [extensions]
5671 # disabling extension bar residing in /path/to/extension/bar.py
5672 bar = !/path/to/extension/bar.py
5673 # ditto, but no path was supplied for extension baz
5674 baz = !
5675 </pre>
5676 <p>disabled extensions:</p>
5677 <blockquote>
5678 <table class="docutils field-list" frame="void" rules="none">
5679 <col class="field-name" />
5680 <col class="field-body" />
5681 <tbody valign="top">
5682 <tr class="field"><th class="field-name">acl:</th><td class="field-body">hooks for controlling repository access</td>
5683 </tr>
5684 <tr class="field"><th class="field-name">blackbox:</th><td class="field-body">log repository events to a blackbox for debugging</td>
5685 </tr>
5686 <tr class="field"><th class="field-name">bugzilla:</th><td class="field-body">hooks for integrating with the Bugzilla bug tracker</td>
5687 </tr>
5688 <tr class="field"><th class="field-name">censor:</th><td class="field-body">erase file content at a given revision</td>
5689 </tr>
5690 <tr class="field"><th class="field-name">churn:</th><td class="field-body">command to display statistics about repository history</td>
5691 </tr>
5692 <tr class="field"><th class="field-name">clonebundles:</th><td class="field-body">advertise pre-generated bundles to seed clones</td>
5693 </tr>
5694 <tr class="field"><th class="field-name">closehead:</th><td class="field-body">close arbitrary heads without checking them out first</td>
5695 </tr>
5696 <tr class="field"><th class="field-name">convert:</th><td class="field-body">import revisions from foreign VCS repositories into Mercurial</td>
5697 </tr>
5698 <tr class="field"><th class="field-name">eol:</th><td class="field-body">automatically manage newlines in repository files</td>
5699 </tr>
5700 <tr class="field"><th class="field-name">extdiff:</th><td class="field-body">command to allow external programs to compare revisions</td>
5701 </tr>
5702 <tr class="field"><th class="field-name">factotum:</th><td class="field-body">http authentication with factotum</td>
5703 </tr>
5704 <tr class="field"><th class="field-name">fastexport:</th><td class="field-body">export repositories as git fast-import stream</td>
5705 </tr>
5706 <tr class="field"><th class="field-name">githelp:</th><td class="field-body">try mapping git commands to Mercurial commands</td>
5707 </tr>
5708 <tr class="field"><th class="field-name">gpg:</th><td class="field-body">commands to sign and verify changesets</td>
5709 </tr>
5710 <tr class="field"><th class="field-name">hgk:</th><td class="field-body">browse the repository in a graphical way</td>
5711 </tr>
5712 <tr class="field"><th class="field-name">highlight:</th><td class="field-body">syntax highlighting for hgweb (requires Pygments)</td>
5713 </tr>
5714 <tr class="field"><th class="field-name">histedit:</th><td class="field-body">interactive history editing</td>
5715 </tr>
5716 <tr class="field"><th class="field-name">keyword:</th><td class="field-body">expand keywords in tracked files</td>
5717 </tr>
5718 <tr class="field"><th class="field-name">largefiles:</th><td class="field-body">track large binary files</td>
5719 </tr>
5720 <tr class="field"><th class="field-name">mq:</th><td class="field-body">manage a stack of patches</td>
5721 </tr>
5722 <tr class="field"><th class="field-name">notify:</th><td class="field-body">hooks for sending email push notifications</td>
5723 </tr>
5724 <tr class="field"><th class="field-name">patchbomb:</th><td class="field-body">command to send changesets as (a series of) patch emails</td>
5725 </tr>
5726 <tr class="field"><th class="field-name">rebase:</th><td class="field-body">command to move sets of revisions to a different ancestor</td>
5727 </tr>
5728 <tr class="field"><th class="field-name">relink:</th><td class="field-body">recreates hardlinks between repository clones</td>
5729 </tr>
5730 <tr class="field"><th class="field-name">schemes:</th><td class="field-body">extend schemes with shortcuts to repository swarms</td>
5731 </tr>
5732 <tr class="field"><th class="field-name">share:</th><td class="field-body">share a common history between several working directories</td>
5733 </tr>
5734 <tr class="field"><th class="field-name">transplant:</th><td class="field-body">command to transplant changesets from another branch</td>
5735 </tr>
5736 <tr class="field"><th class="field-name">win32mbcs:</th><td class="field-body">allow the use of MBCS paths with problematic encodings</td>
5737 </tr>
5738 <tr class="field"><th class="field-name">zeroconf:</th><td class="field-body">discover and advertise repositories on the local network</td>
5739 </tr>
5740 </tbody>
5741 </table>
5742 </blockquote>
5743 </div>
5744 <div class="section" id="specifying-file-sets">
5745 <span id="fileset"></span><span id="filesets"></span><h1><a class="toc-backref" href="#contents">Specifying File Sets</a></h1>
5746 <p>Mercurial supports a functional language for selecting a set of
5747 files.</p>
5748 <p>Like other file patterns, this pattern type is indicated by a prefix,
5749 'set:'. The language supports a number of predicates which are joined
5750 by infix operators. Parenthesis can be used for grouping.</p>
5751 <p>Identifiers such as filenames or patterns must be quoted with single
5752 or double quotes if they contain characters outside of
5753 <tt class="docutils literal"><span class="pre">[.*{}[]?/\_a-zA-Z0-9\x80-\xff]</span></tt> or if they match one of the
5754 predefined predicates. This generally applies to file patterns other
5755 than globs and arguments for predicates. Pattern prefixes such as
5756 <tt class="docutils literal">path:</tt> may be specified without quoting.</p>
5757 <p>Special characters can be used in quoted identifiers by escaping them,
5758 e.g., <tt class="docutils literal">\n</tt> is interpreted as a newline. To prevent them from being
5759 interpreted, strings can be prefixed with <tt class="docutils literal">r</tt>, e.g. <tt class="docutils literal"><span class="pre">r'...'</span></tt>.</p>
5760 <p>See also <a class="reference external" href="hg.1.html#patterns"><tt class="docutils literal">hg help patterns</tt></a>.</p>
5761 <div class="section" id="operators">
5762 <h2>Operators</h2>
5763 <p>There is a single prefix operator:</p>
5764 <dl class="docutils">
5765 <dt><tt class="docutils literal">not x</tt></dt>
5766 <dd>Files not in x. Short form is <tt class="docutils literal">! x</tt>.</dd>
5767 </dl>
5768 <p>These are the supported infix operators:</p>
5769 <dl class="docutils">
5770 <dt><tt class="docutils literal">x and y</tt></dt>
5771 <dd>The intersection of files in x and y. Short form is <tt class="docutils literal">x &amp; y</tt>.</dd>
5772 <dt><tt class="docutils literal">x or y</tt></dt>
5773 <dd>The union of files in x and y. There are two alternative short
5774 forms: <tt class="docutils literal">x | y</tt> and <tt class="docutils literal">x + y</tt>.</dd>
5775 <dt><tt class="docutils literal">x - y</tt></dt>
5776 <dd>Files in x but not in y.</dd>
5777 </dl>
5778 </div>
5779 <div class="section" id="predicates">
5780 <h2>Predicates</h2>
5781 <p>The following predicates are supported:</p>
5782 <dl class="docutils">
5783 <dt><tt class="docutils literal">added()</tt></dt>
5784 <dd>File that is added according to <a class="reference external" href="hg.1.html#status"><tt class="docutils literal">hg status</tt></a>.</dd>
5785 <dt><tt class="docutils literal">binary()</tt></dt>
5786 <dd>File that appears to be binary (contains NUL bytes).</dd>
5787 <dt><tt class="docutils literal">clean()</tt></dt>
5788 <dd>File that is clean according to <a class="reference external" href="hg.1.html#status"><tt class="docutils literal">hg status</tt></a>.</dd>
5789 <dt><tt class="docutils literal">copied()</tt></dt>
5790 <dd>File that is recorded as being copied.</dd>
5791 <dt><tt class="docutils literal">deleted()</tt></dt>
5792 <dd>Alias for <tt class="docutils literal">missing()</tt>.</dd>
5793 <dt><tt class="docutils literal">encoding(name)</tt></dt>
5794 <dd>File can be successfully decoded with the given character
5795 encoding. May not be useful for encodings other than ASCII and
5796 UTF-8.</dd>
5797 <dt><tt class="docutils literal">eol(style)</tt></dt>
5798 <dd>File contains newlines of the given style (dos, unix, mac). Binary
5799 files are excluded, files with mixed line endings match multiple
5800 styles.</dd>
5801 <dt><tt class="docutils literal">exec()</tt></dt>
5802 <dd>File that is marked as executable.</dd>
5803 <dt><tt class="docutils literal">grep(regex)</tt></dt>
5804 <dd>File contains the given regular expression.</dd>
5805 <dt><tt class="docutils literal">hgignore()</tt></dt>
5806 <dd>File that matches the active .hgignore pattern.</dd>
5807 <dt><tt class="docutils literal">ignored()</tt></dt>
5808 <dd>File that is ignored according to <a class="reference external" href="hg.1.html#status"><tt class="docutils literal">hg status</tt></a>.</dd>
5809 <dt><tt class="docutils literal">missing()</tt></dt>
5810 <dd>File that is missing according to <a class="reference external" href="hg.1.html#status"><tt class="docutils literal">hg status</tt></a>.</dd>
5811 <dt><tt class="docutils literal">modified()</tt></dt>
5812 <dd>File that is modified according to <a class="reference external" href="hg.1.html#status"><tt class="docutils literal">hg status</tt></a>.</dd>
5813 <dt><tt class="docutils literal">portable()</tt></dt>
5814 <dd>File that has a portable name. (This doesn't include filenames with case
5815 collisions.)</dd>
5816 <dt><tt class="docutils literal">removed()</tt></dt>
5817 <dd>File that is removed according to <a class="reference external" href="hg.1.html#status"><tt class="docutils literal">hg status</tt></a>.</dd>
5818 <dt><tt class="docutils literal">resolved()</tt></dt>
5819 <dd>File that is marked resolved according to <a class="reference external" href="hg.1.html#resolve"><tt class="docutils literal">hg resolve <span class="pre">-l</span></tt></a>.</dd>
5820 <dt><tt class="docutils literal">revs(revs, pattern)</tt></dt>
5821 <dd>Evaluate set in the specified revisions. If the revset match multiple
5822 revs, this will return file matching pattern in any of the revision.</dd>
5823 <dt><tt class="docutils literal">size(expression)</tt></dt>
5824 <dd><p class="first">File size matches the given expression. Examples:</p>
5825 <ul class="last simple">
5826 <li>size('1k') - files from 1024 to 2047 bytes</li>
5827 <li>size('&lt; 20k') - files less than 20480 bytes</li>
5828 <li>size('&gt;= .5MB') - files at least 524288 bytes</li>
5829 <li>size('4k - 1MB') - files from 4096 bytes to 1048576 bytes</li>
5830 </ul>
5831 </dd>
5832 <dt><tt class="docutils literal">status(base, rev, pattern)</tt></dt>
5833 <dd><p class="first">Evaluate predicate using status change between <tt class="docutils literal">base</tt> and
5834 <tt class="docutils literal">rev</tt>. Examples:</p>
5835 <ul class="last simple">
5836 <li><tt class="docutils literal">status(3, 7, <span class="pre">added())</span></tt> - matches files added from &quot;3&quot; to &quot;7&quot;</li>
5837 </ul>
5838 </dd>
5839 <dt><tt class="docutils literal"><span class="pre">subrepo([pattern])</span></tt></dt>
5840 <dd>Subrepositories whose paths match the given pattern.</dd>
5841 <dt><tt class="docutils literal">symlink()</tt></dt>
5842 <dd>File that is marked as a symlink.</dd>
5843 <dt><tt class="docutils literal">tracked()</tt></dt>
5844 <dd>File that is under Mercurial control.</dd>
5845 <dt><tt class="docutils literal">unknown()</tt></dt>
5846 <dd>File that is unknown according to <a class="reference external" href="hg.1.html#status"><tt class="docutils literal">hg status</tt></a>.</dd>
5847 <dt><tt class="docutils literal">unresolved()</tt></dt>
5848 <dd>File that is marked unresolved according to <a class="reference external" href="hg.1.html#resolve"><tt class="docutils literal">hg resolve <span class="pre">-l</span></tt></a>.</dd>
5849 </dl>
5850 </div>
5851 <div class="section" id="examples-1">
5852 <h2>Examples</h2>
5853 <p>Some sample queries:</p>
5854 <ul>
5855 <li><p class="first">Show status of files that appear to be binary in the working directory:</p>
5856 <pre class="literal-block">
5857 hg status -A &quot;set:binary()&quot;
5858 </pre>
5859 </li>
5860 <li><p class="first">Forget files that are in .hgignore but are already tracked:</p>
5861 <pre class="literal-block">
5862 hg forget &quot;set:hgignore() and not ignored()&quot;
5863 </pre>
5864 </li>
5865 <li><p class="first">Find text files that contain a string:</p>
5866 <pre class="literal-block">
5867 hg files &quot;set:grep(magic) and not binary()&quot;
5868 </pre>
5869 </li>
5870 <li><p class="first">Find C files in a non-standard encoding:</p>
5871 <pre class="literal-block">
5872 hg files &quot;set:**.c and not encoding('UTF-8')&quot;
5873 </pre>
5874 </li>
5875 <li><p class="first">Revert copies of large binary files:</p>
5876 <pre class="literal-block">
5877 hg revert &quot;set:copied() and binary() and size('&gt;1M')&quot;
5878 </pre>
5879 </li>
5880 <li><p class="first">Revert files that were added to the working directory:</p>
5881 <pre class="literal-block">
5882 hg revert &quot;set:revs('wdir()', added())&quot;
5883 </pre>
5884 </li>
5885 <li><p class="first">Remove files listed in foo.lst that contain the letter a or b:</p>
5886 <pre class="literal-block">
5887 hg remove &quot;set: listfile:foo.lst and (**a* or **b*)&quot;
5888 </pre>
5889 </li>
5890 </ul>
5891 </div>
5892 </div>
5893 <div class="section" id="command-line-flags">
5894 <span id="flags"></span><h1><a class="toc-backref" href="#contents">Command-line flags</a></h1>
5895 <p>Most Mercurial commands accept various flags.</p>
5896 <div class="section" id="flag-names">
5897 <h2>Flag names</h2>
5898 <p>Flags for each command are listed in <a class="reference external" href="hg.1.html#help"><tt class="docutils literal">hg help</tt></a> for that command.
5899 Additionally, some flags, such as --repository, are global and can be used with
5900 any command - those are seen in <a class="reference external" href="hg.1.html#-v"><tt class="docutils literal">hg help <span class="pre">-v</span></tt></a>, and can be specified before or
5901 after the command.</p>
5902 <p>Every flag has at least a long name, such as --repository. Some flags may also
5903 have a short one-letter name, such as the equivalent -R. Using the short or long
5904 name is equivalent and has the same effect. The long name may be abbreviated to
5905 any unambiguous prefix. For example, <a class="reference external" href="hg.1.html#commit"><tt class="docutils literal">hg commit <span class="pre">--amend</span></tt></a> can be abbreviated
5906 to <a class="reference external" href="hg.1.html#commit"><tt class="docutils literal">hg commit <span class="pre">--am</span></tt></a>.</p>
5907 <p>Flags that have a short name can also be bundled together - for instance, to
5908 specify both --edit (short -e) and --interactive (short -i), one could use:</p>
5909 <pre class="literal-block">
5910 hg commit -ei
5911 </pre>
5912 <p>If any of the bundled flags takes a value (i.e. is not a boolean), it must be
5913 last, followed by the value:</p>
5914 <pre class="literal-block">
5915 hg commit -im 'Message'
5916 </pre>
5917 </div>
5918 <div class="section" id="flag-types">
5919 <h2>Flag types</h2>
5920 <p>Mercurial command-line flags can be strings, numbers, booleans, or lists of
5921 strings.</p>
5922 </div>
5923 <div class="section" id="specifying-flag-values">
5924 <h2>Specifying flag values</h2>
5925 <p>The following syntaxes are allowed, assuming a flag 'flagname' with short name
5926 'f':</p>
5927 <pre class="literal-block">
5928 --flagname=foo
5929 --flagname foo
5930 -f foo
5931 -ffoo
5932 </pre>
5933 <p>This syntax applies to all non-boolean flags (strings, numbers or lists).</p>
5934 </div>
5935 <div class="section" id="specifying-boolean-flags">
5936 <h2>Specifying boolean flags</h2>
5937 <p>Boolean flags do not take a value parameter. To specify a boolean, use the flag
5938 name to set it to true, or the same name prefixed with 'no-' to set it to
5939 false:</p>
5940 <pre class="literal-block">
5941 hg commit --interactive
5942 hg commit --no-interactive
5943 </pre>
5944 </div>
5945 <div class="section" id="specifying-list-flags">
5946 <h2>Specifying list flags</h2>
5947 <p>List flags take multiple values. To specify them, pass the flag multiple times:</p>
5948 <pre class="literal-block">
5949 hg files --include mercurial --include tests
5950 </pre>
5951 </div>
5952 <div class="section" id="setting-flag-defaults">
5953 <h2>Setting flag defaults</h2>
5954 <p>In order to set a default value for a flag in an hgrc file, it is recommended to
5955 use aliases:</p>
5956 <pre class="literal-block">
5957 [alias]
5958 commit = commit --interactive
5959 </pre>
5960 <p>For more information on hgrc files, see <a class="reference external" href="hgrc.5.html"><tt class="docutils literal">hg help config</tt></a>.</p>
5961 </div>
5962 <div class="section" id="overriding-flags-on-the-command-line">
5963 <h2>Overriding flags on the command line</h2>
5964 <p>If the same non-list flag is specified multiple times on the command line, the
5965 latest specification is used:</p>
5966 <pre class="literal-block">
5967 hg commit -m &quot;Ignored value&quot; -m &quot;Used value&quot;
5968 </pre>
5969 <p>This includes the use of aliases - e.g., if one has:</p>
5970 <pre class="literal-block">
5971 [alias]
5972 committemp = commit -m &quot;Ignored value&quot;
5973 </pre>
5974 <p>then the following command will override that -m:</p>
5975 <pre class="literal-block">
5976 hg committemp -m &quot;Used value&quot;
5977 </pre>
5978 </div>
5979 <div class="section" id="overriding-flag-defaults">
5980 <h2>Overriding flag defaults</h2>
5981 <p>Every flag has a default value, and you may also set your own defaults in hgrc
5982 as described above.
5983 Except for list flags, defaults can be overridden on the command line simply by
5984 specifying the flag in that location.</p>
5985 </div>
5986 <div class="section" id="hidden-flags">
5987 <h2>Hidden flags</h2>
5988 <p>Some flags are not shown in a command's help by default - specifically, those
5989 that are deemed to be experimental, deprecated or advanced. To show all flags,
5990 add the --verbose flag for the help command:</p>
5991 <pre class="literal-block">
5992 hg help --verbose commit
5993 </pre>
5994 </div>
5995 </div>
5996 <div class="section" id="glossary-1">
5997 <span id="glossary"></span><h1><a class="toc-backref" href="#contents">Glossary</a></h1>
5998 <dl class="docutils">
5999 <dt>Ancestor</dt>
6000 <dd>Any changeset that can be reached by an unbroken chain of parent
6001 changesets from a given changeset. More precisely, the ancestors
6002 of a changeset can be defined by two properties: a parent of a
6003 changeset is an ancestor, and a parent of an ancestor is an
6004 ancestor. See also: 'Descendant'.</dd>
6005 <dt>Bookmark</dt>
6006 <dd><p class="first">Bookmarks are pointers to certain commits that move when
6007 committing. They are similar to tags in that it is possible to use
6008 bookmark names in all places where Mercurial expects a changeset
6009 ID, e.g., with <a class="reference external" href="hg.1.html#update"><tt class="docutils literal">hg update</tt></a>. Unlike tags, bookmarks move along
6010 when you make a commit.</p>
6011 <p class="last">Bookmarks can be renamed, copied and deleted. Bookmarks are local,
6012 unless they are explicitly pushed or pulled between repositories.
6013 Pushing and pulling bookmarks allow you to collaborate with others
6014 on a branch without creating a named branch.</p>
6015 </dd>
6016 <dt>Branch</dt>
6017 <dd><p class="first">(Noun) A child changeset that has been created from a parent that
6018 is not a head. These are known as topological branches, see
6019 'Branch, topological'. If a topological branch is named, it becomes
6020 a named branch. If a topological branch is not named, it becomes
6021 an anonymous branch. See 'Branch, anonymous' and 'Branch, named'.</p>
6022 <p>Branches may be created when changes are pulled from or pushed to
6023 a remote repository, since new heads may be created by these
6024 operations. Note that the term branch can also be used informally
6025 to describe a development process in which certain development is
6026 done independently of other development. This is sometimes done
6027 explicitly with a named branch, but it can also be done locally,
6028 using bookmarks or clones and anonymous branches.</p>
6029 <p>Example: &quot;The experimental branch.&quot;</p>
6030 <p>(Verb) The action of creating a child changeset which results in
6031 its parent having more than one child.</p>
6032 <p class="last">Example: &quot;I'm going to branch at X.&quot;</p>
6033 </dd>
6034 <dt>Branch, anonymous</dt>
6035 <dd>Every time a new child changeset is created from a parent that is not
6036 a head and the name of the branch is not changed, a new anonymous
6037 branch is created.</dd>
6038 <dt>Branch, closed</dt>
6039 <dd>A named branch whose branch heads have all been closed.</dd>
6040 <dt>Branch, default</dt>
6041 <dd>The branch assigned to a changeset when no name has previously been
6042 assigned.</dd>
6043 <dt>Branch head</dt>
6044 <dd>See 'Head, branch'.</dd>
6045 <dt>Branch, inactive</dt>
6046 <dd><p class="first">If a named branch has no topological heads, it is considered to be
6047 inactive. As an example, a feature branch becomes inactive when it
6048 is merged into the default branch. The <a class="reference external" href="hg.1.html#branches"><tt class="docutils literal">hg branches</tt></a> command
6049 shows inactive branches by default, though they can be hidden with
6050 <a class="reference external" href="hg.1.html#branches"><tt class="docutils literal">hg branches <span class="pre">--active</span></tt></a>.</p>
6051 <p class="last">NOTE: this concept is deprecated because it is too implicit.
6052 Branches should now be explicitly closed using <a class="reference external" href="hg.1.html#commit"><tt class="docutils literal">hg commit
6053 <span class="pre">--close-branch</span></tt></a> when they are no longer needed.</p>
6054 </dd>
6055 <dt>Branch, named</dt>
6056 <dd><p class="first">A collection of changesets which have the same branch name. By
6057 default, children of a changeset in a named branch belong to the
6058 same named branch. A child can be explicitly assigned to a
6059 different branch. See <a class="reference external" href="hg.1.html#branch"><tt class="docutils literal">hg help branch</tt></a>, <a class="reference external" href="hg.1.html#branches"><tt class="docutils literal">hg help branches</tt></a> and
6060 <a class="reference external" href="hg.1.html#commit"><tt class="docutils literal">hg commit <span class="pre">--close-branch</span></tt></a> for more information on managing
6061 branches.</p>
6062 <p class="last">Named branches can be thought of as a kind of namespace, dividing
6063 the collection of changesets that comprise the repository into a
6064 collection of disjoint subsets. A named branch is not necessarily
6065 a topological branch. If a new named branch is created from the
6066 head of another named branch, or the default branch, but no
6067 further changesets are added to that previous branch, then that
6068 previous branch will be a branch in name only.</p>
6069 </dd>
6070 <dt>Branch tip</dt>
6071 <dd>See 'Tip, branch'.</dd>
6072 <dt>Branch, topological</dt>
6073 <dd>Every time a new child changeset is created from a parent that is
6074 not a head, a new topological branch is created. If a topological
6075 branch is named, it becomes a named branch. If a topological
6076 branch is not named, it becomes an anonymous branch of the
6077 current, possibly default, branch.</dd>
6078 <dt>Changelog</dt>
6079 <dd>A record of the changesets in the order in which they were added
6080 to the repository. This includes details such as changeset id,
6081 author, commit message, date, and list of changed files.</dd>
6082 <dt>Changeset</dt>
6083 <dd>A snapshot of the state of the repository used to record a change.</dd>
6084 <dt>Changeset, child</dt>
6085 <dd>The converse of parent changeset: if P is a parent of C, then C is
6086 a child of P. There is no limit to the number of children that a
6087 changeset may have.</dd>
6088 <dt>Changeset id</dt>
6089 <dd>A SHA-1 hash that uniquely identifies a changeset. It may be
6090 represented as either a &quot;long&quot; 40 hexadecimal digit string, or a
6091 &quot;short&quot; 12 hexadecimal digit string.</dd>
6092 <dt>Changeset, merge</dt>
6093 <dd>A changeset with two parents. This occurs when a merge is
6094 committed.</dd>
6095 <dt>Changeset, parent</dt>
6096 <dd>A revision upon which a child changeset is based. Specifically, a
6097 parent changeset of a changeset C is a changeset whose node
6098 immediately precedes C in the DAG. Changesets have at most two
6099 parents.</dd>
6100 <dt>Checkout</dt>
6101 <dd><p class="first">(Noun) The working directory being updated to a specific
6102 revision. This use should probably be avoided where possible, as
6103 changeset is much more appropriate than checkout in this context.</p>
6104 <p>Example: &quot;I'm using checkout X.&quot;</p>
6105 <p>(Verb) Updating the working directory to a specific changeset. See
6106 <a class="reference external" href="hg.1.html#update"><tt class="docutils literal">hg help update</tt></a>.</p>
6107 <p class="last">Example: &quot;I'm going to check out changeset X.&quot;</p>
6108 </dd>
6109 <dt>Child changeset</dt>
6110 <dd>See 'Changeset, child'.</dd>
6111 <dt>Close changeset</dt>
6112 <dd>See 'Head, closed branch'.</dd>
6113 <dt>Closed branch</dt>
6114 <dd>See 'Branch, closed'.</dd>
6115 <dt>Clone</dt>
6116 <dd><p class="first">(Noun) An entire or partial copy of a repository. The partial
6117 clone must be in the form of a revision and its ancestors.</p>
6118 <p>Example: &quot;Is your clone up to date?&quot;</p>
6119 <p>(Verb) The process of creating a clone, using <a class="reference external" href="hg.1.html#clone"><tt class="docutils literal">hg clone</tt></a>.</p>
6120 <p class="last">Example: &quot;I'm going to clone the repository.&quot;</p>
6121 </dd>
6122 <dt>Closed branch head</dt>
6123 <dd>See 'Head, closed branch'.</dd>
6124 <dt>Commit</dt>
6125 <dd><p class="first">(Noun) A synonym for changeset.</p>
6126 <p>Example: &quot;Is the bug fixed in your recent commit?&quot;</p>
6127 <p>(Verb) The act of recording changes to a repository. When files
6128 are committed in a working directory, Mercurial finds the
6129 differences between the committed files and their parent
6130 changeset, creating a new changeset in the repository.</p>
6131 <p class="last">Example: &quot;You should commit those changes now.&quot;</p>
6132 </dd>
6133 <dt>Cset</dt>
6134 <dd>A common abbreviation of the term changeset.</dd>
6135 <dt>DAG</dt>
6136 <dd>The repository of changesets of a distributed version control
6137 system (DVCS) can be described as a directed acyclic graph (DAG),
6138 consisting of nodes and edges, where nodes correspond to
6139 changesets and edges imply a parent -&gt; child relation. This graph
6140 can be visualized by graphical tools such as <a class="reference external" href="hg.1.html#log"><tt class="docutils literal">hg log <span class="pre">--graph</span></tt></a>. In
6141 Mercurial, the DAG is limited by the requirement for children to
6142 have at most two parents.</dd>
6143 <dt>Deprecated</dt>
6144 <dd>Feature removed from documentation, but not scheduled for removal.</dd>
6145 <dt>Default branch</dt>
6146 <dd>See 'Branch, default'.</dd>
6147 <dt>Descendant</dt>
6148 <dd>Any changeset that can be reached by a chain of child changesets
6149 from a given changeset. More precisely, the descendants of a
6150 changeset can be defined by two properties: the child of a
6151 changeset is a descendant, and the child of a descendant is a
6152 descendant. See also: 'Ancestor'.</dd>
6153 <dt>Diff</dt>
6154 <dd><p class="first">(Noun) The difference between the contents and attributes of files
6155 in two changesets or a changeset and the current working
6156 directory. The difference is usually represented in a standard
6157 form called a &quot;diff&quot; or &quot;patch&quot;. The &quot;git diff&quot; format is used
6158 when the changes include copies, renames, or changes to file
6159 attributes, none of which can be represented/handled by classic
6160 &quot;diff&quot; and &quot;patch&quot;.</p>
6161 <p>Example: &quot;Did you see my correction in the diff?&quot;</p>
6162 <p>(Verb) Diffing two changesets is the action of creating a diff or
6163 patch.</p>
6164 <p class="last">Example: &quot;If you diff with changeset X, you will see what I mean.&quot;</p>
6165 </dd>
6166 <dt>Directory, working</dt>
6167 <dd>The working directory represents the state of the files tracked by
6168 Mercurial, that will be recorded in the next commit. The working
6169 directory initially corresponds to the snapshot at an existing
6170 changeset, known as the parent of the working directory. See
6171 'Parent, working directory'. The state may be modified by changes
6172 to the files introduced manually or by a merge. The repository
6173 metadata exists in the .hg directory inside the working directory.</dd>
6174 <dt>Draft</dt>
6175 <dd>Changesets in the draft phase have not been shared with publishing
6176 repositories and may thus be safely changed by history-modifying
6177 extensions. See <a class="reference external" href="hg.1.html#phases"><tt class="docutils literal">hg help phases</tt></a>.</dd>
6178 <dt>Experimental</dt>
6179 <dd>Feature that may change or be removed at a later date.</dd>
6180 <dt>Graph</dt>
6181 <dd>See DAG and <a class="reference external" href="hg.1.html#log"><tt class="docutils literal">hg log <span class="pre">--graph</span></tt></a>.</dd>
6182 <dt>Head</dt>
6183 <dd><p class="first">The term 'head' may be used to refer to both a branch head or a
6184 repository head, depending on the context. See 'Head, branch' and
6185 'Head, repository' for specific definitions.</p>
6186 <p class="last">Heads are where development generally takes place and are the
6187 usual targets for update and merge operations.</p>
6188 </dd>
6189 <dt>Head, branch</dt>
6190 <dd>A changeset with no descendants on the same named branch.</dd>
6191 <dt>Head, closed branch</dt>
6192 <dd><p class="first">A changeset that marks a head as no longer interesting. The closed
6193 head is no longer listed by <a class="reference external" href="hg.1.html#heads"><tt class="docutils literal">hg heads</tt></a>. A branch is considered
6194 closed when all its heads are closed and consequently is not
6195 listed by <a class="reference external" href="hg.1.html#branches"><tt class="docutils literal">hg branches</tt></a>.</p>
6196 <p class="last">Closed heads can be re-opened by committing new changeset as the
6197 child of the changeset that marks a head as closed.</p>
6198 </dd>
6199 <dt>Head, repository</dt>
6200 <dd>A topological head which has not been closed.</dd>
6201 <dt>Head, topological</dt>
6202 <dd>A changeset with no children in the repository.</dd>
6203 <dt>History, immutable</dt>
6204 <dd>Once committed, changesets cannot be altered. Extensions which
6205 appear to change history actually create new changesets that
6206 replace existing ones, and then destroy the old changesets. Doing
6207 so in public repositories can result in old changesets being
6208 reintroduced to the repository.</dd>
6209 <dt>History, rewriting</dt>
6210 <dd>The changesets in a repository are immutable. However, extensions
6211 to Mercurial can be used to alter the repository, usually in such
6212 a way as to preserve changeset contents.</dd>
6213 <dt>Immutable history</dt>
6214 <dd>See 'History, immutable'.</dd>
6215 <dt>Merge changeset</dt>
6216 <dd>See 'Changeset, merge'.</dd>
6217 <dt>Manifest</dt>
6218 <dd>Each changeset has a manifest, which is the list of files that are
6219 tracked by the changeset.</dd>
6220 <dt>Merge</dt>
6221 <dd>Used to bring together divergent branches of work. When you update
6222 to a changeset and then merge another changeset, you bring the
6223 history of the latter changeset into your working directory. Once
6224 conflicts are resolved (and marked), this merge may be committed
6225 as a merge changeset, bringing two branches together in the DAG.</dd>
6226 <dt>Named branch</dt>
6227 <dd>See 'Branch, named'.</dd>
6228 <dt>Null changeset</dt>
6229 <dd>The empty changeset. It is the parent state of newly-initialized
6230 repositories and repositories with no checked out revision. It is
6231 thus the parent of root changesets and the effective ancestor when
6232 merging unrelated changesets. Can be specified by the alias 'null'
6233 or by the changeset ID '000000000000'.</dd>
6234 <dt>Parent</dt>
6235 <dd>See 'Changeset, parent'.</dd>
6236 <dt>Parent changeset</dt>
6237 <dd>See 'Changeset, parent'.</dd>
6238 <dt>Parent, working directory</dt>
6239 <dd>The working directory parent reflects a virtual revision which is
6240 the child of the changeset (or two changesets with an uncommitted
6241 merge) shown by <a class="reference external" href="hg.1.html#parents"><tt class="docutils literal">hg parents</tt></a>. This is changed with
6242 <a class="reference external" href="hg.1.html#update"><tt class="docutils literal">hg update</tt></a>. Other commands to see the working directory parent
6243 are <a class="reference external" href="hg.1.html#summary"><tt class="docutils literal">hg summary</tt></a> and <a class="reference external" href="hg.1.html#id"><tt class="docutils literal">hg id</tt></a>. Can be specified by the alias &quot;.&quot;.</dd>
6244 <dt>Patch</dt>
6245 <dd><p class="first">(Noun) The product of a diff operation.</p>
6246 <p>Example: &quot;I've sent you my patch.&quot;</p>
6247 <p>(Verb) The process of using a patch file to transform one
6248 changeset into another.</p>
6249 <p class="last">Example: &quot;You will need to patch that revision.&quot;</p>
6250 </dd>
6251 <dt>Phase</dt>
6252 <dd>A per-changeset state tracking how the changeset has been or
6253 should be shared. See <a class="reference external" href="hg.1.html#phases"><tt class="docutils literal">hg help phases</tt></a>.</dd>
6254 <dt>Public</dt>
6255 <dd>Changesets in the public phase have been shared with publishing
6256 repositories and are therefore considered immutable. See <a class="reference external" href="hg.1.html#phases"><tt class="docutils literal">hg help
6257 phases</tt></a>.</dd>
6258 <dt>Pull</dt>
6259 <dd>An operation in which changesets in a remote repository which are
6260 not in the local repository are brought into the local
6261 repository. Note that this operation without special arguments
6262 only updates the repository, it does not update the files in the
6263 working directory. See <a class="reference external" href="hg.1.html#pull"><tt class="docutils literal">hg help pull</tt></a>.</dd>
6264 <dt>Push</dt>
6265 <dd>An operation in which changesets in a local repository which are
6266 not in a remote repository are sent to the remote repository. Note
6267 that this operation only adds changesets which have been committed
6268 locally to the remote repository. Uncommitted changes are not
6269 sent. See <a class="reference external" href="hg.1.html#push"><tt class="docutils literal">hg help push</tt></a>.</dd>
6270 <dt>Repository</dt>
6271 <dd>The metadata describing all recorded states of a collection of
6272 files. Each recorded state is represented by a changeset. A
6273 repository is usually (but not always) found in the <tt class="docutils literal">.hg</tt>
6274 subdirectory of a working directory. Any recorded state can be
6275 recreated by &quot;updating&quot; a working directory to a specific
6276 changeset.</dd>
6277 <dt>Repository head</dt>
6278 <dd>See 'Head, repository'.</dd>
6279 <dt>Revision</dt>
6280 <dd>A state of the repository at some point in time. Earlier revisions
6281 can be updated to by using <a class="reference external" href="hg.1.html#update"><tt class="docutils literal">hg update</tt></a>. See also 'Revision
6282 number'; See also 'Changeset'.</dd>
6283 <dt>Revision number</dt>
6284 <dd>This integer uniquely identifies a changeset in a specific
6285 repository. It represents the order in which changesets were added
6286 to a repository, starting with revision number 0. Note that the
6287 revision number may be different in each clone of a repository. To
6288 identify changesets uniquely between different clones, see
6289 'Changeset id'.</dd>
6290 <dt>Revlog</dt>
6291 <dd>History storage mechanism used by Mercurial. It is a form of delta
6292 encoding, with occasional full revision of data followed by delta
6293 of each successive revision. It includes data and an index
6294 pointing to the data.</dd>
6295 <dt>Rewriting history</dt>
6296 <dd>See 'History, rewriting'.</dd>
6297 <dt>Root</dt>
6298 <dd>A changeset that has only the null changeset as its parent. Most
6299 repositories have only a single root changeset.</dd>
6300 <dt>Secret</dt>
6301 <dd>Changesets in the secret phase may not be shared via push, pull,
6302 or clone. See <a class="reference external" href="hg.1.html#phases"><tt class="docutils literal">hg help phases</tt></a>.</dd>
6303 <dt>Tag</dt>
6304 <dd>An alternative name given to a changeset. Tags can be used in all
6305 places where Mercurial expects a changeset ID, e.g., with
6306 <a class="reference external" href="hg.1.html#update"><tt class="docutils literal">hg update</tt></a>. The creation of a tag is stored in the history and
6307 will thus automatically be shared with other using push and pull.</dd>
6308 <dt>Tip</dt>
6309 <dd>The changeset with the highest revision number. It is the changeset
6310 most recently added in a repository.</dd>
6311 <dt>Tip, branch</dt>
6312 <dd>The head of a given branch with the highest revision number. When
6313 a branch name is used as a revision identifier, it refers to the
6314 branch tip. See also 'Branch, head'. Note that because revision
6315 numbers may be different in different repository clones, the
6316 branch tip may be different in different cloned repositories.</dd>
6317 <dt>Update</dt>
6318 <dd><p class="first">(Noun) Another synonym of changeset.</p>
6319 <p>Example: &quot;I've pushed an update.&quot;</p>
6320 <p>(Verb) This term is usually used to describe updating the state of
6321 the working directory to that of a specific changeset. See
6322 <a class="reference external" href="hg.1.html#update"><tt class="docutils literal">hg help update</tt></a>.</p>
6323 <p class="last">Example: &quot;You should update.&quot;</p>
6324 </dd>
6325 <dt>Working directory</dt>
6326 <dd>See 'Directory, working'.</dd>
6327 <dt>Working directory parent</dt>
6328 <dd>See 'Parent, working directory'.</dd>
6329 </dl>
6330 </div>
6331 <div class="section" id="syntax-for-mercurial-ignore-files">
6332 <span id="ignore"></span><span id="hgignore"></span><h1><a class="toc-backref" href="#contents">Syntax for Mercurial Ignore Files</a></h1>
6333 <div class="section" id="synopsis-1">
6334 <h2>Synopsis</h2>
6335 <p>The Mercurial system uses a file called <tt class="docutils literal">.hgignore</tt> in the root
6336 directory of a repository to control its behavior when it searches
6337 for files that it is not currently tracking.</p>
6338 </div>
6339 <div class="section" id="description-1">
6340 <h2>Description</h2>
6341 <p>The working directory of a Mercurial repository will often contain
6342 files that should not be tracked by Mercurial. These include backup
6343 files created by editors and build products created by compilers.
6344 These files can be ignored by listing them in a <tt class="docutils literal">.hgignore</tt> file in
6345 the root of the working directory. The <tt class="docutils literal">.hgignore</tt> file must be
6346 created manually. It is typically put under version control, so that
6347 the settings will propagate to other repositories with push and pull.</p>
6348 <p>An untracked file is ignored if its path relative to the repository
6349 root directory, or any prefix path of that path, is matched against
6350 any pattern in <tt class="docutils literal">.hgignore</tt>.</p>
6351 <p>For example, say we have an untracked file, <tt class="docutils literal">file.c</tt>, at
6352 <tt class="docutils literal">a/b/file.c</tt> inside our repository. Mercurial will ignore <tt class="docutils literal">file.c</tt>
6353 if any pattern in <tt class="docutils literal">.hgignore</tt> matches <tt class="docutils literal">a/b/file.c</tt>, <tt class="docutils literal">a/b</tt> or <tt class="docutils literal">a</tt>.</p>
6354 <p>In addition, a Mercurial configuration file can reference a set of
6355 per-user or global ignore files. See the <tt class="docutils literal">ignore</tt> configuration
6356 key on the <tt class="docutils literal">[ui]</tt> section of <a class="reference external" href="hgrc.5.html"><tt class="docutils literal">hg help config</tt></a> for details of how to
6357 configure these files.</p>
6358 <p>To control Mercurial's handling of files that it manages, many
6359 commands support the <tt class="docutils literal"><span class="pre">-I</span></tt> and <tt class="docutils literal"><span class="pre">-X</span></tt> options; see
6360 <a class="reference external" href="hg.1.html#&lt;command&gt;"><tt class="docutils literal">hg help &lt;command&gt;</tt></a> and <a class="reference external" href="hg.1.html#patterns"><tt class="docutils literal">hg help patterns</tt></a> for details.</p>
6361 <p>Files that are already tracked are not affected by .hgignore, even
6362 if they appear in .hgignore. An untracked file X can be explicitly
6363 added with <a class="reference external" href="hg.1.html#add"><tt class="docutils literal">hg add X</tt></a>, even if X would be excluded by a pattern
6364 in .hgignore.</p>
6365 </div>
6366 <div class="section" id="syntax">
6367 <h2>Syntax</h2>
6368 <p>An ignore file is a plain text file consisting of a list of patterns,
6369 with one pattern per line. Empty lines are skipped. The <tt class="docutils literal">#</tt>
6370 character is treated as a comment character, and the <tt class="docutils literal">\</tt> character
6371 is treated as an escape character.</p>
6372 <p>Mercurial supports several pattern syntaxes. The default syntax used
6373 is Python/Perl-style regular expressions.</p>
6374 <p>To change the syntax used, use a line of the following form:</p>
6375 <pre class="literal-block">
6376 syntax: NAME
6377 </pre>
6378 <p>where <tt class="docutils literal">NAME</tt> is one of the following:</p>
6379 <dl class="docutils">
6380 <dt><tt class="docutils literal">regexp</tt></dt>
6381 <dd>Regular expression, Python/Perl syntax.</dd>
6382 <dt><tt class="docutils literal">glob</tt></dt>
6383 <dd>Shell-style glob.</dd>
6384 <dt><tt class="docutils literal">rootglob</tt></dt>
6385 <dd>A variant of <tt class="docutils literal">glob</tt> that is rooted (see below).</dd>
6386 </dl>
6387 <p>The chosen syntax stays in effect when parsing all patterns that
6388 follow, until another syntax is selected.</p>
6389 <p>Neither <tt class="docutils literal">glob</tt> nor regexp patterns are rooted. A glob-syntax
6390 pattern of the form <tt class="docutils literal">*.c</tt> will match a file ending in <tt class="docutils literal">.c</tt> in any
6391 directory, and a regexp pattern of the form <tt class="docutils literal">\.c$</tt> will do the
6392 same. To root a regexp pattern, start it with <tt class="docutils literal">^</tt>. To get the same
6393 effect with glob-syntax, you have to use <tt class="docutils literal">rootglob</tt>.</p>
6394 <p>Subdirectories can have their own .hgignore settings by adding
6395 <tt class="docutils literal"><span class="pre">subinclude:path/to/subdir/.hgignore</span></tt> to the root <tt class="docutils literal">.hgignore</tt>. See
6396 <a class="reference external" href="hg.1.html#patterns"><tt class="docutils literal">hg help patterns</tt></a> for details on <tt class="docutils literal">subinclude:</tt> and <tt class="docutils literal">include:</tt>.</p>
6397 <div class="admonition note">
6398 <p class="first admonition-title">Note</p>
6399 <p class="last">Patterns specified in other than <tt class="docutils literal">.hgignore</tt> are always rooted.
6400 Please see <a class="reference external" href="hg.1.html#patterns"><tt class="docutils literal">hg help patterns</tt></a> for details.</p>
6401 </div>
6402 </div>
6403 <div class="section" id="example">
6404 <h2>Example</h2>
6405 <p>Here is an example ignore file.</p>
6406 <pre class="literal-block">
6407 # use glob syntax.
6408 syntax: glob
6409
6410 *.elc
6411 *.pyc
6412 *~
6413
6414 # switch to regexp syntax.
6415 syntax: regexp
6416 ^\.pc/
6417 </pre>
6418 </div>
6419 <div class="section" id="debugging">
6420 <h2>Debugging</h2>
6421 <p>Use the <tt class="docutils literal">debugignore</tt> command to see if and why a file is ignored, or to
6422 see the combined ignore pattern. See <a class="reference external" href="hg.1.html#debugignore"><tt class="docutils literal">hg help debugignore</tt></a> for details.</p>
6423 </div>
6424 </div>
6425 <div class="section" id="configuring-hgweb">
6426 <span id="hgweb"></span><h1><a class="toc-backref" href="#contents">Configuring hgweb</a></h1>
6427 <p>Mercurial's internal web server, hgweb, can serve either a single
6428 repository, or a tree of repositories. In the second case, repository
6429 paths and global options can be defined using a dedicated
6430 configuration file common to <a class="reference external" href="hg.1.html#serve"><tt class="docutils literal">hg serve</tt></a>, <tt class="docutils literal">hgweb.wsgi</tt>,
6431 <tt class="docutils literal">hgweb.cgi</tt> and <tt class="docutils literal">hgweb.fcgi</tt>.</p>
6432 <p>This file uses the same syntax as other Mercurial configuration files
6433 but recognizes only the following sections:</p>
6434 <blockquote>
6435 <ul class="simple">
6436 <li>web</li>
6437 <li>paths</li>
6438 <li>collections</li>
6439 </ul>
6440 </blockquote>
6441 <p>The <tt class="docutils literal">web</tt> options are thoroughly described in <a class="reference external" href="hgrc.5.html"><tt class="docutils literal">hg help config</tt></a>.</p>
6442 <p>The <tt class="docutils literal">paths</tt> section maps URL paths to paths of repositories in the
6443 filesystem. hgweb will not expose the filesystem directly - only
6444 Mercurial repositories can be published and only according to the
6445 configuration.</p>
6446 <p>The left hand side is the path in the URL. Note that hgweb reserves
6447 subpaths like <tt class="docutils literal">rev</tt> or <tt class="docutils literal">file</tt>, try using different names for
6448 nested repositories to avoid confusing effects.</p>
6449 <p>The right hand side is the path in the filesystem. If the specified
6450 path ends with <tt class="docutils literal">*</tt> or <tt class="docutils literal">**</tt> the filesystem will be searched
6451 recursively for repositories below that point.
6452 With <tt class="docutils literal">*</tt> it will not recurse into the repositories it finds (except for
6453 <tt class="docutils literal">.hg/patches</tt>).
6454 With <tt class="docutils literal">**</tt> it will also search inside repository working directories
6455 and possibly find subrepositories.</p>
6456 <p>In this example:</p>
6457 <pre class="literal-block">
6458 [paths]
6459 /projects/a = /srv/tmprepos/a
6460 /projects/b = c:/repos/b
6461 / = /srv/repos/*
6462 /user/bob = /home/bob/repos/**
6463 </pre>
6464 <ul class="simple">
6465 <li>The first two entries make two repositories in different directories
6466 appear under the same directory in the web interface</li>
6467 <li>The third entry will publish every Mercurial repository found in
6468 <tt class="docutils literal">/srv/repos/</tt>, for instance the repository <tt class="docutils literal">/srv/repos/quux/</tt>
6469 will appear as <tt class="docutils literal"><span class="pre">http://server/quux/</span></tt></li>
6470 <li>The fourth entry will publish both <tt class="docutils literal"><span class="pre">http://server/user/bob/quux/</span></tt>
6471 and <tt class="docutils literal"><span class="pre">http://server/user/bob/quux/testsubrepo/</span></tt></li>
6472 </ul>
6473 <p>The <tt class="docutils literal">collections</tt> section is deprecated and has been superseded by
6474 <tt class="docutils literal">paths</tt>.</p>
6475 <div class="section" id="urls-and-common-arguments">
6476 <h2>URLs and Common Arguments</h2>
6477 <p>URLs under each repository have the form <tt class="docutils literal"><span class="pre">/{command}[/{arguments}]</span></tt>
6478 where <tt class="docutils literal">{command}</tt> represents the name of a command or handler and
6479 <tt class="docutils literal">{arguments}</tt> represents any number of additional URL parameters
6480 to that command.</p>
6481 <p>The web server has a default style associated with it. Styles map to
6482 a collection of named templates. Each template is used to render a
6483 specific piece of data, such as a changeset or diff.</p>
6484 <p>The style for the current request can be overridden two ways. First,
6485 if <tt class="docutils literal">{command}</tt> contains a hyphen (<tt class="docutils literal">-</tt>), the text before the hyphen
6486 defines the style. For example, <tt class="docutils literal"><span class="pre">/atom-log</span></tt> will render the <tt class="docutils literal">log</tt>
6487 command handler with the <tt class="docutils literal">atom</tt> style. The second way to set the
6488 style is with the <tt class="docutils literal">style</tt> query string argument. For example,
6489 <tt class="docutils literal"><span class="pre">/log?style=atom</span></tt>. The hyphenated URL parameter is preferred.</p>
6490 <p>Not all templates are available for all styles. Attempting to use
6491 a style that doesn't have all templates defined may result in an error
6492 rendering the page.</p>
6493 <p>Many commands take a <tt class="docutils literal">{revision}</tt> URL parameter. This defines the
6494 changeset to operate on. This is commonly specified as the short,
6495 12 digit hexadecimal abbreviation for the full 40 character unique
6496 revision identifier. However, any value described by
6497 <a class="reference external" href="hg.1.html#revisions"><tt class="docutils literal">hg help revisions</tt></a> typically works.</p>
6498 </div>
6499 <div class="section" id="commands-and-urls">
6500 <h2>Commands and URLs</h2>
6501 <p>The following web commands and their URLs are available:</p>
6502 <div class="section" id="annotate-revision-path">
6503 <h3>/annotate/{revision}/{path}</h3>
6504 <p>Show changeset information for each line in a file.</p>
6505 <p>The <tt class="docutils literal">ignorews</tt>, <tt class="docutils literal">ignorewsamount</tt>, <tt class="docutils literal">ignorewseol</tt>, and
6506 <tt class="docutils literal">ignoreblanklines</tt> query string arguments have the same meaning as
6507 their <tt class="docutils literal">[annotate]</tt> config equivalents. It uses the hgrc boolean
6508 parsing logic to interpret the value. e.g. <tt class="docutils literal">0</tt> and <tt class="docutils literal">false</tt> are
6509 false and <tt class="docutils literal">1</tt> and <tt class="docutils literal">true</tt> are true. If not defined, the server
6510 default settings are used.</p>
6511 <p>The <tt class="docutils literal">fileannotate</tt> template is rendered.</p>
6512 </div>
6513 <div class="section" id="archive-revision-format-path">
6514 <h3>/archive/{revision}.{format}[/{path}]</h3>
6515 <p>Obtain an archive of repository content.</p>
6516 <p>The content and type of the archive is defined by a URL path parameter.
6517 <tt class="docutils literal">format</tt> is the file extension of the archive type to be generated. e.g.
6518 <tt class="docutils literal">zip</tt> or <tt class="docutils literal">tar.bz2</tt>. Not all archive types may be allowed by your
6519 server configuration.</p>
6520 <p>The optional <tt class="docutils literal">path</tt> URL parameter controls content to include in the
6521 archive. If omitted, every file in the specified revision is present in the
6522 archive. If included, only the specified file or contents of the specified
6523 directory will be included in the archive.</p>
6524 <p>No template is used for this handler. Raw, binary content is generated.</p>
6525 </div>
6526 <div class="section" id="bookmarks-1">
6527 <h3>/bookmarks</h3>
6528 <p>Show information about bookmarks.</p>
6529 <p>No arguments are accepted.</p>
6530 <p>The <tt class="docutils literal">bookmarks</tt> template is rendered.</p>
6531 </div>
6532 <div class="section" id="branches-1">
6533 <h3>/branches</h3>
6534 <p>Show information about branches.</p>
6535 <p>All known branches are contained in the output, even closed branches.</p>
6536 <p>No arguments are accepted.</p>
6537 <p>The <tt class="docutils literal">branches</tt> template is rendered.</p>
6538 </div>
6539 <div class="section" id="changelog-revision">
6540 <h3>/changelog[/{revision}]</h3>
6541 <p>Show information about multiple changesets.</p>
6542 <p>If the optional <tt class="docutils literal">revision</tt> URL argument is absent, information about
6543 all changesets starting at <tt class="docutils literal">tip</tt> will be rendered. If the <tt class="docutils literal">revision</tt>
6544 argument is present, changesets will be shown starting from the specified
6545 revision.</p>
6546 <p>If <tt class="docutils literal">revision</tt> is absent, the <tt class="docutils literal">rev</tt> query string argument may be
6547 defined. This will perform a search for changesets.</p>
6548 <p>The argument for <tt class="docutils literal">rev</tt> can be a single revision, a revision set,
6549 or a literal keyword to search for in changeset data (equivalent to
6550 <a class="reference external" href="hg.1.html#log"><tt class="docutils literal">hg log <span class="pre">-k</span></tt></a>).</p>
6551 <p>The <tt class="docutils literal">revcount</tt> query string argument defines the maximum numbers of
6552 changesets to render.</p>
6553 <p>For non-searches, the <tt class="docutils literal">changelog</tt> template will be rendered.</p>
6554 </div>
6555 <div class="section" id="changeset-revision">
6556 <h3>/changeset[/{revision}]</h3>
6557 <p>Show information about a single changeset.</p>
6558 <p>A URL path argument is the changeset identifier to show. See <tt class="docutils literal">hg help
6559 revisions</tt> for possible values. If not defined, the <tt class="docutils literal">tip</tt> changeset
6560 will be shown.</p>
6561 <p>The <tt class="docutils literal">changeset</tt> template is rendered. Contents of the <tt class="docutils literal">changesettag</tt>,
6562 <tt class="docutils literal">changesetbookmark</tt>, <tt class="docutils literal">filenodelink</tt>, <tt class="docutils literal">filenolink</tt>, and the many
6563 templates related to diffs may all be used to produce the output.</p>
6564 </div>
6565 <div class="section" id="comparison-revision-path">
6566 <h3>/comparison/{revision}/{path}</h3>
6567 <p>Show a comparison between the old and new versions of a file from changes
6568 made on a particular revision.</p>
6569 <p>This is similar to the <tt class="docutils literal">diff</tt> handler. However, this form features
6570 a split or side-by-side diff rather than a unified diff.</p>
6571 <p>The <tt class="docutils literal">context</tt> query string argument can be used to control the lines of
6572 context in the diff.</p>
6573 <p>The <tt class="docutils literal">filecomparison</tt> template is rendered.</p>
6574 </div>
6575 <div class="section" id="diff-revision-path">
6576 <h3>/diff/{revision}/{path}</h3>
6577 <p>Show how a file changed in a particular commit.</p>
6578 <p>The <tt class="docutils literal">filediff</tt> template is rendered.</p>
6579 <p>This handler is registered under both the <tt class="docutils literal">/diff</tt> and <tt class="docutils literal">/filediff</tt>
6580 paths. <tt class="docutils literal">/diff</tt> is used in modern code.</p>
6581 </div>
6582 <div class="section" id="file-revision-path">
6583 <h3>/file/{revision}[/{path}]</h3>
6584 <p>Show information about a directory or file in the repository.</p>
6585 <p>Info about the <tt class="docutils literal">path</tt> given as a URL parameter will be rendered.</p>
6586 <p>If <tt class="docutils literal">path</tt> is a directory, information about the entries in that
6587 directory will be rendered. This form is equivalent to the <tt class="docutils literal">manifest</tt>
6588 handler.</p>
6589 <p>If <tt class="docutils literal">path</tt> is a file, information about that file will be shown via
6590 the <tt class="docutils literal">filerevision</tt> template.</p>
6591 <p>If <tt class="docutils literal">path</tt> is not defined, information about the root directory will
6592 be rendered.</p>
6593 </div>
6594 <div class="section" id="diff-revision-path-1">
6595 <h3>/diff/{revision}/{path}</h3>
6596 <p>Show how a file changed in a particular commit.</p>
6597 <p>The <tt class="docutils literal">filediff</tt> template is rendered.</p>
6598 <p>This handler is registered under both the <tt class="docutils literal">/diff</tt> and <tt class="docutils literal">/filediff</tt>
6599 paths. <tt class="docutils literal">/diff</tt> is used in modern code.</p>
6600 </div>
6601 <div class="section" id="filelog-revision-path">
6602 <h3>/filelog/{revision}/{path}</h3>
6603 <p>Show information about the history of a file in the repository.</p>
6604 <p>The <tt class="docutils literal">revcount</tt> query string argument can be defined to control the
6605 maximum number of entries to show.</p>
6606 <p>The <tt class="docutils literal">filelog</tt> template will be rendered.</p>
6607 </div>
6608 <div class="section" id="graph-revision">
6609 <h3>/graph[/{revision}]</h3>
6610 <p>Show information about the graphical topology of the repository.</p>
6611 <p>Information rendered by this handler can be used to create visual
6612 representations of repository topology.</p>
6613 <p>The <tt class="docutils literal">revision</tt> URL parameter controls the starting changeset. If it's
6614 absent, the default is <tt class="docutils literal">tip</tt>.</p>
6615 <p>The <tt class="docutils literal">revcount</tt> query string argument can define the number of changesets
6616 to show information for.</p>
6617 <p>The <tt class="docutils literal">graphtop</tt> query string argument can specify the starting changeset
6618 for producing <tt class="docutils literal">jsdata</tt> variable that is used for rendering graph in
6619 JavaScript. By default it has the same value as <tt class="docutils literal">revision</tt>.</p>
6620 <p>This handler will render the <tt class="docutils literal">graph</tt> template.</p>
6621 </div>
6622 <div class="section" id="help-topic">
6623 <h3>/help[/{topic}]</h3>
6624 <p>Render help documentation.</p>
6625 <p>This web command is roughly equivalent to <a class="reference external" href="hg.1.html#help"><tt class="docutils literal">hg help</tt></a>. If a <tt class="docutils literal">topic</tt>
6626 is defined, that help topic will be rendered. If not, an index of
6627 available help topics will be rendered.</p>
6628 <p>The <tt class="docutils literal">help</tt> template will be rendered when requesting help for a topic.
6629 <tt class="docutils literal">helptopics</tt> will be rendered for the index of help topics.</p>
6630 </div>
6631 <div class="section" id="log-revision-path">
6632 <h3>/log[/{revision}[/{path}]]</h3>
6633 <p>Show repository or file history.</p>
6634 <p>For URLs of the form <tt class="docutils literal"><span class="pre">/log/{revision}</span></tt>, a list of changesets starting at
6635 the specified changeset identifier is shown. If <tt class="docutils literal">{revision}</tt> is not
6636 defined, the default is <tt class="docutils literal">tip</tt>. This form is equivalent to the
6637 <tt class="docutils literal">changelog</tt> handler.</p>
6638 <p>For URLs of the form <tt class="docutils literal"><span class="pre">/log/{revision}/{file}</span></tt>, the history for a specific
6639 file will be shown. This form is equivalent to the <tt class="docutils literal">filelog</tt> handler.</p>
6640 </div>
6641 <div class="section" id="manifest-revision-path">
6642 <h3>/manifest[/{revision}[/{path}]]</h3>
6643 <p>Show information about a directory.</p>
6644 <p>If the URL path arguments are omitted, information about the root
6645 directory for the <tt class="docutils literal">tip</tt> changeset will be shown.</p>
6646 <p>Because this handler can only show information for directories, it
6647 is recommended to use the <tt class="docutils literal">file</tt> handler instead, as it can handle both
6648 directories and files.</p>
6649 <p>The <tt class="docutils literal">manifest</tt> template will be rendered for this handler.</p>
6650 </div>
6651 <div class="section" id="changeset-revision-1">
6652 <h3>/changeset[/{revision}]</h3>
6653 <p>Show information about a single changeset.</p>
6654 <p>A URL path argument is the changeset identifier to show. See <tt class="docutils literal">hg help
6655 revisions</tt> for possible values. If not defined, the <tt class="docutils literal">tip</tt> changeset
6656 will be shown.</p>
6657 <p>The <tt class="docutils literal">changeset</tt> template is rendered. Contents of the <tt class="docutils literal">changesettag</tt>,
6658 <tt class="docutils literal">changesetbookmark</tt>, <tt class="docutils literal">filenodelink</tt>, <tt class="docutils literal">filenolink</tt>, and the many
6659 templates related to diffs may all be used to produce the output.</p>
6660 </div>
6661 <div class="section" id="shortlog">
6662 <h3>/shortlog</h3>
6663 <p>Show basic information about a set of changesets.</p>
6664 <p>This accepts the same parameters as the <tt class="docutils literal">changelog</tt> handler. The only
6665 difference is the <tt class="docutils literal">shortlog</tt> template will be rendered instead of the
6666 <tt class="docutils literal">changelog</tt> template.</p>
6667 </div>
6668 <div class="section" id="summary-1">
6669 <h3>/summary</h3>
6670 <p>Show a summary of repository state.</p>
6671 <p>Information about the latest changesets, bookmarks, tags, and branches
6672 is captured by this handler.</p>
6673 <p>The <tt class="docutils literal">summary</tt> template is rendered.</p>
6674 </div>
6675 <div class="section" id="tags-1">
6676 <h3>/tags</h3>
6677 <p>Show information about tags.</p>
6678 <p>No arguments are accepted.</p>
6679 <p>The <tt class="docutils literal">tags</tt> template is rendered.</p>
6680 </div>
6681 </div>
6682 </div>
6683 <div class="section" id="technical-implementation-topics">
6684 <span id="internals"></span><h1><a class="toc-backref" href="#contents">Technical implementation topics</a></h1>
6685 <p>To access a subtopic, use &quot;hg help internals.{subtopic-name}&quot;</p>
6686 <blockquote>
6687 <table class="docutils field-list" frame="void" rules="none">
6688 <col class="field-name" />
6689 <col class="field-body" />
6690 <tbody valign="top">
6691 <tr class="field"><th class="field-name">bid-merge:</th><td class="field-body">Bid Merge Algorithm</td>
6692 </tr>
6693 <tr class="field"><th class="field-name">bundle2:</th><td class="field-body">Bundle2</td>
6694 </tr>
6695 <tr class="field"><th class="field-name">bundles:</th><td class="field-body">Bundles</td>
6696 </tr>
6697 <tr class="field"><th class="field-name">cbor:</th><td class="field-body">CBOR</td>
6698 </tr>
6699 <tr class="field"><th class="field-name">censor:</th><td class="field-body">Censor</td>
6700 </tr>
6701 <tr class="field"><th class="field-name">changegroups:</th><td class="field-body">Changegroups</td>
6702 </tr>
6703 <tr class="field"><th class="field-name">config:</th><td class="field-body">Config Registrar</td>
6704 </tr>
6705 <tr class="field"><th class="field-name">dirstate-v2:</th><td class="field-body">dirstate-v2 file format</td>
6706 </tr>
6707 <tr class="field"><th class="field-name">extensions:</th><td class="field-body">Extension API</td>
6708 </tr>
6709 <tr class="field"><th class="field-name">file-index:</th><td class="field-body">File Index</td>
6710 </tr>
6711 <tr class="field"><th class="field-name">mergestate:</th><td class="field-body">Mergestate</td>
6712 </tr>
6713 <tr class="field"><th class="field-name">requirements:</th><td class="field-body">Repository Requirements</td>
6714 </tr>
6715 <tr class="field"><th class="field-name">revlogs:</th><td class="field-body">Revision Logs</td>
6716 </tr>
6717 <tr class="field"><th class="field-name">wireprotocol:</th><td class="field-body">Wire Protocol</td>
6718 </tr>
6719 <tr class="field"><th class="field-name" colspan="2">wireprotocolrpc:</th></tr>
6720 <tr class="field"><td>&nbsp;</td><td class="field-body">Wire Protocol RPC</td>
6721 </tr>
6722 <tr class="field"><th class="field-name">wireprotocolv2:</th><td class="field-body">Wire Protocol Version 2</td>
6723 </tr>
6724 </tbody>
6725 </table>
6726 </blockquote>
6727 </div>
6728 <div class="section" id="merge-tools-1">
6729 <span id="mergetool"></span><span id="mergetools"></span><span id="merge-tools"></span><h1><a class="toc-backref" href="#contents">Merge Tools</a></h1>
6730 <p>To merge files Mercurial uses merge tools.</p>
6731 <p>A merge tool combines two different versions of a file into a merged
6732 file. Merge tools are given the two files and the greatest common
6733 ancestor of the two file versions, so they can determine the changes
6734 made on both branches.</p>
6735 <p>Merge tools are used both for <a class="reference external" href="hg.1.html#resolve"><tt class="docutils literal">hg resolve</tt></a>, <a class="reference external" href="hg.1.html#merge"><tt class="docutils literal">hg merge</tt></a>, <a class="reference external" href="hg.1.html#update"><tt class="docutils literal">hg update</tt></a>,
6736 <a class="reference external" href="hg.1.html#backout"><tt class="docutils literal">hg backout</tt></a> and in several extensions.</p>
6737 <p>Usually, the merge tool tries to automatically reconcile the files by
6738 combining all non-overlapping changes that occurred separately in
6739 the two different evolutions of the same initial base file. Furthermore, some
6740 interactive merge programs make it easier to manually resolve
6741 conflicting merges, either in a graphical way, or by inserting some
6742 conflict markers. Mercurial does not include any interactive merge
6743 programs but relies on external tools for that.</p>
6744 <div class="section" id="available-merge-tools">
6745 <h2>Available merge tools</h2>
6746 <p>External merge tools and their properties are configured in the
6747 merge-tools configuration section - see hgrc(5) - but they can often just
6748 be named by their executable.</p>
6749 <p>A merge tool is generally usable if its executable can be found on the
6750 system and if it can handle the merge. The executable is found if it
6751 is an absolute or relative executable path or the name of an
6752 application in the executable search path. The tool is assumed to be
6753 able to handle the merge if it can handle symlinks if the file is a
6754 symlink, if it can handle binary files if the file is binary, and if a
6755 GUI is available if the tool requires a GUI.</p>
6756 <p>There are some internal merge tools which can be used. The internal
6757 merge tools are:</p>
6758 <dl class="docutils">
6759 <dt><tt class="docutils literal">:dump</tt></dt>
6760 <dd><p class="first">Creates three versions of the files to merge, containing the
6761 contents of local, other and base. These files can then be used to
6762 perform a merge manually. If the file to be merged is named
6763 <tt class="docutils literal">a.txt</tt>, these files will accordingly be named <tt class="docutils literal">a.txt.local</tt>,
6764 <tt class="docutils literal">a.txt.other</tt> and <tt class="docutils literal">a.txt.base</tt> and they will be placed in the
6765 same directory as <tt class="docutils literal">a.txt</tt>.</p>
6766 <p>This implies premerge. Therefore, files aren't dumped, if premerge
6767 runs successfully. Use :forcedump to forcibly write files out.</p>
6768 <p class="last">(actual capabilities: binary, symlink)</p>
6769 </dd>
6770 <dt><tt class="docutils literal">:fail</tt></dt>
6771 <dd><p class="first">Rather than attempting to merge files that were modified on both
6772 branches, it marks them as unresolved. The resolve command must be
6773 used to resolve these conflicts.</p>
6774 <p class="last">(actual capabilities: binary, symlink)</p>
6775 </dd>
6776 <dt><tt class="docutils literal">:forcedump</tt></dt>
6777 <dd><p class="first">Creates three versions of the files as same as :dump, but omits premerge.</p>
6778 <p class="last">(actual capabilities: binary, symlink)</p>
6779 </dd>
6780 <dt><tt class="docutils literal">:local</tt></dt>
6781 <dd><p class="first">Uses the local <cite>p1()</cite> version of files as the merged version.</p>
6782 <p class="last">(actual capabilities: binary, symlink)</p>
6783 </dd>
6784 <dt><tt class="docutils literal">:merge</tt></dt>
6785 <dd>Uses the internal non-interactive simple merge algorithm for merging
6786 files. It will fail if there are any conflicts and leave markers in
6787 the partially merged file. Markers will have two sections, one for each side
6788 of merge.</dd>
6789 <dt><tt class="docutils literal"><span class="pre">:merge-local</span></tt></dt>
6790 <dd>Like :merge, but resolve all conflicts non-interactively in favor
6791 of the local <cite>p1()</cite> changes.</dd>
6792 <dt><tt class="docutils literal"><span class="pre">:merge-other</span></tt></dt>
6793 <dd>Like :merge, but resolve all conflicts non-interactively in favor
6794 of the other <cite>p2()</cite> changes.</dd>
6795 <dt><tt class="docutils literal">:merge3</tt></dt>
6796 <dd>Uses the internal non-interactive simple merge algorithm for merging
6797 files. It will fail if there are any conflicts and leave markers in
6798 the partially merged file. Marker will have three sections, one from each
6799 side of the merge and one for the base content.</dd>
6800 <dt><tt class="docutils literal">:mergediff</tt></dt>
6801 <dd>Uses the internal non-interactive simple merge algorithm for merging
6802 files. It will fail if there are any conflicts and leave markers in
6803 the partially merged file. The marker will have two sections, one with the
6804 content from one side of the merge, and one with a diff from the base
6805 content to the content on the other side. (experimental)</dd>
6806 <dt><tt class="docutils literal">:other</tt></dt>
6807 <dd><p class="first">Uses the other <cite>p2()</cite> version of files as the merged version.</p>
6808 <p class="last">(actual capabilities: binary, symlink)</p>
6809 </dd>
6810 <dt><tt class="docutils literal">:prompt</tt></dt>
6811 <dd><p class="first">Asks the user which of the local <cite>p1()</cite> or the other <cite>p2()</cite> version to
6812 keep as the merged version.</p>
6813 <p class="last">(actual capabilities: binary, symlink)</p>
6814 </dd>
6815 <dt><tt class="docutils literal">:tagmerge</tt></dt>
6816 <dd>Uses the internal tag merge algorithm (experimental).</dd>
6817 <dt><tt class="docutils literal">:union</tt></dt>
6818 <dd>Uses the internal non-interactive simple merge algorithm for merging
6819 files. It will use both local and other sides for conflict regions by
6820 adding local on top of other.
6821 No markers are inserted.</dd>
6822 <dt><tt class="docutils literal"><span class="pre">:union-other-first</span></tt></dt>
6823 <dd>Like :union, but add other on top of local.</dd>
6824 </dl>
6825 <p>Internal tools are always available and do not require a GUI but will
6826 by default not handle symlinks or binary files. See next section for
6827 detail about &quot;actual capabilities&quot; described above.</p>
6828 </div>
6829 <div class="section" id="choosing-a-merge-tool">
6830 <h2>Choosing a merge tool</h2>
6831 <p>Mercurial uses these rules when deciding which merge tool to use:</p>
6832 <ol class="arabic simple">
6833 <li>If a tool has been specified with the --tool option to merge or resolve, it
6834 is used. If it is the name of a tool in the merge-tools configuration, its
6835 configuration is used. Otherwise the specified tool must be executable by
6836 the shell.</li>
6837 <li>If the <tt class="docutils literal">HGMERGE</tt> environment variable is present, its value is used and
6838 must be executable by the shell.</li>
6839 <li>If the filename of the file to be merged matches any of the patterns in the
6840 merge-patterns configuration section, the first usable merge tool
6841 corresponding to a matching pattern is used.</li>
6842 <li>If ui.merge is set it will be considered next. If the value is not the name
6843 of a configured tool, the specified value is used and must be executable by
6844 the shell. Otherwise the named tool is used if it is usable.</li>
6845 <li>If any usable merge tools are present in the merge-tools configuration
6846 section, the one with the highest priority is used.</li>
6847 <li>If a program named <tt class="docutils literal">hgmerge</tt> can be found on the system, it is used - but
6848 it will by default not be used for symlinks and binary files.</li>
6849 <li>If the file to be merged is not binary and is not a symlink, then
6850 internal <tt class="docutils literal">:merge</tt> is used.</li>
6851 <li>Otherwise, <tt class="docutils literal">:prompt</tt> is used.</li>
6852 </ol>
6853 <p>For historical reason, Mercurial treats merge tools as below while
6854 examining rules above.</p>
6855 <table border="1" class="docutils">
6856 <colgroup>
6857 <col width="13%" />
6858 <col width="47%" />
6859 <col width="19%" />
6860 <col width="22%" />
6861 </colgroup>
6862 <thead valign="bottom">
6863 <tr><th class="head">step</th>
6864 <th class="head">specified via</th>
6865 <th class="head">binary</th>
6866 <th class="head">symlink</th>
6867 </tr>
6868 </thead>
6869 <tbody valign="top">
6870 <tr><td><ol class="first last arabic simple">
6871 <li></li>
6872 </ol>
6873 </td>
6874 <td>--tool</td>
6875 <td>o/o</td>
6876 <td>o/o</td>
6877 </tr>
6878 <tr><td><ol class="first last arabic simple" start="2">
6879 <li></li>
6880 </ol>
6881 </td>
6882 <td>HGMERGE</td>
6883 <td>o/o</td>
6884 <td>o/o</td>
6885 </tr>
6886 <tr><td><ol class="first last arabic simple" start="3">
6887 <li></li>
6888 </ol>
6889 </td>
6890 <td>merge-patterns</td>
6891 <td>o/o(*)</td>
6892 <td>x/?(*)</td>
6893 </tr>
6894 <tr><td><ol class="first last arabic simple" start="4">
6895 <li></li>
6896 </ol>
6897 </td>
6898 <td>ui.merge</td>
6899 <td>x/?(*)</td>
6900 <td>x/?(*)</td>
6901 </tr>
6902 </tbody>
6903 </table>
6904 <p>Each capability column indicates Mercurial behavior for
6905 internal/external merge tools at examining each rule.</p>
6906 <ul class="simple">
6907 <li>&quot;o&quot;: &quot;assume that a tool has capability&quot;</li>
6908 <li>&quot;x&quot;: &quot;assume that a tool does not have capability&quot;</li>
6909 <li>&quot;?&quot;: &quot;check actual capability of a tool&quot;</li>
6910 </ul>
6911 <p>If <tt class="docutils literal"><span class="pre">merge.strict-capability-check</span></tt> configuration is true, Mercurial
6912 checks capabilities of merge tools strictly in (*) cases above (= each
6913 capability column becomes &quot;?/?&quot;). It is false by default for backward
6914 compatibility.</p>
6915 <div class="admonition note">
6916 <p class="first admonition-title">Note</p>
6917 <p class="last">After selecting a merge program, Mercurial will by default attempt
6918 to merge the files using a simple merge algorithm first. Only if it doesn't
6919 succeed because of conflicting changes will Mercurial actually execute the
6920 merge program. Whether to use the simple merge algorithm first can be
6921 controlled by the premerge setting of the merge tool. Premerge is enabled by
6922 default unless the file is binary or a symlink.</p>
6923 </div>
6924 <p>See the merge-tools and ui sections of hgrc(5) for details on the
6925 configuration of merge tools.</p>
6926 </div>
6927 </div>
6928 <div class="section" id="pager-support">
6929 <span id="pager"></span><h1><a class="toc-backref" href="#contents">Pager Support</a></h1>
6930 <p>Some Mercurial commands can produce a lot of output, and Mercurial will
6931 attempt to use a pager to make those commands more pleasant.</p>
6932 <p>To set the pager that should be used, set the application variable:</p>
6933 <pre class="literal-block">
6934 [pager]
6935 pager = less -FRX
6936 </pre>
6937 <p>If no pager is set in the user or repository configuration, Mercurial uses the
6938 environment variable $PAGER. If $PAGER is not set, pager.pager from the default
6939 or system configuration is used. If none of these are set, a default pager will
6940 be used, typically <cite>less</cite> on Unix and <cite>more</cite> on Windows.</p>
6941 <div class="windows docutils container">
6942 On Windows, <cite>more</cite> is not color aware, so using it effectively disables color.
6943 MSYS and Cygwin shells provide <cite>less</cite> as a pager, which can be configured to
6944 support ANSI color codes. See <a class="reference external" href="hgrc.5.html#color"><tt class="docutils literal">hg help config.color.pagermode</tt></a> to configure
6945 the color mode when invoking a pager.</div>
6946 <p>You can disable the pager for certain commands by adding them to the
6947 pager.ignore list:</p>
6948 <pre class="literal-block">
6949 [pager]
6950 ignore = version, help, update
6951 </pre>
6952 <p>To ignore global commands like <a class="reference external" href="hg.1.html#version"><tt class="docutils literal">hg version</tt></a> or <a class="reference external" href="hg.1.html#help"><tt class="docutils literal">hg help</tt></a>, you have
6953 to specify them in your user configuration file.</p>
6954 <p>To control whether the pager is used at all for an individual command,
6955 you can use --pager=&lt;value&gt;:</p>
6956 <blockquote>
6957 <ul class="simple">
6958 <li>use as needed: <cite>auto</cite>.</li>
6959 <li>require the pager: <cite>yes</cite> or <cite>on</cite>.</li>
6960 <li>suppress the pager: <cite>no</cite> or <cite>off</cite> (any unrecognized value
6961 will also work).</li>
6962 </ul>
6963 </blockquote>
6964 <p>To globally turn off all attempts to use a pager, set:</p>
6965 <pre class="literal-block">
6966 [ui]
6967 paginate = never
6968 </pre>
6969 <p>which will prevent the pager from running.</p>
6970 </div>
6971 <div class="section" id="file-name-patterns">
6972 <span id="patterns"></span><h1><a class="toc-backref" href="#contents">File Name Patterns</a></h1>
6973 <p>Mercurial accepts several notations for identifying one or more files
6974 at a time.</p>
6975 <p>By default, Mercurial treats filenames verbatim without pattern
6976 matching, relative to the current working directory. Note that your
6977 system shell might perform pattern matching of its own before passing
6978 filenames into Mercurial.</p>
6979 <p>Alternate pattern notations must be specified explicitly.</p>
6980 <div class="admonition note">
6981 <p class="first admonition-title">Note</p>
6982 <p class="last">Patterns specified in <tt class="docutils literal">.hgignore</tt> are not rooted.
6983 Please see <a class="reference external" href="hg.1.html#hgignore"><tt class="docutils literal">hg help hgignore</tt></a> for details.</p>
6984 </div>
6985 <p>To use a plain path name without any pattern matching, start it with
6986 <tt class="docutils literal">path:</tt>. These path names must completely match starting at the
6987 current repository root, and when the path points to a directory, it is matched
6988 recursively. To match all files in a directory non-recursively (not including
6989 any files in subdirectories), <tt class="docutils literal">rootfilesin:</tt> can be used, specifying an
6990 absolute path (relative to the repository root). To match a single file exactly,
6991 relative to the repository root, you can use <tt class="docutils literal">filepath:</tt>.</p>
6992 <p>To use an extended glob, start a name with <tt class="docutils literal">glob:</tt>. Globs are rooted
6993 at the current directory; a glob such as <tt class="docutils literal">*.c</tt> will only match files
6994 in the current directory ending with <tt class="docutils literal">.c</tt>. <tt class="docutils literal">rootglob:</tt> can be used
6995 instead of <tt class="docutils literal">glob:</tt> for a glob that is rooted at the root of the
6996 repository.</p>
6997 <p>The supported glob syntax extensions are <tt class="docutils literal">**</tt> to match any string
6998 across path separators and <tt class="docutils literal">{a,b}</tt> to mean &quot;a or b&quot;.</p>
6999 <p>To use a Perl/Python regular expression, start a name with <tt class="docutils literal">re:</tt>.
7000 Regexp pattern matching is anchored at the root of the repository.</p>
7001 <p>To read name patterns from a file, use <tt class="docutils literal">listfile:</tt> or <tt class="docutils literal">listfile0:</tt>.
7002 The latter expects null delimited patterns while the former expects line
7003 feeds. Each string read from the file is itself treated as a file
7004 pattern.</p>
7005 <p>To read a set of patterns from a file, use <tt class="docutils literal">include:</tt> or <tt class="docutils literal">subinclude:</tt>.
7006 <tt class="docutils literal">include:</tt> will use all the patterns from the given file and treat them as if
7007 they had been passed in manually. <tt class="docutils literal">subinclude:</tt> will only apply the patterns
7008 against files that are under the subinclude file's directory. See <a class="reference external" href="hg.1.html#hgignore"><tt class="docutils literal">hg help
7009 hgignore</tt></a> for details on the format of these files.</p>
7010 <p>All patterns, except for <tt class="docutils literal">glob:</tt> specified in command line (not for
7011 <tt class="docutils literal"><span class="pre">-I</span></tt> or <tt class="docutils literal"><span class="pre">-X</span></tt> options), can match also against directories: files
7012 under matched directories are treated as matched.
7013 For <tt class="docutils literal"><span class="pre">-I</span></tt> and <tt class="docutils literal"><span class="pre">-X</span></tt> options, <tt class="docutils literal">glob:</tt> will match directories recursively.</p>
7014 <p>Plain examples:</p>
7015 <pre class="literal-block">
7016 path:foo/bar a name bar in a directory named foo in the root
7017 of the repository
7018 path:some/path a file or directory named &quot;some/path&quot;
7019 filepath:some/path/to/a/file exactly a single file named
7020 &quot;some/path/to/a/file&quot;, relative to the root
7021 of the repository
7022 rootfilesin:foo/bar the files in a directory called foo/bar, but
7023 not any files in its subdirectories and not
7024 a file bar in directory foo
7025 </pre>
7026 <p>Glob examples:</p>
7027 <pre class="literal-block">
7028 glob:*.c any name ending in &quot;.c&quot; in the current directory
7029 *.c any name ending in &quot;.c&quot; in the current directory
7030 **.c any name ending in &quot;.c&quot; in any subdirectory of the
7031 current directory including itself.
7032 foo/* any file in directory foo
7033 foo/** any file in directory foo plus all its subdirectories,
7034 recursively
7035 foo/*.c any name ending in &quot;.c&quot; in the directory foo
7036 foo/**.c any name ending in &quot;.c&quot; in any subdirectory of foo
7037 including itself.
7038 rootglob:*.c any name ending in &quot;.c&quot; in the root of the repository
7039 </pre>
7040 <p>Regexp examples:</p>
7041 <pre class="literal-block">
7042 re:.*\.c$ any name ending in &quot;.c&quot;, anywhere in the repository
7043 </pre>
7044 <p>File examples:</p>
7045 <pre class="literal-block">
7046 listfile:list.txt read list from list.txt with one file pattern per line
7047 listfile0:list.txt read list from list.txt with null byte delimiters
7048 </pre>
7049 <p>See also <a class="reference external" href="hg.1.html#filesets"><tt class="docutils literal">hg help filesets</tt></a>.</p>
7050 <p>Include examples:</p>
7051 <pre class="literal-block">
7052 include:path/to/mypatternfile reads patterns to be applied to all paths
7053 subinclude:path/to/subignorefile reads patterns specifically for paths in the
7054 subdirectory
7055 </pre>
7056 </div>
7057 <div class="section" id="working-with-phases">
7058 <span id="phases"></span><h1><a class="toc-backref" href="#contents">Working with Phases</a></h1>
7059 <div class="section" id="what-are-phases">
7060 <h2>What are phases?</h2>
7061 <p>Phases are a system for tracking which changesets have been or should
7062 be shared. This helps prevent common mistakes when modifying history
7063 (for instance, with the mq or rebase extensions).</p>
7064 <p>Each changeset in a repository is in one of the following phases:</p>
7065 <blockquote>
7066 <ul class="simple">
7067 <li>public : changeset is visible on a public server</li>
7068 <li>draft : changeset is not yet published</li>
7069 <li>secret : changeset should not be pushed, pulled, or cloned</li>
7070 </ul>
7071 </blockquote>
7072 <p>These phases are ordered (public &lt; draft &lt; secret) and no changeset
7073 can be in a lower phase than its ancestors. For instance, if a
7074 changeset is public, all its ancestors are also public. Lastly,
7075 changeset phases should only be changed towards the public phase.</p>
7076 </div>
7077 <div class="section" id="how-are-phases-managed">
7078 <h2>How are phases managed?</h2>
7079 <p>For the most part, phases should work transparently. By default, a
7080 changeset is created in the draft phase and is moved into the public
7081 phase when it is pushed to another repository.</p>
7082 <p>Once changesets become public, extensions like mq and rebase will
7083 refuse to operate on them to prevent creating duplicate changesets.
7084 Phases can also be manually manipulated with the <a class="reference external" href="hg.1.html#phase"><tt class="docutils literal">hg phase</tt></a> command
7085 if needed. See <a class="reference external" href="hg.1.html#-v"><tt class="docutils literal">hg help <span class="pre">-v</span> phase</tt></a> for examples.</p>
7086 <p>To make your commits secret by default, put this in your
7087 configuration file:</p>
7088 <pre class="literal-block">
7089 [phases]
7090 new-commit = secret
7091 </pre>
7092 </div>
7093 <div class="section" id="phases-and-servers">
7094 <h2>Phases and servers</h2>
7095 <p>Normally, all servers are <tt class="docutils literal">publishing</tt> by default. This means:</p>
7096 <pre class="literal-block">
7097 - all draft changesets that are pulled or cloned appear in phase
7098 public on the client
7099
7100 - all draft changesets that are pushed appear as public on both
7101 client and server
7102
7103 - secret changesets are neither pushed, pulled, or cloned
7104 </pre>
7105 <div class="admonition note">
7106 <p class="first admonition-title">Note</p>
7107 <p class="last">Pulling a draft changeset from a publishing server does not mark it
7108 as public on the server side due to the read-only nature of pull.</p>
7109 </div>
7110 <p>Sometimes it may be desirable to push and pull changesets in the draft
7111 phase to share unfinished work. This can be done by setting a
7112 repository to disable publishing in its configuration file:</p>
7113 <pre class="literal-block">
7114 [phases]
7115 publish = False
7116 </pre>
7117 <p>See <a class="reference external" href="hgrc.5.html"><tt class="docutils literal">hg help config</tt></a> for more information on configuration files.</p>
7118 <div class="admonition note">
7119 <p class="first admonition-title">Note</p>
7120 <p class="last">Servers running older versions of Mercurial are treated as
7121 publishing.</p>
7122 </div>
7123 <div class="admonition note">
7124 <p class="first admonition-title">Note</p>
7125 <p class="last">Changesets in secret phase are not exchanged with the server. This
7126 applies to their content: file names, file contents, and changeset
7127 metadata. For technical reasons, the identifier (e.g. d825e4025e39)
7128 of the secret changeset may be communicated to the server.</p>
7129 </div>
7130 </div>
7131 <div class="section" id="examples-2">
7132 <h2>Examples</h2>
7133 <blockquote>
7134 <ul>
7135 <li><p class="first">list changesets in draft or secret phase:</p>
7136 <pre class="literal-block">
7137 hg log -r &quot;not public()&quot;
7138 </pre>
7139 </li>
7140 <li><p class="first">change all secret changesets to draft:</p>
7141 <pre class="literal-block">
7142 hg phase --draft &quot;secret()&quot;
7143 </pre>
7144 </li>
7145 <li><p class="first">forcibly move the current changeset and descendants from public to draft:</p>
7146 <pre class="literal-block">
7147 hg phase --force --draft .
7148 </pre>
7149 </li>
7150 <li><p class="first">show a list of changeset revisions and each corresponding phase:</p>
7151 <pre class="literal-block">
7152 hg log --template &quot;{rev} {phase}\n&quot;
7153 </pre>
7154 </li>
7155 <li><p class="first">resynchronize draft changesets relative to a remote repository:</p>
7156 <pre class="literal-block">
7157 hg phase -fd &quot;outgoing(URL)&quot;
7158 </pre>
7159 </li>
7160 </ul>
7161 </blockquote>
7162 <p>See <a class="reference external" href="hg.1.html#phase"><tt class="docutils literal">hg help phase</tt></a> for more information on manually manipulating phases.</p>
7163 </div>
7164 </div>
7165 <div class="section" id="specifying-revisions">
7166 <span id="mrevs"></span><span id="multirevs"></span><span id="revset"></span><span id="revsets"></span><span id="revs"></span><span id="revisions"></span><h1><a class="toc-backref" href="#contents">Specifying Revisions</a></h1>
7167 <p>Mercurial supports several ways to specify revisions.</p>
7168 <div class="section" id="specifying-single-revisions">
7169 <h2>Specifying single revisions</h2>
7170 <p>A plain integer is treated as a revision number. Negative integers are
7171 treated as sequential offsets from the tip, with -1 denoting the tip,
7172 -2 denoting the revision prior to the tip, and so forth.</p>
7173 <p>A 40-digit hexadecimal string is treated as a unique revision identifier.
7174 A hexadecimal string less than 40 characters long is treated as a
7175 unique revision identifier and is referred to as a short-form
7176 identifier. A short-form identifier is only valid if it is the prefix
7177 of exactly one full-length identifier.</p>
7178 <p>Any other string is treated as a bookmark, tag, or branch name. A
7179 bookmark is a movable pointer to a revision. A tag is a permanent name
7180 associated with a revision. A branch name denotes the tipmost open branch head
7181 of that branch - or if they are all closed, the tipmost closed head of the
7182 branch. Bookmark, tag, and branch names must not contain the &quot;:&quot; character.</p>
7183 <p>The reserved name &quot;tip&quot; always identifies the most recent revision.</p>
7184 <p>The reserved name &quot;null&quot; indicates the null revision. This is the
7185 revision of an empty repository, and the parent of revision 0.</p>
7186 <p>The reserved name &quot;.&quot; indicates the working directory parent. If no
7187 working directory is checked out, it is equivalent to null. If an
7188 uncommitted merge is in progress, &quot;.&quot; is the revision of the first
7189 parent.</p>
7190 <p>Finally, commands that expect a single revision (like <tt class="docutils literal">hg update</tt>) also
7191 accept revsets (see below for details). When given a revset, they use the
7192 last revision of the revset. A few commands accept two single revisions
7193 (like <tt class="docutils literal">hg diff</tt>). When given a revset, they use the first and the last
7194 revisions of the revset.</p>
7195 </div>
7196 <div class="section" id="specifying-multiple-revisions">
7197 <h2>Specifying multiple revisions</h2>
7198 <p>Mercurial supports a functional language for selecting a set of
7199 revisions. Expressions in this language are called revsets.</p>
7200 <p>The language supports a number of predicates which are joined by infix
7201 operators. Parenthesis can be used for grouping.</p>
7202 <p>Identifiers such as branch names may need quoting with single or
7203 double quotes if they contain characters like <tt class="docutils literal">-</tt> or if they match
7204 one of the predefined predicates.</p>
7205 <p>Special characters can be used in quoted identifiers by escaping them,
7206 e.g., <tt class="docutils literal">\n</tt> is interpreted as a newline. To prevent them from being
7207 interpreted, strings can be prefixed with <tt class="docutils literal">r</tt>, e.g. <tt class="docutils literal"><span class="pre">r'...'</span></tt>.</p>
7208 </div>
7209 <div class="section" id="operators-1">
7210 <h2>Operators</h2>
7211 <p>There is a single prefix operator:</p>
7212 <dl class="docutils">
7213 <dt><tt class="docutils literal">not x</tt></dt>
7214 <dd>Changesets not in x. Short form is <tt class="docutils literal">! x</tt>.</dd>
7215 </dl>
7216 <p>These are the supported infix operators:</p>
7217 <dl class="docutils">
7218 <dt><tt class="docutils literal"><span class="pre">x::y</span></tt></dt>
7219 <dd><p class="first">A DAG range, meaning all changesets that are descendants of x and
7220 ancestors of y, including x and y themselves. If the first endpoint
7221 is left out, this is equivalent to <tt class="docutils literal">ancestors(y)</tt>, if the second
7222 is left out it is equivalent to <tt class="docutils literal">descendants(x)</tt>.</p>
7223 <p class="last">An alternative syntax is <tt class="docutils literal"><span class="pre">x..y</span></tt>.</p>
7224 </dd>
7225 <dt><tt class="docutils literal">x:y</tt></dt>
7226 <dd>All changesets with revision numbers between x and y, both
7227 inclusive. Either endpoint can be left out, they default to 0 and
7228 tip.</dd>
7229 <dt><tt class="docutils literal">x and y</tt></dt>
7230 <dd>The intersection of changesets in x and y. Short form is <tt class="docutils literal">x &amp; y</tt>.</dd>
7231 <dt><tt class="docutils literal">x or y</tt></dt>
7232 <dd>The union of changesets in x and y. There are two alternative short
7233 forms: <tt class="docutils literal">x | y</tt> and <tt class="docutils literal">x + y</tt>.</dd>
7234 <dt><tt class="docutils literal">x - y</tt></dt>
7235 <dd>Changesets in x but not in y.</dd>
7236 <dt><tt class="docutils literal">x % y</tt></dt>
7237 <dd>Changesets that are ancestors of x but not ancestors of y (i.e. ::x - ::y).
7238 This is shorthand notation for <tt class="docutils literal">only(x, y)</tt> (see below). The second
7239 argument is optional and, if left out, is equivalent to <tt class="docutils literal">only(x)</tt>.</dd>
7240 <dt><tt class="docutils literal">x^n</tt></dt>
7241 <dd>The nth parent of x, n == 0, 1, or 2.
7242 For n == 0, x; for n == 1, the first parent of each changeset in x;
7243 for n == 2, the second parent of changeset in x.</dd>
7244 <dt><tt class="docutils literal">x~n</tt></dt>
7245 <dd>The nth first ancestor of x; <tt class="docutils literal">x~0</tt> is x; <tt class="docutils literal">x~3</tt> is <tt class="docutils literal"><span class="pre">x^^^</span></tt>.
7246 For n &lt; 0, the nth unambiguous descendent of x.</dd>
7247 <dt><tt class="docutils literal">x ## y</tt></dt>
7248 <dd><p class="first">Concatenate strings and identifiers into one string.</p>
7249 <p>All other prefix, infix and postfix operators have lower priority than
7250 <tt class="docutils literal">##</tt>. For example, <tt class="docutils literal">a1 ## a2~2</tt> is equivalent to <tt class="docutils literal">(a1 ## <span class="pre">a2)~2</span></tt>.</p>
7251 <p>For example:</p>
7252 <pre class="literal-block">
7253 [revsetalias]
7254 issue(a1) = grep(r'\bissue[ :]?' ## a1 ## r'\b|\bbug\(' ## a1 ## r'\)')
7255 </pre>
7256 <p class="last"><tt class="docutils literal">issue(1234)</tt> is equivalent to
7257 <tt class="docutils literal"><span class="pre">grep(r'\bissue[</span> <span class="pre">:]?1234\b|\bbug\(1234\)')</span></tt>
7258 in this case. This matches against all of &quot;issue 1234&quot;, &quot;issue:1234&quot;,
7259 &quot;issue1234&quot; and &quot;bug(1234)&quot;.</p>
7260 </dd>
7261 </dl>
7262 <p>There is a single postfix operator:</p>
7263 <dl class="docutils">
7264 <dt><tt class="docutils literal">x^</tt></dt>
7265 <dd>Equivalent to <tt class="docutils literal">x^1</tt>, the first parent of each changeset in x.</dd>
7266 </dl>
7267 </div>
7268 <div class="section" id="patterns-1">
7269 <h2>Patterns</h2>
7270 <p>Where noted, predicates that perform string matching can accept a pattern
7271 string. The pattern may be either a literal, or a regular expression. If the
7272 pattern starts with <tt class="docutils literal">re:</tt>, the remainder of the pattern is treated as a
7273 regular expression. Otherwise, it is treated as a literal. To match a pattern
7274 that actually starts with <tt class="docutils literal">re:</tt>, use the prefix <tt class="docutils literal">literal:</tt>.</p>
7275 <p>Matching is case-sensitive, unless otherwise noted. To perform a case-
7276 insensitive match on a case-sensitive predicate, use a regular expression,
7277 prefixed with <tt class="docutils literal"><span class="pre">(?i)</span></tt>.</p>
7278 <p>For example, <tt class="docutils literal"><span class="pre">tag(r're:(?i)release')</span></tt> matches &quot;release&quot; or &quot;RELEASE&quot;
7279 or &quot;Release&quot;, etc.</p>
7280 </div>
7281 <div class="section" id="predicates-1">
7282 <h2>Predicates</h2>
7283 <p>The following predicates are supported:</p>
7284 <dl class="docutils">
7285 <dt><tt class="docutils literal">adds(pattern)</tt></dt>
7286 <dd><p class="first">Changesets that add a file matching pattern.</p>
7287 <p class="last">The pattern without explicit kind like <tt class="docutils literal">glob:</tt> is expected to be
7288 relative to the current directory and match against a file or a
7289 directory.</p>
7290 </dd>
7291 <dt><tt class="docutils literal">all()</tt></dt>
7292 <dd>All changesets, the same as <tt class="docutils literal">0:tip</tt>.</dd>
7293 <dt><tt class="docutils literal"><span class="pre">ancestor(*changeset)</span></tt></dt>
7294 <dd><p class="first">A greatest common ancestor of the changesets.</p>
7295 <p class="last">Accepts 0 or more changesets.
7296 Will return empty list when passed no args.
7297 Greatest common ancestor of a single changeset is that changeset.</p>
7298 </dd>
7299 <dt><tt class="docutils literal">ancestors(set[, depth])</tt></dt>
7300 <dd><p class="first">Changesets that are ancestors of changesets in set, including the
7301 given changesets themselves.</p>
7302 <p class="last">If depth is specified, the result only includes changesets up to
7303 the specified generation.</p>
7304 </dd>
7305 <dt><tt class="docutils literal">author(string)</tt></dt>
7306 <dd>Alias for <tt class="docutils literal">user(string)</tt>.</dd>
7307 <dt><tt class="docutils literal">bisect(string)</tt></dt>
7308 <dd><p class="first">Changesets marked in the specified bisect status:</p>
7309 <ul class="last simple">
7310 <li><tt class="docutils literal">good</tt>, <tt class="docutils literal">bad</tt>, <tt class="docutils literal">skip</tt>: csets explicitly marked as good/bad/skip</li>
7311 <li><tt class="docutils literal">goods</tt>, <tt class="docutils literal">bads</tt> : csets topologically good/bad</li>
7312 <li><tt class="docutils literal">range</tt> : csets taking part in the bisection</li>
7313 <li><tt class="docutils literal">pruned</tt> : csets that are goods, bads or skipped</li>
7314 <li><tt class="docutils literal">untested</tt> : csets whose fate is yet unknown</li>
7315 <li><tt class="docutils literal">ignored</tt> : csets ignored due to DAG topology</li>
7316 <li><tt class="docutils literal">current</tt> : the cset currently being bisected</li>
7317 </ul>
7318 </dd>
7319 <dt><tt class="docutils literal"><span class="pre">bookmark([name])</span></tt></dt>
7320 <dd><p class="first">The named bookmark or all bookmarks.</p>
7321 <p class="last">Pattern matching is supported for <cite>name</cite>. See <a class="reference external" href="hg.1.html#revisions.patterns"><tt class="docutils literal">hg help revisions.patterns</tt></a>.</p>
7322 </dd>
7323 <dt><tt class="docutils literal">branch(string or set)</tt></dt>
7324 <dd><p class="first">All changesets belonging to the given branch or the branches of the given
7325 changesets.</p>
7326 <p class="last">Pattern matching is supported for <cite>string</cite>. See
7327 <a class="reference external" href="hg.1.html#revisions.patterns"><tt class="docutils literal">hg help revisions.patterns</tt></a>.</p>
7328 </dd>
7329 <dt><tt class="docutils literal">branchpoint()</tt></dt>
7330 <dd>Changesets with more than one child.</dd>
7331 <dt><tt class="docutils literal">bundle()</tt></dt>
7332 <dd><p class="first">Changesets in the bundle.</p>
7333 <p class="last">Bundle must be specified by the -R option.</p>
7334 </dd>
7335 <dt><tt class="docutils literal">children(set)</tt></dt>
7336 <dd>Child changesets of changesets in set.</dd>
7337 <dt><tt class="docutils literal">closed()</tt></dt>
7338 <dd>Changeset is closed.</dd>
7339 <dt><tt class="docutils literal">commonancestors(set)</tt></dt>
7340 <dd>Changesets that are ancestors of every changeset in set.</dd>
7341 <dt><tt class="docutils literal">conflictlocal()</tt></dt>
7342 <dd><p class="first">The local side of the merge, if currently in an unresolved merge.</p>
7343 <p class="last">&quot;merge&quot; here includes merge conflicts from e.g. 'hg rebase' or 'hg graft'.</p>
7344 </dd>
7345 <dt><tt class="docutils literal">conflictother()</tt></dt>
7346 <dd><p class="first">The other side of the merge, if currently in an unresolved merge.</p>
7347 <p class="last">&quot;merge&quot; here includes merge conflicts from e.g. 'hg rebase' or 'hg graft'.</p>
7348 </dd>
7349 <dt><tt class="docutils literal">contains(pattern)</tt></dt>
7350 <dd><p class="first">The revision's manifest contains a file matching pattern (but might not
7351 modify it). See <a class="reference external" href="hg.1.html#patterns"><tt class="docutils literal">hg help patterns</tt></a> for information about file patterns.</p>
7352 <p class="last">The pattern without explicit kind like <tt class="docutils literal">glob:</tt> is expected to be
7353 relative to the current directory and match against a file exactly
7354 for efficiency.</p>
7355 </dd>
7356 <dt><tt class="docutils literal"><span class="pre">converted([id])</span></tt></dt>
7357 <dd>Changesets converted from the given identifier in the old repository if
7358 present, or all converted changesets if no identifier is specified.</dd>
7359 <dt><tt class="docutils literal">date(interval)</tt></dt>
7360 <dd>Changesets within the interval, see <a class="reference external" href="hg.1.html#dates"><tt class="docutils literal">hg help dates</tt></a>.</dd>
7361 <dt><tt class="docutils literal">desc(string)</tt></dt>
7362 <dd><p class="first">Search commit message for string. The match is case-insensitive.</p>
7363 <p class="last">Pattern matching is supported for <cite>string</cite>. See
7364 <a class="reference external" href="hg.1.html#revisions.patterns"><tt class="docutils literal">hg help revisions.patterns</tt></a>.</p>
7365 </dd>
7366 <dt><tt class="docutils literal">descendants(set[, depth])</tt></dt>
7367 <dd><p class="first">Changesets which are descendants of changesets in set, including the
7368 given changesets themselves.</p>
7369 <p class="last">If depth is specified, the result only includes changesets up to
7370 the specified generation.</p>
7371 </dd>
7372 <dt><tt class="docutils literal"><span class="pre">destination([set])</span></tt></dt>
7373 <dd>Changesets that were created by a graft, transplant or rebase operation,
7374 with the given revisions specified as the source. Omitting the optional set
7375 is the same as passing all().</dd>
7376 <dt><tt class="docutils literal">diffcontains(pattern)</tt></dt>
7377 <dd><p class="first">Search revision differences for when the pattern was added or removed.</p>
7378 <p class="last">The pattern may be a substring literal or a regular expression. See
7379 <a class="reference external" href="hg.1.html#revisions.patterns"><tt class="docutils literal">hg help revisions.patterns</tt></a>.</p>
7380 </dd>
7381 <dt><tt class="docutils literal">draft()</tt></dt>
7382 <dd>Changeset in draft phase.</dd>
7383 <dt><tt class="docutils literal">expectsize(set[, size])</tt></dt>
7384 <dd><p class="first">Return the given revset if size matches the revset size.
7385 Abort if the revset doesn't expect given size.
7386 size can either be an integer range or an integer.</p>
7387 <p class="last">For example, <tt class="docutils literal">expectsize(0:1, 3:5)</tt> will abort as revset size is 2 and
7388 2 is not between 3 and 5 inclusive.</p>
7389 </dd>
7390 <dt><tt class="docutils literal">extra(label, [value])</tt></dt>
7391 <dd><p class="first">Changesets with the given label in the extra metadata, with the given
7392 optional value.</p>
7393 <p class="last">Pattern matching is supported for <cite>value</cite>. See
7394 <a class="reference external" href="hg.1.html#revisions.patterns"><tt class="docutils literal">hg help revisions.patterns</tt></a>.</p>
7395 </dd>
7396 <dt><tt class="docutils literal">file(pattern)</tt></dt>
7397 <dd><p class="first">Changesets affecting files matched by pattern.</p>
7398 <p>For a faster but less accurate result, consider using <tt class="docutils literal">filelog()</tt>
7399 instead.</p>
7400 <p class="last">This predicate uses <tt class="docutils literal">glob:</tt> as the default kind of pattern.</p>
7401 </dd>
7402 <dt><tt class="docutils literal">filelog(pattern)</tt></dt>
7403 <dd><p class="first">Changesets connected to the specified filelog.</p>
7404 <p>For performance reasons, visits only revisions mentioned in the file-level
7405 filelog, rather than filtering through all changesets (much faster, but
7406 doesn't include deletes or duplicate changes). For a slower, more accurate
7407 result, use <tt class="docutils literal">file()</tt>.</p>
7408 <p class="last">The pattern without explicit kind like <tt class="docutils literal">glob:</tt> is expected to be
7409 relative to the current directory and match against a file exactly
7410 for efficiency.</p>
7411 </dd>
7412 <dt><tt class="docutils literal">first(set, [n])</tt></dt>
7413 <dd>An alias for limit().</dd>
7414 <dt><tt class="docutils literal"><span class="pre">follow([file[,</span> <span class="pre">startrev]])</span></tt></dt>
7415 <dd>An alias for <tt class="docutils literal">::.</tt> (ancestors of the working directory's first parent).
7416 If file pattern is specified, the histories of files matching given
7417 pattern in the revision given by startrev are followed, including copies.</dd>
7418 <dt><tt class="docutils literal">followlines(file, fromline:toline[, <span class="pre">startrev=.,</span> descend=False])</tt></dt>
7419 <dd><p class="first">Changesets modifying <cite>file</cite> in line range ('fromline', 'toline').</p>
7420 <p>Line range corresponds to 'file' content at 'startrev' and should hence be
7421 consistent with file size. If startrev is not specified, working directory's
7422 parent is used.</p>
7423 <p class="last">By default, ancestors of 'startrev' are returned. If 'descend' is True,
7424 descendants of 'startrev' are returned though renames are (currently) not
7425 followed in this direction.</p>
7426 </dd>
7427 <dt><tt class="docutils literal">grep(regex)</tt></dt>
7428 <dd>Like <tt class="docutils literal">keyword(string)</tt> but accepts a regex. Use <tt class="docutils literal"><span class="pre">grep(r'...')</span></tt>
7429 to ensure special escape characters are handled correctly. Unlike
7430 <tt class="docutils literal">keyword(string)</tt>, the match is case-sensitive.</dd>
7431 <dt><tt class="docutils literal">head()</tt></dt>
7432 <dd>Changeset is a named branch head.</dd>
7433 <dt><tt class="docutils literal">heads(set)</tt></dt>
7434 <dd>Members of set with no children in set.</dd>
7435 <dt><tt class="docutils literal">hidden()</tt></dt>
7436 <dd>Hidden changesets.</dd>
7437 <dt><tt class="docutils literal">id(string)</tt></dt>
7438 <dd>Revision non-ambiguously specified by the given hex string prefix.</dd>
7439 <dt><tt class="docutils literal">keyword(string)</tt></dt>
7440 <dd><p class="first">Search commit message, user name, and names of changed files for
7441 string. The match is case-insensitive.</p>
7442 <p class="last">For a regular expression or case sensitive search of these fields, use
7443 <tt class="docutils literal">grep(regex)</tt>.</p>
7444 </dd>
7445 <dt><tt class="docutils literal">last(set, [n])</tt></dt>
7446 <dd>Last n members of set, defaulting to 1.</dd>
7447 <dt><tt class="docutils literal">limit(set[, n[, <span class="pre">offset]])</span></tt></dt>
7448 <dd>First n members of set, defaulting to 1, starting from offset.</dd>
7449 <dt><tt class="docutils literal">matching(revision [, field])</tt></dt>
7450 <dd><p class="first">Changesets in which a given set of fields match the set of fields in the
7451 selected revision or set.</p>
7452 <p>To match more than one field pass the list of fields to match separated
7453 by spaces (e.g. <tt class="docutils literal">author description</tt>).</p>
7454 <p>Valid fields are most regular revision fields and some special fields.</p>
7455 <p>Regular revision fields are <tt class="docutils literal">description</tt>, <tt class="docutils literal">author</tt>, <tt class="docutils literal">branch</tt>,
7456 <tt class="docutils literal">date</tt>, <tt class="docutils literal">files</tt>, <tt class="docutils literal">phase</tt>, <tt class="docutils literal">parents</tt>, <tt class="docutils literal">substate</tt>, <tt class="docutils literal">user</tt>
7457 and <tt class="docutils literal">diff</tt>.
7458 Note that <tt class="docutils literal">author</tt> and <tt class="docutils literal">user</tt> are synonyms. <tt class="docutils literal">diff</tt> refers to the
7459 contents of the revision. Two revisions matching their <tt class="docutils literal">diff</tt> will
7460 also match their <tt class="docutils literal">files</tt>.</p>
7461 <p>Special fields are <tt class="docutils literal">summary</tt> and <tt class="docutils literal">metadata</tt>:
7462 <tt class="docutils literal">summary</tt> matches the first line of the description.
7463 <tt class="docutils literal">metadata</tt> is equivalent to matching <tt class="docutils literal">description user date</tt>
7464 (i.e. it matches the main metadata fields).</p>
7465 <p class="last"><tt class="docutils literal">metadata</tt> is the default field which is used when no fields are
7466 specified. You can match more than one field at a time.</p>
7467 </dd>
7468 <dt><tt class="docutils literal">max(set)</tt></dt>
7469 <dd>Changeset with highest revision number in set.</dd>
7470 <dt><tt class="docutils literal">merge()</tt></dt>
7471 <dd>Changeset is a merge changeset.</dd>
7472 <dt><tt class="docutils literal">min(set)</tt></dt>
7473 <dd>Changeset with lowest revision number in set.</dd>
7474 <dt><tt class="docutils literal">modifies(pattern)</tt></dt>
7475 <dd><p class="first">Changesets modifying files matched by pattern.</p>
7476 <p class="last">The pattern without explicit kind like <tt class="docutils literal">glob:</tt> is expected to be
7477 relative to the current directory and match against a file or a
7478 directory.</p>
7479 </dd>
7480 <dt><tt class="docutils literal">named(namespace)</tt></dt>
7481 <dd><p class="first">The changesets in a given namespace.</p>
7482 <p class="last">Pattern matching is supported for <cite>namespace</cite>. See
7483 <a class="reference external" href="hg.1.html#revisions.patterns"><tt class="docutils literal">hg help revisions.patterns</tt></a>.</p>
7484 </dd>
7485 <dt><tt class="docutils literal">nodefromfile(path)</tt></dt>
7486 <dd><p class="first">Read a list of nodes from the file at <cite>path</cite>.</p>
7487 <p>This applies <cite>id(LINE)</cite> to each line of the file.</p>
7488 <p class="last">This is useful when the amount of nodes you need to specify gets too large
7489 for the command line.</p>
7490 </dd>
7491 <dt><tt class="docutils literal">none()</tt></dt>
7492 <dd>No changesets.</dd>
7493 <dt><tt class="docutils literal">only(set, [set])</tt></dt>
7494 <dd>Changesets that are ancestors of the first set that are not ancestors
7495 of any other head in the repo. If a second set is specified, the result
7496 is ancestors of the first set that are not ancestors of the second set
7497 (i.e. ::&lt;set1&gt; - ::&lt;set2&gt;).</dd>
7498 <dt><tt class="docutils literal"><span class="pre">origin([set])</span></tt></dt>
7499 <dd>Changesets that were specified as a source for the grafts, transplants or
7500 rebases that created the given revisions. Omitting the optional set is the
7501 same as passing all(). If a changeset created by these operations is itself
7502 specified as a source for one of these operations, only the source changeset
7503 for the first operation is selected.</dd>
7504 <dt><tt class="docutils literal"><span class="pre">outgoing([path])</span></tt></dt>
7505 <dd><p class="first">Changesets not found in the specified destination repository, or the
7506 default push location.</p>
7507 <p class="last">If the location resolve to multiple repositories, the union of all
7508 outgoing changeset will be used.</p>
7509 </dd>
7510 <dt><tt class="docutils literal"><span class="pre">p1([set])</span></tt></dt>
7511 <dd>First parent of changesets in set, or the working directory.</dd>
7512 <dt><tt class="docutils literal"><span class="pre">p2([set])</span></tt></dt>
7513 <dd>Second parent of changesets in set, or the working directory.</dd>
7514 <dt><tt class="docutils literal"><span class="pre">parents([set])</span></tt></dt>
7515 <dd>The set of all parents for all changesets in set, or the working directory.</dd>
7516 <dt><tt class="docutils literal">present(set)</tt></dt>
7517 <dd><p class="first">An empty set, if any revision in set isn't found; otherwise,
7518 all revisions in set.</p>
7519 <p class="last">If any of specified revisions is not present in the local repository,
7520 the query is normally aborted. But this predicate allows the query
7521 to continue even in such cases.</p>
7522 </dd>
7523 <dt><tt class="docutils literal">public()</tt></dt>
7524 <dd>Changeset in public phase.</dd>
7525 <dt><tt class="docutils literal"><span class="pre">remote([id</span> <span class="pre">[,path]])</span></tt></dt>
7526 <dd>Local revision that corresponds to the given identifier in a
7527 remote repository, if present. Here, the '.' identifier is a
7528 synonym for the current local branch.</dd>
7529 <dt><tt class="docutils literal">removes(pattern)</tt></dt>
7530 <dd><p class="first">Changesets which remove files matching pattern.</p>
7531 <p class="last">The pattern without explicit kind like <tt class="docutils literal">glob:</tt> is expected to be
7532 relative to the current directory and match against a file or a
7533 directory.</p>
7534 </dd>
7535 <dt><tt class="docutils literal">rev(number)</tt></dt>
7536 <dd>Revision with the given numeric identifier.</dd>
7537 <dt><tt class="docutils literal">reverse(set)</tt></dt>
7538 <dd>Reverse order of set.</dd>
7539 <dt><tt class="docutils literal">revset(set)</tt></dt>
7540 <dd><p class="first">Strictly interpret the content as a revset.</p>
7541 <p class="last">The content of this special predicate will be strictly interpreted as a
7542 revset. For example, <tt class="docutils literal">revset(id(0))</tt> will be interpreted as &quot;id(0)&quot;
7543 without possible ambiguity with a &quot;id(0)&quot; bookmark or tag.</p>
7544 </dd>
7545 <dt><tt class="docutils literal">roots(set)</tt></dt>
7546 <dd>Changesets in set with no parent changeset in set.</dd>
7547 <dt><tt class="docutils literal">secret()</tt></dt>
7548 <dd>Changeset in secret phase.</dd>
7549 <dt><tt class="docutils literal">sort(set[, <span class="pre">[-]key...</span> [, <span class="pre">...]])</span></tt></dt>
7550 <dd><p class="first">Sort set by keys. The default sort order is ascending, specify a key
7551 as <tt class="docutils literal"><span class="pre">-key</span></tt> to sort in descending order.</p>
7552 <p>The keys can be:</p>
7553 <ul class="simple">
7554 <li><tt class="docutils literal">rev</tt> for the revision number,</li>
7555 <li><tt class="docutils literal">branch</tt> for the branch name,</li>
7556 <li><tt class="docutils literal">desc</tt> for the commit message (description),</li>
7557 <li><tt class="docutils literal">user</tt> for user name (<tt class="docutils literal">author</tt> can be used as an alias),</li>
7558 <li><tt class="docutils literal">date</tt> for the commit date</li>
7559 <li><tt class="docutils literal">topo</tt> for a reverse topographical sort</li>
7560 <li><tt class="docutils literal">node</tt> the nodeid of the revision</li>
7561 <li><tt class="docutils literal">random</tt> randomly shuffle revisions</li>
7562 </ul>
7563 <p>The <tt class="docutils literal">topo</tt> sort order cannot be combined with other sort keys. This sort
7564 takes one optional argument, <tt class="docutils literal">topo.firstbranch</tt>, which takes a revset that
7565 specifies what topographical branches to prioritize in the sort.</p>
7566 <p class="last">The <tt class="docutils literal">random</tt> sort takes one optional <tt class="docutils literal">random.seed</tt> argument to control
7567 the pseudo-randomness of the result.</p>
7568 </dd>
7569 <dt><tt class="docutils literal"><span class="pre">subrepo([pattern])</span></tt></dt>
7570 <dd>Changesets that add, modify or remove the given subrepo. If no subrepo
7571 pattern is named, any subrepo changes are returned.</dd>
7572 <dt><tt class="docutils literal"><span class="pre">tag([name])</span></tt></dt>
7573 <dd><p class="first">The specified tag by name, or all tagged revisions if no name is given.</p>
7574 <p class="last">Pattern matching is supported for <cite>name</cite>. See
7575 <a class="reference external" href="hg.1.html#revisions.patterns"><tt class="docutils literal">hg help revisions.patterns</tt></a>.</p>
7576 </dd>
7577 <dt><tt class="docutils literal">user(string)</tt></dt>
7578 <dd><p class="first">User name contains string. The match is case-insensitive.</p>
7579 <p class="last">Pattern matching is supported for <cite>string</cite>. See
7580 <a class="reference external" href="hg.1.html#revisions.patterns"><tt class="docutils literal">hg help revisions.patterns</tt></a>.</p>
7581 </dd>
7582 </dl>
7583 </div>
7584 <div class="section" id="aliases">
7585 <h2>Aliases</h2>
7586 <p>New predicates (known as &quot;aliases&quot;) can be defined, using any combination of
7587 existing predicates or other aliases. An alias definition looks like:</p>
7588 <pre class="literal-block">
7589 &lt;alias&gt; = &lt;definition&gt;
7590 </pre>
7591 <p>in the <tt class="docutils literal">revsetalias</tt> section of a Mercurial configuration file. Arguments
7592 of the form <cite>a1</cite>, <cite>a2</cite>, etc. are substituted from the alias into the
7593 definition.</p>
7594 <p>For example,</p>
7595 <pre class="literal-block">
7596 [revsetalias]
7597 h = heads()
7598 d(s) = sort(s, date)
7599 rs(s, k) = reverse(sort(s, k))
7600 </pre>
7601 <p>defines three aliases, <tt class="docutils literal">h</tt>, <tt class="docutils literal">d</tt>, and <tt class="docutils literal">rs</tt>. <tt class="docutils literal">rs(0:tip, author)</tt> is
7602 exactly equivalent to <tt class="docutils literal">reverse(sort(0:tip, author))</tt>.</p>
7603 </div>
7604 <div class="section" id="equivalents">
7605 <h2>Equivalents</h2>
7606 <p>Command line equivalents for <a class="reference external" href="hg.1.html#log"><tt class="docutils literal">hg log</tt></a>:</p>
7607 <pre class="literal-block">
7608 -f -&gt; ::.
7609 -d x -&gt; date(x)
7610 -k x -&gt; keyword(x)
7611 -m -&gt; merge()
7612 -u x -&gt; user(x)
7613 -b x -&gt; branch(x)
7614 -P x -&gt; !::x
7615 -l x -&gt; limit(expr, x)
7616 </pre>
7617 </div>
7618 <div class="section" id="examples-3">
7619 <h2>Examples</h2>
7620 <p>Some sample queries:</p>
7621 <ul>
7622 <li><p class="first">Changesets on the default branch:</p>
7623 <pre class="literal-block">
7624 hg log -r &quot;branch(default)&quot;
7625 </pre>
7626 </li>
7627 <li><p class="first">Changesets on the default branch since tag 1.5 (excluding merges):</p>
7628 <pre class="literal-block">
7629 hg log -r &quot;branch(default) and 1.5:: and not merge()&quot;
7630 </pre>
7631 </li>
7632 <li><p class="first">Open branch heads:</p>
7633 <pre class="literal-block">
7634 hg log -r &quot;head() and not closed()&quot;
7635 </pre>
7636 </li>
7637 <li><p class="first">Changesets between tags 1.3 and 1.5 mentioning &quot;bug&quot; that affect
7638 <tt class="docutils literal">hgext/*</tt>:</p>
7639 <pre class="literal-block">
7640 hg log -r &quot;1.3::1.5 and keyword(bug) and file('hgext/*')&quot;
7641 </pre>
7642 </li>
7643 <li><p class="first">Changesets committed in May 2008, sorted by user:</p>
7644 <pre class="literal-block">
7645 hg log -r &quot;sort(date('May 2008'), user)&quot;
7646 </pre>
7647 </li>
7648 <li><p class="first">Changesets mentioning &quot;bug&quot; or &quot;issue&quot; that are not in a tagged
7649 release:</p>
7650 <pre class="literal-block">
7651 hg log -r &quot;(keyword(bug) or keyword(issue)) and not ancestors(tag())&quot;
7652 </pre>
7653 </li>
7654 <li><p class="first">Update to the commit that bookmark &#64; is pointing to, without activating the
7655 bookmark (this works because the last revision of the revset is used):</p>
7656 <pre class="literal-block">
7657 hg update :&#64;
7658 </pre>
7659 </li>
7660 <li><p class="first">Show diff between tags 1.3 and 1.5 (this works because the first and the
7661 last revisions of the revset are used):</p>
7662 <pre class="literal-block">
7663 hg diff -r 1.3::1.5
7664 </pre>
7665 </li>
7666 </ul>
7667 </div>
7668 </div>
7669 <div class="section" id="rust-in-mercurial">
7670 <span id="rhg"></span><span id="rustext"></span><span id="rust"></span><h1><a class="toc-backref" href="#contents">Rust in Mercurial</a></h1>
7671 <p>Mercurial can be augmented with Rust extensions for speeding up certain
7672 operations.</p>
7673 <div class="section" id="word-of-caution">
7674 <h2>Word of Caution</h2>
7675 <p>Using the Rust extension might result in the use of various repository formats
7676 that are not supported by non-Rust mercurial. When using a Mercurial
7677 without Rust support on the same repositories, you might need to downgrade your
7678 repository formats and/or activate cripplingly slow paths for compatibility.
7679 For details, see:</p>
7680 <blockquote>
7681 <ul class="simple">
7682 <li><a class="reference external" href="hgrc.5.html#format"><tt class="docutils literal">hg help <span class="pre">config.format.use-persistent-nodemap</span></tt></a></li>
7683 <li><a class="reference external" href="hgrc.5.html#format"><tt class="docutils literal">hg help <span class="pre">config.format.use-dirstate-v2</span></tt></a></li>
7684 </ul>
7685 </blockquote>
7686 <p>In addition, while the tests are run with the Rust code, there might be
7687 subtle undetected divergences from the historical non-Rust code. So keep
7688 your eyes open and report any oddity. Rust is not considered a first class
7689 citizen to the project yet.</p>
7690 </div>
7691 <div class="section" id="compatibility">
7692 <h2>Compatibility</h2>
7693 <p>Though the Rust extensions are only tested by the project under Linux, users of
7694 MacOS, FreeBSD and other UNIX-likes have been using the Rust extensions. Your
7695 mileage may vary, but by all means do give us feedback or signal your interest
7696 for better support.</p>
7697 <p>For compatibility with non-Rust version of Mercurial check the previous &quot;Word of
7698 Caution&quot; section.</p>
7699 <p>No Rust extensions are available for Windows at this time.</p>
7700 </div>
7701 <div class="section" id="features">
7702 <h2>Features</h2>
7703 <p>The following operations are sped up when using Rust:</p>
7704 <blockquote>
7705 <ul class="simple">
7706 <li>discovery of differences between repositories (pull/push)</li>
7707 <li>nodemap (see <a class="reference external" href="hgrc.5.html#format"><tt class="docutils literal">hg help <span class="pre">config.format.use-persistent-nodemap</span></tt></a>)</li>
7708 <li>all commands using the dirstate (status, commit, diff, add, update, etc.)</li>
7709 <li>dirstate-v2 (see <a class="reference external" href="hgrc.5.html#format"><tt class="docutils literal">hg help <span class="pre">config.format.use-dirstate-v2</span></tt></a>)</li>
7710 <li>iteration over ancestors in a graph</li>
7711 </ul>
7712 </blockquote>
7713 <p>More features are in the works, and improvements on the above listed are still
7714 in progress. For more experimental work see the &quot;rhg&quot; section.</p>
7715 </div>
7716 <div class="section" id="checking-for-rust">
7717 <h2>Checking for Rust</h2>
7718 <p>You may already have the Rust extensions depending on how you install
7719 Mercurial:</p>
7720 <pre class="literal-block">
7721 $ hg debuginstall | grep -i rust
7722 checking Rust extensions (installed)
7723 checking module policy (rust+c-allow)
7724 </pre>
7725 <p>If those lines don't even exist, you're using an old version of <cite>hg</cite> which does
7726 not have any Rust extensions yet.</p>
7727 </div>
7728 <div class="section" id="installing">
7729 <h2>Installing</h2>
7730 <p>You will need <cite>cargo</cite> to be in your <cite>$PATH</cite>. See the &quot;MSRV&quot; section for which
7731 version to use.</p>
7732 <div class="section" id="using-pip">
7733 <h3>Using pip</h3>
7734 <p>Users of <cite>pip</cite> can install the Rust extensions with the following commands:</p>
7735 <pre class="literal-block">
7736 $ pip cache remove mercurial
7737 $ pip install mercurial -v \
7738 --config-settings --global-option=--rust \
7739 --no-binary mercurial --force
7740 </pre>
7741 <p><cite>pip cache remove</cite> and <cite>--no-binary</cite> are there to tell pip to not use the
7742 pre-compiled wheels that are missing rust support. This might take a couple
7743 of minutes because you're compiling everything.</p>
7744 <p>See the &quot;Checking for Rust&quot; section to see if the install succeeded.</p>
7745 </div>
7746 <div class="section" id="using-pipx">
7747 <h3>Using pipx</h3>
7748 <p>Using pipx is an efficient way to get an isolated installation of mercurial
7749 available for a user or globally.</p>
7750 <blockquote>
7751 <dl class="docutils">
7752 <dt>$ pipx install mercurial </dt>
7753 <dd>--pip-args '--no-cache-dir --config-settings --global-option=--rust --no-binary=mercurial'</dd>
7754 </dl>
7755 </blockquote>
7756 <p>You can then add extensions to that install using</p>
7757 <blockquote>
7758 $ pipx inject mercurial hg-foo</blockquote>
7759 </div>
7760 <div class="section" id="using-uv-tool">
7761 <h3>Using uv tool</h3>
7762 <p>Using <cite>uv tool</cite> is another efficient way to get an isolated installation of
7763 mercurial available for a user or globally.</p>
7764 <blockquote>
7765 <dl class="docutils">
7766 <dt>$ uv tool install mercurial </dt>
7767 <dd>--no-binary=mercurial --no-cache --config-setting=--build-option=--rust</dd>
7768 </dl>
7769 </blockquote>
7770 <p>You can bring extensions along using the <cite>--with</cite> flag. For example</p>
7771 <blockquote>
7772 $ uv tool install mercurial --with hg-evolve [...]</blockquote>
7773 </div>
7774 <div class="section" id="from-your-distribution">
7775 <h3>From your distribution</h3>
7776 <p>Some distributions are shipping Mercurial with Rust extensions enabled and
7777 pre-compiled (meaning you won't have to install <cite>cargo</cite>), or allow you to
7778 specify an install flag. Check with your specific distribution for how to do
7779 that, or ask their team to add support for hg+Rust!</p>
7780 </div>
7781 <div class="section" id="from-source">
7782 <h3>From source</h3>
7783 <p>Please refer to the <cite>rust/README.md</cite> file in the Mercurial repository for
7784 instructions on how to install from source.</p>
7785 </div>
7786 </div>
7787 <div class="section" id="msrv">
7788 <h2>MSRV</h2>
7789 <p>The minimum supported Rust version is defined in <cite>rust/clippy.toml</cite>.
7790 The project's policy is to keep it at or below the version from Debian testing,
7791 to make the distributions' job easier.</p>
7792 </div>
7793 <div class="section" id="rhg-1">
7794 <h2>rhg</h2>
7795 <p>There exists an experimental pure-Rust version of Mercurial called <cite>rhg</cite> with a
7796 fallback mechanism for unsupported invocations. It allows for much faster
7797 execution of certain commands while adding no discernable overhead for the rest.</p>
7798 <p>The only way of trying it out is by building it from source. Please refer to
7799 <cite>rust/README.md</cite> in the Mercurial repository.</p>
7800 <p>See <cite>hg help config.rhg</cite> for configuration options.</p>
7801 </div>
7802 <div class="section" id="contributing">
7803 <h2>Contributing</h2>
7804 <p>If you would like to help the Rust endeavor, please refer to <cite>rust/README.md</cite>
7805 in the Mercurial repository.</p>
7806 </div>
7807 </div>
7808 <div class="section" id="using-mercurial-from-scripts-and-automation">
7809 <span id="scripting"></span><h1><a class="toc-backref" href="#contents">Using Mercurial from scripts and automation</a></h1>
7810 <p>It is common for machines (as opposed to humans) to consume Mercurial.
7811 This help topic describes some of the considerations for interfacing
7812 machines with Mercurial.</p>
7813 <div class="section" id="choosing-an-interface">
7814 <h2>Choosing an Interface</h2>
7815 <p>Machines have a choice of several methods to interface with Mercurial.
7816 These include:</p>
7817 <ul class="simple">
7818 <li>Executing the <tt class="docutils literal">hg</tt> process</li>
7819 <li>Querying a HTTP server</li>
7820 <li>Calling out to a command server</li>
7821 </ul>
7822 <p>Executing <tt class="docutils literal">hg</tt> processes is very similar to how humans interact with
7823 Mercurial in the shell. It should already be familiar to you.</p>
7824 <p><a class="reference external" href="hg.1.html#serve"><tt class="docutils literal">hg serve</tt></a> can be used to start a server. By default, this will start
7825 a &quot;hgweb&quot; HTTP server. This HTTP server has support for machine-readable
7826 output, such as JSON. For more, see <a class="reference external" href="hg.1.html#hgweb"><tt class="docutils literal">hg help hgweb</tt></a>.</p>
7827 <p><a class="reference external" href="hg.1.html#serve"><tt class="docutils literal">hg serve</tt></a> can also start a &quot;command server.&quot; Clients can connect
7828 to this server and issue Mercurial commands over a special protocol.
7829 For more details on the command server, including links to client
7830 libraries, see <a class="reference external" href="https://www.mercurial-scm.org/wiki/CommandServer">https://www.mercurial-scm.org/wiki/CommandServer</a>.</p>
7831 <p><a class="reference external" href="hg.1.html#serve"><tt class="docutils literal">hg serve</tt></a> based interfaces (the hgweb and command servers) have the
7832 advantage over simple <tt class="docutils literal">hg</tt> process invocations in that they are
7833 likely more efficient. This is because there is significant overhead
7834 to spawn new Python processes.</p>
7835 <div class="admonition tip">
7836 <p class="first admonition-title">Tip</p>
7837 <p class="last">If you need to invoke several <tt class="docutils literal">hg</tt> processes in short order and/or
7838 performance is important to you, use of a server-based interface
7839 is highly recommended.</p>
7840 </div>
7841 </div>
7842 <div class="section" id="environment-variables-1">
7843 <h2>Environment Variables</h2>
7844 <p>As documented in <a class="reference external" href="hg.1.html#environment"><tt class="docutils literal">hg help environment</tt></a>, various environment variables
7845 influence the operation of Mercurial. The following are particularly
7846 relevant for machines consuming Mercurial:</p>
7847 <dl class="docutils">
7848 <dt>HGPLAIN</dt>
7849 <dd><p class="first">If not set, Mercurial's output could be influenced by configuration
7850 settings that impact its encoding, verbose mode, localization, etc.</p>
7851 <p class="last">It is highly recommended for machines to set this variable when
7852 invoking <tt class="docutils literal">hg</tt> processes.</p>
7853 </dd>
7854 <dt>HGENCODING</dt>
7855 <dd><p class="first">If not set, the locale used by Mercurial will be detected from the
7856 environment. If the determined locale does not support display of
7857 certain characters, Mercurial may render these character sequences
7858 incorrectly (often by using &quot;?&quot; as a placeholder for invalid
7859 characters in the current locale).</p>
7860 <p class="last">Explicitly setting this environment variable is a good practice to
7861 guarantee consistent results. &quot;utf-8&quot; is a good choice on UNIX-like
7862 environments.</p>
7863 </dd>
7864 <dt>HGRCPATH</dt>
7865 <dd><p class="first">If not set, Mercurial will inherit config options from config files
7866 using the process described in <a class="reference external" href="hgrc.5.html"><tt class="docutils literal">hg help config</tt></a>. This includes
7867 inheriting user or system-wide config files.</p>
7868 <p class="last">When utmost control over the Mercurial configuration is desired, the
7869 value of <tt class="docutils literal">HGRCPATH</tt> can be set to an explicit file with known good
7870 configs. In rare cases, the value can be set to an empty file or the
7871 null device (often <tt class="docutils literal">/dev/null</tt>) to bypass loading of any user or
7872 system config files. Note that these approaches can have unintended
7873 consequences, as the user and system config files often define things
7874 like the username and extensions that may be required to interface
7875 with a repository.</p>
7876 </dd>
7877 <dt>HGRCSKIPREPO</dt>
7878 <dd><p class="first">When set, the .hg/hgrc from repositories are not read.</p>
7879 <p class="last">Note that not reading the repository's configuration can have
7880 unintended consequences, as the repository config files can define
7881 things like extensions that are required for access to the
7882 repository.</p>
7883 </dd>
7884 </dl>
7885 </div>
7886 <div class="section" id="command-line-flags-1">
7887 <h2>Command-line Flags</h2>
7888 <p>Mercurial's default command-line parser is designed for humans, and is not
7889 robust against malicious input. For instance, you can start a debugger by
7890 passing <tt class="docutils literal"><span class="pre">--debugger</span></tt> as an option value:</p>
7891 <pre class="literal-block">
7892 $ REV=--debugger sh -c 'hg log -r &quot;$REV&quot;'
7893 </pre>
7894 <p>This happens because several command-line flags need to be scanned without
7895 using a concrete command table, which may be modified while loading repository
7896 settings and extensions.</p>
7897 <p>Since Mercurial 4.4.2, the parsing of such flags may be restricted by setting
7898 <tt class="docutils literal"><span class="pre">HGPLAIN=+strictflags</span></tt>. When this feature is enabled, all early options
7899 (e.g. <tt class="docutils literal"><span class="pre">-R/--repository</span></tt>, <tt class="docutils literal"><span class="pre">--cwd</span></tt>, <tt class="docutils literal"><span class="pre">--config</span></tt>) must be specified first
7900 amongst the other global options, and cannot be injected to an arbitrary
7901 location:</p>
7902 <pre class="literal-block">
7903 $ HGPLAIN=+strictflags hg -R &quot;$REPO&quot; log -r &quot;$REV&quot;
7904 </pre>
7905 <p>In earlier Mercurial versions where <tt class="docutils literal">+strictflags</tt> isn't available, you
7906 can mitigate the issue by concatenating an option value with its flag:</p>
7907 <pre class="literal-block">
7908 $ hg log -r&quot;$REV&quot; --keyword=&quot;$KEYWORD&quot;
7909 </pre>
7910 </div>
7911 <div class="section" id="consuming-command-output">
7912 <h2>Consuming Command Output</h2>
7913 <p>It is common for machines to need to parse the output of Mercurial
7914 commands for relevant data. This section describes the various
7915 techniques for doing so.</p>
7916 <div class="section" id="parsing-raw-command-output">
7917 <h3>Parsing Raw Command Output</h3>
7918 <p>Likely the simplest and most effective solution for consuming command
7919 output is to simply invoke <tt class="docutils literal">hg</tt> commands as you would as a user and
7920 parse their output.</p>
7921 <p>The output of many commands can easily be parsed with tools like
7922 <tt class="docutils literal">grep</tt>, <tt class="docutils literal">sed</tt>, and <tt class="docutils literal">awk</tt>.</p>
7923 <p>A potential downside with parsing command output is that the output
7924 of commands can change when Mercurial is upgraded. While Mercurial
7925 does generally strive for strong backwards compatibility, command
7926 output does occasionally change. Having tests for your automated
7927 interactions with <tt class="docutils literal">hg</tt> commands is generally recommended, but is
7928 even more important when raw command output parsing is involved.</p>
7929 </div>
7930 <div class="section" id="using-templates-to-control-output">
7931 <h3>Using Templates to Control Output</h3>
7932 <p>Many <tt class="docutils literal">hg</tt> commands support templatized output via the
7933 <tt class="docutils literal"><span class="pre">-T/--template</span></tt> argument. For more, see <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help templates</tt></a>.</p>
7934 <p>Templates are useful for explicitly controlling output so that
7935 you get exactly the data you want formatted how you want it. For
7936 example, <tt class="docutils literal">log <span class="pre">-T</span> <span class="pre">{node}\n</span></tt> can be used to print a newline
7937 delimited list of changeset nodes instead of a human-tailored
7938 output containing authors, dates, descriptions, etc.</p>
7939 <div class="admonition tip">
7940 <p class="first admonition-title">Tip</p>
7941 <p class="last">If parsing raw command output is too complicated, consider
7942 using templates to make your life easier.</p>
7943 </div>
7944 <p>The <tt class="docutils literal"><span class="pre">-T/--template</span></tt> argument allows specifying pre-defined styles.
7945 Mercurial ships with the machine-readable styles <tt class="docutils literal">cbor</tt>, <tt class="docutils literal">json</tt>,
7946 and <tt class="docutils literal">xml</tt>, which provide CBOR, JSON, and XML output, respectively.
7947 These are useful for producing output that is machine readable as-is.</p>
7948 <p>(Mercurial 5.0 is required for CBOR style.)</p>
7949 <div class="admonition important">
7950 <p class="first admonition-title">Important</p>
7951 <p>The <tt class="docutils literal">json</tt> and <tt class="docutils literal">xml</tt> styles are considered experimental. While
7952 they may be attractive to use for easily obtaining machine-readable
7953 output, their behavior may change in subsequent versions.</p>
7954 <p class="last">These styles may also exhibit unexpected results when dealing with
7955 certain encodings. Mercurial treats things like filenames as a
7956 series of bytes and normalizing certain byte sequences to JSON
7957 or XML with certain encoding settings can lead to surprises.</p>
7958 </div>
7959 </div>
7960 <div class="section" id="command-server-output">
7961 <h3>Command Server Output</h3>
7962 <p>If using the command server to interact with Mercurial, you are likely
7963 using an existing library/API that abstracts implementation details of
7964 the command server. If so, this interface layer may perform parsing for
7965 you, saving you the work of implementing it yourself.</p>
7966 </div>
7967 <div class="section" id="output-verbosity">
7968 <h3>Output Verbosity</h3>
7969 <p>Commands often have varying output verbosity, even when machine
7970 readable styles are being used (e.g. <tt class="docutils literal"><span class="pre">-T</span> json</tt>). Adding
7971 <tt class="docutils literal"><span class="pre">-v/--verbose</span></tt> and <tt class="docutils literal"><span class="pre">--debug</span></tt> to the command's arguments can
7972 increase the amount of data exposed by Mercurial.</p>
7973 <p>An alternate way to get the data you need is by explicitly specifying
7974 a template.</p>
7975 </div>
7976 </div>
7977 <div class="section" id="other-topics">
7978 <h2>Other Topics</h2>
7979 <dl class="docutils">
7980 <dt>revsets</dt>
7981 <dd><p class="first">Revisions sets is a functional query language for selecting a set
7982 of revisions. Think of it as SQL for Mercurial repositories. Revsets
7983 are useful for querying repositories for specific data.</p>
7984 <p class="last">See <a class="reference external" href="hg.1.html#revsets"><tt class="docutils literal">hg help revsets</tt></a> for more.</p>
7985 </dd>
7986 <dt>share extension</dt>
7987 <dd><p class="first">The <tt class="docutils literal">share</tt> extension provides functionality for sharing
7988 repository data across several working copies. It can even
7989 automatically &quot;pool&quot; storage for logically related repositories when
7990 cloning.</p>
7991 <p>Configuring the <tt class="docutils literal">share</tt> extension can lead to significant resource
7992 utilization reduction, particularly around disk space and the
7993 network. This is especially true for continuous integration (CI)
7994 environments.</p>
7995 <p class="last">See <a class="reference external" href="hg.1.html#-e"><tt class="docutils literal">hg help <span class="pre">-e</span> share</tt></a> for more.</p>
7996 </dd>
7997 </dl>
7998 </div>
7999 </div>
8000 <div class="section" id="subrepositories">
8001 <span id="subrepo"></span><span id="subrepos"></span><h1><a class="toc-backref" href="#contents">Subrepositories</a></h1>
8002 <p>Subrepositories let you nest external repositories or projects into a
8003 parent Mercurial repository, and make commands operate on them as a
8004 group.</p>
8005 <p>Mercurial currently supports Mercurial, Git, and Subversion
8006 subrepositories.</p>
8007 <p>Subrepositories are made of three components:</p>
8008 <ol class="arabic">
8009 <li><p class="first">Nested repository checkouts. They can appear anywhere in the
8010 parent working directory.</p>
8011 </li>
8012 <li><p class="first">Nested repository references. They are defined in <tt class="docutils literal">.hgsub</tt>, which
8013 should be placed in the root of working directory, and
8014 tell where the subrepository checkouts come from. Mercurial
8015 subrepositories are referenced like:</p>
8016 <pre class="literal-block">
8017 path/to/nested = https://example.com/nested/repo/path
8018 </pre>
8019 <p>Git and Subversion subrepos are also supported:</p>
8020 <pre class="literal-block">
8021 path/to/nested = [git]git://example.com/nested/repo/path
8022 path/to/nested = [svn]https://example.com/nested/trunk/path
8023 </pre>
8024 <p>where <tt class="docutils literal">path/to/nested</tt> is the checkout location relatively to the
8025 parent Mercurial root, and <tt class="docutils literal"><span class="pre">https://example.com/nested/repo/path</span></tt>
8026 is the source repository path. The source can also reference a
8027 filesystem path.</p>
8028 <p>Note that <tt class="docutils literal">.hgsub</tt> does not exist by default in Mercurial
8029 repositories, you have to create and add it to the parent
8030 repository before using subrepositories.</p>
8031 </li>
8032 <li><p class="first">Nested repository states. They are defined in <tt class="docutils literal">.hgsubstate</tt>, which
8033 is placed in the root of working directory, and
8034 capture whatever information is required to restore the
8035 subrepositories to the state they were committed in a parent
8036 repository changeset. Mercurial automatically record the nested
8037 repositories states when committing in the parent repository.</p>
8038 <div class="admonition note">
8039 <p class="first admonition-title">Note</p>
8040 <p class="last">The <tt class="docutils literal">.hgsubstate</tt> file should not be edited manually.</p>
8041 </div>
8042 </li>
8043 </ol>
8044 <div class="section" id="adding-a-subrepository">
8045 <h2>Adding a Subrepository</h2>
8046 <p>If <tt class="docutils literal">.hgsub</tt> does not exist, create it and add it to the parent
8047 repository. Clone or checkout the external projects where you want it
8048 to live in the parent repository. Edit <tt class="docutils literal">.hgsub</tt> and add the
8049 subrepository entry as described above. At this point, the
8050 subrepository is tracked and the next commit will record its state in
8051 <tt class="docutils literal">.hgsubstate</tt> and bind it to the committed changeset.</p>
8052 </div>
8053 <div class="section" id="synchronizing-a-subrepository">
8054 <h2>Synchronizing a Subrepository</h2>
8055 <p>Subrepos do not automatically track the latest changeset of their
8056 sources. Instead, they are updated to the changeset that corresponds
8057 with the changeset checked out in the top-level changeset. This is so
8058 developers always get a consistent set of compatible code and
8059 libraries when they update.</p>
8060 <p>Thus, updating subrepos is a manual process. Simply check out target
8061 subrepo at the desired revision, test in the top-level repo, then
8062 commit in the parent repository to record the new combination.</p>
8063 </div>
8064 <div class="section" id="deleting-a-subrepository">
8065 <h2>Deleting a Subrepository</h2>
8066 <p>To remove a subrepository from the parent repository, delete its
8067 reference from <tt class="docutils literal">.hgsub</tt>, then remove its files.</p>
8068 </div>
8069 <div class="section" id="interaction-with-mercurial-commands">
8070 <h2>Interaction with Mercurial Commands</h2>
8071 <table class="docutils field-list" frame="void" rules="none">
8072 <col class="field-name" />
8073 <col class="field-body" />
8074 <tbody valign="top">
8075 <tr class="field"><th class="field-name">add:</th><td class="field-body">add does not recurse in subrepos unless -S/--subrepos is
8076 specified. However, if you specify the full path of a file in a
8077 subrepo, it will be added even without -S/--subrepos specified.
8078 Subversion subrepositories are currently silently
8079 ignored.</td>
8080 </tr>
8081 <tr class="field"><th class="field-name">addremove:</th><td class="field-body">addremove does not recurse into subrepos unless
8082 -S/--subrepos is specified. However, if you specify the full
8083 path of a directory in a subrepo, addremove will be performed on
8084 it even without -S/--subrepos being specified. Git and
8085 Subversion subrepositories will print a warning and continue.</td>
8086 </tr>
8087 <tr class="field"><th class="field-name">archive:</th><td class="field-body">archive does not recurse in subrepositories unless
8088 -S/--subrepos is specified.</td>
8089 </tr>
8090 <tr class="field"><th class="field-name">cat:</th><td class="field-body">Git subrepositories only support exact file matches.
8091 Subversion subrepositories are currently ignored.</td>
8092 </tr>
8093 <tr class="field"><th class="field-name">commit:</th><td class="field-body">commit creates a consistent snapshot of the state of the
8094 entire project and its subrepositories. If any subrepositories
8095 have been modified, Mercurial will abort. Mercurial can be made
8096 to instead commit all modified subrepositories by specifying
8097 -S/--subrepos, or setting &quot;ui.commitsubrepos=True&quot; in a
8098 configuration file (see <a class="reference external" href="hgrc.5.html"><tt class="docutils literal">hg help config</tt></a>). After there are no
8099 longer any modified subrepositories, it records their state and
8100 finally commits it in the parent repository. The --addremove
8101 option also honors the -S/--subrepos option. However, Git and
8102 Subversion subrepositories will print a warning and abort.</td>
8103 </tr>
8104 <tr class="field"><th class="field-name">diff:</th><td class="field-body">diff does not recurse in subrepos unless -S/--subrepos is
8105 specified. However, if you specify the full path of a file or
8106 directory in a subrepo, it will be diffed even without
8107 -S/--subrepos being specified. Subversion subrepositories are
8108 currently silently ignored.</td>
8109 </tr>
8110 <tr class="field"><th class="field-name">files:</th><td class="field-body">files does not recurse into subrepos unless -S/--subrepos is
8111 specified. However, if you specify the full path of a file or
8112 directory in a subrepo, it will be displayed even without
8113 -S/--subrepos being specified. Git and Subversion subrepositories
8114 are currently silently ignored.</td>
8115 </tr>
8116 <tr class="field"><th class="field-name">forget:</th><td class="field-body">forget currently only handles exact file matches in subrepos.
8117 Git and Subversion subrepositories are currently silently ignored.</td>
8118 </tr>
8119 <tr class="field"><th class="field-name">incoming:</th><td class="field-body">incoming does not recurse in subrepos unless -S/--subrepos
8120 is specified. Git and Subversion subrepositories are currently
8121 silently ignored.</td>
8122 </tr>
8123 <tr class="field"><th class="field-name">outgoing:</th><td class="field-body">outgoing does not recurse in subrepos unless -S/--subrepos
8124 is specified. Git and Subversion subrepositories are currently
8125 silently ignored.</td>
8126 </tr>
8127 <tr class="field"><th class="field-name">pull:</th><td class="field-body">pull is not recursive since it is not clear what to pull prior
8128 to running <a class="reference external" href="hg.1.html#update"><tt class="docutils literal">hg update</tt></a>. Listing and retrieving all
8129 subrepositories changes referenced by the parent repository pulled
8130 changesets is expensive at best, impossible in the Subversion
8131 case.</td>
8132 </tr>
8133 <tr class="field"><th class="field-name">push:</th><td class="field-body">Mercurial will automatically push all subrepositories first
8134 when the parent repository is being pushed. This ensures new
8135 subrepository changes are available when referenced by top-level
8136 repositories. Push is a no-op for Subversion subrepositories.</td>
8137 </tr>
8138 <tr class="field"><th class="field-name">serve:</th><td class="field-body">serve does not recurse into subrepositories unless
8139 -S/--subrepos is specified. Git and Subversion subrepositories
8140 are currently silently ignored.</td>
8141 </tr>
8142 <tr class="field"><th class="field-name">status:</th><td class="field-body">status does not recurse into subrepositories unless
8143 -S/--subrepos is specified. Subrepository changes are displayed as
8144 regular Mercurial changes on the subrepository
8145 elements. Subversion subrepositories are currently silently
8146 ignored.</td>
8147 </tr>
8148 <tr class="field"><th class="field-name">remove:</th><td class="field-body">remove does not recurse into subrepositories unless
8149 -S/--subrepos is specified. However, if you specify a file or
8150 directory path in a subrepo, it will be removed even without
8151 -S/--subrepos. Git and Subversion subrepositories are currently
8152 silently ignored.</td>
8153 </tr>
8154 <tr class="field"><th class="field-name">update:</th><td class="field-body">update restores the subrepos in the state they were
8155 originally committed in target changeset. If the recorded
8156 changeset is not available in the current subrepository, Mercurial
8157 will pull it in first before updating. This means that updating
8158 can require network access when using subrepositories.</td>
8159 </tr>
8160 </tbody>
8161 </table>
8162 </div>
8163 <div class="section" id="remapping-subrepositories-sources">
8164 <h2>Remapping Subrepositories Sources</h2>
8165 <p>A subrepository source location may change during a project life,
8166 invalidating references stored in the parent repository history. To
8167 fix this, rewriting rules can be defined in parent repository <tt class="docutils literal">hgrc</tt>
8168 file or in Mercurial configuration. See the <tt class="docutils literal">[subpaths]</tt> section in
8169 hgrc(5) for more details.</p>
8170 </div>
8171 </div>
8172 <div class="section" id="template-usage">
8173 <span id="style"></span><span id="template"></span><span id="templates"></span><span id="templating"></span><h1><a class="toc-backref" href="#contents">Template Usage</a></h1>
8174 <p>Mercurial allows you to customize output of commands through
8175 templates. You can either pass in a template or select an existing
8176 template-style from the command line, via the --template option.</p>
8177 <p>You can customize output for any &quot;log-like&quot; command: log,
8178 outgoing, incoming, tip, parents, and heads.</p>
8179 <p>Some built-in styles are packaged with Mercurial. These can be listed
8180 with <a class="reference external" href="hg.1.html#log"><tt class="docutils literal">hg log <span class="pre">--template</span> list</tt></a>. Example usage:</p>
8181 <pre class="literal-block">
8182 $ hg log -r1.0::1.1 --template changelog
8183 </pre>
8184 <p>A template is a piece of text, with markup to invoke variable
8185 expansion:</p>
8186 <pre class="literal-block">
8187 $ hg log -r1 --template &quot;{node}\n&quot;
8188 b56ce7b07c52de7d5fd79fb89701ea538af65746
8189 </pre>
8190 <div class="section" id="keywords">
8191 <h2>Keywords</h2>
8192 <p>Strings in curly braces are called keywords. The availability of
8193 keywords depends on the exact context of the templater. These
8194 keywords are usually available for templating a log-like command:</p>
8195 <table class="docutils field-list" frame="void" rules="none">
8196 <col class="field-name" />
8197 <col class="field-body" />
8198 <tbody valign="top">
8199 <tr class="field"><th class="field-name">_fast_rank:</th><td class="field-body"><p class="first">the rank of a changeset if cached</p>
8200 <p>The rank of a revision is the size of the sub-graph it defines as a head.
8201 Equivalently, the rank of a revision <cite>r</cite> is the size of the set
8202 <cite>ancestors(r)</cite>, <cite>r</cite> included.</p>
8203 </td>
8204 </tr>
8205 <tr class="field"><th class="field-name">activebookmark:</th><td class="field-body"><p class="first">String. The active bookmark, if it is associated with the changeset.</p>
8206 </td>
8207 </tr>
8208 <tr class="field"><th class="field-name">author:</th><td class="field-body"><p class="first">Alias for <tt class="docutils literal">{user}</tt></p>
8209 </td>
8210 </tr>
8211 <tr class="field"><th class="field-name">bisect:</th><td class="field-body"><p class="first">String. The changeset bisection status.</p>
8212 </td>
8213 </tr>
8214 <tr class="field"><th class="field-name">bookmarks:</th><td class="field-body"><p class="first">List of strings. Any bookmarks associated with the
8215 changeset. Also sets 'active', the name of the active bookmark.</p>
8216 </td>
8217 </tr>
8218 <tr class="field"><th class="field-name">branch:</th><td class="field-body"><p class="first">String. The name of the branch on which the changeset was
8219 committed.</p>
8220 </td>
8221 </tr>
8222 <tr class="field"><th class="field-name" colspan="2">changessincelatesttag:</th></tr>
8223 <tr class="field"><td>&nbsp;</td><td class="field-body"><p class="first">Integer. All ancestors not in the latest tag.</p>
8224 </td>
8225 </tr>
8226 <tr class="field"><th class="field-name">children:</th><td class="field-body"><p class="first">List of strings. The children of the changeset.</p>
8227 </td>
8228 </tr>
8229 <tr class="field"><th class="field-name">closesbranch:</th><td class="field-body"><p class="first">&quot;yes&quot; if this changeset is branch-closing, &quot;no&quot; otherwise</p>
8230 </td>
8231 </tr>
8232 <tr class="field"><th class="field-name">date:</th><td class="field-body"><p class="first">Date information. The date when the changeset was committed.</p>
8233 </td>
8234 </tr>
8235 <tr class="field"><th class="field-name">desc:</th><td class="field-body"><p class="first">String. The text of the changeset description.</p>
8236 </td>
8237 </tr>
8238 <tr class="field"><th class="field-name">diffstat:</th><td class="field-body"><p class="first">String. Statistics of changes with the following format:
8239 &quot;modified files: +added/-removed lines&quot;</p>
8240 </td>
8241 </tr>
8242 <tr class="field"><th class="field-name">extras:</th><td class="field-body"><p class="first">List of dicts with key, value entries of the 'extras'
8243 field of this changeset.</p>
8244 </td>
8245 </tr>
8246 <tr class="field"><th class="field-name">file_adds:</th><td class="field-body"><p class="first">List of strings. Files added by this changeset.</p>
8247 </td>
8248 </tr>
8249 <tr class="field"><th class="field-name">file_copies:</th><td class="field-body"><p class="first">List of strings. Files copied in this changeset with
8250 their sources.</p>
8251 </td>
8252 </tr>
8253 <tr class="field"><th class="field-name" colspan="2">file_copies_switch:</th></tr>
8254 <tr class="field"><td>&nbsp;</td><td class="field-body"><p class="first">List of strings. Like &quot;file_copies&quot; but displayed
8255 only if the --copied switch is set.</p>
8256 </td>
8257 </tr>
8258 <tr class="field"><th class="field-name">file_dels:</th><td class="field-body"><p class="first">List of strings. Files removed by this changeset.</p>
8259 </td>
8260 </tr>
8261 <tr class="field"><th class="field-name">file_mods:</th><td class="field-body"><p class="first">List of strings. Files modified by this changeset.</p>
8262 </td>
8263 </tr>
8264 <tr class="field"><th class="field-name">files:</th><td class="field-body"><p class="first">List of strings. All files modified, added, or removed by this
8265 changeset.</p>
8266 </td>
8267 </tr>
8268 <tr class="field"><th class="field-name">graphnode:</th><td class="field-body"><p class="first">String. The character representing the changeset node in an ASCII
8269 revision graph.</p>
8270 </td>
8271 </tr>
8272 <tr class="field"><th class="field-name">graphwidth:</th><td class="field-body"><p class="first">Integer. The width of the graph drawn by 'log --graph' or zero.</p>
8273 </td>
8274 </tr>
8275 <tr class="field"><th class="field-name">index:</th><td class="field-body"><p class="first">Integer. The current iteration of the loop. (0 indexed)</p>
8276 </td>
8277 </tr>
8278 <tr class="field"><th class="field-name">latesttag:</th><td class="field-body"><p class="first">List of strings. The global tags on the most recent globally
8279 tagged ancestor of this changeset. If no such tags exist, the list
8280 consists of the single string &quot;null&quot;.</p>
8281 </td>
8282 </tr>
8283 <tr class="field"><th class="field-name" colspan="2">latesttagdistance:</th></tr>
8284 <tr class="field"><td>&nbsp;</td><td class="field-body"><p class="first">Integer. Longest path to the latest tag.</p>
8285 </td>
8286 </tr>
8287 <tr class="field"><th class="field-name">namespaces:</th><td class="field-body"><p class="first">Dict of lists. Names attached to this changeset per
8288 namespace.</p>
8289 </td>
8290 </tr>
8291 <tr class="field"><th class="field-name">negrev:</th><td class="field-body"><p class="first">Integer. The repository-local changeset negative revision number,
8292 which counts in the opposite direction.</p>
8293 </td>
8294 </tr>
8295 <tr class="field"><th class="field-name">node:</th><td class="field-body"><p class="first">String. The changeset identification hash, as a 40 hexadecimal
8296 digit string.</p>
8297 </td>
8298 </tr>
8299 <tr class="field"><th class="field-name">onelinesummary:</th><td class="field-body"><p class="first">String. A one-line summary for the ctx (not including trailing newline).
8300 The default template be overridden in command-templates.oneline-summary.</p>
8301 </td>
8302 </tr>
8303 <tr class="field"><th class="field-name">p1:</th><td class="field-body"><p class="first">Changeset. The changeset's first parent. <tt class="docutils literal">{p1.rev}</tt> for the revision
8304 number, and <tt class="docutils literal">{p1.node}</tt> for the identification hash.</p>
8305 </td>
8306 </tr>
8307 <tr class="field"><th class="field-name">p2:</th><td class="field-body"><p class="first">Changeset. The changeset's second parent. <tt class="docutils literal">{p2.rev}</tt> for the revision
8308 number, and <tt class="docutils literal">{p2.node}</tt> for the identification hash.</p>
8309 </td>
8310 </tr>
8311 <tr class="field"><th class="field-name">parents:</th><td class="field-body"><p class="first">List of strings. The parents of the changeset in &quot;rev:node&quot;
8312 format. If the changeset has only one &quot;natural&quot; parent (the predecessor
8313 revision) nothing is shown.</p>
8314 </td>
8315 </tr>
8316 <tr class="field"><th class="field-name">peerurls:</th><td class="field-body"><p class="first">A dictionary of repository locations defined in the [paths] section
8317 of your configuration file.</p>
8318 </td>
8319 </tr>
8320 <tr class="field"><th class="field-name">phase:</th><td class="field-body"><p class="first">String. The changeset phase name.</p>
8321 </td>
8322 </tr>
8323 <tr class="field"><th class="field-name">reporoot:</th><td class="field-body"><p class="first">String. The root directory of the current repository.</p>
8324 </td>
8325 </tr>
8326 <tr class="field"><th class="field-name">rev:</th><td class="field-body"><p class="first">Integer. The repository-local changeset revision number.</p>
8327 </td>
8328 </tr>
8329 <tr class="field"><th class="field-name">subrepos:</th><td class="field-body"><p class="first">List of strings. Updated subrepositories in the changeset.</p>
8330 </td>
8331 </tr>
8332 <tr class="field"><th class="field-name">tags:</th><td class="field-body"><p class="first">List of strings. Any tags associated with the changeset.</p>
8333 </td>
8334 </tr>
8335 <tr class="field"><th class="field-name">termwidth:</th><td class="field-body"><p class="first">Integer. The width of the current terminal.</p>
8336 </td>
8337 </tr>
8338 <tr class="field"><th class="field-name">user:</th><td class="field-body"><p class="first">String. The unmodified author of the changeset.</p>
8339 </td>
8340 </tr>
8341 <tr class="field"><th class="field-name">verbosity:</th><td class="field-body"><p class="first last">String. The current output verbosity in 'debug', 'quiet', 'verbose',
8342 or ''.</p>
8343 </td>
8344 </tr>
8345 </tbody>
8346 </table>
8347 <p>The &quot;date&quot; keyword does not produce human-readable output. If you
8348 want to use a date in your output, you can use a filter to process
8349 it. Filters are functions which return a string based on the input
8350 variable. Be sure to use the stringify filter first when you're
8351 applying a string-input filter to a list-like input variable.
8352 You can also use a chain of filters to get the desired output:</p>
8353 <pre class="literal-block">
8354 $ hg tip --template &quot;{date|isodate}\n&quot;
8355 2008-08-21 18:22 +0000
8356 </pre>
8357 </div>
8358 <div class="section" id="filters">
8359 <h2>Filters</h2>
8360 <p>List of filters:</p>
8361 <table class="docutils field-list" frame="void" rules="none">
8362 <col class="field-name" />
8363 <col class="field-body" />
8364 <tbody valign="top">
8365 <tr class="field"><th class="field-name">addbreaks:</th><td class="field-body"><p class="first">Any text. Add an XHTML &quot;&lt;br /&gt;&quot; tag before the end of
8366 every line except the last.</p>
8367 </td>
8368 </tr>
8369 <tr class="field"><th class="field-name">age:</th><td class="field-body"><p class="first">Date. Returns a human-readable date/time difference between the
8370 given date/time and the current date/time.</p>
8371 </td>
8372 </tr>
8373 <tr class="field"><th class="field-name">basename:</th><td class="field-body"><p class="first">Any text. Treats the text as a path, and returns the last
8374 component of the path after splitting by the path separator.
8375 For example, &quot;foo/bar/baz&quot; becomes &quot;baz&quot; and &quot;foo/bar//&quot; becomes &quot;&quot;.</p>
8376 </td>
8377 </tr>
8378 <tr class="field"><th class="field-name">cbor:</th><td class="field-body"><p class="first">Any object. Serializes the object to CBOR bytes.</p>
8379 </td>
8380 </tr>
8381 <tr class="field"><th class="field-name">commondir:</th><td class="field-body"><p class="first">List of text. Treats each list item as file name with /
8382 as path separator and returns the longest common directory
8383 prefix shared by all list items.
8384 Returns the empty string if no common prefix exists.</p>
8385 <p>The list items are not normalized, i.e. &quot;foo/../bar&quot; is handled as
8386 file &quot;bar&quot; in the directory &quot;foo/..&quot;. Leading slashes are ignored.</p>
8387 <p>For example, [&quot;foo/bar/baz&quot;, &quot;foo/baz/bar&quot;] becomes &quot;foo&quot; and
8388 [&quot;foo/bar&quot;, &quot;baz&quot;] becomes &quot;&quot;.</p>
8389 </td>
8390 </tr>
8391 <tr class="field"><th class="field-name">count:</th><td class="field-body"><p class="first">List or text. Returns the length as an integer.</p>
8392 </td>
8393 </tr>
8394 <tr class="field"><th class="field-name">dirname:</th><td class="field-body"><p class="first">Any text. Treats the text as a path, and strips the last
8395 component of the path after splitting by the path separator.</p>
8396 </td>
8397 </tr>
8398 <tr class="field"><th class="field-name">domain:</th><td class="field-body"><p class="first">Any text. Finds the first string that looks like an email
8399 address, and extracts just the domain component. Example: <tt class="docutils literal">User
8400 &lt;user&#64;example.com&gt;</tt> becomes <tt class="docutils literal">example.com</tt>.</p>
8401 </td>
8402 </tr>
8403 <tr class="field"><th class="field-name">email:</th><td class="field-body"><p class="first">Any text. Extracts the first string that looks like an email
8404 address. Example: <tt class="docutils literal">User &lt;user&#64;example.com&gt;</tt> becomes
8405 <tt class="docutils literal">user&#64;example.com</tt>.</p>
8406 </td>
8407 </tr>
8408 <tr class="field"><th class="field-name">emailuser:</th><td class="field-body"><p class="first">Any text. Returns the user portion of an email address.</p>
8409 </td>
8410 </tr>
8411 <tr class="field"><th class="field-name">escape:</th><td class="field-body"><p class="first">Any text. Replaces the special XML/XHTML characters &quot;&amp;&quot;, &quot;&lt;&quot;
8412 and &quot;&gt;&quot; with XML entities, and filters out NUL characters.</p>
8413 </td>
8414 </tr>
8415 <tr class="field"><th class="field-name">fill68:</th><td class="field-body"><p class="first">Any text. Wraps the text to fit in 68 columns.</p>
8416 </td>
8417 </tr>
8418 <tr class="field"><th class="field-name">fill76:</th><td class="field-body"><p class="first">Any text. Wraps the text to fit in 76 columns.</p>
8419 </td>
8420 </tr>
8421 <tr class="field"><th class="field-name">firstline:</th><td class="field-body"><p class="first">Any text. Returns the first line of text.</p>
8422 </td>
8423 </tr>
8424 <tr class="field"><th class="field-name">hex:</th><td class="field-body"><p class="first">Any text. Convert a binary Mercurial node identifier into
8425 its long hexadecimal representation.</p>
8426 </td>
8427 </tr>
8428 <tr class="field"><th class="field-name">hgdate:</th><td class="field-body"><p class="first">Date. Returns the date as a pair of numbers: &quot;1157407993
8429 25200&quot; (Unix timestamp, timezone offset).</p>
8430 </td>
8431 </tr>
8432 <tr class="field"><th class="field-name">isodate:</th><td class="field-body"><p class="first">Date. Returns the date in ISO 8601 format: &quot;2009-08-18 13:00
8433 +0200&quot;.</p>
8434 </td>
8435 </tr>
8436 <tr class="field"><th class="field-name">isodatesec:</th><td class="field-body"><p class="first">Date. Returns the date in ISO 8601 format, including
8437 seconds: &quot;2009-08-18 13:00:13 +0200&quot;. See also the rfc3339date
8438 filter.</p>
8439 </td>
8440 </tr>
8441 <tr class="field"><th class="field-name">json:</th><td class="field-body"><p class="first">Any object. Serializes the object to a JSON formatted text.</p>
8442 </td>
8443 </tr>
8444 <tr class="field"><th class="field-name">lower:</th><td class="field-body"><p class="first">Any text. Converts the text to lowercase.</p>
8445 </td>
8446 </tr>
8447 <tr class="field"><th class="field-name">nonempty:</th><td class="field-body"><p class="first">Any text. Returns '(none)' if the string is empty.</p>
8448 </td>
8449 </tr>
8450 <tr class="field"><th class="field-name">obfuscate:</th><td class="field-body"><p class="first">Any text. Returns the input text rendered as a sequence of
8451 XML entities.</p>
8452 </td>
8453 </tr>
8454 <tr class="field"><th class="field-name">person:</th><td class="field-body"><p class="first">Any text. Returns the name before an email address,
8455 interpreting it as per RFC 5322.</p>
8456 </td>
8457 </tr>
8458 <tr class="field"><th class="field-name">reverse:</th><td class="field-body"><p class="first">List. Reverses the order of list items.</p>
8459 </td>
8460 </tr>
8461 <tr class="field"><th class="field-name">revescape:</th><td class="field-body"><p class="first">Any text. Escapes all &quot;special&quot; characters, except &#64;.
8462 Forward slashes are escaped twice to prevent web servers from prematurely
8463 unescaping them. For example, &quot;&#64;foo bar/baz&quot; becomes &quot;&#64;foo%20bar%252Fbaz&quot;.</p>
8464 </td>
8465 </tr>
8466 <tr class="field"><th class="field-name">rfc3339date:</th><td class="field-body"><p class="first">Date. Returns a date using the Internet date format
8467 specified in RFC 3339: &quot;2009-08-18T13:00:13+02:00&quot;.</p>
8468 </td>
8469 </tr>
8470 <tr class="field"><th class="field-name">rfc822date:</th><td class="field-body"><p class="first">Date. Returns a date using the same format used in email
8471 headers: &quot;Tue, 18 Aug 2009 13:00:13 +0200&quot;.</p>
8472 </td>
8473 </tr>
8474 <tr class="field"><th class="field-name">short:</th><td class="field-body"><p class="first">Changeset hash. Returns the short form of a changeset hash,
8475 i.e. a 12 hexadecimal digit string.</p>
8476 </td>
8477 </tr>
8478 <tr class="field"><th class="field-name">shortbisect:</th><td class="field-body"><p class="first">Any text. Treats <cite>label</cite> as a bisection status, and
8479 returns a single-character representing the status (G: good, B: bad,
8480 S: skipped, U: untested, I: ignored). Returns single space if <cite>text</cite>
8481 is not a valid bisection status.</p>
8482 </td>
8483 </tr>
8484 <tr class="field"><th class="field-name">shortdate:</th><td class="field-body"><p class="first">Date. Returns a date like &quot;2006-09-18&quot;.</p>
8485 </td>
8486 </tr>
8487 <tr class="field"><th class="field-name">slashpath:</th><td class="field-body"><p class="first">Any text. Replaces the native path separator with slash.</p>
8488 </td>
8489 </tr>
8490 <tr class="field"><th class="field-name">splitlines:</th><td class="field-body"><p class="first">Any text. Split text into a list of lines.</p>
8491 </td>
8492 </tr>
8493 <tr class="field"><th class="field-name">stringify:</th><td class="field-body"><p class="first">Any type. Turns the value into text by converting values into
8494 text and concatenating them.</p>
8495 </td>
8496 </tr>
8497 <tr class="field"><th class="field-name">stripdir:</th><td class="field-body"><p class="first">Treat the text as path and strip a directory level, if
8498 possible. For example, &quot;foo&quot; and &quot;foo/bar&quot; becomes &quot;foo&quot;.</p>
8499 </td>
8500 </tr>
8501 <tr class="field"><th class="field-name">tabindent:</th><td class="field-body"><p class="first">Any text. Returns the text, with every non-empty line
8502 except the first starting with a tab character.</p>
8503 </td>
8504 </tr>
8505 <tr class="field"><th class="field-name">upper:</th><td class="field-body"><p class="first">Any text. Converts the text to uppercase.</p>
8506 </td>
8507 </tr>
8508 <tr class="field"><th class="field-name">urlescape:</th><td class="field-body"><p class="first">Any text. Escapes all &quot;special&quot; characters. For example,
8509 &quot;foo bar&quot; becomes &quot;foo%20bar&quot;.</p>
8510 </td>
8511 </tr>
8512 <tr class="field"><th class="field-name">user:</th><td class="field-body"><p class="first">Any text. Returns a short representation of a user name or email
8513 address.</p>
8514 </td>
8515 </tr>
8516 <tr class="field"><th class="field-name">utf8:</th><td class="field-body"><p class="first last">Any text. Converts from the local character encoding to UTF-8.</p>
8517 </td>
8518 </tr>
8519 </tbody>
8520 </table>
8521 <p>Note that a filter is nothing more than a function call, i.e.
8522 <tt class="docutils literal">expr|filter</tt> is equivalent to <tt class="docutils literal">filter(expr)</tt>.</p>
8523 </div>
8524 <div class="section" id="functions">
8525 <h2>Functions</h2>
8526 <p>In addition to filters, there are some basic built-in functions:</p>
8527 <table class="docutils field-list" frame="void" rules="none">
8528 <col class="field-name" />
8529 <col class="field-body" />
8530 <tbody valign="top">
8531 <tr class="field"><th class="field-name" colspan="2">config(section, name[, default]):</th></tr>
8532 <tr class="field"><td>&nbsp;</td><td class="field-body">Returns the requested hgrc config option as a string.</td>
8533 </tr>
8534 <tr class="field"><th class="field-name" colspan="2">configbool(section, name[, default]):</th></tr>
8535 <tr class="field"><td>&nbsp;</td><td class="field-body">Returns the requested hgrc config option as a boolean.</td>
8536 </tr>
8537 <tr class="field"><th class="field-name" colspan="2">configint(section, name[, default]):</th></tr>
8538 <tr class="field"><td>&nbsp;</td><td class="field-body">Returns the requested hgrc config option as an integer.</td>
8539 </tr>
8540 <tr class="field"><th class="field-name" colspan="2">date(date[, fmt]):</th></tr>
8541 <tr class="field"><td>&nbsp;</td><td class="field-body">Format a date. The format string uses the Python strftime format.
8542 The default is a Unix date format, including the timezone:
8543 &quot;Mon Sep 04 15:13:13 2006 0700&quot;.</td>
8544 </tr>
8545 <tr class="field"><th class="field-name" colspan="2">dict([[key=]value...]):</th></tr>
8546 <tr class="field"><td>&nbsp;</td><td class="field-body">Construct a dict from key-value pairs. A key may be omitted if
8547 a value expression can provide an unambiguous name.</td>
8548 </tr>
8549 <tr class="field"><th class="field-name" colspan="2">diff([includepattern [, excludepattern]]):</th></tr>
8550 <tr class="field"><td>&nbsp;</td><td class="field-body">Show a diff, optionally
8551 specifying files to include or exclude.</td>
8552 </tr>
8553 <tr class="field"><th class="field-name">files(pattern):</th><td class="field-body">All files of the current changeset matching the pattern. See
8554 <a class="reference external" href="hg.1.html#patterns"><tt class="docutils literal">hg help patterns</tt></a>.</td>
8555 </tr>
8556 <tr class="field"><th class="field-name" colspan="2">fill(text[, width[, initialident[, hangindent]]]):</th></tr>
8557 <tr class="field"><td>&nbsp;</td><td class="field-body">Fill many
8558 paragraphs with optional indentation. See the &quot;fill&quot; filter.</td>
8559 </tr>
8560 <tr class="field"><th class="field-name" colspan="2">filter(iterable[, expr]):</th></tr>
8561 <tr class="field"><td>&nbsp;</td><td class="field-body">Remove empty elements from a list or a dict. If expr specified, it's
8562 applied to each element to test emptiness.</td>
8563 </tr>
8564 <tr class="field"><th class="field-name">get(dict, key):</th><td class="field-body">Get an attribute/key from an object. Some keywords
8565 are complex types. This function allows you to obtain the value of an
8566 attribute on these types.</td>
8567 </tr>
8568 <tr class="field"><th class="field-name" colspan="2">if(expr, then[, else]):</th></tr>
8569 <tr class="field"><td>&nbsp;</td><td class="field-body">Conditionally execute based on the result of
8570 an expression.</td>
8571 </tr>
8572 <tr class="field"><th class="field-name" colspan="2">ifcontains(needle, haystack, then[, else]):</th></tr>
8573 <tr class="field"><td>&nbsp;</td><td class="field-body">Conditionally execute based
8574 on whether the item &quot;needle&quot; is in &quot;haystack&quot;.</td>
8575 </tr>
8576 <tr class="field"><th class="field-name" colspan="2">ifeq(expr1, expr2, then[, else]):</th></tr>
8577 <tr class="field"><td>&nbsp;</td><td class="field-body">Conditionally execute based on
8578 whether 2 items are equivalent.</td>
8579 </tr>
8580 <tr class="field"><th class="field-name" colspan="2">indent(text, indentchars[, firstline]):</th></tr>
8581 <tr class="field"><td>&nbsp;</td><td class="field-body">Indents all non-empty lines
8582 with the characters given in the indentchars string. An optional
8583 third parameter will override the indent for the first line only
8584 if present.</td>
8585 </tr>
8586 <tr class="field"><th class="field-name" colspan="2">join(list, sep):</th></tr>
8587 <tr class="field"><td>&nbsp;</td><td class="field-body">Join items in a list with a delimiter.</td>
8588 </tr>
8589 <tr class="field"><th class="field-name" colspan="2">label(label, expr):</th></tr>
8590 <tr class="field"><td>&nbsp;</td><td class="field-body">Apply a label to generated content. Content with a label
8591 applied can result in additional post-processing, such as
8592 automatic colorization. In order to receive effects, labels must
8593 have a dot, such as <cite>log.secret</cite> or <cite>branch.active</cite>.</td>
8594 </tr>
8595 <tr class="field"><th class="field-name" colspan="2">latesttag([pattern]):</th></tr>
8596 <tr class="field"><td>&nbsp;</td><td class="field-body">The global tags matching the given pattern on the
8597 most recent globally tagged ancestor of this changeset.
8598 If no such tags exist, the &quot;{tag}&quot; template resolves to
8599 the string &quot;null&quot;. See <a class="reference external" href="hg.1.html#revisions.patterns"><tt class="docutils literal">hg help revisions.patterns</tt></a> for the pattern
8600 syntax.</td>
8601 </tr>
8602 <tr class="field"><th class="field-name" colspan="2">localdate(date[, tz]):</th></tr>
8603 <tr class="field"><td>&nbsp;</td><td class="field-body">Converts a date to the specified timezone.
8604 The default is local date.</td>
8605 </tr>
8606 <tr class="field"><th class="field-name" colspan="2">mailmap(author):</th></tr>
8607 <tr class="field"><td>&nbsp;</td><td class="field-body">Return the author, updated according to the value
8608 set in the .mailmap file</td>
8609 </tr>
8610 <tr class="field"><th class="field-name">max(iterable):</th><td class="field-body">Return the max of an iterable</td>
8611 </tr>
8612 <tr class="field"><th class="field-name">min(iterable):</th><td class="field-body">Return the min of an iterable</td>
8613 </tr>
8614 <tr class="field"><th class="field-name">mod(a, b):</th><td class="field-body">Calculate a mod b such that a / b + a mod b == a</td>
8615 </tr>
8616 <tr class="field"><th class="field-name" colspan="2">pad(text, width[, fillchar=' '[, left=False[, truncate=False]]]):</th></tr>
8617 <tr class="field"><td>&nbsp;</td><td class="field-body">Pad text with a
8618 fill character.</td>
8619 </tr>
8620 <tr class="field"><th class="field-name">relpath(path):</th><td class="field-body">Convert a repository-absolute path into a filesystem path relative to
8621 the current working directory.</td>
8622 </tr>
8623 <tr class="field"><th class="field-name" colspan="2">revset(query[, formatargs...]):</th></tr>
8624 <tr class="field"><td>&nbsp;</td><td class="field-body">Execute a revision set query. See
8625 <a class="reference external" href="hg.1.html#revset"><tt class="docutils literal">hg help revset</tt></a>.</td>
8626 </tr>
8627 <tr class="field"><th class="field-name" colspan="2">rstdoc(text, style):</th></tr>
8628 <tr class="field"><td>&nbsp;</td><td class="field-body">Format reStructuredText.</td>
8629 </tr>
8630 <tr class="field"><th class="field-name" colspan="2">search(pattern, text):</th></tr>
8631 <tr class="field"><td>&nbsp;</td><td class="field-body">Look for the first text matching the regular expression pattern.
8632 Groups are accessible as <tt class="docutils literal">{1}</tt>, <tt class="docutils literal">{2}</tt>, ... in %-mapped template.</td>
8633 </tr>
8634 <tr class="field"><th class="field-name" colspan="2">separate(sep, args...):</th></tr>
8635 <tr class="field"><td>&nbsp;</td><td class="field-body">Add a separator between non-empty arguments.</td>
8636 </tr>
8637 <tr class="field"><th class="field-name" colspan="2">shortest(node, minlength=4):</th></tr>
8638 <tr class="field"><td>&nbsp;</td><td class="field-body">Obtain the shortest representation of
8639 a node.</td>
8640 </tr>
8641 <tr class="field"><th class="field-name" colspan="2">startswith(pattern, text):</th></tr>
8642 <tr class="field"><td>&nbsp;</td><td class="field-body">Returns the value from the &quot;text&quot; argument
8643 if it begins with the content from the &quot;pattern&quot; argument.</td>
8644 </tr>
8645 <tr class="field"><th class="field-name" colspan="2">strip(text[, chars]):</th></tr>
8646 <tr class="field"><td>&nbsp;</td><td class="field-body">Strip characters from a string. By default,
8647 strips all leading and trailing whitespace.</td>
8648 </tr>
8649 <tr class="field"><th class="field-name" colspan="2">sub(pattern, replacement, expression):</th></tr>
8650 <tr class="field"><td>&nbsp;</td><td class="field-body">Perform text substitution
8651 using regular expressions.</td>
8652 </tr>
8653 <tr class="field"><th class="field-name" colspan="2">subsetparents(rev, revset):</th></tr>
8654 <tr class="field"><td>&nbsp;</td><td class="field-body">Look up parents of the rev in the sub graph given by the revset.</td>
8655 </tr>
8656 <tr class="field"><th class="field-name" colspan="2">word(number, text[, separator]):</th></tr>
8657 <tr class="field"><td>&nbsp;</td><td class="field-body">Return the nth word from a string.</td>
8658 </tr>
8659 </tbody>
8660 </table>
8661 </div>
8662 <div class="section" id="operators-2">
8663 <h2>Operators</h2>
8664 <p>We provide a limited set of infix arithmetic operations on integers:</p>
8665 <pre class="literal-block">
8666 + for addition
8667 - for subtraction
8668 * for multiplication
8669 / for floor division (division rounded to integer nearest -infinity)
8670 </pre>
8671 <p>Division fulfills the law x = x / y + mod(x, y).</p>
8672 <p>Also, for any expression that returns a list, there is a list operator:</p>
8673 <pre class="literal-block">
8674 expr % &quot;{template}&quot;
8675 </pre>
8676 <p>As seen in the above example, <tt class="docutils literal">{template}</tt> is interpreted as a template.
8677 To prevent it from being interpreted, you can use an escape character <tt class="docutils literal">\{</tt>
8678 or a raw string prefix, <tt class="docutils literal"><span class="pre">r'...'</span></tt>.</p>
8679 <p>The dot operator can be used as a shorthand for accessing a sub item:</p>
8680 <ul class="simple">
8681 <li><tt class="docutils literal">expr.member</tt> is roughly equivalent to <tt class="docutils literal">expr % '{member}'</tt> if <tt class="docutils literal">expr</tt>
8682 returns a non-list/dict. The returned value is not stringified.</li>
8683 <li><tt class="docutils literal">dict.key</tt> is identical to <tt class="docutils literal">get(dict, 'key')</tt>.</li>
8684 </ul>
8685 </div>
8686 <div class="section" id="aliases-1">
8687 <h2>Aliases</h2>
8688 <p>New keywords and functions can be defined in the <tt class="docutils literal">templatealias</tt> section of
8689 a Mercurial configuration file:</p>
8690 <pre class="literal-block">
8691 &lt;alias&gt; = &lt;definition&gt;
8692 </pre>
8693 <p>Arguments of the form <cite>a1</cite>, <cite>a2</cite>, etc. are substituted from the alias into
8694 the definition.</p>
8695 <p>For example,</p>
8696 <pre class="literal-block">
8697 [templatealias]
8698 r = rev
8699 rn = &quot;{r}:{node|short}&quot;
8700 leftpad(s, w) = pad(s, w, ' ', True)
8701 </pre>
8702 <p>defines two symbol aliases, <tt class="docutils literal">r</tt> and <tt class="docutils literal">rn</tt>, and a function alias
8703 <tt class="docutils literal">leftpad()</tt>.</p>
8704 <p>It's also possible to specify complete template strings, using the
8705 <tt class="docutils literal">templates</tt> section. The syntax used is the general template string syntax.</p>
8706 <p>For example,</p>
8707 <pre class="literal-block">
8708 [templates]
8709 nodedate = &quot;{node|short}: {date(date, &quot;%Y-%m-%d&quot;)}\n&quot;
8710 </pre>
8711 <p>defines a template, <tt class="docutils literal">nodedate</tt>, which can be called like:</p>
8712 <pre class="literal-block">
8713 $ hg log -r . -Tnodedate
8714 </pre>
8715 <p>A template defined in <tt class="docutils literal">templates</tt> section can also be referenced from
8716 another template:</p>
8717 <pre class="literal-block">
8718 $ hg log -r . -T &quot;{rev} {nodedate}&quot;
8719 </pre>
8720 <p>but be aware that the keywords cannot be overridden by templates. For example,
8721 a template defined as <tt class="docutils literal">templates.rev</tt> cannot be referenced as <tt class="docutils literal">{rev}</tt>.</p>
8722 <p>A template defined in <tt class="docutils literal">templates</tt> section may have sub templates which
8723 are inserted before/after/between items:</p>
8724 <pre class="literal-block">
8725 [templates]
8726 myjson = ' {dict(rev, node|short)|json}'
8727 myjson:docheader = '\{\n'
8728 myjson:docfooter = '\n}\n'
8729 myjson:separator = ',\n'
8730 </pre>
8731 </div>
8732 <div class="section" id="examples-4">
8733 <h2>Examples</h2>
8734 <p>Some sample command line templates:</p>
8735 <ul>
8736 <li><p class="first">Format lists, e.g. files:</p>
8737 <pre class="literal-block">
8738 $ hg log -r 0 --template &quot;files:\n{files % ' {file}\n'}&quot;
8739 </pre>
8740 </li>
8741 <li><p class="first">Join the list of files with a &quot;, &quot;:</p>
8742 <pre class="literal-block">
8743 $ hg log -r 0 --template &quot;files: {join(files, ', ')}\n&quot;
8744 </pre>
8745 </li>
8746 <li><p class="first">Join the list of files ending with &quot;.py&quot; with a &quot;, &quot;:</p>
8747 <pre class="literal-block">
8748 $ hg log -r 0 --template &quot;pythonfiles: {join(files('**.py'), ', ')}\n&quot;
8749 </pre>
8750 </li>
8751 <li><p class="first">Separate non-empty arguments by a &quot; &quot;:</p>
8752 <pre class="literal-block">
8753 $ hg log -r 0 --template &quot;{separate(' ', node, bookmarks, tags}\n&quot;
8754 </pre>
8755 </li>
8756 <li><p class="first">Modify each line of a commit description:</p>
8757 <pre class="literal-block">
8758 $ hg log --template &quot;{splitlines(desc) % '**** {line}\n'}&quot;
8759 </pre>
8760 </li>
8761 <li><p class="first">Format date:</p>
8762 <pre class="literal-block">
8763 $ hg log -r 0 --template &quot;{date(date, '%Y')}\n&quot;
8764 </pre>
8765 </li>
8766 <li><p class="first">Display date in UTC:</p>
8767 <pre class="literal-block">
8768 $ hg log -r 0 --template &quot;{localdate(date, 'UTC')|date}\n&quot;
8769 </pre>
8770 </li>
8771 <li><p class="first">Output the description set to a fill-width of 30:</p>
8772 <pre class="literal-block">
8773 $ hg log -r 0 --template &quot;{fill(desc, 30)}&quot;
8774 </pre>
8775 </li>
8776 <li><p class="first">Use a conditional to test for the default branch:</p>
8777 <pre class="literal-block">
8778 $ hg log -r 0 --template &quot;{ifeq(branch, 'default', 'on the main branch',
8779 'on branch {branch}')}\n&quot;
8780 </pre>
8781 </li>
8782 <li><p class="first">Append a newline if not empty:</p>
8783 <pre class="literal-block">
8784 $ hg tip --template &quot;{if(author, '{author}\n')}&quot;
8785 </pre>
8786 </li>
8787 <li><p class="first">Label the output for use with the color extension:</p>
8788 <pre class="literal-block">
8789 $ hg log -r 0 --template &quot;{label('changeset.{phase}', node|short)}\n&quot;
8790 </pre>
8791 </li>
8792 <li><p class="first">Invert the firstline filter, i.e. everything but the first line:</p>
8793 <pre class="literal-block">
8794 $ hg log -r 0 --template &quot;{sub(r'^.*\n?\n?', '', desc)}\n&quot;
8795 </pre>
8796 </li>
8797 <li><p class="first">Display the contents of the 'extra' field, one per line:</p>
8798 <pre class="literal-block">
8799 $ hg log -r 0 --template &quot;{join(extras, '\n')}\n&quot;
8800 </pre>
8801 </li>
8802 <li><p class="first">Mark the active bookmark with '*':</p>
8803 <pre class="literal-block">
8804 $ hg log --template &quot;{bookmarks % '{bookmark}{ifeq(bookmark, active, '*')} '}\n&quot;
8805 </pre>
8806 </li>
8807 <li><p class="first">Find the previous release candidate tag, the distance and changes since the tag:</p>
8808 <pre class="literal-block">
8809 $ hg log -r . --template &quot;{latesttag('re:^.*-rc$') % '{tag}, {changes}, {distance}'}\n&quot;
8810 </pre>
8811 </li>
8812 <li><p class="first">Mark the working copy parent with '&#64;':</p>
8813 <pre class="literal-block">
8814 $ hg log --template &quot;{ifcontains(rev, revset('.'), '&#64;')}\n&quot;
8815 </pre>
8816 </li>
8817 <li><p class="first">Show details of parent revisions:</p>
8818 <pre class="literal-block">
8819 $ hg log --template &quot;{revset('parents(%d)', rev) % '{desc|firstline}\n'}&quot;
8820 </pre>
8821 </li>
8822 <li><p class="first">Show only commit descriptions that start with &quot;template&quot;:</p>
8823 <pre class="literal-block">
8824 $ hg log --template &quot;{startswith('template', firstline(desc))}\n&quot;
8825 </pre>
8826 </li>
8827 <li><p class="first">Print the first word of each line of a commit message:</p>
8828 <pre class="literal-block">
8829 $ hg log --template &quot;{word(0, desc)}\n&quot;
8830 </pre>
8831 </li>
8832 </ul>
8833 </div>
8834 </div>
8835 <div class="section" id="url-paths">
8836 <span id="urls"></span><h1><a class="toc-backref" href="#contents">URL Paths</a></h1>
8837 <p>Valid URLs are of the form:</p>
8838 <pre class="literal-block">
8839 local/filesystem/path[#revision]
8840 file://local/filesystem/path[#revision]
8841 http://[user[:pass]&#64;]host[:port]/[path][#revision]
8842 https://[user[:pass]&#64;]host[:port]/[path][#revision]
8843 ssh://[user&#64;]host[:port]/[path][#revision]
8844 path://pathname
8845 </pre>
8846 <p>Paths in the local filesystem can either point to Mercurial
8847 repositories or to bundle files (as created by <a class="reference external" href="hg.1.html#bundle"><tt class="docutils literal">hg bundle</tt></a> or
8848 <a class="reference external" href="hg.1.html#incoming"><tt class="docutils literal">hg incoming <span class="pre">--bundle</span></tt></a>). See also <a class="reference external" href="hg.1.html#paths"><tt class="docutils literal">hg help paths</tt></a>.</p>
8849 <p>An optional identifier after # indicates a particular branch, tag, or
8850 changeset to use from the remote repository. See also <a class="reference external" href="hg.1.html#revisions"><tt class="docutils literal">hg help
8851 revisions</tt></a>.</p>
8852 <p>Some features, such as pushing to <a class="reference external" href="http://">http://</a> and <a class="reference external" href="https://">https://</a> URLs are only
8853 possible if the feature is explicitly enabled on the remote Mercurial
8854 server.</p>
8855 <p>Note that the security of HTTPS URLs depends on proper configuration of
8856 web.cacerts.</p>
8857 <p>Some notes about using SSH with Mercurial:</p>
8858 <ul>
8859 <li><p class="first">SSH requires an accessible shell account on the destination machine
8860 and a copy of hg in the remote path or specified with remotecmd.</p>
8861 </li>
8862 <li><p class="first">path is relative to the remote user's home directory by default. Use
8863 an extra slash at the start of a path to specify an absolute path:</p>
8864 <pre class="literal-block">
8865 ssh://example.com//tmp/repository
8866 </pre>
8867 </li>
8868 <li><p class="first">Mercurial doesn't use its own compression via SSH; the right thing
8869 to do is to configure it in your ~/.ssh/config, e.g.:</p>
8870 <pre class="literal-block">
8871 Host *.mylocalnetwork.example.com
8872 Compression no
8873 Host *
8874 Compression yes
8875 </pre>
8876 <p>Alternatively specify &quot;ssh -C&quot; as your ssh command in your
8877 configuration file or with the --ssh command line option.</p>
8878 </li>
8879 </ul>
8880 <p>These URLs can all be stored in your configuration file with path
8881 aliases under the [paths] section like so:</p>
8882 <pre class="literal-block">
8883 [paths]
8884 alias1 = URL1
8885 alias2 = URL2
8886 ...
8887 </pre>
8888 <p>You can then use the alias for any command that uses a URL (for
8889 example <a class="reference external" href="hg.1.html#pull"><tt class="docutils literal">hg pull alias1</tt></a> will be treated as <a class="reference external" href="hg.1.html#pull"><tt class="docutils literal">hg pull URL1</tt></a>).</p>
8890 <p>Two path aliases are special because they are used as defaults when
8891 you do not provide the URL to a command:</p>
8892 <dl class="docutils">
8893 <dt>default:</dt>
8894 <dd>When you create a repository with hg clone, the clone command saves
8895 the location of the source repository as the new repository's
8896 'default' path. This is then used when you omit path from push- and
8897 pull-like commands (including incoming and outgoing).</dd>
8898 <dt>default-push:</dt>
8899 <dd>The push command will look for a path named 'default-push', and
8900 prefer it over 'default' if both are defined.</dd>
8901 </dl>
8902 <p>These alias can also be use in the <cite>path://</cite> scheme:</p>
8903 <pre class="literal-block">
8904 [paths]
8905 alias1 = URL1
8906 alias2 = path://alias1
8907 ...
8908 </pre>
8909 <p>check <a class="reference external" href="hgrc.5.html#paths"><tt class="docutils literal">hg help config.paths</tt></a> for details about the behavior of such &quot;sub-path&quot;.</p>
8910 </div>
8911 <div class="section" id="extensions-1">
8912 <h1><a class="toc-backref" href="#contents">Extensions</a></h1>
8913 <p>This section contains help for extensions that are distributed together with Mercurial. Help for other extensions is available in the help system.</p>
8914 <div class="contents htmlonly local topic" id="topic-1">
8915 <ul class="simple">
8916 <li><a class="reference internal" href="#absorb" id="toc-entry-37">absorb</a></li>
8917 <li><a class="reference internal" href="#acl" id="toc-entry-38">acl</a></li>
8918 <li><a class="reference internal" href="#amend" id="toc-entry-39">amend</a></li>
8919 <li><a class="reference internal" href="#automv" id="toc-entry-40">automv</a></li>
8920 <li><a class="reference internal" href="#beautifygraph" id="toc-entry-41">beautifygraph</a></li>
8921 <li><a class="reference internal" href="#blackbox" id="toc-entry-42">blackbox</a></li>
8922 <li><a class="reference internal" href="#bookflow" id="toc-entry-43">bookflow</a></li>
8923 <li><a class="reference internal" href="#bugzilla" id="toc-entry-44">bugzilla</a></li>
8924 <li><a class="reference internal" href="#censor" id="toc-entry-45">censor</a></li>
8925 <li><a class="reference internal" href="#children" id="toc-entry-46">children</a></li>
8926 <li><a class="reference internal" href="#churn" id="toc-entry-47">churn</a></li>
8927 <li><a class="reference internal" href="#clonebundles" id="toc-entry-48">clonebundles</a></li>
8928 <li><a class="reference internal" href="#closehead" id="toc-entry-49">closehead</a></li>
8929 <li><a class="reference internal" href="#commitextras" id="toc-entry-50">commitextras</a></li>
8930 <li><a class="reference internal" href="#convert" id="toc-entry-51">convert</a></li>
8931 <li><a class="reference internal" href="#eol" id="toc-entry-52">eol</a></li>
8932 <li><a class="reference internal" href="#extdiff" id="toc-entry-53">extdiff</a></li>
8933 <li><a class="reference internal" href="#factotum" id="toc-entry-54">factotum</a></li>
8934 <li><a class="reference internal" href="#fastannotate" id="toc-entry-55">fastannotate</a></li>
8935 <li><a class="reference internal" href="#fastexport" id="toc-entry-56">fastexport</a></li>
8936 <li><a class="reference internal" href="#fetch" id="toc-entry-57">fetch</a></li>
8937 <li><a class="reference internal" href="#fix" id="toc-entry-58">fix</a></li>
8938 <li><a class="reference internal" href="#fsmonitor" id="toc-entry-59">fsmonitor</a></li>
8939 <li><a class="reference internal" href="#git" id="toc-entry-60">git</a></li>
8940 <li><a class="reference internal" href="#githelp" id="toc-entry-61">githelp</a></li>
8941 <li><a class="reference internal" href="#gpg" id="toc-entry-62">gpg</a></li>
8942 <li><a class="reference internal" href="#graphlog" id="toc-entry-63">graphlog</a></li>
8943 <li><a class="reference internal" href="#hgk" id="toc-entry-64">hgk</a></li>
8944 <li><a class="reference internal" href="#highlight" id="toc-entry-65">highlight</a></li>
8945 <li><a class="reference internal" href="#histedit" id="toc-entry-66">histedit</a></li>
8946 <li><a class="reference internal" href="#hooklib" id="toc-entry-67">hooklib</a></li>
8947 <li><a class="reference internal" href="#journal" id="toc-entry-68">journal</a></li>
8948 <li><a class="reference internal" href="#keyword" id="toc-entry-69">keyword</a></li>
8949 <li><a class="reference internal" href="#largefiles" id="toc-entry-70">largefiles</a></li>
8950 <li><a class="reference internal" href="#lfs" id="toc-entry-71">lfs</a></li>
8951 <li><a class="reference internal" href="#logtoprocess" id="toc-entry-72">logtoprocess</a></li>
8952 <li><a class="reference internal" href="#mq" id="toc-entry-73">mq</a></li>
8953 <li><a class="reference internal" href="#narrow" id="toc-entry-74">narrow</a></li>
8954 <li><a class="reference internal" href="#notify" id="toc-entry-75">notify</a></li>
8955 <li><a class="reference internal" href="#pager-1" id="toc-entry-76">pager</a></li>
8956 <li><a class="reference internal" href="#patchbomb" id="toc-entry-77">patchbomb</a></li>
8957 <li><a class="reference internal" href="#phabricator" id="toc-entry-78">phabricator</a></li>
8958 <li><a class="reference internal" href="#purge-1" id="toc-entry-79">purge</a></li>
8959 <li><a class="reference internal" href="#rebase" id="toc-entry-80">rebase</a></li>
8960 <li><a class="reference internal" href="#record" id="toc-entry-81">record</a></li>
8961 <li><a class="reference internal" href="#releasenotes" id="toc-entry-82">releasenotes</a></li>
8962 <li><a class="reference internal" href="#relink" id="toc-entry-83">relink</a></li>
8963 <li><a class="reference internal" href="#remotefilelog" id="toc-entry-84">remotefilelog</a></li>
8964 <li><a class="reference internal" href="#remotenames" id="toc-entry-85">remotenames</a></li>
8965 <li><a class="reference internal" href="#schemes" id="toc-entry-86">schemes</a></li>
8966 <li><a class="reference internal" href="#share" id="toc-entry-87">share</a></li>
8967 <li><a class="reference internal" href="#show" id="toc-entry-88">show</a></li>
8968 <li><a class="reference internal" href="#sparse" id="toc-entry-89">sparse</a></li>
8969 <li><a class="reference internal" href="#split" id="toc-entry-90">split</a></li>
8970 <li><a class="reference internal" href="#strip" id="toc-entry-91">strip</a></li>
8971 <li><a class="reference internal" href="#transplant" id="toc-entry-92">transplant</a></li>
8972 <li><a class="reference internal" href="#uncommit" id="toc-entry-93">uncommit</a></li>
8973 <li><a class="reference internal" href="#win32mbcs" id="toc-entry-94">win32mbcs</a></li>
8974 <li><a class="reference internal" href="#win32text" id="toc-entry-95">win32text</a></li>
8975 <li><a class="reference internal" href="#zeroconf" id="toc-entry-96">zeroconf</a></li>
8976 </ul>
8977 </div>
8978 <div class="section" id="absorb">
8979 <h2><a class="toc-backref" href="#toc-entry-37">absorb</a></h2>
8980 <p>apply working directory changes to changesets (EXPERIMENTAL)</p>
8981 <p>The absorb extension provides a command to use annotate information to
8982 amend modified chunks into the corresponding non-public changesets.</p>
8983 <pre class="literal-block">
8984 [absorb]
8985 # only check 50 recent non-public changesets at most
8986 max-stack-size = 50
8987 # whether to add noise to new commits to avoid obsolescence cycle
8988 add-noise = 1
8989 # make `amend --correlated` a shortcut to the main command
8990 amend-flag = correlated
8991
8992 [color]
8993 absorb.description = yellow
8994 absorb.node = blue bold
8995 absorb.path = bold
8996 </pre>
8997 <div class="section" id="commands-2">
8998 <h3>Commands</h3>
8999 <div class="section" id="change-creation-1">
9000 <h4>Change creation</h4>
9001 <div class="section" id="absorb-1">
9002 <h5>absorb</h5>
9003 <p>incorporate corrections into the stack of draft changesets:</p>
9004 <pre class="literal-block">
9005 hg absorb [OPTION] [FILE]...
9006 </pre>
9007 <p>absorb analyzes each change in your working directory and attempts to
9008 amend the changed lines into the changesets in your stack that first
9009 introduced those lines.</p>
9010 <p>If absorb cannot find an unambiguous changeset to amend for a change,
9011 that change will be left in the working directory, untouched. They can be
9012 observed by <a class="reference external" href="hg.1.html#status"><tt class="docutils literal">hg status</tt></a> or <a class="reference external" href="hg.1.html#diff"><tt class="docutils literal">hg diff</tt></a> afterwards. In other words,
9013 absorb does not write to the working directory.</p>
9014 <p>Changesets outside the revset <cite>::. and not public() and not merge()</cite> will
9015 not be changed.</p>
9016 <p>Changesets that become empty after applying the changes will be deleted.</p>
9017 <p>By default, absorb will show what it plans to do and prompt for
9018 confirmation. If you are confident that the changes will be absorbed
9019 to the correct place, run <a class="reference external" href="hg.1.html#absorb"><tt class="docutils literal">hg absorb <span class="pre">-a</span></tt></a> to apply the changes
9020 immediately.</p>
9021 <p>Returns 0 on success, 1 if all chunks were ignored and nothing amended.</p>
9022 <p>Options:</p>
9023 <table class="docutils option-list" frame="void" rules="none">
9024 <col class="option" />
9025 <col class="description" />
9026 <tbody valign="top">
9027 <tr><td class="option-group" colspan="2">
9028 <kbd><span class="option">-a</span>, <span class="option">--apply-changes</span></kbd></td>
9029 </tr>
9030 <tr><td>&nbsp;</td><td>apply changes without prompting for confirmation</td></tr>
9031 <tr><td class="option-group" colspan="2">
9032 <kbd><span class="option">-p</span>, <span class="option">--print-changes</span></kbd></td>
9033 </tr>
9034 <tr><td>&nbsp;</td><td>always print which changesets are modified by which changes</td></tr>
9035 <tr><td class="option-group" colspan="2">
9036 <kbd><span class="option">-i</span>, <span class="option">--interactive</span></kbd></td>
9037 </tr>
9038 <tr><td>&nbsp;</td><td>interactively select which chunks to apply</td></tr>
9039 <tr><td class="option-group" colspan="2">
9040 <kbd><span class="option">-e</span>, <span class="option">--edit-lines</span></kbd></td>
9041 </tr>
9042 <tr><td>&nbsp;</td><td>edit what lines belong to which changesets before commit (EXPERIMENTAL)</td></tr>
9043 <tr><td class="option-group">
9044 <kbd><span class="option">-n</span>, <span class="option">--dry-run</span></kbd></td>
9045 <td>do not perform actions, just print output</td></tr>
9046 <tr><td class="option-group" colspan="2">
9047 <kbd><span class="option">--style <var>&lt;STYLE&gt;</var></span></kbd></td>
9048 </tr>
9049 <tr><td>&nbsp;</td><td>display using template map file (DEPRECATED)</td></tr>
9050 <tr><td class="option-group" colspan="2">
9051 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
9052 </tr>
9053 <tr><td>&nbsp;</td><td>display with template</td></tr>
9054 <tr><td class="option-group" colspan="2">
9055 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
9056 </tr>
9057 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
9058 <tr><td class="option-group" colspan="2">
9059 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
9060 </tr>
9061 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
9062 </tbody>
9063 </table>
9064 <p>[+] marked option can be specified multiple times</p>
9065 </div>
9066 </div>
9067 </div>
9068 </div>
9069 <div class="section" id="acl">
9070 <h2><a class="toc-backref" href="#toc-entry-38">acl</a></h2>
9071 <p>hooks for controlling repository access</p>
9072 <p>This hook makes it possible to allow or deny write access to given
9073 branches and paths of a repository when receiving incoming changesets
9074 via pretxnchangegroup and pretxncommit.</p>
9075 <p>The authorization is matched based on the local user name on the
9076 system where the hook runs, and not the committer of the original
9077 changeset (since the latter is merely informative).</p>
9078 <p>The acl hook is best used along with a restricted shell like hgsh,
9079 preventing authenticating users from doing anything other than pushing
9080 or pulling. The hook is not safe to use if users have interactive
9081 shell access, as they can then disable the hook. Nor is it safe if
9082 remote users share an account, because then there is no way to
9083 distinguish them.</p>
9084 <p>The order in which access checks are performed is:</p>
9085 <ol class="arabic simple">
9086 <li>Deny list for branches (section <tt class="docutils literal">acl.deny.branches</tt>)</li>
9087 <li>Allow list for branches (section <tt class="docutils literal">acl.allow.branches</tt>)</li>
9088 <li>Deny list for paths (section <tt class="docutils literal">acl.deny</tt>)</li>
9089 <li>Allow list for paths (section <tt class="docutils literal">acl.allow</tt>)</li>
9090 </ol>
9091 <p>The allow and deny sections take key-value pairs.</p>
9092 <div class="section" id="branch-based-access-control">
9093 <h3>Branch-based Access Control</h3>
9094 <p>Use the <tt class="docutils literal">acl.deny.branches</tt> and <tt class="docutils literal">acl.allow.branches</tt> sections to
9095 have branch-based access control. Keys in these sections can be
9096 either:</p>
9097 <ul class="simple">
9098 <li>a branch name, or</li>
9099 <li>an asterisk, to match any branch;</li>
9100 </ul>
9101 <p>The corresponding values can be either:</p>
9102 <ul class="simple">
9103 <li>a comma-separated list containing users and groups, or</li>
9104 <li>an asterisk, to match anyone;</li>
9105 </ul>
9106 <p>You can add the &quot;!&quot; prefix to a user or group name to invert the sense
9107 of the match.</p>
9108 </div>
9109 <div class="section" id="path-based-access-control">
9110 <h3>Path-based Access Control</h3>
9111 <p>Use the <tt class="docutils literal">acl.deny</tt> and <tt class="docutils literal">acl.allow</tt> sections to have path-based
9112 access control. Keys in these sections accept a subtree pattern (with
9113 a glob syntax by default). The corresponding values follow the same
9114 syntax as the other sections above.</p>
9115 </div>
9116 <div class="section" id="bookmark-based-access-control">
9117 <h3>Bookmark-based Access Control</h3>
9118 <p>Use the <tt class="docutils literal">acl.deny.bookmarks</tt> and <tt class="docutils literal">acl.allow.bookmarks</tt> sections to
9119 have bookmark-based access control. Keys in these sections can be
9120 either:</p>
9121 <ul class="simple">
9122 <li>a bookmark name, or</li>
9123 <li>an asterisk, to match any bookmark;</li>
9124 </ul>
9125 <p>The corresponding values can be either:</p>
9126 <ul class="simple">
9127 <li>a comma-separated list containing users and groups, or</li>
9128 <li>an asterisk, to match anyone;</li>
9129 </ul>
9130 <p>You can add the &quot;!&quot; prefix to a user or group name to invert the sense
9131 of the match.</p>
9132 <p>Note: for interactions between clients and servers using Mercurial 3.6+
9133 a rejection will generally reject the entire push, for interactions
9134 involving older clients, the commit transactions will already be accepted,
9135 and only the bookmark movement will be rejected.</p>
9136 </div>
9137 <div class="section" id="groups">
9138 <h3>Groups</h3>
9139 <p>Group names must be prefixed with an <tt class="docutils literal">&#64;</tt> symbol. Specifying a group
9140 name has the same effect as specifying all the users in that group.</p>
9141 <p>You can define group members in the <tt class="docutils literal">acl.groups</tt> section.
9142 If a group name is not defined there, and Mercurial is running under
9143 a Unix-like system, the list of users will be taken from the OS.
9144 Otherwise, an exception will be raised.</p>
9145 </div>
9146 <div class="section" id="example-configuration">
9147 <h3>Example Configuration</h3>
9148 <pre class="literal-block">
9149 [hooks]
9150
9151 # Use this if you want to check access restrictions at commit time
9152 pretxncommit.acl = python:hgext.acl.hook
9153
9154 # Use this if you want to check access restrictions for pull, push,
9155 # bundle and serve.
9156 pretxnchangegroup.acl = python:hgext.acl.hook
9157
9158 [acl]
9159 # Allow or deny access for incoming changes only if their source is
9160 # listed here, let them pass otherwise. Source is &quot;serve&quot; for all
9161 # remote access (http or ssh), &quot;push&quot;, &quot;pull&quot; or &quot;bundle&quot; when the
9162 # related commands are run locally.
9163 # Default: serve
9164 sources = serve
9165
9166 [acl.deny.branches]
9167
9168 # Everyone is denied to the frozen branch:
9169 frozen-branch = *
9170
9171 # A bad user is denied on all branches:
9172 * = bad-user
9173
9174 [acl.allow.branches]
9175
9176 # A few users are allowed on branch-a:
9177 branch-a = user-1, user-2, user-3
9178
9179 # Only one user is allowed on branch-b:
9180 branch-b = user-1
9181
9182 # The super user is allowed on any branch:
9183 * = super-user
9184
9185 # Everyone is allowed on branch-for-tests:
9186 branch-for-tests = *
9187
9188 [acl.deny]
9189 # This list is checked first. If a match is found, acl.allow is not
9190 # checked. All users are granted access if acl.deny is not present.
9191 # Format for both lists: glob pattern = user, ..., &#64;group, ...
9192
9193 # To match everyone, use an asterisk for the user:
9194 # my/glob/pattern = *
9195
9196 # user6 will not have write access to any file:
9197 ** = user6
9198
9199 # Group &quot;hg-denied&quot; will not have write access to any file:
9200 ** = &#64;hg-denied
9201
9202 # Nobody will be able to change &quot;DONT-TOUCH-THIS.txt&quot;, despite
9203 # everyone being able to change all other files. See below.
9204 src/main/resources/DONT-TOUCH-THIS.txt = *
9205
9206 [acl.allow]
9207 # if acl.allow is not present, all users are allowed by default
9208 # empty acl.allow = no users allowed
9209
9210 # User &quot;doc_writer&quot; has write access to any file under the &quot;docs&quot;
9211 # folder:
9212 docs/** = doc_writer
9213
9214 # User &quot;jack&quot; and group &quot;designers&quot; have write access to any file
9215 # under the &quot;images&quot; folder:
9216 images/** = jack, &#64;designers
9217
9218 # Everyone (except for &quot;user6&quot; and &quot;&#64;hg-denied&quot; - see acl.deny above)
9219 # will have write access to any file under the &quot;resources&quot; folder
9220 # (except for 1 file. See acl.deny):
9221 src/main/resources/** = *
9222
9223 .hgtags = release_engineer
9224 </pre>
9225 <div class="section" id="examples-using-the-prefix">
9226 <h4>Examples using the &quot;!&quot; prefix</h4>
9227 <p>Suppose there's a branch that only a given user (or group) should be able to
9228 push to, and you don't want to restrict access to any other branch that may
9229 be created.</p>
9230 <p>The &quot;!&quot; prefix allows you to prevent anyone except a given user or group to
9231 push changesets in a given branch or path.</p>
9232 <p>In the examples below, we will:
9233 1) Deny access to branch &quot;ring&quot; to anyone but user &quot;gollum&quot;
9234 2) Deny access to branch &quot;lake&quot; to anyone but members of the group &quot;hobbit&quot;
9235 3) Deny access to a file to anyone but user &quot;gollum&quot;</p>
9236 <pre class="literal-block">
9237 [acl.allow.branches]
9238 # Empty
9239
9240 [acl.deny.branches]
9241
9242 # 1) only 'gollum' can commit to branch 'ring';
9243 # 'gollum' and anyone else can still commit to any other branch.
9244 ring = !gollum
9245
9246 # 2) only members of the group 'hobbit' can commit to branch 'lake';
9247 # 'hobbit' members and anyone else can still commit to any other branch.
9248 lake = !&#64;hobbit
9249
9250 # You can also deny access based on file paths:
9251
9252 [acl.allow]
9253 # Empty
9254
9255 [acl.deny]
9256 # 3) only 'gollum' can change the file below;
9257 # 'gollum' and anyone else can still change any other file.
9258 /misty/mountains/cave/ring = !gollum
9259 </pre>
9260 </div>
9261 </div>
9262 </div>
9263 <div class="section" id="amend">
9264 <h2><a class="toc-backref" href="#toc-entry-39">amend</a></h2>
9265 <p>provide the amend command (EXPERIMENTAL)</p>
9266 <p>This extension provides an <tt class="docutils literal">amend</tt> command that is similar to
9267 <tt class="docutils literal">commit <span class="pre">--amend</span></tt> but does not prompt an editor.</p>
9268 <div class="section" id="commands-3">
9269 <h3>Commands</h3>
9270 <div class="section" id="change-creation-2">
9271 <h4>Change creation</h4>
9272 <div class="section" id="amend-1">
9273 <h5>amend</h5>
9274 <p>amend the working copy parent with all or specified outstanding changes:</p>
9275 <pre class="literal-block">
9276 hg amend [OPTION]... [FILE]...
9277 </pre>
9278 <p>Similar to <a class="reference external" href="hg.1.html#commit"><tt class="docutils literal">hg commit <span class="pre">--amend</span></tt></a>, but reuse the commit message without
9279 invoking editor, unless <tt class="docutils literal"><span class="pre">--edit</span></tt> was set.</p>
9280 <p>See <a class="reference external" href="hg.1.html#commit"><tt class="docutils literal">hg help commit</tt></a> for more details.</p>
9281 <p>Options:</p>
9282 <table class="docutils option-list" frame="void" rules="none">
9283 <col class="option" />
9284 <col class="description" />
9285 <tbody valign="top">
9286 <tr><td class="option-group" colspan="2">
9287 <kbd><span class="option">-A</span>, <span class="option">--addremove</span></kbd></td>
9288 </tr>
9289 <tr><td>&nbsp;</td><td>mark new/missing files as added/removed before committing</td></tr>
9290 <tr><td class="option-group">
9291 <kbd><span class="option">-e</span>, <span class="option">--edit</span></kbd></td>
9292 <td>invoke editor on commit messages</td></tr>
9293 <tr><td class="option-group" colspan="2">
9294 <kbd><span class="option">-i</span>, <span class="option">--interactive</span></kbd></td>
9295 </tr>
9296 <tr><td>&nbsp;</td><td>use interactive mode</td></tr>
9297 <tr><td class="option-group">
9298 <kbd><span class="option">--close-branch</span></kbd></td>
9299 <td>mark a branch as closed, hiding it from the branch list</td></tr>
9300 <tr><td class="option-group">
9301 <kbd><span class="option">-s</span>, <span class="option">--secret</span></kbd></td>
9302 <td>use the secret phase for committing</td></tr>
9303 <tr><td class="option-group">
9304 <kbd><span class="option">--draft</span></kbd></td>
9305 <td>use the draft phase for committing</td></tr>
9306 <tr><td class="option-group" colspan="2">
9307 <kbd><span class="option">-n</span>, <span class="option">--note <var>&lt;VALUE&gt;</var></span></kbd></td>
9308 </tr>
9309 <tr><td>&nbsp;</td><td>store a note on the amend</td></tr>
9310 <tr><td class="option-group" colspan="2">
9311 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
9312 </tr>
9313 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
9314 <tr><td class="option-group" colspan="2">
9315 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
9316 </tr>
9317 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
9318 <tr><td class="option-group" colspan="2">
9319 <kbd><span class="option">-m</span>, <span class="option">--message <var>&lt;TEXT&gt;</var></span></kbd></td>
9320 </tr>
9321 <tr><td>&nbsp;</td><td>use text as commit message</td></tr>
9322 <tr><td class="option-group" colspan="2">
9323 <kbd><span class="option">-l</span>, <span class="option">--logfile <var>&lt;FILE&gt;</var></span></kbd></td>
9324 </tr>
9325 <tr><td>&nbsp;</td><td>read commit message from file</td></tr>
9326 <tr><td class="option-group" colspan="2">
9327 <kbd><span class="option">-d</span>, <span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
9328 </tr>
9329 <tr><td>&nbsp;</td><td>record the specified date as commit date</td></tr>
9330 <tr><td class="option-group" colspan="2">
9331 <kbd><span class="option">-u</span>, <span class="option">--user <var>&lt;USER&gt;</var></span></kbd></td>
9332 </tr>
9333 <tr><td>&nbsp;</td><td>record the specified user as committer</td></tr>
9334 <tr><td class="option-group" colspan="2">
9335 <kbd><span class="option">-D</span>, <span class="option">--currentdate</span></kbd></td>
9336 </tr>
9337 <tr><td>&nbsp;</td><td>record the current date as commit date</td></tr>
9338 <tr><td class="option-group" colspan="2">
9339 <kbd><span class="option">-U</span>, <span class="option">--currentuser</span></kbd></td>
9340 </tr>
9341 <tr><td>&nbsp;</td><td>record the current user as committer</td></tr>
9342 </tbody>
9343 </table>
9344 <p>[+] marked option can be specified multiple times</p>
9345 </div>
9346 </div>
9347 </div>
9348 </div>
9349 <div class="section" id="automv">
9350 <h2><a class="toc-backref" href="#toc-entry-40">automv</a></h2>
9351 <p>check for unrecorded moves at commit time (EXPERIMENTAL)</p>
9352 <p>This extension checks at commit/amend time if any of the committed files
9353 comes from an unrecorded mv.</p>
9354 <p>The threshold at which a file is considered a move can be set with the
9355 <tt class="docutils literal">automv.similarity</tt> config option. This option takes a percentage between 0
9356 (disabled) and 100 (files must be identical), the default is 95.</p>
9357 </div>
9358 <div class="section" id="beautifygraph">
9359 <h2><a class="toc-backref" href="#toc-entry-41">beautifygraph</a></h2>
9360 <p>beautify log -G output by using Unicode characters (EXPERIMENTAL)</p>
9361 <p>A terminal with UTF-8 support and monospace narrow text are required.</p>
9362 </div>
9363 <div class="section" id="blackbox">
9364 <h2><a class="toc-backref" href="#toc-entry-42">blackbox</a></h2>
9365 <p>log repository events to a blackbox for debugging</p>
9366 <p>Logs event information to .hg/blackbox.log to help debug and diagnose problems.
9367 The events that get logged can be configured via the blackbox.track and
9368 blackbox.ignore config keys.</p>
9369 <p>Examples:</p>
9370 <pre class="literal-block">
9371 [blackbox]
9372 track = *
9373 ignore = pythonhook
9374 # dirty is *EXPENSIVE* (slow);
9375 # each log entry indicates `+` if the repository is dirty, like :hg:`id`.
9376 dirty = True
9377 # record the source of log messages
9378 logsource = True
9379
9380 [blackbox]
9381 track = command, commandfinish, commandexception, exthook, pythonhook
9382
9383 [blackbox]
9384 track = incoming
9385
9386 [blackbox]
9387 # limit the size of a log file
9388 maxsize = 1.5 MB
9389 # rotate up to N log files when the current one gets too big
9390 maxfiles = 3
9391
9392 [blackbox]
9393 # Include microseconds in log entries with %f (see Python function
9394 # datetime.datetime.strftime)
9395 date-format = %Y-%m-%d &#64; %H:%M:%S.%f
9396 </pre>
9397 <div class="section" id="commands-4">
9398 <h3>Commands</h3>
9399 <div class="section" id="repository-maintenance-1">
9400 <h4>Repository maintenance</h4>
9401 <div class="section" id="blackbox-1">
9402 <h5>blackbox</h5>
9403 <p>view the recent repository events:</p>
9404 <pre class="literal-block">
9405 hg blackbox [OPTION]...
9406 </pre>
9407 <p>view the recent repository events</p>
9408 <p>Options:</p>
9409 <table class="docutils option-list" frame="void" rules="none">
9410 <col class="option" />
9411 <col class="description" />
9412 <tbody valign="top">
9413 <tr><td class="option-group" colspan="2">
9414 <kbd><span class="option">-l</span>, <span class="option">--limit <var>&lt;VALUE&gt;</var></span></kbd></td>
9415 </tr>
9416 <tr><td>&nbsp;</td><td>the number of events to show (default: 10)</td></tr>
9417 </tbody>
9418 </table>
9419 </div>
9420 </div>
9421 </div>
9422 </div>
9423 <div class="section" id="bookflow">
9424 <h2><a class="toc-backref" href="#toc-entry-43">bookflow</a></h2>
9425 <p>implements bookmark-based branching (EXPERIMENTAL)</p>
9426 <ul class="simple">
9427 <li>Disables creation of new branches (config: enable_branches=False).</li>
9428 <li>Requires an active bookmark on commit (config: require_bookmark=True).</li>
9429 <li>Doesn't move the active bookmark on update, only on commit.</li>
9430 <li>Requires '--rev' for moving an existing bookmark.</li>
9431 <li>Protects special bookmarks (config: protect=&#64;).</li>
9432 </ul>
9433 <p>flow related commands</p>
9434 <blockquote>
9435 <table class="docutils field-list" frame="void" rules="none">
9436 <col class="field-name" />
9437 <col class="field-body" />
9438 <tbody valign="top">
9439 <tr class="field"><th class="field-name">hg book NAME:</th><td class="field-body">create a new bookmark</td>
9440 </tr>
9441 <tr class="field"><th class="field-name" colspan="2">hg book NAME -r REV:</th></tr>
9442 <tr class="field"><td>&nbsp;</td><td class="field-body">move bookmark to revision (fast-forward)</td>
9443 </tr>
9444 <tr class="field"><th class="field-name">hg up|co NAME:</th><td class="field-body">switch to bookmark</td>
9445 </tr>
9446 <tr class="field"><th class="field-name">hg push -B .:</th><td class="field-body">push active bookmark</td>
9447 </tr>
9448 </tbody>
9449 </table>
9450 </blockquote>
9451 </div>
9452 <div class="section" id="bugzilla">
9453 <h2><a class="toc-backref" href="#toc-entry-44">bugzilla</a></h2>
9454 <p>hooks for integrating with the Bugzilla bug tracker</p>
9455 <p>This hook extension adds comments on bugs in Bugzilla when changesets
9456 that refer to bugs by Bugzilla ID are seen. The comment is formatted using
9457 the Mercurial template mechanism.</p>
9458 <p>The bug references can optionally include an update for Bugzilla of the
9459 hours spent working on the bug. Bugs can also be marked fixed.</p>
9460 <p>Four basic modes of access to Bugzilla are provided:</p>
9461 <ol class="arabic simple">
9462 <li>Access via the Bugzilla REST-API. Requires bugzilla 5.0 or later.</li>
9463 <li>Access via the Bugzilla XMLRPC interface. Requires Bugzilla 3.4 or later.</li>
9464 <li>Check data via the Bugzilla XMLRPC interface and submit bug change
9465 via email to Bugzilla email interface. Requires Bugzilla 3.4 or later.</li>
9466 <li>Writing directly to the Bugzilla database. Only Bugzilla installations
9467 using MySQL are supported. Requires Python MySQLdb.</li>
9468 </ol>
9469 <p>Writing directly to the database is susceptible to schema changes, and
9470 relies on a Bugzilla contrib script to send out bug change
9471 notification emails. This script runs as the user running Mercurial,
9472 must be run on the host with the Bugzilla install, and requires
9473 permission to read Bugzilla configuration details and the necessary
9474 MySQL user and password to have full access rights to the Bugzilla
9475 database. For these reasons this access mode is now considered
9476 deprecated, and will not be updated for new Bugzilla versions going
9477 forward. Only adding comments is supported in this access mode.</p>
9478 <p>Access via XMLRPC needs a Bugzilla username and password to be specified
9479 in the configuration. Comments are added under that username. Since the
9480 configuration must be readable by all Mercurial users, it is recommended
9481 that the rights of that user are restricted in Bugzilla to the minimum
9482 necessary to add comments. Marking bugs fixed requires Bugzilla 4.0 and later.</p>
9483 <p>Access via XMLRPC/email uses XMLRPC to query Bugzilla, but sends
9484 email to the Bugzilla email interface to submit comments to bugs.
9485 The From: address in the email is set to the email address of the Mercurial
9486 user, so the comment appears to come from the Mercurial user. In the event
9487 that the Mercurial user email is not recognized by Bugzilla as a Bugzilla
9488 user, the email associated with the Bugzilla username used to log into
9489 Bugzilla is used instead as the source of the comment. Marking bugs fixed
9490 works on all supported Bugzilla versions.</p>
9491 <p>Access via the REST-API needs either a Bugzilla username and password
9492 or an apikey specified in the configuration. Comments are made under
9493 the given username or the user associated with the apikey in Bugzilla.</p>
9494 <p>Configuration items common to all access modes:</p>
9495 <dl class="docutils">
9496 <dt>bugzilla.version</dt>
9497 <dd><p class="first">The access type to use. Values recognized are:</p>
9498 <table class="last docutils field-list" frame="void" rules="none">
9499 <col class="field-name" />
9500 <col class="field-body" />
9501 <tbody valign="top">
9502 <tr class="field"><th class="field-name"><tt class="docutils literal">restapi</tt>:</th><td class="field-body">Bugzilla REST-API, Bugzilla 5.0 and later.</td>
9503 </tr>
9504 <tr class="field"><th class="field-name"><tt class="docutils literal">xmlrpc</tt>:</th><td class="field-body">Bugzilla XMLRPC interface.</td>
9505 </tr>
9506 <tr class="field"><th class="field-name"><tt class="docutils literal">xmlrpc+email</tt>:</th><td class="field-body">Bugzilla XMLRPC and email interfaces.</td>
9507 </tr>
9508 <tr class="field"><th class="field-name"><tt class="docutils literal">3.0</tt>:</th><td class="field-body">MySQL access, Bugzilla 3.0 and later.</td>
9509 </tr>
9510 <tr class="field"><th class="field-name"><tt class="docutils literal">2.18</tt>:</th><td class="field-body">MySQL access, Bugzilla 2.18 and up to but not
9511 including 3.0.</td>
9512 </tr>
9513 <tr class="field"><th class="field-name"><tt class="docutils literal">2.16</tt>:</th><td class="field-body">MySQL access, Bugzilla 2.16 and up to but not
9514 including 2.18.</td>
9515 </tr>
9516 </tbody>
9517 </table>
9518 </dd>
9519 <dt>bugzilla.regexp</dt>
9520 <dd>Regular expression to match bug IDs for update in changeset commit message.
9521 It must contain one &quot;()&quot; named group <tt class="docutils literal">&lt;ids&gt;</tt> containing the bug
9522 IDs separated by non-digit characters. It may also contain
9523 a named group <tt class="docutils literal">&lt;hours&gt;</tt> with a floating-point number giving the
9524 hours worked on the bug. If no named groups are present, the first
9525 &quot;()&quot; group is assumed to contain the bug IDs, and work time is not
9526 updated. The default expression matches <tt class="docutils literal">Bug 1234</tt>, <tt class="docutils literal">Bug no. 1234</tt>,
9527 <tt class="docutils literal">Bug number 1234</tt>, <tt class="docutils literal">Bugs 1234,5678</tt>, <tt class="docutils literal">Bug 1234 and 5678</tt> and
9528 variations thereof, followed by an hours number prefixed by <tt class="docutils literal">h</tt> or
9529 <tt class="docutils literal">hours</tt>, e.g. <tt class="docutils literal">hours 1.5</tt>. Matching is case insensitive.</dd>
9530 <dt>bugzilla.fixregexp</dt>
9531 <dd>Regular expression to match bug IDs for marking fixed in changeset
9532 commit message. This must contain a &quot;()&quot; named group <tt class="docutils literal">&lt;ids&gt;` containing
9533 the bug IDs separated by <span class="pre">non-digit</span> characters. It may also contain
9534 a named group <span class="pre">``&lt;hours&gt;</span></tt> with a floating-point number giving the
9535 hours worked on the bug. If no named groups are present, the first
9536 &quot;()&quot; group is assumed to contain the bug IDs, and work time is not
9537 updated. The default expression matches <tt class="docutils literal">Fixes 1234</tt>, <tt class="docutils literal">Fixes bug 1234</tt>,
9538 <tt class="docutils literal">Fixes bugs 1234,5678</tt>, <tt class="docutils literal">Fixes 1234 and 5678</tt> and
9539 variations thereof, followed by an hours number prefixed by <tt class="docutils literal">h</tt> or
9540 <tt class="docutils literal">hours</tt>, e.g. <tt class="docutils literal">hours 1.5</tt>. Matching is case insensitive.</dd>
9541 <dt>bugzilla.fixstatus</dt>
9542 <dd>The status to set a bug to when marking fixed. Default <tt class="docutils literal">RESOLVED</tt>.</dd>
9543 <dt>bugzilla.fixresolution</dt>
9544 <dd>The resolution to set a bug to when marking fixed. Default <tt class="docutils literal">FIXED</tt>.</dd>
9545 <dt>bugzilla.style</dt>
9546 <dd>The style file to use when formatting comments.</dd>
9547 <dt>bugzilla.template</dt>
9548 <dd><p class="first">Template to use when formatting comments. Overrides style if
9549 specified. In addition to the usual Mercurial keywords, the
9550 extension specifies:</p>
9551 <table class="docutils field-list" frame="void" rules="none">
9552 <col class="field-name" />
9553 <col class="field-body" />
9554 <tbody valign="top">
9555 <tr class="field"><th class="field-name"><tt class="docutils literal">{bug}</tt>:</th><td class="field-body">The Bugzilla bug ID.</td>
9556 </tr>
9557 <tr class="field"><th class="field-name"><tt class="docutils literal">{root}</tt>:</th><td class="field-body">The full pathname of the Mercurial repository.</td>
9558 </tr>
9559 <tr class="field"><th class="field-name"><tt class="docutils literal">{webroot}</tt>:</th><td class="field-body">Stripped pathname of the Mercurial repository.</td>
9560 </tr>
9561 <tr class="field"><th class="field-name"><tt class="docutils literal">{hgweb}</tt>:</th><td class="field-body">Base URL for browsing Mercurial repositories.</td>
9562 </tr>
9563 </tbody>
9564 </table>
9565 <p class="last">Default <tt class="docutils literal">changeset {node|short} in repo {root} refers to bug
9566 <span class="pre">{bug}.\ndetails:\n\t{desc|tabindent}</span></tt></p>
9567 </dd>
9568 <dt>bugzilla.strip</dt>
9569 <dd>The number of path separator characters to strip from the front of
9570 the Mercurial repository path (<tt class="docutils literal">{root}</tt> in templates) to produce
9571 <tt class="docutils literal">{webroot}</tt>. For example, a repository with <tt class="docutils literal">{root}</tt>
9572 <tt class="docutils literal"><span class="pre">/var/local/my-project</span></tt> with a strip of 2 gives a value for
9573 <tt class="docutils literal">{webroot}</tt> of <tt class="docutils literal"><span class="pre">my-project</span></tt>. Default 0.</dd>
9574 <dt>web.baseurl</dt>
9575 <dd>Base URL for browsing Mercurial repositories. Referenced from
9576 templates as <tt class="docutils literal">{hgweb}</tt>.</dd>
9577 </dl>
9578 <p>Configuration items common to XMLRPC+email and MySQL access modes:</p>
9579 <dl class="docutils">
9580 <dt>bugzilla.usermap</dt>
9581 <dd><p class="first">Path of file containing Mercurial committer email to Bugzilla user email
9582 mappings. If specified, the file should contain one mapping per
9583 line:</p>
9584 <pre class="literal-block">
9585 committer = Bugzilla user
9586 </pre>
9587 <p class="last">See also the <tt class="docutils literal">[usermap]</tt> section.</p>
9588 </dd>
9589 </dl>
9590 <p>The <tt class="docutils literal">[usermap]</tt> section is used to specify mappings of Mercurial
9591 committer email to Bugzilla user email. See also <tt class="docutils literal">bugzilla.usermap</tt>.
9592 Contains entries of the form <tt class="docutils literal">committer = Bugzilla user</tt>.</p>
9593 <p>XMLRPC and REST-API access mode configuration:</p>
9594 <dl class="docutils">
9595 <dt>bugzilla.bzurl</dt>
9596 <dd>The base URL for the Bugzilla installation.
9597 Default <tt class="docutils literal"><span class="pre">http://localhost/bugzilla</span></tt>.</dd>
9598 <dt>bugzilla.user</dt>
9599 <dd>The username to use to log into Bugzilla via XMLRPC. Default
9600 <tt class="docutils literal">bugs</tt>.</dd>
9601 <dt>bugzilla.password</dt>
9602 <dd>The password for Bugzilla login.</dd>
9603 </dl>
9604 <p>REST-API access mode uses the options listed above as well as:</p>
9605 <dl class="docutils">
9606 <dt>bugzilla.apikey</dt>
9607 <dd>An apikey generated on the Bugzilla instance for api access.
9608 Using an apikey removes the need to store the user and password
9609 options.</dd>
9610 </dl>
9611 <p>XMLRPC+email access mode uses the XMLRPC access mode configuration items,
9612 and also:</p>
9613 <dl class="docutils">
9614 <dt>bugzilla.bzemail</dt>
9615 <dd>The Bugzilla email address.</dd>
9616 </dl>
9617 <p>In addition, the Mercurial email settings must be configured. See the
9618 documentation in hgrc(5), sections <tt class="docutils literal">[email]</tt> and <tt class="docutils literal">[smtp]</tt>.</p>
9619 <p>MySQL access mode configuration:</p>
9620 <dl class="docutils">
9621 <dt>bugzilla.host</dt>
9622 <dd>Hostname of the MySQL server holding the Bugzilla database.
9623 Default <tt class="docutils literal">localhost</tt>.</dd>
9624 <dt>bugzilla.db</dt>
9625 <dd>Name of the Bugzilla database in MySQL. Default <tt class="docutils literal">bugs</tt>.</dd>
9626 <dt>bugzilla.user</dt>
9627 <dd>Username to use to access MySQL server. Default <tt class="docutils literal">bugs</tt>.</dd>
9628 <dt>bugzilla.password</dt>
9629 <dd>Password to use to access MySQL server.</dd>
9630 <dt>bugzilla.timeout</dt>
9631 <dd>Database connection timeout (seconds). Default 5.</dd>
9632 <dt>bugzilla.bzuser</dt>
9633 <dd>Fallback Bugzilla user name to record comments with, if changeset
9634 committer cannot be found as a Bugzilla user.</dd>
9635 <dt>bugzilla.bzdir</dt>
9636 <dd>Bugzilla install directory. Used by default notify. Default
9637 <tt class="docutils literal">/var/www/html/bugzilla</tt>.</dd>
9638 <dt>bugzilla.notify</dt>
9639 <dd>The command to run to get Bugzilla to send bug change notification
9640 emails. Substitutes from a map with 3 keys, <tt class="docutils literal">bzdir</tt>, <tt class="docutils literal">id</tt> (bug
9641 id) and <tt class="docutils literal">user</tt> (committer bugzilla email). Default depends on
9642 version; from 2.18 it is &quot;cd %(bzdir)s &amp;&amp; perl -T
9643 contrib/sendbugmail.pl %(id)s %(user)s&quot;.</dd>
9644 </dl>
9645 <p>Activating the extension:</p>
9646 <pre class="literal-block">
9647 [extensions]
9648 bugzilla =
9649
9650 [hooks]
9651 # run bugzilla hook on every change pulled or pushed in here
9652 incoming.bugzilla = python:hgext.bugzilla.hook
9653 </pre>
9654 <p>Example configurations:</p>
9655 <p>XMLRPC example configuration. This uses the Bugzilla at
9656 <tt class="docutils literal"><span class="pre">http://my-project.org/bugzilla</span></tt>, logging in as user
9657 <tt class="docutils literal"><span class="pre">bugmail&#64;my-project.org</span></tt> with password <tt class="docutils literal">plugh</tt>. It is used with a
9658 collection of Mercurial repositories in <tt class="docutils literal">/var/local/hg/repos/</tt>,
9659 with a web interface at <tt class="docutils literal"><span class="pre">http://my-project.org/hg</span></tt>.</p>
9660 <pre class="literal-block">
9661 [bugzilla]
9662 bzurl=http://my-project.org/bugzilla
9663 user=bugmail&#64;my-project.org
9664 password=plugh
9665 version=xmlrpc
9666 template=Changeset {node|short} in {root|basename}.
9667 {hgweb}/{webroot}/rev/{node|short}\n
9668 {desc}\n
9669 strip=5
9670
9671 [web]
9672 baseurl=http://my-project.org/hg
9673 </pre>
9674 <p>XMLRPC+email example configuration. This uses the Bugzilla at
9675 <tt class="docutils literal"><span class="pre">http://my-project.org/bugzilla</span></tt>, logging in as user
9676 <tt class="docutils literal"><span class="pre">bugmail&#64;my-project.org</span></tt> with password <tt class="docutils literal">plugh</tt>. It is used with a
9677 collection of Mercurial repositories in <tt class="docutils literal">/var/local/hg/repos/</tt>,
9678 with a web interface at <tt class="docutils literal"><span class="pre">http://my-project.org/hg</span></tt>. Bug comments
9679 are sent to the Bugzilla email address
9680 <tt class="docutils literal"><span class="pre">bugzilla&#64;my-project.org</span></tt>.</p>
9681 <pre class="literal-block">
9682 [bugzilla]
9683 bzurl=http://my-project.org/bugzilla
9684 user=bugmail&#64;my-project.org
9685 password=plugh
9686 version=xmlrpc+email
9687 bzemail=bugzilla&#64;my-project.org
9688 template=Changeset {node|short} in {root|basename}.
9689 {hgweb}/{webroot}/rev/{node|short}\n
9690 {desc}\n
9691 strip=5
9692
9693 [web]
9694 baseurl=http://my-project.org/hg
9695
9696 [usermap]
9697 user&#64;emaildomain.com=user.name&#64;bugzilladomain.com
9698 </pre>
9699 <p>MySQL example configuration. This has a local Bugzilla 3.2 installation
9700 in <tt class="docutils literal"><span class="pre">/opt/bugzilla-3.2</span></tt>. The MySQL database is on <tt class="docutils literal">localhost</tt>,
9701 the Bugzilla database name is <tt class="docutils literal">bugs</tt> and MySQL is
9702 accessed with MySQL username <tt class="docutils literal">bugs</tt> password <tt class="docutils literal">XYZZY</tt>. It is used
9703 with a collection of Mercurial repositories in <tt class="docutils literal">/var/local/hg/repos/</tt>,
9704 with a web interface at <tt class="docutils literal"><span class="pre">http://my-project.org/hg</span></tt>.</p>
9705 <pre class="literal-block">
9706 [bugzilla]
9707 host=localhost
9708 password=XYZZY
9709 version=3.0
9710 bzuser=unknown&#64;domain.com
9711 bzdir=/opt/bugzilla-3.2
9712 template=Changeset {node|short} in {root|basename}.
9713 {hgweb}/{webroot}/rev/{node|short}\n
9714 {desc}\n
9715 strip=5
9716
9717 [web]
9718 baseurl=http://my-project.org/hg
9719
9720 [usermap]
9721 user&#64;emaildomain.com=user.name&#64;bugzilladomain.com
9722 </pre>
9723 <p>All the above add a comment to the Bugzilla bug record of the form:</p>
9724 <pre class="literal-block">
9725 Changeset 3b16791d6642 in repository-name.
9726 http://my-project.org/hg/repository-name/rev/3b16791d6642
9727
9728 Changeset commit comment. Bug 1234.
9729 </pre>
9730 </div>
9731 <div class="section" id="censor">
9732 <h2><a class="toc-backref" href="#toc-entry-45">censor</a></h2>
9733 <p>erase file content at a given revision</p>
9734 <p>The censor command instructs Mercurial to erase all content of a file at a given
9735 revision <em>without updating the changeset hash.</em> This allows existing history to
9736 remain valid while preventing future clones/pulls from receiving the erased
9737 data.</p>
9738 <p>Typical uses for censor are due to security or legal requirements, including:</p>
9739 <pre class="literal-block">
9740 * Passwords, private keys, cryptographic material
9741 * Licensed data/code/libraries for which the license has expired
9742 * Personally Identifiable Information or other private data
9743 </pre>
9744 <p>Censored nodes can interrupt mercurial's typical operation whenever the excised
9745 data needs to be materialized. Some commands, like <tt class="docutils literal">hg cat</tt>/<tt class="docutils literal">hg revert</tt>,
9746 simply fail when asked to produce censored data. Others, like <tt class="docutils literal">hg verify</tt> and
9747 <tt class="docutils literal">hg update</tt>, must be capable of tolerating censored data to continue to
9748 function in a meaningful way. Such commands only tolerate censored file
9749 As having a censored version in a checkout is impractical. The current head
9750 revisions of the repository are checked. If the revision to be censored is in
9751 any of them the command will abort. You can configure this behavior using the
9752 following option:</p>
9753 <blockquote>
9754 <dl class="docutils">
9755 <dt><cite>censor.policy</cite></dt>
9756 <dd><p class="first">Control how to react when accessing censored content.
9757 Accepted value: &quot;abort&quot;, &quot;ignore&quot;. Defaults to abort.</p>
9758 <p class="last">A few informative commands such as <tt class="docutils literal">hg grep</tt> will unconditionally ignore
9759 censored data and merely report that it was encountered.</p>
9760 </dd>
9761 </dl>
9762 </blockquote>
9763 <div class="section" id="commands-5">
9764 <h3>Commands</h3>
9765 <div class="section" id="repository-maintenance-2">
9766 <h4>Repository maintenance</h4>
9767 <div class="section" id="censor-1">
9768 <h5>censor</h5>
9769 <pre class="literal-block">
9770 hg censor -r REV [-t TEXT] [FILE]
9771 </pre>
9772 <p>Options:</p>
9773 <table class="docutils option-list" frame="void" rules="none">
9774 <col class="option" />
9775 <col class="description" />
9776 <tbody valign="top">
9777 <tr><td class="option-group" colspan="2">
9778 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
9779 </tr>
9780 <tr><td>&nbsp;</td><td>censor file from specified revision</td></tr>
9781 <tr><td class="option-group">
9782 <kbd><span class="option">--check-heads</span></kbd></td>
9783 <td>check that repository heads are not affected (default: True)</td></tr>
9784 <tr><td class="option-group" colspan="2">
9785 <kbd><span class="option">-t</span>, <span class="option">--tombstone <var>&lt;TEXT&gt;</var></span></kbd></td>
9786 </tr>
9787 <tr><td>&nbsp;</td><td>replacement tombstone data</td></tr>
9788 </tbody>
9789 </table>
9790 <p>[+] marked option can be specified multiple times</p>
9791 </div>
9792 </div>
9793 </div>
9794 </div>
9795 <div class="section" id="children">
9796 <h2><a class="toc-backref" href="#toc-entry-46">children</a></h2>
9797 <p>command to display child changesets (DEPRECATED)</p>
9798 <p>This extension is deprecated. You should use <a class="reference external" href="hg.1.html#log"><tt class="docutils literal">hg log <span class="pre">-r</span>
9799 &quot;children(REV)&quot;</tt></a> instead.</p>
9800 <div class="section" id="commands-6">
9801 <h3>Commands</h3>
9802 <div class="section" id="change-navigation-1">
9803 <h4>Change navigation</h4>
9804 <div class="section" id="children-1">
9805 <h5>children</h5>
9806 <p>show the children of the given or working directory revision:</p>
9807 <pre class="literal-block">
9808 hg children [-r REV] [FILE]
9809 </pre>
9810 <p>Print the children of the working directory's revisions. If a
9811 revision is given via -r/--rev, the children of that revision will
9812 be printed. If a file argument is given, revision in which the
9813 file was last changed (after the working directory revision or the
9814 argument to --rev if given) is printed.</p>
9815 <p>Please use <a class="reference external" href="hg.1.html#log"><tt class="docutils literal">hg log</tt></a> instead:</p>
9816 <pre class="literal-block">
9817 hg children =&gt; hg log -r &quot;children(.)&quot;
9818 hg children -r REV =&gt; hg log -r &quot;children(REV)&quot;
9819 </pre>
9820 <p>See <a class="reference external" href="hg.1.html#log"><tt class="docutils literal">hg help log</tt></a> and <a class="reference external" href="hg.1.html#revsets.children"><tt class="docutils literal">hg help revsets.children</tt></a>.</p>
9821 <p>Options:</p>
9822 <table class="docutils option-list" frame="void" rules="none">
9823 <col class="option" />
9824 <col class="description" />
9825 <tbody valign="top">
9826 <tr><td class="option-group" colspan="2">
9827 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV&gt;</var></span></kbd></td>
9828 </tr>
9829 <tr><td>&nbsp;</td><td>show children of the specified revision (default: .)</td></tr>
9830 <tr><td class="option-group" colspan="2">
9831 <kbd><span class="option">--style <var>&lt;STYLE&gt;</var></span></kbd></td>
9832 </tr>
9833 <tr><td>&nbsp;</td><td>display using template map file (DEPRECATED)</td></tr>
9834 <tr><td class="option-group" colspan="2">
9835 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
9836 </tr>
9837 <tr><td>&nbsp;</td><td>display with template</td></tr>
9838 </tbody>
9839 </table>
9840 </div>
9841 </div>
9842 </div>
9843 </div>
9844 <div class="section" id="churn">
9845 <h2><a class="toc-backref" href="#toc-entry-47">churn</a></h2>
9846 <p>command to display statistics about repository history</p>
9847 <div class="section" id="commands-7">
9848 <h3>Commands</h3>
9849 <div class="section" id="repository-maintenance-3">
9850 <h4>Repository maintenance</h4>
9851 <div class="section" id="churn-1">
9852 <h5>churn</h5>
9853 <p>histogram of changes to the repository:</p>
9854 <pre class="literal-block">
9855 hg churn [-d DATE] [-r REV] [--aliases FILE] [FILE]
9856 </pre>
9857 <p>This command will display a histogram representing the number
9858 of changed lines or revisions, grouped according to the given
9859 template. The default template will group changes by author.
9860 The --dateformat option may be used to group the results by
9861 date instead.</p>
9862 <p>Statistics are based on the number of changed lines, or
9863 alternatively the number of matching revisions if the
9864 --changesets option is specified.</p>
9865 <p>Examples:</p>
9866 <pre class="literal-block">
9867 # display count of changed lines for every committer
9868 hg churn -T &quot;{author|email}&quot;
9869
9870 # display daily activity graph
9871 hg churn -f &quot;%H&quot; -s -c
9872
9873 # display activity of developers by month
9874 hg churn -f &quot;%Y-%m&quot; -s -c
9875
9876 # display count of lines changed in every year
9877 hg churn -f &quot;%Y&quot; -s
9878
9879 # display count of lines changed in a time range
9880 hg churn -d &quot;2020-04 to 2020-09&quot;
9881 </pre>
9882 <p>It is possible to map alternate email addresses to a main address
9883 by providing a file using the following format:</p>
9884 <pre class="literal-block">
9885 &lt;alias email&gt; = &lt;actual email&gt;
9886 </pre>
9887 <p>Such a file may be specified with the --aliases option, otherwise
9888 a .hgchurn file will be looked for in the working directory root.
9889 Aliases will be split from the rightmost &quot;=&quot;.</p>
9890 <p>Options:</p>
9891 <table class="docutils option-list" frame="void" rules="none">
9892 <col class="option" />
9893 <col class="description" />
9894 <tbody valign="top">
9895 <tr><td class="option-group" colspan="2">
9896 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
9897 </tr>
9898 <tr><td>&nbsp;</td><td>count rate for the specified revision or revset</td></tr>
9899 <tr><td class="option-group" colspan="2">
9900 <kbd><span class="option">-d</span>, <span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
9901 </tr>
9902 <tr><td>&nbsp;</td><td>count rate for revisions matching date spec</td></tr>
9903 <tr><td class="option-group" colspan="2">
9904 <kbd><span class="option">-t</span>, <span class="option">--oldtemplate <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
9905 </tr>
9906 <tr><td>&nbsp;</td><td>template to group changesets (DEPRECATED)</td></tr>
9907 <tr><td class="option-group" colspan="2">
9908 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
9909 </tr>
9910 <tr><td>&nbsp;</td><td>template to group changesets (default: {author|email})</td></tr>
9911 <tr><td class="option-group" colspan="2">
9912 <kbd><span class="option">-f</span>, <span class="option">--dateformat <var>&lt;FORMAT&gt;</var></span></kbd></td>
9913 </tr>
9914 <tr><td>&nbsp;</td><td>strftime-compatible format for grouping by date</td></tr>
9915 <tr><td class="option-group" colspan="2">
9916 <kbd><span class="option">-c</span>, <span class="option">--changesets</span></kbd></td>
9917 </tr>
9918 <tr><td>&nbsp;</td><td>count rate by number of changesets</td></tr>
9919 <tr><td class="option-group">
9920 <kbd><span class="option">-s</span>, <span class="option">--sort</span></kbd></td>
9921 <td>sort by key (default: sort by count)</td></tr>
9922 <tr><td class="option-group">
9923 <kbd><span class="option">--diffstat</span></kbd></td>
9924 <td>display added/removed lines separately</td></tr>
9925 <tr><td class="option-group" colspan="2">
9926 <kbd><span class="option">--aliases <var>&lt;FILE&gt;</var></span></kbd></td>
9927 </tr>
9928 <tr><td>&nbsp;</td><td>file with email aliases</td></tr>
9929 <tr><td class="option-group" colspan="2">
9930 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
9931 </tr>
9932 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
9933 <tr><td class="option-group" colspan="2">
9934 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
9935 </tr>
9936 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
9937 </tbody>
9938 </table>
9939 <p>[+] marked option can be specified multiple times</p>
9940 </div>
9941 </div>
9942 </div>
9943 </div>
9944 <div class="section" id="clonebundles">
9945 <h2><a class="toc-backref" href="#toc-entry-48">clonebundles</a></h2>
9946 <p>advertise pre-generated bundles to seed clones</p>
9947 <p>&quot;clonebundles&quot; is a server-side extension used to advertise the existence
9948 of pre-generated, externally hosted bundle files to clients that are
9949 cloning so that cloning can be faster, more reliable, and require less
9950 resources on the server. &quot;pullbundles&quot; is a related feature for sending
9951 pre-generated bundle files to clients as part of pull operations.</p>
9952 <p>Cloning can be a CPU and I/O intensive operation on servers. Traditionally,
9953 the server, in response to a client's request to clone, dynamically generates
9954 a bundle containing the entire repository content and sends it to the client.
9955 There is no caching on the server and the server will have to redundantly
9956 generate the same outgoing bundle in response to each clone request. For
9957 servers with large repositories or with high clone volume, the load from
9958 clones can make scaling the server challenging and costly.</p>
9959 <p>This extension provides server operators the ability to offload
9960 potentially expensive clone load to an external service. Pre-generated
9961 bundles also allow using more CPU intensive compression, reducing the
9962 effective bandwidth requirements.</p>
9963 <p>Here's how clone bundles work:</p>
9964 <ol class="arabic simple">
9965 <li>A server operator establishes a mechanism for making bundle files available
9966 on a hosting service where Mercurial clients can fetch them.</li>
9967 <li>A manifest file listing available bundle URLs and some optional metadata
9968 is added to the Mercurial repository on the server.</li>
9969 <li>A client initiates a clone against a clone bundles aware server.</li>
9970 <li>The client sees the server is advertising clone bundles and fetches the
9971 manifest listing available bundles.</li>
9972 <li>The client filters and sorts the available bundles based on what it
9973 supports and prefers.</li>
9974 <li>The client downloads and applies an available bundle from the
9975 server-specified URL.</li>
9976 <li>The client reconnects to the original server and performs the equivalent
9977 of <a class="reference external" href="hg.1.html#pull"><tt class="docutils literal">hg pull</tt></a> to retrieve all repository data not in the bundle. (The
9978 repository could have been updated between when the bundle was created
9979 and when the client started the clone.) This may use &quot;pullbundles&quot;.</li>
9980 </ol>
9981 <p>Instead of the server generating full repository bundles for every clone
9982 request, it generates full bundles once and they are subsequently reused to
9983 bootstrap new clones. The server may still transfer data at clone time.
9984 However, this is only data that has been added/changed since the bundle was
9985 created. For large, established repositories, this can reduce server load for
9986 clones to less than 1% of original.</p>
9987 <p>Here's how pullbundles work:</p>
9988 <ol class="arabic simple">
9989 <li>A manifest file listing available bundles and describing the revisions
9990 is added to the Mercurial repository on the server.</li>
9991 <li>A new-enough client informs the server that it supports partial pulls
9992 and initiates a pull.</li>
9993 <li>If the server has pull bundles enabled and sees the client advertising
9994 partial pulls, it checks for a matching pull bundle in the manifest.
9995 A bundle matches if the format is supported by the client, the client
9996 has the required revisions already and needs something from the bundle.</li>
9997 <li>If there is at least one matching bundle, the server sends it to the client.</li>
9998 <li>The client applies the bundle and notices that the server reply was
9999 incomplete. It initiates another pull.</li>
10000 </ol>
10001 <p>To work, this extension requires the following of server operators:</p>
10002 <ul class="simple">
10003 <li>Generating bundle files of repository content (typically periodically,
10004 such as once per day).</li>
10005 <li>Clone bundles: A file server that clients have network access to and that
10006 Python knows how to talk to through its normal URL handling facility
10007 (typically an HTTP/HTTPS server).</li>
10008 <li>A process for keeping the bundles manifest in sync with available bundle
10009 files.</li>
10010 </ul>
10011 <p>Strictly speaking, using a static file hosting server isn't required: a server
10012 operator could use a dynamic service for retrieving bundle data. However,
10013 static file hosting services are simple and scalable and should be sufficient
10014 for most needs.</p>
10015 <p>Bundle files can be generated with the <a class="reference external" href="hg.1.html#bundle"><tt class="docutils literal">hg bundle</tt></a> command. Typically
10016 <a class="reference external" href="hg.1.html#bundle"><tt class="docutils literal">hg bundle <span class="pre">--all</span></tt></a> is used to produce a bundle of the entire repository.</p>
10017 <p>The bundlespec option <cite>stream</cite> (see <a class="reference external" href="hg.1.html#bundlespec"><tt class="docutils literal">hg help bundlespec</tt></a>)
10018 can be used to produce a special <em>streaming clonebundle</em>, typically using
10019 <a class="reference external" href="hg.1.html#bundle"><tt class="docutils literal">hg bundle <span class="pre">--all</span> <span class="pre">--type=&quot;none-streamv2&quot;</span></tt></a>.
10020 These are bundle files that are extremely efficient
10021 to produce and consume (read: fast). However, they are larger than
10022 traditional bundle formats and require that clients support the exact set
10023 of repository data store formats in use by the repository that created them.
10024 Typically, a newer server can serve data that is compatible with older clients.
10025 However, <em>streaming clone bundles</em> don't have this guarantee. <strong>Server
10026 operators need to be aware that newer versions of Mercurial may produce
10027 streaming clone bundles incompatible with older Mercurial versions.</strong></p>
10028 <p>A server operator is responsible for creating a <tt class="docutils literal">.hg/clonebundles.manifest</tt>
10029 file containing the list of available bundle files suitable for seeding
10030 clones. If this file does not exist, the repository will not advertise the
10031 existence of clone bundles when clients connect. For pull bundles,
10032 <tt class="docutils literal">.hg/pullbundles.manifest</tt> is used.</p>
10033 <p>The manifest file contains a newline (n) delimited list of entries.</p>
10034 <p>Each line in this file defines an available bundle. Lines have the format:</p>
10035 <blockquote>
10036 &lt;URL&gt; [&lt;key&gt;=&lt;value&gt;[ &lt;key&gt;=&lt;value&gt;]]</blockquote>
10037 <p>That is, a URL followed by an optional, space-delimited list of key=value
10038 pairs describing additional properties of this bundle. Both keys and values
10039 are URI encoded.</p>
10040 <p>For pull bundles, the URL is a path under the <tt class="docutils literal">.hg</tt> directory of the
10041 repository.</p>
10042 <p>Keys in UPPERCASE are reserved for use by Mercurial and are defined below.
10043 All non-uppercase keys can be used by site installations. An example use
10044 for custom properties is to use the <em>datacenter</em> attribute to define which
10045 data center a file is hosted in. Clients could then prefer a server in the
10046 data center closest to them.</p>
10047 <p>The following reserved keys are currently defined:</p>
10048 <dl class="docutils">
10049 <dt>BUNDLESPEC</dt>
10050 <dd><p class="first">A &quot;bundle specification&quot; string that describes the type of the bundle.</p>
10051 <p>These are string values that are accepted by the &quot;--type&quot; argument of
10052 <a class="reference external" href="hg.1.html#bundle"><tt class="docutils literal">hg bundle</tt></a>.</p>
10053 <p>The values are parsed in strict mode, which means they must be of the
10054 &quot;&lt;compression&gt;-&lt;type&gt;&quot; form. See
10055 mercurial.exchange.parsebundlespec() for more details.</p>
10056 <p><a class="reference external" href="hg.1.html#debugbundle"><tt class="docutils literal">hg debugbundle <span class="pre">--spec</span></tt></a> can be used to print the bundle specification
10057 string for a bundle file. The output of this command can be used verbatim
10058 for the value of <tt class="docutils literal">BUNDLESPEC</tt> (it is already escaped).</p>
10059 <p>Clients will automatically filter out specifications that are unknown or
10060 unsupported so they won't attempt to download something that likely won't
10061 apply.</p>
10062 <p>The actual value doesn't impact client behavior beyond filtering:
10063 clients will still sniff the bundle type from the header of downloaded
10064 files.</p>
10065 <p class="last"><strong>Use of this key is highly recommended</strong>, as it allows clients to
10066 easily skip unsupported bundles. If this key is not defined, an old
10067 client may attempt to apply a bundle that it is incapable of reading.</p>
10068 </dd>
10069 <dt>REQUIRESNI</dt>
10070 <dd><p class="first">Whether Server Name Indication (SNI) is required to connect to the URL.
10071 SNI allows servers to use multiple certificates on the same IP. It is
10072 somewhat common in CDNs and other hosting providers. Older Python
10073 versions do not support SNI. Defining this attribute enables clients
10074 with older Python versions to filter this entry without experiencing
10075 an opaque SSL failure at connection time.</p>
10076 <p>If this is defined, it is important to advertise a non-SNI fallback
10077 URL or clients running old Python releases may not be able to clone
10078 with the clonebundles facility.</p>
10079 <p class="last">Value should be &quot;true&quot;.</p>
10080 </dd>
10081 <dt>REQUIREDRAM</dt>
10082 <dd><p class="first">Value specifies expected memory requirements to decode the payload.
10083 Values can have suffixes for common bytes sizes. e.g. &quot;64MB&quot;.</p>
10084 <p class="last">This key is often used with zstd-compressed bundles using a high
10085 compression level / window size, which can require 100+ MB of memory
10086 to decode.</p>
10087 </dd>
10088 <dt>heads</dt>
10089 <dd>Used for pull bundles. This contains the <tt class="docutils literal">;</tt> separated changeset
10090 hashes of the heads of the bundle content.</dd>
10091 <dt>bases</dt>
10092 <dd>Used for pull bundles. This contains the <tt class="docutils literal">;</tt> separated changeset
10093 hashes of the roots of the bundle content. This can be skipped if
10094 the bundle was created without <tt class="docutils literal"><span class="pre">--base</span></tt>.</dd>
10095 </dl>
10096 <p>Manifests can contain multiple entries. Assuming metadata is defined, clients
10097 will filter entries from the manifest that they don't support. The remaining
10098 entries are optionally sorted by client preferences
10099 (<tt class="docutils literal">ui.clonebundleprefers</tt> config option). The client then attempts
10100 to fetch the bundle at the first URL in the remaining list.</p>
10101 <p><strong>Errors when downloading a bundle will fail the entire clone operation:
10102 clients do not automatically fall back to a traditional clone.</strong> The reason
10103 for this is that if a server is using clone bundles, it is probably doing so
10104 because the feature is necessary to help it scale. In other words, there
10105 is an assumption that clone load will be offloaded to another service and
10106 that the Mercurial server isn't responsible for serving this clone load.
10107 If that other service experiences issues and clients start mass falling back to
10108 the original Mercurial server, the added clone load could overwhelm the server
10109 due to unexpected load and effectively take it offline. Not having clients
10110 automatically fall back to cloning from the original server mitigates this
10111 scenario.</p>
10112 <p>Because there is no automatic Mercurial server fallback on failure of the
10113 bundle hosting service, it is important for server operators to view the bundle
10114 hosting service as an extension of the Mercurial server in terms of
10115 availability and service level agreements: if the bundle hosting service goes
10116 down, so does the ability for clients to clone. Note: clients will see a
10117 message informing them how to bypass the clone bundles facility when a failure
10118 occurs. So server operators should prepare for some people to follow these
10119 instructions when a failure occurs, thus driving more load to the original
10120 Mercurial server when the bundle hosting service fails.</p>
10121 <div class="section" id="inline-clonebundles">
10122 <h3>inline clonebundles</h3>
10123 <p>It is possible to transmit clonebundles inline in case repositories are
10124 accessed over SSH. This avoids having to setup an external HTTPS server
10125 and results in the same access control as already present for the SSH setup.</p>
10126 <p>Inline clonebundles should be placed into the <cite>.hg/bundle-cache</cite> directory.
10127 A clonebundle at <cite>.hg/bundle-cache/mybundle.bundle</cite> is referred to
10128 in the <cite>clonebundles.manifest</cite> file as <cite>peer-bundle-cache://mybundle.bundle</cite>.</p>
10129 </div>
10130 <div class="section" id="auto-generation-of-clone-bundles">
10131 <h3>auto-generation of clone bundles</h3>
10132 <p>It is possible to set Mercurial to automatically re-generate clone bundles when
10133 enough new content is available.</p>
10134 <p>Mercurial will take care of the process asynchronously. The defined list of
10135 bundle-type will be generated, uploaded, and advertised. Older bundles will get
10136 decommissioned as newer ones replace them.</p>
10137 <div class="section" id="bundles-generation">
10138 <h4>Bundles Generation:</h4>
10139 <p>The extension can generate multiple variants of the clone bundle. Each
10140 different variant will be defined by the &quot;bundle-spec&quot; they use:</p>
10141 <pre class="literal-block">
10142 [clone-bundles]
10143 auto-generate.formats= zstd-v2, gzip-v2
10144 </pre>
10145 <p>See <cite>hg help bundlespec</cite> for details about available options.</p>
10146 <p>By default, new bundles are generated when 5% of the repository contents or at
10147 least 1000 revisions are not contained in the cached bundles. This option can
10148 be controlled by the <cite>clone-bundles.trigger.below-bundled-ratio</cite> option
10149 (default 0.95) and the <cite>clone-bundles.trigger.revs</cite> option (default 1000):</p>
10150 <pre class="literal-block">
10151 [clone-bundles]
10152 trigger.below-bundled-ratio=0.95
10153 trigger.revs=1000
10154 </pre>
10155 <p>This logic can be manually triggered using the <cite>admin::clone-bundles-refresh</cite>
10156 command, or automatically on each repository change if
10157 <cite>clone-bundles.auto-generate.on-change</cite> is set to <cite>yes</cite>:</p>
10158 <pre class="literal-block">
10159 [clone-bundles]
10160 auto-generate.on-change=yes
10161 auto-generate.formats= zstd-v2, gzip-v2
10162 </pre>
10163 </div>
10164 <div class="section" id="automatic-inline-serving">
10165 <h4>Automatic Inline serving</h4>
10166 <p>The simplest way to serve the generated bundle is through the Mercurial
10167 protocol. However it is not the most efficient as request will still be served
10168 by that main server. It is useful in case where authentication is complexe or
10169 when an efficient mirror system is already in use anyway. See the <cite>inline
10170 clonebundles</cite> section above for details about inline clonebundles</p>
10171 <p>To automatically serve generated bundle through inline clonebundle, simply set
10172 the following option:</p>
10173 <pre class="literal-block">
10174 auto-generate.serve-inline=yes
10175 </pre>
10176 <p>Enabling this option disable the managed upload and serving explained below.</p>
10177 </div>
10178 <div class="section" id="bundles-upload-and-serving">
10179 <h4>Bundles Upload and Serving:</h4>
10180 <p>This is the most efficient way to serve automatically generated clone bundles,
10181 but requires some setup.</p>
10182 <p>The generated bundles need to be made available to users through a &quot;public&quot; URL.
10183 This should be donne through <cite>clone-bundles.upload-command</cite> configuration. The
10184 value of this command should be a shell command. It will have access to the
10185 bundle file path through the <cite>$HGCB_BUNDLE_PATH</cite> variable. And the expected
10186 basename in the &quot;public&quot; URL is accessible at:</p>
10187 <pre class="literal-block">
10188 [clone-bundles]
10189 upload-command=sftp put $HGCB_BUNDLE_PATH sftp://bundles.host/clone-bundles/$HGCB_BUNDLE_BASENAME
10190 </pre>
10191 <p>If the file was already uploaded, the command must still succeed.</p>
10192 <p>After upload, the file should be available at an url defined by
10193 <cite>clone-bundles.url-template</cite>.</p>
10194 <blockquote>
10195 [clone-bundles]
10196 url-template=https://bundles.host/cache/clone-bundles/{basename}</blockquote>
10197 </div>
10198 <div class="section" id="old-bundles-cleanup">
10199 <h4>Old bundles cleanup:</h4>
10200 <p>When new bundles are generated, the older ones are no longer necessary and can
10201 be removed from storage. This is done through the <cite>clone-bundles.delete-command</cite>
10202 configuration. The command is given the url of the artifact to delete through
10203 the <cite>$HGCB_BUNDLE_URL</cite> environment variable.</p>
10204 <blockquote>
10205 [clone-bundles]
10206 delete-command=sftp rm sftp://bundles.host/clone-bundles/$HGCB_BUNDLE_BASENAME</blockquote>
10207 <p>If the file was already deleted, the command must still succeed.</p>
10208 </div>
10209 </div>
10210 <div class="section" id="commands-8">
10211 <h3>Commands</h3>
10212 <div class="section" id="uncategorized-commands-1">
10213 <h4>Uncategorized commands</h4>
10214 <div class="section" id="admin-clone-bundles-clear">
10215 <h5>admin::clone-bundles-clear</h5>
10216 <p>remove existing clone bundle caches:</p>
10217 <pre class="literal-block">
10218 hg admin::clone-bundles-clear
10219 </pre>
10220 <p>See <cite>hg help admin::clone-bundles-refresh</cite> for details on how to regenerate
10221 them.</p>
10222 <p>This command will only affect bundles currently available, it will not
10223 affect bundles being asynchronously generated.</p>
10224 </div>
10225 <div class="section" id="admin-clone-bundles-refresh">
10226 <h5>admin::clone-bundles-refresh</h5>
10227 <p>generate clone bundles according to the configuration:</p>
10228 <pre class="literal-block">
10229 hg admin::clone-bundles-refresh
10230 </pre>
10231 <p>This runs the logic for automatic generation, removing outdated bundles and
10232 generating new ones if necessary. See <a class="reference external" href="hg.1.html#-e"><tt class="docutils literal">hg help <span class="pre">-e</span> <span class="pre">clone-bundles</span></tt></a> for
10233 details about how to configure this feature.</p>
10234 <p>Options:</p>
10235 <table class="docutils option-list" frame="void" rules="none">
10236 <col class="option" />
10237 <col class="description" />
10238 <tbody valign="top">
10239 <tr><td class="option-group">
10240 <kbd><span class="option">--background</span></kbd></td>
10241 <td>start bundle generation in the background</td></tr>
10242 </tbody>
10243 </table>
10244 </div>
10245 </div>
10246 </div>
10247 </div>
10248 <div class="section" id="closehead">
10249 <h2><a class="toc-backref" href="#toc-entry-49">closehead</a></h2>
10250 <p>close arbitrary heads without checking them out first</p>
10251 <div class="section" id="commands-9">
10252 <h3>Commands</h3>
10253 <div class="section" id="change-manipulation-1">
10254 <h4>Change manipulation</h4>
10255 <div class="section" id="close-head">
10256 <h5>close-head</h5>
10257 <p>close the given head revisions:</p>
10258 <pre class="literal-block">
10259 hg close-head [OPTION]... [REV]...
10260 </pre>
10261 <p>This is equivalent to checking out each revision in a clean tree and running
10262 <tt class="docutils literal">hg commit <span class="pre">--close-branch</span></tt>, except that it doesn't change the working
10263 directory.</p>
10264 <p>The commit message must be specified with -l or -m.</p>
10265 <p>Options:</p>
10266 <table class="docutils option-list" frame="void" rules="none">
10267 <col class="option" />
10268 <col class="description" />
10269 <tbody valign="top">
10270 <tr><td class="option-group" colspan="2">
10271 <kbd><span class="option">-m</span>, <span class="option">--message <var>&lt;TEXT&gt;</var></span></kbd></td>
10272 </tr>
10273 <tr><td>&nbsp;</td><td>use text as commit message</td></tr>
10274 <tr><td class="option-group" colspan="2">
10275 <kbd><span class="option">-l</span>, <span class="option">--logfile <var>&lt;FILE&gt;</var></span></kbd></td>
10276 </tr>
10277 <tr><td>&nbsp;</td><td>read commit message from file</td></tr>
10278 <tr><td class="option-group" colspan="2">
10279 <kbd><span class="option">-d</span>, <span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
10280 </tr>
10281 <tr><td>&nbsp;</td><td>record the specified date as commit date</td></tr>
10282 <tr><td class="option-group" colspan="2">
10283 <kbd><span class="option">-u</span>, <span class="option">--user <var>&lt;USER&gt;</var></span></kbd></td>
10284 </tr>
10285 <tr><td>&nbsp;</td><td>record the specified user as committer</td></tr>
10286 <tr><td class="option-group" colspan="2">
10287 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
10288 </tr>
10289 <tr><td>&nbsp;</td><td>revision to check</td></tr>
10290 </tbody>
10291 </table>
10292 <p>[+] marked option can be specified multiple times</p>
10293 <!-- -->
10294 <blockquote>
10295 aliases: close-heads</blockquote>
10296 </div>
10297 </div>
10298 </div>
10299 </div>
10300 <div class="section" id="commitextras">
10301 <h2><a class="toc-backref" href="#toc-entry-50">commitextras</a></h2>
10302 <p>adds a new flag extras to commit (ADVANCED)</p>
10303 </div>
10304 <div class="section" id="convert">
10305 <h2><a class="toc-backref" href="#toc-entry-51">convert</a></h2>
10306 <p>import revisions from foreign VCS repositories into Mercurial</p>
10307 <div class="section" id="commands-10">
10308 <h3>Commands</h3>
10309 <div class="section" id="uncategorized-commands-2">
10310 <h4>Uncategorized commands</h4>
10311 <div class="section" id="convert-1">
10312 <h5>convert</h5>
10313 <p>convert a foreign SCM repository to a Mercurial one.:</p>
10314 <pre class="literal-block">
10315 hg convert [OPTION]... SOURCE [DEST [REVMAP]]
10316 </pre>
10317 <p>Accepted source formats [identifiers]:</p>
10318 <ul class="simple">
10319 <li>Mercurial [hg]</li>
10320 <li>CVS [cvs]</li>
10321 <li>Darcs [darcs]</li>
10322 <li>git [git]</li>
10323 <li>Subversion [svn]</li>
10324 <li>Monotone [mtn]</li>
10325 <li>GNU Arch [gnuarch]</li>
10326 <li>Bazaar [bzr]</li>
10327 <li>Perforce [p4]</li>
10328 </ul>
10329 <p>Accepted destination formats [identifiers]:</p>
10330 <ul class="simple">
10331 <li>Mercurial [hg]</li>
10332 <li>Subversion [svn] (history on branches is not preserved)</li>
10333 </ul>
10334 <p>If no revision is given, all revisions will be converted.
10335 Otherwise, convert will only import up to the named revision
10336 (given in a format understood by the source).</p>
10337 <p>If no destination directory name is specified, it defaults to the
10338 basename of the source with <tt class="docutils literal"><span class="pre">-hg</span></tt> appended. If the destination
10339 repository doesn't exist, it will be created.</p>
10340 <p>By default, all sources except Mercurial will use --branchsort.
10341 Mercurial uses --sourcesort to preserve original revision numbers
10342 order. Sort modes have the following effects:</p>
10343 <table class="docutils option-list" frame="void" rules="none">
10344 <col class="option" />
10345 <col class="description" />
10346 <tbody valign="top">
10347 <tr><td class="option-group">
10348 <kbd><span class="option">--branchsort</span></kbd></td>
10349 <td>convert from parent to child revision when possible,
10350 which means branches are usually converted one after
10351 the other. It generates more compact repositories.</td></tr>
10352 <tr><td class="option-group">
10353 <kbd><span class="option">--datesort</span></kbd></td>
10354 <td>sort revisions by date. Converted repositories have
10355 good-looking changelogs but are often an order of
10356 magnitude larger than the same ones generated by
10357 --branchsort.</td></tr>
10358 <tr><td class="option-group">
10359 <kbd><span class="option">--sourcesort</span></kbd></td>
10360 <td>try to preserve source revisions order, only
10361 supported by Mercurial sources.</td></tr>
10362 <tr><td class="option-group">
10363 <kbd><span class="option">--closesort</span></kbd></td>
10364 <td>try to move closed revisions as close as possible
10365 to parent branches, only supported by Mercurial
10366 sources.</td></tr>
10367 </tbody>
10368 </table>
10369 <p>If <tt class="docutils literal">REVMAP</tt> isn't given, it will be put in a default location
10370 (<tt class="docutils literal"><span class="pre">&lt;dest&gt;/.hg/shamap</span></tt> by default). The <tt class="docutils literal">REVMAP</tt> is a simple
10371 text file that maps each source commit ID to the destination ID
10372 for that revision, like so:</p>
10373 <pre class="literal-block">
10374 &lt;source ID&gt; &lt;destination ID&gt;
10375 </pre>
10376 <p>If the file doesn't exist, it's automatically created. It's
10377 updated on each commit copied, so <a class="reference external" href="hg.1.html#convert"><tt class="docutils literal">hg convert</tt></a> can be interrupted
10378 and can be run repeatedly to copy new commits.</p>
10379 <p>The authormap is a simple text file that maps each source commit
10380 author to a destination commit author. It is handy for source SCMs
10381 that use unix logins to identify authors (e.g.: CVS). One line per
10382 author mapping and the line format is:</p>
10383 <pre class="literal-block">
10384 source author = destination author
10385 </pre>
10386 <p>Empty lines and lines starting with a <tt class="docutils literal">#</tt> are ignored.</p>
10387 <p>The filemap is a file that allows filtering and remapping of files
10388 and directories. Each line can contain one of the following
10389 directives:</p>
10390 <pre class="literal-block">
10391 include path/to/file-or-dir
10392
10393 exclude path/to/file-or-dir
10394
10395 rename path/to/source path/to/destination
10396 </pre>
10397 <p>Comment lines start with <tt class="docutils literal">#</tt>. A specified path matches if it
10398 equals the full relative name of a file or one of its parent
10399 directories. The <tt class="docutils literal">include</tt> or <tt class="docutils literal">exclude</tt> directive with the
10400 longest matching path applies, so line order does not matter.</p>
10401 <p>The <tt class="docutils literal">include</tt> directive causes a file, or all files under a
10402 directory, to be included in the destination repository. The default
10403 if there are no <tt class="docutils literal">include</tt> statements is to include everything.
10404 If there are any <tt class="docutils literal">include</tt> statements, nothing else is included.
10405 The <tt class="docutils literal">exclude</tt> directive causes files or directories to
10406 be omitted. The <tt class="docutils literal">rename</tt> directive renames a file or directory if
10407 it is converted. To rename from a subdirectory into the root of
10408 the repository, use <tt class="docutils literal">.</tt> as the path to rename to.</p>
10409 <p><tt class="docutils literal"><span class="pre">--full</span></tt> will make sure the converted changesets contain exactly
10410 the right files with the right content. It will make a full
10411 conversion of all files, not just the ones that have
10412 changed. Files that already are correct will not be changed. This
10413 can be used to apply filemap changes when converting
10414 incrementally. This is currently only supported for Mercurial and
10415 Subversion.</p>
10416 <p>The splicemap is a file that allows insertion of synthetic
10417 history, letting you specify the parents of a revision. This is
10418 useful if you want to e.g. give a Subversion merge two parents, or
10419 graft two disconnected series of history together. Each entry
10420 contains a key, followed by a space, followed by one or two
10421 comma-separated values:</p>
10422 <pre class="literal-block">
10423 key parent1, parent2
10424 </pre>
10425 <p>The key is the revision ID in the source
10426 revision control system whose parents should be modified (same
10427 format as a key in .hg/shamap). The values are the revision IDs
10428 (in either the source or destination revision control system) that
10429 should be used as the new parents for that node. For example, if
10430 you have merged &quot;release-1.0&quot; into &quot;trunk&quot;, then you should
10431 specify the revision on &quot;trunk&quot; as the first parent and the one on
10432 the &quot;release-1.0&quot; branch as the second.</p>
10433 <p>The branchmap is a file that allows you to rename a branch when it is
10434 being brought in from whatever external repository. When used in
10435 conjunction with a splicemap, it allows for a powerful combination
10436 to help fix even the most badly mismanaged repositories and turn them
10437 into nicely structured Mercurial repositories. The branchmap contains
10438 lines of the form:</p>
10439 <pre class="literal-block">
10440 original_branch_name new_branch_name
10441 </pre>
10442 <p>where &quot;original_branch_name&quot; is the name of the branch in the
10443 source repository, and &quot;new_branch_name&quot; is the name of the branch
10444 is the destination repository. No whitespace is allowed in the new
10445 branch name. This can be used to (for instance) move code in one
10446 repository from &quot;default&quot; to a named branch.</p>
10447 <div class="section" id="mercurial-source">
10448 <h6>Mercurial Source</h6>
10449 <p>The Mercurial source recognizes the following configuration
10450 options, which you can set on the command line with <tt class="docutils literal"><span class="pre">--config</span></tt>:</p>
10451 <table class="docutils field-list" frame="void" rules="none">
10452 <col class="field-name" />
10453 <col class="field-body" />
10454 <tbody valign="top">
10455 <tr class="field"><th class="field-name" colspan="2">convert.hg.ignoreerrors:</th></tr>
10456 <tr class="field"><td>&nbsp;</td><td class="field-body">ignore integrity errors when reading.
10457 Use it to fix Mercurial repositories with missing revlogs, by
10458 converting from and to Mercurial. Default is False.</td>
10459 </tr>
10460 <tr class="field"><th class="field-name" colspan="2">convert.hg.saverev:</th></tr>
10461 <tr class="field"><td>&nbsp;</td><td class="field-body">store original revision ID in changeset
10462 (forces target IDs to change). It takes a boolean argument and
10463 defaults to False.</td>
10464 </tr>
10465 <tr class="field"><th class="field-name" colspan="2">convert.hg.startrev:</th></tr>
10466 <tr class="field"><td>&nbsp;</td><td class="field-body">specify the initial Mercurial revision.
10467 The default is 0.</td>
10468 </tr>
10469 <tr class="field"><th class="field-name" colspan="2">convert.hg.revs:</th></tr>
10470 <tr class="field"><td>&nbsp;</td><td class="field-body">revset specifying the source revisions to convert.</td>
10471 </tr>
10472 </tbody>
10473 </table>
10474 </div>
10475 <div class="section" id="bazaar-source">
10476 <h6>Bazaar Source</h6>
10477 <p>The following options can be used with <tt class="docutils literal"><span class="pre">--config</span></tt>:</p>
10478 <table class="docutils field-list" frame="void" rules="none">
10479 <col class="field-name" />
10480 <col class="field-body" />
10481 <tbody valign="top">
10482 <tr class="field"><th class="field-name" colspan="2">convert.bzr.saverev:</th></tr>
10483 <tr class="field"><td>&nbsp;</td><td class="field-body">whether to store the original Bazaar commit ID in
10484 the metadata of the destination commit. The default is True.</td>
10485 </tr>
10486 </tbody>
10487 </table>
10488 </div>
10489 <div class="section" id="cvs-source">
10490 <h6>CVS Source</h6>
10491 <p>CVS source will use a sandbox (i.e. a checked-out copy) from CVS
10492 to indicate the starting point of what will be converted. Direct
10493 access to the repository files is not needed, unless of course the
10494 repository is <tt class="docutils literal">:local:</tt>. The conversion uses the top level
10495 directory in the sandbox to find the CVS repository, and then uses
10496 CVS rlog commands to find files to convert. This means that unless
10497 a filemap is given, all files under the starting directory will be
10498 converted, and that any directory reorganization in the CVS
10499 sandbox is ignored.</p>
10500 <p>The following options can be used with <tt class="docutils literal"><span class="pre">--config</span></tt>:</p>
10501 <table class="docutils field-list" frame="void" rules="none">
10502 <col class="field-name" />
10503 <col class="field-body" />
10504 <tbody valign="top">
10505 <tr class="field"><th class="field-name" colspan="2">convert.cvsps.cache:</th></tr>
10506 <tr class="field"><td>&nbsp;</td><td class="field-body">Set to False to disable remote log caching,
10507 for testing and debugging purposes. Default is True.</td>
10508 </tr>
10509 <tr class="field"><th class="field-name" colspan="2">convert.cvsps.fuzz:</th></tr>
10510 <tr class="field"><td>&nbsp;</td><td class="field-body">Specify the maximum time (in seconds) that is
10511 allowed between commits with identical user and log message in
10512 a single changeset. When very large files were checked in as
10513 part of a changeset then the default may not be long enough.
10514 The default is 60.</td>
10515 </tr>
10516 <tr class="field"><th class="field-name" colspan="2">convert.cvsps.logencoding:</th></tr>
10517 <tr class="field"><td>&nbsp;</td><td class="field-body">Specify encoding name to be used for
10518 transcoding CVS log messages. Multiple encoding names can be
10519 specified as a list (see <a class="reference external" href="hgrc.5.html#Syntax"><tt class="docutils literal">hg help config.Syntax</tt></a>), but only
10520 the first acceptable encoding in the list is used per CVS log
10521 entries. This transcoding is executed before cvslog hook below.</td>
10522 </tr>
10523 <tr class="field"><th class="field-name" colspan="2">convert.cvsps.mergeto:</th></tr>
10524 <tr class="field"><td>&nbsp;</td><td class="field-body">Specify a regular expression to which
10525 commit log messages are matched. If a match occurs, then the
10526 conversion process will insert a dummy revision merging the
10527 branch on which this log message occurs to the branch
10528 indicated in the regex. Default is <tt class="docutils literal">{{mergetobranch
10529 <span class="pre">([-\w]+)}}</span></tt></td>
10530 </tr>
10531 <tr class="field"><th class="field-name" colspan="2">convert.cvsps.mergefrom:</th></tr>
10532 <tr class="field"><td>&nbsp;</td><td class="field-body">Specify a regular expression to which
10533 commit log messages are matched. If a match occurs, then the
10534 conversion process will add the most recent revision on the
10535 branch indicated in the regex as the second parent of the
10536 changeset. Default is <tt class="docutils literal">{{mergefrombranch <span class="pre">([-\w]+)}}</span></tt></td>
10537 </tr>
10538 <tr class="field"><th class="field-name" colspan="2">convert.localtimezone:</th></tr>
10539 <tr class="field"><td>&nbsp;</td><td class="field-body">use local time (as determined by the TZ
10540 environment variable) for changeset date/times. The default
10541 is False (use UTC).</td>
10542 </tr>
10543 <tr class="field"><th class="field-name">hooks.cvslog:</th><td class="field-body">Specify a Python function to be called at the end of
10544 gathering the CVS log. The function is passed a list with the
10545 log entries, and can modify the entries in-place, or add or
10546 delete them.</td>
10547 </tr>
10548 <tr class="field"><th class="field-name" colspan="2">hooks.cvschangesets:</th></tr>
10549 <tr class="field"><td>&nbsp;</td><td class="field-body">Specify a Python function to be called after
10550 the changesets are calculated from the CVS log. The
10551 function is passed a list with the changeset entries, and can
10552 modify the changesets in-place, or add or delete them.</td>
10553 </tr>
10554 </tbody>
10555 </table>
10556 <p>An additional &quot;debugcvsps&quot; Mercurial command allows the builtin
10557 changeset merging code to be run without doing a conversion. Its
10558 parameters and output are similar to that of cvsps 2.1. Please see
10559 the command help for more details.</p>
10560 </div>
10561 <div class="section" id="subversion-source">
10562 <h6>Subversion Source</h6>
10563 <p>Subversion source detects classical trunk/branches/tags layouts.
10564 By default, the supplied <tt class="docutils literal"><span class="pre">svn://repo/path/</span></tt> source URL is
10565 converted as a single branch. If <tt class="docutils literal"><span class="pre">svn://repo/path/trunk</span></tt> exists
10566 it replaces the default branch. If <tt class="docutils literal"><span class="pre">svn://repo/path/branches</span></tt>
10567 exists, its subdirectories are listed as possible branches. If
10568 <tt class="docutils literal"><span class="pre">svn://repo/path/tags</span></tt> exists, it is looked for tags referencing
10569 converted branches. Default <tt class="docutils literal">trunk</tt>, <tt class="docutils literal">branches</tt> and <tt class="docutils literal">tags</tt>
10570 values can be overridden with following options. Set them to paths
10571 relative to the source URL, or leave them blank to disable auto
10572 detection.</p>
10573 <p>The following options can be set with <tt class="docutils literal"><span class="pre">--config</span></tt>:</p>
10574 <table class="docutils field-list" frame="void" rules="none">
10575 <col class="field-name" />
10576 <col class="field-body" />
10577 <tbody valign="top">
10578 <tr class="field"><th class="field-name" colspan="2">convert.svn.branches:</th></tr>
10579 <tr class="field"><td>&nbsp;</td><td class="field-body">specify the directory containing branches.
10580 The default is <tt class="docutils literal">branches</tt>.</td>
10581 </tr>
10582 <tr class="field"><th class="field-name" colspan="2">convert.svn.tags:</th></tr>
10583 <tr class="field"><td>&nbsp;</td><td class="field-body">specify the directory containing tags. The
10584 default is <tt class="docutils literal">tags</tt>.</td>
10585 </tr>
10586 <tr class="field"><th class="field-name" colspan="2">convert.svn.trunk:</th></tr>
10587 <tr class="field"><td>&nbsp;</td><td class="field-body">specify the name of the trunk branch. The
10588 default is <tt class="docutils literal">trunk</tt>.</td>
10589 </tr>
10590 <tr class="field"><th class="field-name" colspan="2">convert.localtimezone:</th></tr>
10591 <tr class="field"><td>&nbsp;</td><td class="field-body">use local time (as determined by the TZ
10592 environment variable) for changeset date/times. The default
10593 is False (use UTC).</td>
10594 </tr>
10595 </tbody>
10596 </table>
10597 <p>Source history can be retrieved starting at a specific revision,
10598 instead of being integrally converted. Only single branch
10599 conversions are supported.</p>
10600 <table class="docutils field-list" frame="void" rules="none">
10601 <col class="field-name" />
10602 <col class="field-body" />
10603 <tbody valign="top">
10604 <tr class="field"><th class="field-name" colspan="2">convert.svn.startrev:</th></tr>
10605 <tr class="field"><td>&nbsp;</td><td class="field-body">specify start Subversion revision number.
10606 The default is 0.</td>
10607 </tr>
10608 </tbody>
10609 </table>
10610 </div>
10611 <div class="section" id="git-source">
10612 <h6>Git Source</h6>
10613 <p>The Git importer converts commits from all reachable branches (refs
10614 in refs/heads) and remotes (refs in refs/remotes) to Mercurial.
10615 Branches are converted to bookmarks with the same name, with the
10616 leading 'refs/heads' stripped. Git submodules are converted to Git
10617 subrepos in Mercurial.</p>
10618 <p>The following options can be set with <tt class="docutils literal"><span class="pre">--config</span></tt>:</p>
10619 <table class="docutils field-list" frame="void" rules="none">
10620 <col class="field-name" />
10621 <col class="field-body" />
10622 <tbody valign="top">
10623 <tr class="field"><th class="field-name" colspan="2">convert.git.similarity:</th></tr>
10624 <tr class="field"><td>&nbsp;</td><td class="field-body"><p class="first">specify how similar files modified in a
10625 commit must be to be imported as renames or copies, as a
10626 percentage between <tt class="docutils literal">0</tt> (disabled) and <tt class="docutils literal">100</tt> (files must be
10627 identical). For example, <tt class="docutils literal">90</tt> means that a delete/add pair will
10628 be imported as a rename if more than 90% of the file hasn't
10629 changed. The default is <tt class="docutils literal">50</tt>.</p>
10630 </td>
10631 </tr>
10632 <tr class="field"><th class="field-name" colspan="2">convert.git.findcopiesharder:</th></tr>
10633 <tr class="field"><td>&nbsp;</td><td class="field-body"><p class="first">while detecting copies, look at all
10634 files in the working copy instead of just changed ones. This
10635 is very expensive for large projects, and is only effective when
10636 <tt class="docutils literal">convert.git.similarity</tt> is greater than 0. The default is False.</p>
10637 </td>
10638 </tr>
10639 <tr class="field"><th class="field-name" colspan="2">convert.git.renamelimit:</th></tr>
10640 <tr class="field"><td>&nbsp;</td><td class="field-body"><p class="first">perform rename and copy detection up to this
10641 many changed files in a commit. Increasing this will make rename
10642 and copy detection more accurate but will significantly slow down
10643 computation on large projects. The option is only relevant if
10644 <tt class="docutils literal">convert.git.similarity</tt> is greater than 0. The default is
10645 <tt class="docutils literal">400</tt>.</p>
10646 </td>
10647 </tr>
10648 <tr class="field"><th class="field-name" colspan="2">convert.git.committeractions:</th></tr>
10649 <tr class="field"><td>&nbsp;</td><td class="field-body"><p class="first">list of actions to take when processing
10650 author and committer values.</p>
10651 <p>Git commits have separate author (who wrote the commit) and committer
10652 (who applied the commit) fields. Not all destinations support separate
10653 author and committer fields (including Mercurial). This config option
10654 controls what to do with these author and committer fields during
10655 conversion.</p>
10656 <p>A value of <tt class="docutils literal">messagedifferent</tt> will append a <tt class="docutils literal">committer: ...</tt>
10657 line to the commit message if the Git committer is different from the
10658 author. The prefix of that line can be specified using the syntax
10659 <tt class="docutils literal"><span class="pre">messagedifferent=&lt;prefix&gt;</span></tt>. e.g. <tt class="docutils literal"><span class="pre">messagedifferent=git-committer:</span></tt>.
10660 When a prefix is specified, a space will always be inserted between the
10661 prefix and the value.</p>
10662 <p><tt class="docutils literal">messagealways</tt> behaves like <tt class="docutils literal">messagedifferent</tt> except it will
10663 always result in a <tt class="docutils literal">committer: ...</tt> line being appended to the commit
10664 message. This value is mutually exclusive with <tt class="docutils literal">messagedifferent</tt>.</p>
10665 <p><tt class="docutils literal">dropcommitter</tt> will remove references to the committer. Only
10666 references to the author will remain. Actions that add references
10667 to the committer will have no effect when this is set.</p>
10668 <p><tt class="docutils literal">replaceauthor</tt> will replace the value of the author field with
10669 the committer. Other actions that add references to the committer
10670 will still take effect when this is set.</p>
10671 <p>The default is <tt class="docutils literal">messagedifferent</tt>.</p>
10672 </td>
10673 </tr>
10674 <tr class="field"><th class="field-name" colspan="2">convert.git.extrakeys:</th></tr>
10675 <tr class="field"><td>&nbsp;</td><td class="field-body"><p class="first">list of extra keys from commit metadata to copy to
10676 the destination. Some Git repositories store extra metadata in commits.
10677 By default, this non-default metadata will be lost during conversion.
10678 Setting this config option can retain that metadata. Some built-in
10679 keys such as <tt class="docutils literal">parent</tt> and <tt class="docutils literal">branch</tt> are not allowed to be copied.</p>
10680 </td>
10681 </tr>
10682 <tr class="field"><th class="field-name" colspan="2">convert.git.remoteprefix:</th></tr>
10683 <tr class="field"><td>&nbsp;</td><td class="field-body"><p class="first">remote refs are converted as bookmarks with
10684 <tt class="docutils literal">convert.git.remoteprefix</tt> as a prefix followed by a /. The default
10685 is 'remote'.</p>
10686 </td>
10687 </tr>
10688 <tr class="field"><th class="field-name" colspan="2">convert.git.saverev:</th></tr>
10689 <tr class="field"><td>&nbsp;</td><td class="field-body"><p class="first">whether to store the original Git commit ID in the
10690 metadata of the destination commit. The default is True.</p>
10691 </td>
10692 </tr>
10693 <tr class="field"><th class="field-name" colspan="2">convert.git.skipsubmodules:</th></tr>
10694 <tr class="field"><td>&nbsp;</td><td class="field-body"><p class="first last">does not convert root level .gitmodules files
10695 or files with 160000 mode indicating a submodule. Default is False.</p>
10696 </td>
10697 </tr>
10698 </tbody>
10699 </table>
10700 </div>
10701 <div class="section" id="perforce-source">
10702 <h6>Perforce Source</h6>
10703 <p>The Perforce (P4) importer can be given a p4 depot path or a
10704 client specification as source. It will convert all files in the
10705 source to a flat Mercurial repository, ignoring labels, branches
10706 and integrations. Note that when a depot path is given you then
10707 usually should specify a target directory, because otherwise the
10708 target may be named <tt class="docutils literal"><span class="pre">...-hg</span></tt>.</p>
10709 <p>The following options can be set with <tt class="docutils literal"><span class="pre">--config</span></tt>:</p>
10710 <table class="docutils field-list" frame="void" rules="none">
10711 <col class="field-name" />
10712 <col class="field-body" />
10713 <tbody valign="top">
10714 <tr class="field"><th class="field-name" colspan="2">convert.p4.encoding:</th></tr>
10715 <tr class="field"><td>&nbsp;</td><td class="field-body">specify the encoding to use when decoding standard
10716 output of the Perforce command line tool. The default is default system
10717 encoding.</td>
10718 </tr>
10719 <tr class="field"><th class="field-name" colspan="2">convert.p4.startrev:</th></tr>
10720 <tr class="field"><td>&nbsp;</td><td class="field-body">specify initial Perforce revision (a
10721 Perforce changelist number).</td>
10722 </tr>
10723 </tbody>
10724 </table>
10725 </div>
10726 <div class="section" id="mercurial-destination">
10727 <h6>Mercurial Destination</h6>
10728 <p>The Mercurial destination will recognize Mercurial subrepositories in the
10729 destination directory, and update the .hgsubstate file automatically if the
10730 destination subrepositories contain the &lt;dest&gt;/&lt;sub&gt;/.hg/shamap file.
10731 Converting a repository with subrepositories requires converting a single
10732 repository at a time, from the bottom up.</p>
10733 <div class="verbose docutils container">
10734 <p>An example showing how to convert a repository with subrepositories:</p>
10735 <pre class="literal-block">
10736 # so convert knows the type when it sees a non empty destination
10737 $ hg init converted
10738
10739 $ hg convert orig/sub1 converted/sub1
10740 $ hg convert orig/sub2 converted/sub2
10741 $ hg convert orig converted
10742 </pre>
10743 </div>
10744 <p>The following options are supported:</p>
10745 <table class="docutils field-list" frame="void" rules="none">
10746 <col class="field-name" />
10747 <col class="field-body" />
10748 <tbody valign="top">
10749 <tr class="field"><th class="field-name" colspan="2">convert.hg.clonebranches:</th></tr>
10750 <tr class="field"><td>&nbsp;</td><td class="field-body">dispatch source branches in separate
10751 clones. The default is False.</td>
10752 </tr>
10753 <tr class="field"><th class="field-name" colspan="2">convert.hg.tagsbranch:</th></tr>
10754 <tr class="field"><td>&nbsp;</td><td class="field-body">branch name for tag revisions, defaults to
10755 <tt class="docutils literal">default</tt>.</td>
10756 </tr>
10757 <tr class="field"><th class="field-name" colspan="2">convert.hg.usebranchnames:</th></tr>
10758 <tr class="field"><td>&nbsp;</td><td class="field-body">preserve branch names. The default is
10759 True.</td>
10760 </tr>
10761 <tr class="field"><th class="field-name" colspan="2">convert.hg.sourcename:</th></tr>
10762 <tr class="field"><td>&nbsp;</td><td class="field-body">records the given string as a 'convert_source' extra
10763 value on each commit made in the target repository. The default is None.</td>
10764 </tr>
10765 <tr class="field"><th class="field-name" colspan="2">convert.hg.preserve-hash:</th></tr>
10766 <tr class="field"><td>&nbsp;</td><td class="field-body">only works with mercurial sources. Make convert
10767 prevent performance improvement to the list of modified files in commits
10768 when such an improvement would cause the hash of a commit to change.
10769 The default is False.</td>
10770 </tr>
10771 </tbody>
10772 </table>
10773 </div>
10774 <div class="section" id="all-destinations">
10775 <h6>All Destinations</h6>
10776 <p>All destination types accept the following options:</p>
10777 <table class="docutils field-list" frame="void" rules="none">
10778 <col class="field-name" />
10779 <col class="field-body" />
10780 <tbody valign="top">
10781 <tr class="field"><th class="field-name" colspan="2">convert.skiptags:</th></tr>
10782 <tr class="field"><td>&nbsp;</td><td class="field-body">does not convert tags from the source repo to the target
10783 repo. The default is False.</td>
10784 </tr>
10785 </tbody>
10786 </table>
10787 </div>
10788 <div class="section" id="subversion-destination">
10789 <h6>Subversion Destination</h6>
10790 <p>Original commit dates are not preserved by default.</p>
10791 <table class="docutils field-list" frame="void" rules="none">
10792 <col class="field-name" />
10793 <col class="field-body" />
10794 <tbody valign="top">
10795 <tr class="field"><th class="field-name" colspan="2">convert.svn.dangerous-set-commit-dates:</th></tr>
10796 <tr class="field"><td>&nbsp;</td><td class="field-body">preserve original commit dates,
10797 forcefully setting <tt class="docutils literal">svn:date</tt> revision properties. This option is
10798 DANGEROUS and may break some subversion functionality for the resulting
10799 repository (e.g. filtering revisions with date ranges in <tt class="docutils literal">svn log</tt>),
10800 as original commit dates are not guaranteed to be monotonically
10801 increasing.</td>
10802 </tr>
10803 </tbody>
10804 </table>
10805 <p>For commit dates setting to work destination repository must have
10806 <tt class="docutils literal"><span class="pre">pre-revprop-change</span></tt> hook configured to allow setting of <tt class="docutils literal">svn:date</tt>
10807 revision properties. See Subversion documentation for more details.</p>
10808 <p>Options:</p>
10809 <table class="docutils option-list" frame="void" rules="none">
10810 <col class="option" />
10811 <col class="description" />
10812 <tbody valign="top">
10813 <tr><td class="option-group" colspan="2">
10814 <kbd><span class="option">--authors <var>&lt;FILE&gt;</var></span></kbd></td>
10815 </tr>
10816 <tr><td>&nbsp;</td><td>username mapping filename (DEPRECATED) (use --authormap instead)</td></tr>
10817 <tr><td class="option-group" colspan="2">
10818 <kbd><span class="option">-s</span>, <span class="option">--source-type <var>&lt;TYPE&gt;</var></span></kbd></td>
10819 </tr>
10820 <tr><td>&nbsp;</td><td>source repository type</td></tr>
10821 <tr><td class="option-group" colspan="2">
10822 <kbd><span class="option">-d</span>, <span class="option">--dest-type <var>&lt;TYPE&gt;</var></span></kbd></td>
10823 </tr>
10824 <tr><td>&nbsp;</td><td>destination repository type</td></tr>
10825 <tr><td class="option-group" colspan="2">
10826 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
10827 </tr>
10828 <tr><td>&nbsp;</td><td>import up to source revision REV</td></tr>
10829 <tr><td class="option-group" colspan="2">
10830 <kbd><span class="option">-A</span>, <span class="option">--authormap <var>&lt;FILE&gt;</var></span></kbd></td>
10831 </tr>
10832 <tr><td>&nbsp;</td><td>remap usernames using this file</td></tr>
10833 <tr><td class="option-group" colspan="2">
10834 <kbd><span class="option">--filemap <var>&lt;FILE&gt;</var></span></kbd></td>
10835 </tr>
10836 <tr><td>&nbsp;</td><td>remap file names using contents of file</td></tr>
10837 <tr><td class="option-group">
10838 <kbd><span class="option">--full</span></kbd></td>
10839 <td>apply filemap changes by converting all files again</td></tr>
10840 <tr><td class="option-group" colspan="2">
10841 <kbd><span class="option">--splicemap <var>&lt;FILE&gt;</var></span></kbd></td>
10842 </tr>
10843 <tr><td>&nbsp;</td><td>splice synthesized history into place</td></tr>
10844 <tr><td class="option-group" colspan="2">
10845 <kbd><span class="option">--branchmap <var>&lt;FILE&gt;</var></span></kbd></td>
10846 </tr>
10847 <tr><td>&nbsp;</td><td>change branch names while converting</td></tr>
10848 <tr><td class="option-group">
10849 <kbd><span class="option">--branchsort</span></kbd></td>
10850 <td>try to sort changesets by branches</td></tr>
10851 <tr><td class="option-group">
10852 <kbd><span class="option">--datesort</span></kbd></td>
10853 <td>try to sort changesets by date</td></tr>
10854 <tr><td class="option-group">
10855 <kbd><span class="option">--sourcesort</span></kbd></td>
10856 <td>preserve source changesets order</td></tr>
10857 <tr><td class="option-group">
10858 <kbd><span class="option">--closesort</span></kbd></td>
10859 <td>try to reorder closed revisions</td></tr>
10860 </tbody>
10861 </table>
10862 <p>[+] marked option can be specified multiple times</p>
10863 </div>
10864 </div>
10865 </div>
10866 </div>
10867 </div>
10868 <div class="section" id="eol">
10869 <h2><a class="toc-backref" href="#toc-entry-52">eol</a></h2>
10870 <p>automatically manage newlines in repository files</p>
10871 <p>This extension allows you to manage the type of line endings (CRLF or
10872 LF) that are used in the repository and in the local working
10873 directory. That way you can get CRLF line endings on Windows and LF on
10874 Unix/Mac, thereby letting everybody use their OS native line endings.</p>
10875 <p>The extension reads its configuration from a versioned <tt class="docutils literal">.hgeol</tt>
10876 configuration file found in the root of the working directory. The
10877 <tt class="docutils literal">.hgeol</tt> file use the same syntax as all other Mercurial
10878 configuration files. It uses two sections, <tt class="docutils literal">[patterns]</tt> and
10879 <tt class="docutils literal">[repository]</tt>.</p>
10880 <p>The <tt class="docutils literal">[patterns]</tt> section specifies how line endings should be
10881 converted between the working directory and the repository. The format is
10882 specified by a file pattern. The first match is used, so put more
10883 specific patterns first. The available line endings are <tt class="docutils literal">LF</tt>,
10884 <tt class="docutils literal">CRLF</tt>, and <tt class="docutils literal">BIN</tt>.</p>
10885 <p>Files with the declared format of <tt class="docutils literal">CRLF</tt> or <tt class="docutils literal">LF</tt> are always
10886 checked out and stored in the repository in that format and files
10887 declared to be binary (<tt class="docutils literal">BIN</tt>) are left unchanged. Additionally,
10888 <tt class="docutils literal">native</tt> is an alias for checking out in the platform's default line
10889 ending: <tt class="docutils literal">LF</tt> on Unix (including Mac OS X) and <tt class="docutils literal">CRLF</tt> on
10890 Windows. Note that <tt class="docutils literal">BIN</tt> (do nothing to line endings) is Mercurial's
10891 default behavior; it is only needed if you need to override a later,
10892 more general pattern.</p>
10893 <p>The optional <tt class="docutils literal">[repository]</tt> section specifies the line endings to
10894 use for files stored in the repository. It has a single setting,
10895 <tt class="docutils literal">native</tt>, which determines the storage line endings for files
10896 declared as <tt class="docutils literal">native</tt> in the <tt class="docutils literal">[patterns]</tt> section. It can be set to
10897 <tt class="docutils literal">LF</tt> or <tt class="docutils literal">CRLF</tt>. The default is <tt class="docutils literal">LF</tt>. For example, this means
10898 that on Windows, files configured as <tt class="docutils literal">native</tt> (<tt class="docutils literal">CRLF</tt> by default)
10899 will be converted to <tt class="docutils literal">LF</tt> when stored in the repository. Files
10900 declared as <tt class="docutils literal">LF</tt>, <tt class="docutils literal">CRLF</tt>, or <tt class="docutils literal">BIN</tt> in the <tt class="docutils literal">[patterns]</tt> section
10901 are always stored as-is in the repository.</p>
10902 <p>Example versioned <tt class="docutils literal">.hgeol</tt> file:</p>
10903 <pre class="literal-block">
10904 [patterns]
10905 **.py = native
10906 **.vcproj = CRLF
10907 **.txt = native
10908 Makefile = LF
10909 **.jpg = BIN
10910
10911 [repository]
10912 native = LF
10913 </pre>
10914 <div class="admonition note">
10915 <p class="first admonition-title">Note</p>
10916 <p class="last">The rules will first apply when files are touched in the working
10917 directory, e.g. by updating to null and back to tip to touch all files.</p>
10918 </div>
10919 <p>The extension uses an optional <tt class="docutils literal">[eol]</tt> section read from both the
10920 normal Mercurial configuration files and the <tt class="docutils literal">.hgeol</tt> file, with the
10921 latter overriding the former. You can use that section to control the
10922 overall behavior. There are three settings:</p>
10923 <ul class="simple">
10924 <li><tt class="docutils literal">eol.native</tt> (default <tt class="docutils literal">os.linesep</tt>) can be set to <tt class="docutils literal">LF</tt> or
10925 <tt class="docutils literal">CRLF</tt> to override the default interpretation of <tt class="docutils literal">native</tt> for
10926 checkout. This can be used with <a class="reference external" href="hg.1.html#archive"><tt class="docutils literal">hg archive</tt></a> on Unix, say, to
10927 generate an archive where files have line endings for Windows.</li>
10928 <li><tt class="docutils literal"><span class="pre">eol.only-consistent</span></tt> (default True) can be set to False to make
10929 the extension convert files with inconsistent EOLs. Inconsistent
10930 means that there is both <tt class="docutils literal">CRLF</tt> and <tt class="docutils literal">LF</tt> present in the file.
10931 Such files are normally not touched under the assumption that they
10932 have mixed EOLs on purpose.</li>
10933 <li><tt class="docutils literal"><span class="pre">eol.fix-trailing-newline</span></tt> (default False) can be set to True to
10934 ensure that converted files end with a EOL character (either <tt class="docutils literal">\n</tt>
10935 or <tt class="docutils literal">\r\n</tt> as per the configured patterns).</li>
10936 </ul>
10937 <p>The extension provides <tt class="docutils literal">cleverencode:</tt> and <tt class="docutils literal">cleverdecode:</tt> filters
10938 like the deprecated win32text extension does. This means that you can
10939 disable win32text and enable eol and your filters will still work. You
10940 only need to these filters until you have prepared a <tt class="docutils literal">.hgeol</tt> file.</p>
10941 <p>The <tt class="docutils literal">win32text.forbid*</tt> hooks provided by the win32text extension
10942 have been unified into a single hook named <tt class="docutils literal">eol.checkheadshook</tt>. The
10943 hook will lookup the expected line endings from the <tt class="docutils literal">.hgeol</tt> file,
10944 which means you must migrate to a <tt class="docutils literal">.hgeol</tt> file first before using
10945 the hook. <tt class="docutils literal">eol.checkheadshook</tt> only checks heads, intermediate
10946 invalid revisions will be pushed. To forbid them completely, use the
10947 <tt class="docutils literal">eol.checkallhook</tt> hook. These hooks are best used as
10948 <tt class="docutils literal">pretxnchangegroup</tt> hooks.</p>
10949 <p>See <a class="reference external" href="hg.1.html#patterns"><tt class="docutils literal">hg help patterns</tt></a> for more information about the glob patterns
10950 used.</p>
10951 </div>
10952 <div class="section" id="extdiff">
10953 <h2><a class="toc-backref" href="#toc-entry-53">extdiff</a></h2>
10954 <p>command to allow external programs to compare revisions</p>
10955 <p>The extdiff Mercurial extension allows you to use external programs
10956 to compare revisions, or revision with working directory. The external
10957 diff programs are called with a configurable set of options and two
10958 non-option arguments: paths to directories containing snapshots of
10959 files to compare.</p>
10960 <p>If there is more than one file being compared and the &quot;child&quot; revision
10961 is the working directory, any modifications made in the external diff
10962 program will be copied back to the working directory from the temporary
10963 directory.</p>
10964 <p>The extdiff extension also allows you to configure new diff commands, so
10965 you do not need to type <a class="reference external" href="hg.1.html#extdiff"><tt class="docutils literal">hg extdiff <span class="pre">-p</span> kdiff3</tt></a> always.</p>
10966 <pre class="literal-block">
10967 [extdiff]
10968 # add new command that runs GNU diff(1) in 'context diff' mode
10969 cdiff = gdiff -Nprc5
10970 ## or the old way:
10971 #cmd.cdiff = gdiff
10972 #opts.cdiff = -Nprc5
10973
10974 # add new command called meld, runs meld (no need to name twice). If
10975 # the meld executable is not available, the meld tool in [merge-tools]
10976 # will be used, if available
10977 meld =
10978
10979 # add new command called vimdiff, runs gvimdiff with DirDiff plugin
10980 # (see http://www.vim.org/scripts/script.php?script_id=102) Non
10981 # English user, be sure to put &quot;let g:DirDiffDynamicDiffText = 1&quot; in
10982 # your .vimrc
10983 vimdiff = gvim -f &quot;+next&quot; \
10984 &quot;+execute 'DirDiff' fnameescape(argv(0)) fnameescape(argv(1))&quot;
10985 </pre>
10986 <p>Tool arguments can include variables that are expanded at runtime:</p>
10987 <pre class="literal-block">
10988 $parent1, $plabel1 - filename, descriptive label of first parent
10989 $child, $clabel - filename, descriptive label of child revision
10990 $parent2, $plabel2 - filename, descriptive label of second parent
10991 $root - repository root
10992 $parent is an alias for $parent1.
10993 </pre>
10994 <p>The extdiff extension will look in your [diff-tools] and [merge-tools]
10995 sections for diff tool arguments, when none are specified in [extdiff].</p>
10996 <pre class="literal-block">
10997 [extdiff]
10998 kdiff3 =
10999
11000 [diff-tools]
11001 kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
11002 </pre>
11003 <p>If a program has a graphical interface, it might be interesting to tell
11004 Mercurial about it. It will prevent the program from being mistakenly
11005 used in a terminal-only environment (such as an SSH terminal session),
11006 and will make <a class="reference external" href="hg.1.html#extdiff"><tt class="docutils literal">hg extdiff <span class="pre">--per-file</span></tt></a> open multiple file diffs at once
11007 instead of one by one (if you still want to open file diffs one by one,
11008 you can use the --confirm option).</p>
11009 <p>Declaring that a tool has a graphical interface can be done with the
11010 <tt class="docutils literal">gui</tt> flag next to where <tt class="docutils literal">diffargs</tt> are specified:</p>
11011 <pre class="literal-block">
11012 [diff-tools]
11013 kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
11014 kdiff3.gui = true
11015 </pre>
11016 <p>You can use -I/-X and list of file or directory names like normal
11017 <a class="reference external" href="hg.1.html#diff"><tt class="docutils literal">hg diff</tt></a> command. The extdiff extension makes snapshots of only
11018 needed files, so running the external diff program will actually be
11019 pretty fast (at least faster than having to compare the entire tree).</p>
11020 <div class="section" id="commands-11">
11021 <h3>Commands</h3>
11022 <div class="section" id="file-content-management-1">
11023 <h4>File content management</h4>
11024 <div class="section" id="extdiff-1">
11025 <h5>extdiff</h5>
11026 <p>use external program to diff repository (or selected files):</p>
11027 <pre class="literal-block">
11028 hg extdiff [OPT]... [FILE]...
11029 </pre>
11030 <p>Show differences between revisions for the specified files, using
11031 an external program. The default program used is diff, with
11032 default options &quot;-Npru&quot;.</p>
11033 <p>To select a different program, use the -p/--program option. The
11034 program will be passed the names of two directories to compare,
11035 unless the --per-file option is specified (see below). To pass
11036 additional options to the program, use -o/--option. These will be
11037 passed before the names of the directories or files to compare.</p>
11038 <p>The --from, --to, and --change options work the same way they do for
11039 <a class="reference external" href="hg.1.html#diff"><tt class="docutils literal">hg diff</tt></a>.</p>
11040 <p>The --per-file option runs the external program repeatedly on each
11041 file to diff, instead of once on two directories. By default,
11042 this happens one by one, where the next file diff is open in the
11043 external program only once the previous external program (for the
11044 previous file diff) has exited. If the external program has a
11045 graphical interface, it can open all the file diffs at once instead
11046 of one by one. See <a class="reference external" href="hg.1.html#-e"><tt class="docutils literal">hg help <span class="pre">-e</span> extdiff</tt></a> for information about how
11047 to tell Mercurial that a given program has a graphical interface.</p>
11048 <p>The --confirm option will prompt the user before each invocation of
11049 the external program. It is ignored if --per-file isn't specified.</p>
11050 <p>Options:</p>
11051 <table class="docutils option-list" frame="void" rules="none">
11052 <col class="option" />
11053 <col class="description" />
11054 <tbody valign="top">
11055 <tr><td class="option-group" colspan="2">
11056 <kbd><span class="option">-p</span>, <span class="option">--program <var>&lt;CMD&gt;</var></span></kbd></td>
11057 </tr>
11058 <tr><td>&nbsp;</td><td>comparison program to run</td></tr>
11059 <tr><td class="option-group" colspan="2">
11060 <kbd><span class="option">-o</span>, <span class="option">--option <var>&lt;OPT[+]&gt;</var></span></kbd></td>
11061 </tr>
11062 <tr><td>&nbsp;</td><td>pass option to comparison program</td></tr>
11063 <tr><td class="option-group" colspan="2">
11064 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
11065 </tr>
11066 <tr><td>&nbsp;</td><td>revision (DEPRECATED)</td></tr>
11067 <tr><td class="option-group">
11068 <kbd><span class="option">--from <var>&lt;REV1&gt;</var></span></kbd></td>
11069 <td>revision to diff from</td></tr>
11070 <tr><td class="option-group">
11071 <kbd><span class="option">--to <var>&lt;REV2&gt;</var></span></kbd></td>
11072 <td>revision to diff to</td></tr>
11073 <tr><td class="option-group" colspan="2">
11074 <kbd><span class="option">-c</span>, <span class="option">--change <var>&lt;REV&gt;</var></span></kbd></td>
11075 </tr>
11076 <tr><td>&nbsp;</td><td>change made by revision</td></tr>
11077 <tr><td class="option-group">
11078 <kbd><span class="option">--per-file</span></kbd></td>
11079 <td>compare each file instead of revision snapshots</td></tr>
11080 <tr><td class="option-group">
11081 <kbd><span class="option">--confirm</span></kbd></td>
11082 <td>prompt user before each external program invocation</td></tr>
11083 <tr><td class="option-group">
11084 <kbd><span class="option">--patch</span></kbd></td>
11085 <td>compare patches for two revisions</td></tr>
11086 <tr><td class="option-group" colspan="2">
11087 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
11088 </tr>
11089 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
11090 <tr><td class="option-group" colspan="2">
11091 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
11092 </tr>
11093 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
11094 <tr><td class="option-group">
11095 <kbd><span class="option">-S</span>, <span class="option">--subrepos</span></kbd></td>
11096 <td>recurse into subrepositories</td></tr>
11097 </tbody>
11098 </table>
11099 <p>[+] marked option can be specified multiple times</p>
11100 </div>
11101 </div>
11102 </div>
11103 </div>
11104 <div class="section" id="factotum">
11105 <h2><a class="toc-backref" href="#toc-entry-54">factotum</a></h2>
11106 <p>http authentication with factotum</p>
11107 <p>This extension allows the factotum(4) facility on Plan 9 from Bell Labs
11108 platforms to provide authentication information for HTTP access. Configuration
11109 entries specified in the auth section as well as authentication information
11110 provided in the repository URL are fully supported. If no prefix is specified,
11111 a value of &quot;*&quot; will be assumed.</p>
11112 <p>By default, keys are specified as:</p>
11113 <pre class="literal-block">
11114 proto=pass service=hg prefix=&lt;prefix&gt; user=&lt;username&gt; !password=&lt;password&gt;
11115 </pre>
11116 <p>If the factotum extension is unable to read the required key, one will be
11117 requested interactively.</p>
11118 <p>A configuration section is available to customize runtime behavior. By
11119 default, these entries are:</p>
11120 <pre class="literal-block">
11121 [factotum]
11122 executable = /bin/auth/factotum
11123 mountpoint = /mnt/factotum
11124 service = hg
11125 </pre>
11126 <p>The executable entry defines the full path to the factotum binary. The
11127 mountpoint entry defines the path to the factotum file service. Lastly, the
11128 service entry controls the service name used when reading keys.</p>
11129 </div>
11130 <div class="section" id="fastannotate">
11131 <h2><a class="toc-backref" href="#toc-entry-55">fastannotate</a></h2>
11132 <p>yet another annotate implementation that might be faster (EXPERIMENTAL)</p>
11133 <p>The fastannotate extension provides a 'fastannotate' command that makes
11134 use of the linelog data structure as a cache layer and is expected to
11135 be faster than the vanilla 'annotate' if the cache is present.</p>
11136 <p>In most cases, fastannotate requires a setup that mainbranch is some pointer
11137 that always moves forward, to be most efficient.</p>
11138 <p>Using fastannotate together with linkrevcache would speed up building the
11139 annotate cache greatly. Run &quot;debugbuildlinkrevcache&quot; before
11140 &quot;debugbuildannotatecache&quot;.</p>
11141 <pre class="literal-block">
11142 [fastannotate]
11143 # specify the main branch head. the internal linelog will only contain
11144 # the linear (ignoring p2) &quot;mainbranch&quot;. since linelog cannot move
11145 # backwards without a rebuild, this should be something that always moves
11146 # forward, usually it is &quot;master&quot; or &quot;&#64;&quot;.
11147 mainbranch = master
11148
11149 # fastannotate supports different modes to expose its feature.
11150 # a list of combination:
11151 # - fastannotate: expose the feature via the &quot;fastannotate&quot; command which
11152 # deals with everything in a most efficient way, and provides extra
11153 # features like --deleted etc.
11154 # - fctx: replace fctx.annotate implementation. note:
11155 # a. it is less efficient than the &quot;fastannotate&quot; command
11156 # b. it will make it practically impossible to access the old (disk
11157 # side-effect free) annotate implementation
11158 # c. it implies &quot;hgweb&quot;.
11159 # - hgweb: replace hgweb's annotate implementation. conflict with &quot;fctx&quot;.
11160 # (default: fastannotate)
11161 modes = fastannotate
11162
11163 # default format when no format flags are used (default: number)
11164 defaultformat = changeset, user, date
11165
11166 # serve the annotate cache via wire protocol (default: False)
11167 # tip: the .hg/fastannotate directory is portable - can be rsynced
11168 server = True
11169
11170 # build annotate cache on demand for every client request (default: True)
11171 # disabling it could make server response faster, useful when there is a
11172 # cronjob building the cache.
11173 serverbuildondemand = True
11174
11175 # update local annotate cache from remote on demand
11176 client = False
11177
11178 # path to use when connecting to the remote server (default: default)
11179 remotepath = default
11180
11181 # minimal length of the history of a file required to fetch linelog from
11182 # the server. (default: 10)
11183 clientfetchthreshold = 10
11184
11185 # for &quot;fctx&quot; mode, always follow renames regardless of command line option.
11186 # this is a BC with the original command but will reduced the space needed
11187 # for annotate cache, and is useful for client-server setup since the
11188 # server will only provide annotate cache with default options (i.e. with
11189 # follow). do not affect &quot;fastannotate&quot; mode. (default: True)
11190 forcefollow = True
11191
11192 # for &quot;fctx&quot; mode, always treat file as text files, to skip the &quot;isbinary&quot;
11193 # check. this is consistent with the &quot;fastannotate&quot; command and could help
11194 # to avoid a file fetch if remotefilelog is used. (default: True)
11195 forcetext = True
11196
11197 # use unfiltered repo for better performance.
11198 unfilteredrepo = True
11199
11200 # sacrifice correctness in some corner cases for performance. it does not
11201 # affect the correctness of the annotate cache being built. the option
11202 # is experimental and may disappear in the future (default: False)
11203 perfhack = True
11204 </pre>
11205 <div class="section" id="commands-12">
11206 <h3>Commands</h3>
11207 </div>
11208 </div>
11209 <div class="section" id="fastexport">
11210 <h2><a class="toc-backref" href="#toc-entry-56">fastexport</a></h2>
11211 <p>export repositories as git fast-import stream</p>
11212 <div class="section" id="commands-13">
11213 <h3>Commands</h3>
11214 <div class="section" id="change-import-export-1">
11215 <h4>Change import/export</h4>
11216 <div class="section" id="fastexport-1">
11217 <h5>fastexport</h5>
11218 <p>export repository as git fast-import stream:</p>
11219 <pre class="literal-block">
11220 hg fastexport [OPTION]... [REV]...
11221 </pre>
11222 <p>This command lets you dump a repository as a human-readable text stream.
11223 It can be piped into corresponding import routines like &quot;git fast-import&quot;.
11224 Incremental dumps can be created by using marks files.</p>
11225 <p>Options:</p>
11226 <table class="docutils option-list" frame="void" rules="none">
11227 <col class="option" />
11228 <col class="description" />
11229 <tbody valign="top">
11230 <tr><td class="option-group" colspan="2">
11231 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
11232 </tr>
11233 <tr><td>&nbsp;</td><td>revisions to export</td></tr>
11234 <tr><td class="option-group" colspan="2">
11235 <kbd><span class="option">-i</span>, <span class="option">--import-marks <var>&lt;FILE&gt;</var></span></kbd></td>
11236 </tr>
11237 <tr><td>&nbsp;</td><td>old marks file to read</td></tr>
11238 <tr><td class="option-group" colspan="2">
11239 <kbd><span class="option">-e</span>, <span class="option">--export-marks <var>&lt;FILE&gt;</var></span></kbd></td>
11240 </tr>
11241 <tr><td>&nbsp;</td><td>new marks file to write</td></tr>
11242 <tr><td class="option-group" colspan="2">
11243 <kbd><span class="option">-A</span>, <span class="option">--authormap <var>&lt;FILE&gt;</var></span></kbd></td>
11244 </tr>
11245 <tr><td>&nbsp;</td><td>remap usernames using this file</td></tr>
11246 </tbody>
11247 </table>
11248 <p>[+] marked option can be specified multiple times</p>
11249 </div>
11250 </div>
11251 </div>
11252 </div>
11253 <div class="section" id="fetch">
11254 <h2><a class="toc-backref" href="#toc-entry-57">fetch</a></h2>
11255 <p>pull, update and merge in one command (DEPRECATED)</p>
11256 <div class="section" id="commands-14">
11257 <h3>Commands</h3>
11258 <div class="section" id="remote-repository-management-1">
11259 <h4>Remote repository management</h4>
11260 <div class="section" id="fetch-1">
11261 <h5>fetch</h5>
11262 <p>pull changes from a remote repository, merge new changes if needed.:</p>
11263 <pre class="literal-block">
11264 hg fetch [SOURCE]
11265 </pre>
11266 <p>This finds all changes from the repository at the specified path
11267 or URL and adds them to the local repository.</p>
11268 <p>If the pulled changes add a new branch head, the head is
11269 automatically merged, and the result of the merge is committed.
11270 Otherwise, the working directory is updated to include the new
11271 changes.</p>
11272 <p>When a merge is needed, the working directory is first updated to
11273 the newly pulled changes. Local changes are then merged into the
11274 pulled changes. To switch the merge order, use --switch-parent.</p>
11275 <p>See <a class="reference external" href="hg.1.html#dates"><tt class="docutils literal">hg help dates</tt></a> for a list of formats valid for -d/--date.</p>
11276 <p>Returns 0 on success.</p>
11277 <p>Options:</p>
11278 <table class="docutils option-list" frame="void" rules="none">
11279 <col class="option" />
11280 <col class="description" />
11281 <tbody valign="top">
11282 <tr><td class="option-group" colspan="2">
11283 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
11284 </tr>
11285 <tr><td>&nbsp;</td><td>a specific revision you would like to pull</td></tr>
11286 <tr><td class="option-group">
11287 <kbd><span class="option">--edit</span></kbd></td>
11288 <td>invoke editor on commit messages</td></tr>
11289 <tr><td class="option-group">
11290 <kbd><span class="option">--force-editor</span></kbd></td>
11291 <td>edit commit message (DEPRECATED)</td></tr>
11292 <tr><td class="option-group" colspan="2">
11293 <kbd><span class="option">--switch-parent</span></kbd></td>
11294 </tr>
11295 <tr><td>&nbsp;</td><td>switch parents when merging</td></tr>
11296 <tr><td class="option-group" colspan="2">
11297 <kbd><span class="option">-m</span>, <span class="option">--message <var>&lt;TEXT&gt;</var></span></kbd></td>
11298 </tr>
11299 <tr><td>&nbsp;</td><td>use text as commit message</td></tr>
11300 <tr><td class="option-group" colspan="2">
11301 <kbd><span class="option">-l</span>, <span class="option">--logfile <var>&lt;FILE&gt;</var></span></kbd></td>
11302 </tr>
11303 <tr><td>&nbsp;</td><td>read commit message from file</td></tr>
11304 <tr><td class="option-group" colspan="2">
11305 <kbd><span class="option">-d</span>, <span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
11306 </tr>
11307 <tr><td>&nbsp;</td><td>record the specified date as commit date</td></tr>
11308 <tr><td class="option-group" colspan="2">
11309 <kbd><span class="option">-u</span>, <span class="option">--user <var>&lt;USER&gt;</var></span></kbd></td>
11310 </tr>
11311 <tr><td>&nbsp;</td><td>record the specified user as committer</td></tr>
11312 <tr><td class="option-group" colspan="2">
11313 <kbd><span class="option">-e</span>, <span class="option">--ssh <var>&lt;CMD&gt;</var></span></kbd></td>
11314 </tr>
11315 <tr><td>&nbsp;</td><td>specify ssh command to use</td></tr>
11316 <tr><td class="option-group" colspan="2">
11317 <kbd><span class="option">--remotecmd <var>&lt;CMD&gt;</var></span></kbd></td>
11318 </tr>
11319 <tr><td>&nbsp;</td><td>specify hg command to run on the remote side</td></tr>
11320 <tr><td class="option-group">
11321 <kbd><span class="option">--insecure</span></kbd></td>
11322 <td>do not verify server certificate (ignoring web.cacerts config)</td></tr>
11323 </tbody>
11324 </table>
11325 <p>[+] marked option can be specified multiple times</p>
11326 </div>
11327 </div>
11328 </div>
11329 </div>
11330 <div class="section" id="fix">
11331 <h2><a class="toc-backref" href="#toc-entry-58">fix</a></h2>
11332 <p>rewrite file content in changesets or working copy (EXPERIMENTAL)</p>
11333 <p>Provides a command that runs configured tools on the contents of modified files,
11334 writing back any fixes to the working copy or replacing changesets.</p>
11335 <p>Fixer tools are run in the repository's root directory. This allows them to read
11336 configuration files from the working copy, or even write to the working copy.
11337 The working copy is not updated to match the revision being fixed. In fact,
11338 several revisions may be fixed in parallel. Writes to the working copy are not
11339 amended into the revision being fixed; fixer tools MUST always read content to
11340 be fixed from stdin, and write fixed file content back to stdout.</p>
11341 <p>Here is an example configuration that causes <a class="reference external" href="hg.1.html#fix"><tt class="docutils literal">hg fix</tt></a> to apply automatic
11342 formatting fixes to modified lines in C++ code:</p>
11343 <pre class="literal-block">
11344 [fix]
11345 clang-format:command=clang-format --assume-filename={rootpath}
11346 clang-format:linerange=--lines={first}:{last}
11347 clang-format:pattern=set:**.cpp or **.hpp
11348 </pre>
11349 <p>The :command suboption forms the first part of the shell command that will be
11350 used to fix a file. The content of the file is passed on standard input, and the
11351 fixed file content is expected on standard output. Any output on standard error
11352 will be displayed as a warning. If the exit status is not zero, the file will
11353 not be affected. A placeholder warning is displayed if there is a non-zero exit
11354 status but no standard error output. Some values may be substituted into the
11355 command:</p>
11356 <pre class="literal-block">
11357 {rootpath} The path of the file being fixed, relative to the repo root
11358 {basename} The name of the file being fixed, without the directory path
11359 </pre>
11360 <p>If the :linerange suboption is set, the tool will only be run if there are
11361 changed lines in a file. The value of this suboption is appended to the shell
11362 command once for every range of changed lines in the file. Some values may be
11363 substituted into the command:</p>
11364 <pre class="literal-block">
11365 {first} The 1-based line number of the first line in the modified range
11366 {last} The 1-based line number of the last line in the modified range
11367 </pre>
11368 <p>Deleted sections of a file will be ignored by :linerange, because there is no
11369 corresponding line range in the version being fixed.</p>
11370 <p>By default, tools that set :linerange will only be executed if there is at least
11371 one changed line range. This is meant to prevent accidents like running a code
11372 formatter in such a way that it unexpectedly reformats the whole file. If such a
11373 tool needs to operate on unchanged files, it should set the :skipclean suboption
11374 to false.</p>
11375 <p>The :pattern suboption determines which files will be passed through each
11376 configured tool. See <a class="reference external" href="hg.1.html#patterns"><tt class="docutils literal">hg help patterns</tt></a> for possible values. However, all
11377 patterns are relative to the repo root, even if that text says they are relative
11378 to the current working directory. If there are file arguments to <a class="reference external" href="hg.1.html#fix"><tt class="docutils literal">hg fix</tt></a>, the
11379 intersection of these patterns is used.</p>
11380 <p>There is also a configurable limit for the maximum size of file that will be
11381 processed by <a class="reference external" href="hg.1.html#fix"><tt class="docutils literal">hg fix</tt></a>:</p>
11382 <pre class="literal-block">
11383 [fix]
11384 maxfilesize = 2MB
11385 </pre>
11386 <p>Normally, execution of configured tools will continue after a failure (indicated
11387 by a non-zero exit status). It can also be configured to abort after the first
11388 such failure, so that no files will be affected if any tool fails. This abort
11389 will also cause <a class="reference external" href="hg.1.html#fix"><tt class="docutils literal">hg fix</tt></a> to exit with a non-zero status:</p>
11390 <pre class="literal-block">
11391 [fix]
11392 failure = abort
11393 </pre>
11394 <p>When multiple tools are configured to affect a file, they execute in an order
11395 defined by the :priority suboption. The priority suboption has a default value
11396 of zero for each tool. Tools are executed in order of descending priority. The
11397 execution order of tools with equal priority is unspecified. For example, you
11398 could use the 'sort' and 'head' utilities to keep only the 10 smallest numbers
11399 in a text file by ensuring that 'sort' runs before 'head':</p>
11400 <pre class="literal-block">
11401 [fix]
11402 sort:command = sort -n
11403 head:command = head -n 10
11404 sort:pattern = numbers.txt
11405 head:pattern = numbers.txt
11406 sort:priority = 2
11407 head:priority = 1
11408 </pre>
11409 <p>To account for changes made by each tool, the line numbers used for incremental
11410 formatting are recomputed before executing the next tool. So, each tool may see
11411 different values for the arguments added by the :linerange suboption.</p>
11412 <p>Each fixer tool is allowed to return some metadata in addition to the fixed file
11413 content. The metadata must be placed before the file content on stdout,
11414 separated from the file content by a zero byte. The metadata is parsed as a JSON
11415 value (so, it should be UTF-8 encoded and contain no zero bytes). A fixer tool
11416 is expected to produce this metadata encoding if and only if the :metadata
11417 suboption is true:</p>
11418 <pre class="literal-block">
11419 [fix]
11420 tool:command = tool --prepend-json-metadata
11421 tool:metadata = true
11422 </pre>
11423 <p>The metadata values are passed to hooks, which can be used to print summaries or
11424 perform other post-fixing work. The supported hooks are:</p>
11425 <pre class="literal-block">
11426 &quot;postfixfile&quot;
11427 Run once for each file in each revision where any fixer tools made changes
11428 to the file content. Provides &quot;$HG_REV&quot; and &quot;$HG_PATH&quot; to identify the file,
11429 and &quot;$HG_METADATA&quot; with a map of fixer names to metadata values from fixer
11430 tools that affected the file. Fixer tools that didn't affect the file have a
11431 value of None. Only fixer tools that executed are present in the metadata.
11432
11433 &quot;postfix&quot;
11434 Run once after all files and revisions have been handled. Provides
11435 &quot;$HG_REPLACEMENTS&quot; with information about what revisions were created and
11436 made obsolete. Provides a boolean &quot;$HG_WDIRWRITTEN&quot; to indicate whether any
11437 files in the working copy were updated. Provides a list &quot;$HG_METADATA&quot;
11438 mapping fixer tool names to lists of metadata values returned from
11439 executions that modified a file. This aggregates the same metadata
11440 previously passed to the &quot;postfixfile&quot; hook.
11441 </pre>
11442 <p>You can specify a list of directories to search the tool command in using the
11443 <cite>fix.extra-bin-paths</cite> configuration.</p>
11444 <div class="section" id="commands-15">
11445 <h3>Commands</h3>
11446 <div class="section" id="file-content-management-2">
11447 <h4>File content management</h4>
11448 <div class="section" id="fix-1">
11449 <h5>fix</h5>
11450 <p>rewrite file content in changesets or working directory:</p>
11451 <pre class="literal-block">
11452 hg fix [OPTION]... [FILE]...
11453 </pre>
11454 <p>Runs any configured tools to fix the content of files. (See
11455 <a class="reference external" href="hg.1.html#-e"><tt class="docutils literal">hg help <span class="pre">-e</span> fix</tt></a> for details about configuring tools.) Only affects files
11456 with changes, unless file arguments are provided. Only affects changed lines
11457 of files, unless the --whole flag is used. Some tools may always affect the
11458 whole file regardless of --whole.</p>
11459 <p>If --working-dir is used, files with uncommitted changes in the working copy
11460 will be fixed. Note that no backup are made.</p>
11461 <p>If revisions are specified with --source, those revisions and their
11462 descendants will be checked, and they may be replaced with new revisions
11463 that have fixed file content. By automatically including the descendants,
11464 no merging, rebasing, or evolution will be required. If an ancestor of the
11465 working copy is included, then the working copy itself will also be fixed,
11466 and the working copy will be updated to the fixed parent.</p>
11467 <p>When determining what lines of each file to fix at each revision, the whole
11468 set of revisions being fixed is considered, so that fixes to earlier
11469 revisions are not forgotten in later ones. The --base flag can be used to
11470 override this default behavior, though it is not usually desirable to do so.</p>
11471 <p>Options:</p>
11472 <table class="docutils option-list" frame="void" rules="none">
11473 <col class="option" />
11474 <col class="description" />
11475 <tbody valign="top">
11476 <tr><td class="option-group">
11477 <kbd><span class="option">--all</span></kbd></td>
11478 <td>fix all non-public non-obsolete revisions</td></tr>
11479 <tr><td class="option-group" colspan="2">
11480 <kbd><span class="option">--base <var>&lt;REV[+]&gt;</var></span></kbd></td>
11481 </tr>
11482 <tr><td>&nbsp;</td><td>revisions to diff against (overrides automatic selection, and applies to every revision being fixed)</td></tr>
11483 <tr><td class="option-group" colspan="2">
11484 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
11485 </tr>
11486 <tr><td>&nbsp;</td><td>revisions to fix (ADVANCED)</td></tr>
11487 <tr><td class="option-group" colspan="2">
11488 <kbd><span class="option">-s</span>, <span class="option">--source <var>&lt;REV[+]&gt;</var></span></kbd></td>
11489 </tr>
11490 <tr><td>&nbsp;</td><td>fix the specified revisions and their descendants</td></tr>
11491 <tr><td class="option-group" colspan="2">
11492 <kbd><span class="option">-w</span>, <span class="option">--working-dir</span></kbd></td>
11493 </tr>
11494 <tr><td>&nbsp;</td><td>fix the working directory</td></tr>
11495 <tr><td class="option-group">
11496 <kbd><span class="option">--whole</span></kbd></td>
11497 <td>always fix every line of a file</td></tr>
11498 </tbody>
11499 </table>
11500 <p>[+] marked option can be specified multiple times</p>
11501 </div>
11502 </div>
11503 </div>
11504 </div>
11505 <div class="section" id="fsmonitor">
11506 <h2><a class="toc-backref" href="#toc-entry-59">fsmonitor</a></h2>
11507 <p>Faster status operations with the Watchman file monitor (EXPERIMENTAL)</p>
11508 <p>Integrates the file-watching program Watchman with Mercurial to produce faster
11509 status results.</p>
11510 <p>On a particular Linux system, for a real-world repository with over 400,000
11511 files hosted on ext4, vanilla <cite>hg status</cite> takes 1.3 seconds. On the same
11512 system, with fsmonitor it takes about 0.3 seconds.</p>
11513 <p>fsmonitor requires no configuration -- it will tell Watchman about your
11514 repository as necessary. You'll need to install Watchman from
11515 <a class="reference external" href="https://facebook.github.io/watchman/">https://facebook.github.io/watchman/</a> and make sure it is in your PATH.</p>
11516 <p>fsmonitor is incompatible with the largefiles and eol extensions, and
11517 will disable itself if any of those are active.</p>
11518 <p>The following configuration options exist:</p>
11519 <pre class="literal-block">
11520 [fsmonitor]
11521 mode = {off, on, paranoid}
11522 </pre>
11523 <p>When <cite>mode = off</cite>, fsmonitor will disable itself (similar to not loading the
11524 extension at all). When <cite>mode = on</cite>, fsmonitor will be enabled (the default).
11525 When <cite>mode = paranoid</cite>, fsmonitor will query both Watchman and the filesystem,
11526 and ensure that the results are consistent.</p>
11527 <pre class="literal-block">
11528 [fsmonitor]
11529 timeout = (float)
11530 </pre>
11531 <p>A value, in seconds, that determines how long fsmonitor will wait for Watchman
11532 to return results. Defaults to <cite>2.0</cite>.</p>
11533 <pre class="literal-block">
11534 [fsmonitor]
11535 blacklistusers = (list of userids)
11536 </pre>
11537 <p>A list of usernames for which fsmonitor will disable itself altogether.</p>
11538 <pre class="literal-block">
11539 [fsmonitor]
11540 walk_on_invalidate = (boolean)
11541 </pre>
11542 <p>Whether or not to walk the whole repo ourselves when our cached state has been
11543 invalidated, for example when Watchman has been restarted or .hgignore rules
11544 have been changed. Walking the repo in that case can result in competing for
11545 I/O with Watchman. For large repos it is recommended to set this value to
11546 false. You may wish to set this to true if you have a very fast filesystem
11547 that can outpace the IPC overhead of getting the result data for the full repo
11548 from Watchman. Defaults to false.</p>
11549 <pre class="literal-block">
11550 [fsmonitor]
11551 warn_when_unused = (boolean)
11552 </pre>
11553 <p>Whether to print a warning during certain operations when fsmonitor would be
11554 beneficial to performance but isn't enabled.</p>
11555 <pre class="literal-block">
11556 [fsmonitor]
11557 warn_update_file_count = (integer)
11558 # or when mercurial is built with rust support
11559 warn_update_file_count_rust = (integer)
11560 </pre>
11561 <p>If <tt class="docutils literal">warn_when_unused</tt> is set and fsmonitor isn't enabled, a warning will
11562 be printed during working directory updates if this many files will be
11563 created.</p>
11564 </div>
11565 <div class="section" id="git">
11566 <h2><a class="toc-backref" href="#toc-entry-60">git</a></h2>
11567 <p>grant Mercurial the ability to operate on Git repositories. (EXPERIMENTAL)</p>
11568 <p>This is currently super experimental. It probably will consume your
11569 firstborn a la Rumpelstiltskin, etc.</p>
11570 </div>
11571 <div class="section" id="githelp">
11572 <h2><a class="toc-backref" href="#toc-entry-61">githelp</a></h2>
11573 <p>try mapping git commands to Mercurial commands</p>
11574 <p>Tries to map a given git command to a Mercurial command:</p>
11575 <blockquote>
11576 $ hg githelp -- git checkout master
11577 hg update master</blockquote>
11578 <p>If an unknown command or parameter combination is detected, an error is
11579 produced.</p>
11580 <div class="section" id="commands-16">
11581 <h3>Commands</h3>
11582 <div class="section" id="help-2">
11583 <h4>Help</h4>
11584 <div class="section" id="githelp-1">
11585 <h5>githelp</h5>
11586 <p>suggests the Mercurial equivalent of the given git command:</p>
11587 <pre class="literal-block">
11588 hg githelp
11589 </pre>
11590 <p>Usage: hg githelp -- &lt;git command&gt;</p>
11591 <!-- -->
11592 <blockquote>
11593 aliases: git</blockquote>
11594 </div>
11595 </div>
11596 </div>
11597 </div>
11598 <div class="section" id="gpg">
11599 <h2><a class="toc-backref" href="#toc-entry-62">gpg</a></h2>
11600 <p>commands to sign and verify changesets</p>
11601 <div class="section" id="commands-17">
11602 <h3>Commands</h3>
11603 <div class="section" id="signing-changes-gpg">
11604 <h4>Signing changes (GPG)</h4>
11605 <div class="section" id="sigcheck">
11606 <h5>sigcheck</h5>
11607 <p>verify all the signatures there may be for a particular revision:</p>
11608 <pre class="literal-block">
11609 hg sigcheck REV
11610 </pre>
11611 <p>verify all the signatures there may be for a particular revision</p>
11612 </div>
11613 <div class="section" id="sign">
11614 <h5>sign</h5>
11615 <p>add a signature for the current or given revision:</p>
11616 <pre class="literal-block">
11617 hg sign [OPTION]... [REV]...
11618 </pre>
11619 <p>If no revision is given, the parent of the working directory is used,
11620 or tip if no revision is checked out.</p>
11621 <p>The <tt class="docutils literal">gpg.cmd</tt> config setting can be used to specify the command
11622 to run. A default key can be specified with <tt class="docutils literal">gpg.key</tt>.</p>
11623 <p>See <a class="reference external" href="hg.1.html#dates"><tt class="docutils literal">hg help dates</tt></a> for a list of formats valid for -d/--date.</p>
11624 <p>Options:</p>
11625 <table class="docutils option-list" frame="void" rules="none">
11626 <col class="option" />
11627 <col class="description" />
11628 <tbody valign="top">
11629 <tr><td class="option-group">
11630 <kbd><span class="option">-l</span>, <span class="option">--local</span></kbd></td>
11631 <td>make the signature local</td></tr>
11632 <tr><td class="option-group">
11633 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
11634 <td>sign even if the sigfile is modified</td></tr>
11635 <tr><td class="option-group">
11636 <kbd><span class="option">--no-commit</span></kbd></td>
11637 <td>do not commit the sigfile after signing</td></tr>
11638 <tr><td class="option-group">
11639 <kbd><span class="option">-k</span>, <span class="option">--key <var>&lt;ID&gt;</var></span></kbd></td>
11640 <td>the key id to sign with</td></tr>
11641 <tr><td class="option-group" colspan="2">
11642 <kbd><span class="option">-m</span>, <span class="option">--message <var>&lt;TEXT&gt;</var></span></kbd></td>
11643 </tr>
11644 <tr><td>&nbsp;</td><td>use text as commit message</td></tr>
11645 <tr><td class="option-group">
11646 <kbd><span class="option">-e</span>, <span class="option">--edit</span></kbd></td>
11647 <td>invoke editor on commit messages</td></tr>
11648 <tr><td class="option-group" colspan="2">
11649 <kbd><span class="option">-d</span>, <span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
11650 </tr>
11651 <tr><td>&nbsp;</td><td>record the specified date as commit date</td></tr>
11652 <tr><td class="option-group" colspan="2">
11653 <kbd><span class="option">-u</span>, <span class="option">--user <var>&lt;USER&gt;</var></span></kbd></td>
11654 </tr>
11655 <tr><td>&nbsp;</td><td>record the specified user as committer</td></tr>
11656 </tbody>
11657 </table>
11658 </div>
11659 <div class="section" id="sigs">
11660 <h5>sigs</h5>
11661 <p>list signed changesets:</p>
11662 <pre class="literal-block">
11663 hg sigs
11664 </pre>
11665 <p>list signed changesets</p>
11666 </div>
11667 </div>
11668 </div>
11669 </div>
11670 <div class="section" id="graphlog">
11671 <h2><a class="toc-backref" href="#toc-entry-63">graphlog</a></h2>
11672 <p>command to view revision graphs from a shell (DEPRECATED)</p>
11673 <p>The functionality of this extension has been include in core Mercurial
11674 since version 2.3. Please use <a class="reference external" href="hg.1.html#log"><tt class="docutils literal">hg log <span class="pre">-G</span> ...</tt></a> instead.</p>
11675 <p>This extension adds a --graph option to the incoming, outgoing and log
11676 commands. When this options is given, an ASCII representation of the
11677 revision graph is also shown.</p>
11678 <div class="section" id="commands-18">
11679 <h3>Commands</h3>
11680 <div class="section" id="change-navigation-2">
11681 <h4>Change navigation</h4>
11682 <div class="section" id="glog">
11683 <h5>glog</h5>
11684 <p>show revision history alongside an ASCII revision graph:</p>
11685 <pre class="literal-block">
11686 hg glog [OPTION]... [FILE]
11687 </pre>
11688 <p>Print a revision history alongside a revision graph drawn with
11689 ASCII characters.</p>
11690 <p>Nodes printed as an &#64; character are parents of the working
11691 directory.</p>
11692 <p>This is an alias to <a class="reference external" href="hg.1.html#log"><tt class="docutils literal">hg log <span class="pre">-G</span></tt></a>.</p>
11693 <p>Options:</p>
11694 <table class="docutils option-list" frame="void" rules="none">
11695 <col class="option" />
11696 <col class="description" />
11697 <tbody valign="top">
11698 <tr><td class="option-group">
11699 <kbd><span class="option">-f</span>, <span class="option">--follow</span></kbd></td>
11700 <td>follow changeset history, or file history across copies and renames</td></tr>
11701 <tr><td class="option-group">
11702 <kbd><span class="option">--follow-first</span></kbd></td>
11703 <td>only follow the first parent of merge changesets (DEPRECATED)</td></tr>
11704 <tr><td class="option-group" colspan="2">
11705 <kbd><span class="option">-d</span>, <span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
11706 </tr>
11707 <tr><td>&nbsp;</td><td>show revisions matching date spec</td></tr>
11708 <tr><td class="option-group">
11709 <kbd><span class="option">-C</span>, <span class="option">--copies</span></kbd></td>
11710 <td>show copied files</td></tr>
11711 <tr><td class="option-group" colspan="2">
11712 <kbd><span class="option">-k</span>, <span class="option">--keyword <var>&lt;TEXT[+]&gt;</var></span></kbd></td>
11713 </tr>
11714 <tr><td>&nbsp;</td><td>do case-insensitive search for a given text</td></tr>
11715 <tr><td class="option-group" colspan="2">
11716 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
11717 </tr>
11718 <tr><td>&nbsp;</td><td>show the specified revision or revset</td></tr>
11719 <tr><td class="option-group">
11720 <kbd><span class="option">--removed</span></kbd></td>
11721 <td>include revisions where files were removed</td></tr>
11722 <tr><td class="option-group" colspan="2">
11723 <kbd><span class="option">-m</span>, <span class="option">--only-merges</span></kbd></td>
11724 </tr>
11725 <tr><td>&nbsp;</td><td>show only merges (DEPRECATED)</td></tr>
11726 <tr><td class="option-group" colspan="2">
11727 <kbd><span class="option">-u</span>, <span class="option">--user <var>&lt;USER[+]&gt;</var></span></kbd></td>
11728 </tr>
11729 <tr><td>&nbsp;</td><td>revisions committed by user</td></tr>
11730 <tr><td class="option-group" colspan="2">
11731 <kbd><span class="option">--only-branch <var>&lt;BRANCH[+]&gt;</var></span></kbd></td>
11732 </tr>
11733 <tr><td>&nbsp;</td><td>show only changesets within the given named branch (DEPRECATED)</td></tr>
11734 <tr><td class="option-group" colspan="2">
11735 <kbd><span class="option">-b</span>, <span class="option">--branch <var>&lt;BRANCH[+]&gt;</var></span></kbd></td>
11736 </tr>
11737 <tr><td>&nbsp;</td><td>show changesets within the given named branch</td></tr>
11738 <tr><td class="option-group" colspan="2">
11739 <kbd><span class="option">-P</span>, <span class="option">--prune <var>&lt;REV[+]&gt;</var></span></kbd></td>
11740 </tr>
11741 <tr><td>&nbsp;</td><td>do not display revision or any of its ancestors</td></tr>
11742 <tr><td class="option-group">
11743 <kbd><span class="option">-p</span>, <span class="option">--patch</span></kbd></td>
11744 <td>show patch</td></tr>
11745 <tr><td class="option-group">
11746 <kbd><span class="option">-g</span>, <span class="option">--git</span></kbd></td>
11747 <td>use git extended diff format</td></tr>
11748 <tr><td class="option-group" colspan="2">
11749 <kbd><span class="option">-l</span>, <span class="option">--limit <var>&lt;NUM&gt;</var></span></kbd></td>
11750 </tr>
11751 <tr><td>&nbsp;</td><td>limit number of changes displayed</td></tr>
11752 <tr><td class="option-group" colspan="2">
11753 <kbd><span class="option">-M</span>, <span class="option">--no-merges</span></kbd></td>
11754 </tr>
11755 <tr><td>&nbsp;</td><td>do not show merges</td></tr>
11756 <tr><td class="option-group">
11757 <kbd><span class="option">--stat</span></kbd></td>
11758 <td>output diffstat-style summary of changes</td></tr>
11759 <tr><td class="option-group">
11760 <kbd><span class="option">-G</span>, <span class="option">--graph</span></kbd></td>
11761 <td>show the revision DAG</td></tr>
11762 <tr><td class="option-group" colspan="2">
11763 <kbd><span class="option">--style <var>&lt;STYLE&gt;</var></span></kbd></td>
11764 </tr>
11765 <tr><td>&nbsp;</td><td>display using template map file (DEPRECATED)</td></tr>
11766 <tr><td class="option-group" colspan="2">
11767 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
11768 </tr>
11769 <tr><td>&nbsp;</td><td>display with template</td></tr>
11770 <tr><td class="option-group" colspan="2">
11771 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
11772 </tr>
11773 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
11774 <tr><td class="option-group" colspan="2">
11775 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
11776 </tr>
11777 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
11778 </tbody>
11779 </table>
11780 <p>[+] marked option can be specified multiple times</p>
11781 </div>
11782 </div>
11783 </div>
11784 </div>
11785 <div class="section" id="hgk">
11786 <h2><a class="toc-backref" href="#toc-entry-64">hgk</a></h2>
11787 <p>browse the repository in a graphical way</p>
11788 <p>The hgk extension allows browsing the history of a repository in a
11789 graphical way. It requires Tcl/Tk version 8.4 or later. (Tcl/Tk is not
11790 distributed with Mercurial.)</p>
11791 <p>hgk consists of two parts: a Tcl script that does the displaying and
11792 querying of information, and an extension to Mercurial named hgk.py,
11793 which provides hooks for hgk to get information. hgk can be found in
11794 the contrib directory, and the extension is shipped in the hgext
11795 repository, and needs to be enabled.</p>
11796 <p>The <a class="reference external" href="hg.1.html#view"><tt class="docutils literal">hg view</tt></a> command will launch the hgk Tcl script. For this command
11797 to work, hgk must be in your search path. Alternately, you can specify
11798 the path to hgk in your configuration file:</p>
11799 <pre class="literal-block">
11800 [hgk]
11801 path = /location/of/hgk
11802 </pre>
11803 <p>hgk can make use of the extdiff extension to visualize revisions.
11804 Assuming you had already configured extdiff vdiff command, just add:</p>
11805 <pre class="literal-block">
11806 [hgk]
11807 vdiff=vdiff
11808 </pre>
11809 <p>Revisions context menu will now display additional entries to fire
11810 vdiff on hovered and selected revisions.</p>
11811 <div class="section" id="commands-19">
11812 <h3>Commands</h3>
11813 <div class="section" id="change-navigation-3">
11814 <h4>Change navigation</h4>
11815 <div class="section" id="view">
11816 <h5>view</h5>
11817 <p>start interactive history viewer:</p>
11818 <pre class="literal-block">
11819 hg view [-l LIMIT] [REVRANGE]
11820 </pre>
11821 <p>start interactive history viewer</p>
11822 <p>Options:</p>
11823 <table class="docutils option-list" frame="void" rules="none">
11824 <col class="option" />
11825 <col class="description" />
11826 <tbody valign="top">
11827 <tr><td class="option-group" colspan="2">
11828 <kbd><span class="option">-l</span>, <span class="option">--limit <var>&lt;NUM&gt;</var></span></kbd></td>
11829 </tr>
11830 <tr><td>&nbsp;</td><td>limit number of changes displayed</td></tr>
11831 </tbody>
11832 </table>
11833 </div>
11834 </div>
11835 </div>
11836 </div>
11837 <div class="section" id="highlight">
11838 <h2><a class="toc-backref" href="#toc-entry-65">highlight</a></h2>
11839 <p>syntax highlighting for hgweb (requires Pygments)</p>
11840 <p>It depends on the Pygments syntax highlighting library:
11841 <a class="reference external" href="http://pygments.org/">http://pygments.org/</a></p>
11842 <p>There are the following configuration options:</p>
11843 <pre class="literal-block">
11844 [web]
11845 pygments_style = &lt;style&gt; (default: colorful)
11846 highlightfiles = &lt;fileset&gt; (default: size('&lt;5M'))
11847 highlightonlymatchfilename = &lt;bool&gt; (default False)
11848 </pre>
11849 <p><tt class="docutils literal">highlightonlymatchfilename</tt> will only highlight files if their type could
11850 be identified by their filename. When this is not enabled (the default),
11851 Pygments will try very hard to identify the file type from content and any
11852 match (even matches with a low confidence score) will be used.</p>
11853 </div>
11854 <div class="section" id="histedit">
11855 <h2><a class="toc-backref" href="#toc-entry-66">histedit</a></h2>
11856 <p>interactive history editing</p>
11857 <p>With this extension installed, Mercurial gains one new command: histedit. Usage
11858 is as follows, assuming the following history:</p>
11859 <pre class="literal-block">
11860 &#64; 3[tip] 7c2fd3b9020c 2009-04-27 18:04 -0500 durin42
11861 | Add delta
11862 |
11863 o 2 030b686bedc4 2009-04-27 18:04 -0500 durin42
11864 | Add gamma
11865 |
11866 o 1 c561b4e977df 2009-04-27 18:04 -0500 durin42
11867 | Add beta
11868 |
11869 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
11870 Add alpha
11871 </pre>
11872 <p>If you were to run <tt class="docutils literal">hg histedit c561b4e977df</tt>, you would see the following
11873 file open in your editor:</p>
11874 <pre class="literal-block">
11875 pick c561b4e977df Add beta
11876 pick 030b686bedc4 Add gamma
11877 pick 7c2fd3b9020c Add delta
11878
11879 # Edit history between c561b4e977df and 7c2fd3b9020c
11880 #
11881 # Commits are listed from least to most recent
11882 #
11883 # Commands:
11884 # p, pick = use commit
11885 # e, edit = use commit, but allow edits before making new commit
11886 # f, fold = use commit, but combine it with the one above
11887 # r, roll = like fold, but discard this commit's description and date
11888 # d, drop = remove commit from history
11889 # m, mess = edit commit message without changing commit content
11890 # b, base = checkout changeset and apply further changesets from there
11891 #
11892 </pre>
11893 <p>In this file, lines beginning with <tt class="docutils literal">#</tt> are ignored. You must specify a rule
11894 for each revision in your history. For example, if you had meant to add gamma
11895 before beta, and then wanted to add delta in the same revision as beta, you
11896 would reorganize the file to look like this:</p>
11897 <pre class="literal-block">
11898 pick 030b686bedc4 Add gamma
11899 pick c561b4e977df Add beta
11900 fold 7c2fd3b9020c Add delta
11901
11902 # Edit history between c561b4e977df and 7c2fd3b9020c
11903 #
11904 # Commits are listed from least to most recent
11905 #
11906 # Commands:
11907 # p, pick = use commit
11908 # e, edit = use commit, but allow edits before making new commit
11909 # f, fold = use commit, but combine it with the one above
11910 # r, roll = like fold, but discard this commit's description and date
11911 # d, drop = remove commit from history
11912 # m, mess = edit commit message without changing commit content
11913 # b, base = checkout changeset and apply further changesets from there
11914 #
11915 </pre>
11916 <p>At which point you close the editor and <tt class="docutils literal">histedit</tt> starts working. When you
11917 specify a <tt class="docutils literal">fold</tt> operation, <tt class="docutils literal">histedit</tt> will open an editor when it folds
11918 those revisions together, offering you a chance to clean up the commit message:</p>
11919 <pre class="literal-block">
11920 Add beta
11921 ***
11922 Add delta
11923 </pre>
11924 <p>Edit the commit message to your liking, then close the editor. The date used
11925 for the commit will be the later of the two commits' dates. For this example,
11926 let's assume that the commit message was changed to <tt class="docutils literal">Add beta and delta.</tt>
11927 After histedit has run and had a chance to remove any old or temporary
11928 revisions it needed, the history looks like this:</p>
11929 <pre class="literal-block">
11930 &#64; 2[tip] 989b4d060121 2009-04-27 18:04 -0500 durin42
11931 | Add beta and delta.
11932 |
11933 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
11934 | Add gamma
11935 |
11936 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
11937 Add alpha
11938 </pre>
11939 <p>Note that <tt class="docutils literal">histedit</tt> does <em>not</em> remove any revisions (even its own temporary
11940 ones) until after it has completed all the editing operations, so it will
11941 probably perform several strip operations when it's done. For the above example,
11942 it had to run strip twice. Strip can be slow depending on a variety of factors,
11943 so you might need to be a little patient. You can choose to keep the original
11944 revisions by passing the <tt class="docutils literal"><span class="pre">--keep</span></tt> flag.</p>
11945 <p>The <tt class="docutils literal">edit</tt> operation will drop you back to a command prompt,
11946 allowing you to edit files freely, or even use <tt class="docutils literal">hg record</tt> to commit
11947 some changes as a separate commit. When you're done, any remaining
11948 uncommitted changes will be committed as well. When done, run <tt class="docutils literal">hg
11949 histedit <span class="pre">--continue</span></tt> to finish this step. If there are uncommitted
11950 changes, you'll be prompted for a new commit message, but the default
11951 commit message will be the original message for the <tt class="docutils literal">edit</tt> ed
11952 revision, and the date of the original commit will be preserved.</p>
11953 <p>The <tt class="docutils literal">message</tt> operation will give you a chance to revise a commit
11954 message without changing the contents. It's a shortcut for doing
11955 <tt class="docutils literal">edit</tt> immediately followed by <cite>hg histedit --continue`</cite>.</p>
11956 <p>If <tt class="docutils literal">histedit</tt> encounters a conflict when moving a revision (while
11957 handling <tt class="docutils literal">pick</tt> or <tt class="docutils literal">fold</tt>), it'll stop in a similar manner to
11958 <tt class="docutils literal">edit</tt> with the difference that it won't prompt you for a commit
11959 message when done. If you decide at this point that you don't like how
11960 much work it will be to rearrange history, or that you made a mistake,
11961 you can use <tt class="docutils literal">hg histedit <span class="pre">--abort</span></tt> to abandon the new changes you
11962 have made and return to the state before you attempted to edit your
11963 history.</p>
11964 <p>If we clone the histedit-ed example repository above and add four more
11965 changes, such that we have the following history:</p>
11966 <pre class="literal-block">
11967 &#64; 6[tip] 038383181893 2009-04-27 18:04 -0500 stefan
11968 | Add theta
11969 |
11970 o 5 140988835471 2009-04-27 18:04 -0500 stefan
11971 | Add eta
11972 |
11973 o 4 122930637314 2009-04-27 18:04 -0500 stefan
11974 | Add zeta
11975 |
11976 o 3 836302820282 2009-04-27 18:04 -0500 stefan
11977 | Add epsilon
11978 |
11979 o 2 989b4d060121 2009-04-27 18:04 -0500 durin42
11980 | Add beta and delta.
11981 |
11982 o 1 081603921c3f 2009-04-27 18:04 -0500 durin42
11983 | Add gamma
11984 |
11985 o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42
11986 Add alpha
11987 </pre>
11988 <p>If you run <tt class="docutils literal">hg histedit <span class="pre">--outgoing</span></tt> on the clone then it is the same
11989 as running <tt class="docutils literal">hg histedit 836302820282</tt>. If you need plan to push to a
11990 repository that Mercurial does not detect to be related to the source
11991 repo, you can add a <tt class="docutils literal"><span class="pre">--force</span></tt> option.</p>
11992 <div class="section" id="config-1">
11993 <h3>Config</h3>
11994 <p>Histedit rule lines are truncated to 80 characters by default. You
11995 can customize this behavior by setting a different length in your
11996 configuration file:</p>
11997 <pre class="literal-block">
11998 [histedit]
11999 linelen = 120 # truncate rule lines at 120 characters
12000 </pre>
12001 <p>The summary of a change can be customized as well:</p>
12002 <pre class="literal-block">
12003 [histedit]
12004 summary-template = '{rev} {bookmarks} {desc|firstline}'
12005 </pre>
12006 <p>The customized summary should be kept short enough that rule lines
12007 will fit in the configured line length. See above if that requires
12008 customization.</p>
12009 <p><tt class="docutils literal">hg histedit</tt> attempts to automatically choose an appropriate base
12010 revision to use. To change which base revision is used, define a
12011 revset in your configuration file:</p>
12012 <pre class="literal-block">
12013 [histedit]
12014 defaultrev = only(.) &amp; draft()
12015 </pre>
12016 <p>By default each edited revision needs to be present in histedit commands.
12017 To remove revision you need to use <tt class="docutils literal">drop</tt> operation. You can configure
12018 the drop to be implicit for missing commits by adding:</p>
12019 <pre class="literal-block">
12020 [histedit]
12021 dropmissing = True
12022 </pre>
12023 <p>By default, histedit will close the transaction after each action. For
12024 performance purposes, you can configure histedit to use a single transaction
12025 across the entire histedit. WARNING: This setting introduces a significant risk
12026 of losing the work you've done in a histedit if the histedit aborts
12027 unexpectedly:</p>
12028 <pre class="literal-block">
12029 [histedit]
12030 singletransaction = True
12031 </pre>
12032 </div>
12033 <div class="section" id="commands-20">
12034 <h3>Commands</h3>
12035 <div class="section" id="change-manipulation-2">
12036 <h4>Change manipulation</h4>
12037 <div class="section" id="histedit-1">
12038 <h5>histedit</h5>
12039 <p>interactively edit changeset history:</p>
12040 <pre class="literal-block">
12041 hg histedit [OPTIONS] ([ANCESTOR] | --outgoing [URL])
12042 </pre>
12043 <p>This command lets you edit a linear series of changesets (up to
12044 and including the working directory, which should be clean).
12045 You can:</p>
12046 <ul class="simple">
12047 <li><cite>pick</cite> to [re]order a changeset</li>
12048 <li><cite>drop</cite> to omit changeset</li>
12049 <li><cite>mess</cite> to reword the changeset commit message</li>
12050 <li><cite>fold</cite> to combine it with the preceding changeset (using the later date)</li>
12051 <li><cite>roll</cite> like fold, but discarding this commit's description and date</li>
12052 <li><cite>edit</cite> to edit this changeset (preserving date)</li>
12053 <li><cite>base</cite> to checkout changeset and apply further changesets from there</li>
12054 </ul>
12055 <p>There are a number of ways to select the root changeset:</p>
12056 <ul class="simple">
12057 <li>Specify ANCESTOR directly</li>
12058 <li>Use --outgoing -- it will be the first linear changeset not
12059 included in destination. (See <a class="reference external" href="hgrc.5.html#paths"><tt class="docutils literal">hg help <span class="pre">config.paths.default-push</span></tt></a>)</li>
12060 <li>Otherwise, the value from the &quot;histedit.defaultrev&quot; config option
12061 is used as a revset to select the base revision when ANCESTOR is not
12062 specified. The first revision returned by the revset is used. By
12063 default, this selects the editable history that is unique to the
12064 ancestry of the working directory.</li>
12065 </ul>
12066 <div class="verbose docutils container">
12067 <p>If you use --outgoing, this command will abort if there are ambiguous
12068 outgoing revisions. For example, if there are multiple branches
12069 containing outgoing revisions.</p>
12070 <p>Use &quot;min(outgoing() and ::.)&quot; or similar revset specification
12071 instead of --outgoing to specify edit target revision exactly in
12072 such ambiguous situation. See <a class="reference external" href="hg.1.html#revsets"><tt class="docutils literal">hg help revsets</tt></a> for detail about
12073 selecting revisions.</p>
12074 </div>
12075 <div class="verbose docutils container">
12076 <p>Examples:</p>
12077 <blockquote>
12078 <ul>
12079 <li><p class="first">A number of changes have been made.
12080 Revision 3 is no longer needed.</p>
12081 <p>Start history editing from revision 3:</p>
12082 <pre class="literal-block">
12083 hg histedit -r 3
12084 </pre>
12085 <p>An editor opens, containing the list of revisions,
12086 with specific actions specified:</p>
12087 <pre class="literal-block">
12088 pick 5339bf82f0ca 3 Zworgle the foobar
12089 pick 8ef592ce7cc4 4 Bedazzle the zerlog
12090 pick 0a9639fcda9d 5 Morgify the cromulancy
12091 </pre>
12092 <p>Additional information about the possible actions
12093 to take appears below the list of revisions.</p>
12094 <p>To remove revision 3 from the history,
12095 its action (at the beginning of the relevant line)
12096 is changed to 'drop':</p>
12097 <pre class="literal-block">
12098 drop 5339bf82f0ca 3 Zworgle the foobar
12099 pick 8ef592ce7cc4 4 Bedazzle the zerlog
12100 pick 0a9639fcda9d 5 Morgify the cromulancy
12101 </pre>
12102 </li>
12103 <li><p class="first">A number of changes have been made.
12104 Revision 2 and 4 need to be swapped.</p>
12105 <p>Start history editing from revision 2:</p>
12106 <pre class="literal-block">
12107 hg histedit -r 2
12108 </pre>
12109 <p>An editor opens, containing the list of revisions,
12110 with specific actions specified:</p>
12111 <pre class="literal-block">
12112 pick 252a1af424ad 2 Blorb a morgwazzle
12113 pick 5339bf82f0ca 3 Zworgle the foobar
12114 pick 8ef592ce7cc4 4 Bedazzle the zerlog
12115 </pre>
12116 <p>To swap revision 2 and 4, its lines are swapped
12117 in the editor:</p>
12118 <pre class="literal-block">
12119 pick 8ef592ce7cc4 4 Bedazzle the zerlog
12120 pick 5339bf82f0ca 3 Zworgle the foobar
12121 pick 252a1af424ad 2 Blorb a morgwazzle
12122 </pre>
12123 </li>
12124 </ul>
12125 </blockquote>
12126 </div>
12127 <p>Returns 0 on success, 1 if user intervention is required (not only
12128 for intentional &quot;edit&quot; command, but also for resolving unexpected
12129 conflicts).</p>
12130 <p>Options:</p>
12131 <table class="docutils option-list" frame="void" rules="none">
12132 <col class="option" />
12133 <col class="description" />
12134 <tbody valign="top">
12135 <tr><td class="option-group" colspan="2">
12136 <kbd><span class="option">--commands <var>&lt;FILE&gt;</var></span></kbd></td>
12137 </tr>
12138 <tr><td>&nbsp;</td><td>read history edits from the specified file</td></tr>
12139 <tr><td class="option-group">
12140 <kbd><span class="option">-c</span>, <span class="option">--continue</span></kbd></td>
12141 <td>continue an edit already in progress</td></tr>
12142 <tr><td class="option-group">
12143 <kbd><span class="option">--edit-plan</span></kbd></td>
12144 <td>edit remaining actions list</td></tr>
12145 <tr><td class="option-group">
12146 <kbd><span class="option">-k</span>, <span class="option">--keep</span></kbd></td>
12147 <td>don't strip old nodes after edit is complete</td></tr>
12148 <tr><td class="option-group">
12149 <kbd><span class="option">--abort</span></kbd></td>
12150 <td>abort an edit in progress</td></tr>
12151 <tr><td class="option-group">
12152 <kbd><span class="option">-o</span>, <span class="option">--outgoing</span></kbd></td>
12153 <td>changesets not found in destination</td></tr>
12154 <tr><td class="option-group">
12155 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
12156 <td>force outgoing even for unrelated repositories</td></tr>
12157 <tr><td class="option-group" colspan="2">
12158 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
12159 </tr>
12160 <tr><td>&nbsp;</td><td>first revision to be edited</td></tr>
12161 <tr><td class="option-group" colspan="2">
12162 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
12163 </tr>
12164 <tr><td>&nbsp;</td><td>display with template</td></tr>
12165 </tbody>
12166 </table>
12167 <p>[+] marked option can be specified multiple times</p>
12168 </div>
12169 </div>
12170 </div>
12171 </div>
12172 <div class="section" id="hooklib">
12173 <h2><a class="toc-backref" href="#toc-entry-67">hooklib</a></h2>
12174 <p>collection of simple hooks for common tasks (EXPERIMENTAL)</p>
12175 <p>This extension provides a number of simple hooks to handle issues
12176 commonly found in repositories with many contributors:
12177 - email notification when changesets move from draft to public phase
12178 - email notification when changesets are obsoleted
12179 - enforcement of draft phase for all incoming changesets
12180 - enforcement of a no-branch-merge policy
12181 - enforcement of a no-multiple-heads policy</p>
12182 <p>The implementation of the hooks is subject to change, e.g. whether to
12183 implement them as individual hooks or merge them into the notify
12184 extension as option. The functionality itself is planned to be supported
12185 long-term.</p>
12186 </div>
12187 <div class="section" id="journal">
12188 <h2><a class="toc-backref" href="#toc-entry-68">journal</a></h2>
12189 <p>track previous positions of bookmarks (EXPERIMENTAL)</p>
12190 <p>This extension adds a new command: <cite>hg journal</cite>, which shows you where
12191 bookmarks were previously located.</p>
12192 <div class="section" id="commands-21">
12193 <h3>Commands</h3>
12194 <div class="section" id="change-organization-1">
12195 <h4>Change organization</h4>
12196 <div class="section" id="journal-1">
12197 <h5>journal</h5>
12198 <p>show the previous position of bookmarks and the working copy:</p>
12199 <pre class="literal-block">
12200 hg journal [OPTION]... [BOOKMARKNAME]
12201 </pre>
12202 <p>The journal is used to see the previous commits that bookmarks and the
12203 working copy pointed to. By default the previous locations for the working
12204 copy. Passing a bookmark name will show all the previous positions of
12205 that bookmark. Use the --all switch to show previous locations for all
12206 bookmarks and the working copy; each line will then include the bookmark
12207 name, or '.' for the working copy, as well.</p>
12208 <p>If <cite>name</cite> starts with <cite>re:</cite>, the remainder of the name is treated as
12209 a regular expression. To match a name that actually starts with <cite>re:</cite>,
12210 use the prefix <cite>literal:</cite>.</p>
12211 <p>By default hg journal only shows the commit hash and the command that was
12212 running at that time. -v/--verbose will show the prior hash, the user, and
12213 the time at which it happened.</p>
12214 <p>Use -c/--commits to output log information on each commit hash; at this
12215 point you can use the usual <cite>--patch</cite>, <cite>--git</cite>, <cite>--stat</cite> and <cite>--template</cite>
12216 switches to alter the log output for these.</p>
12217 <p><cite>hg journal -T json</cite> can be used to produce machine readable output.</p>
12218 <p>Options:</p>
12219 <table class="docutils option-list" frame="void" rules="none">
12220 <col class="option" />
12221 <col class="description" />
12222 <tbody valign="top">
12223 <tr><td class="option-group">
12224 <kbd><span class="option">--all</span></kbd></td>
12225 <td>show history for all names</td></tr>
12226 <tr><td class="option-group">
12227 <kbd><span class="option">-c</span>, <span class="option">--commits</span></kbd></td>
12228 <td>show commit metadata</td></tr>
12229 <tr><td class="option-group">
12230 <kbd><span class="option">-p</span>, <span class="option">--patch</span></kbd></td>
12231 <td>show patch</td></tr>
12232 <tr><td class="option-group">
12233 <kbd><span class="option">-g</span>, <span class="option">--git</span></kbd></td>
12234 <td>use git extended diff format</td></tr>
12235 <tr><td class="option-group" colspan="2">
12236 <kbd><span class="option">-l</span>, <span class="option">--limit <var>&lt;NUM&gt;</var></span></kbd></td>
12237 </tr>
12238 <tr><td>&nbsp;</td><td>limit number of changes displayed</td></tr>
12239 <tr><td class="option-group">
12240 <kbd><span class="option">--stat</span></kbd></td>
12241 <td>output diffstat-style summary of changes</td></tr>
12242 <tr><td class="option-group" colspan="2">
12243 <kbd><span class="option">--style <var>&lt;STYLE&gt;</var></span></kbd></td>
12244 </tr>
12245 <tr><td>&nbsp;</td><td>display using template map file (DEPRECATED)</td></tr>
12246 <tr><td class="option-group" colspan="2">
12247 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
12248 </tr>
12249 <tr><td>&nbsp;</td><td>display with template</td></tr>
12250 </tbody>
12251 </table>
12252 </div>
12253 </div>
12254 </div>
12255 </div>
12256 <div class="section" id="keyword">
12257 <h2><a class="toc-backref" href="#toc-entry-69">keyword</a></h2>
12258 <p>expand keywords in tracked files</p>
12259 <p>This extension expands RCS/CVS-like or self-customized $Keywords$ in
12260 tracked text files selected by your configuration.</p>
12261 <p>Keywords are only expanded in local repositories and not stored in the
12262 change history. The mechanism can be regarded as a convenience for the
12263 current user or for archive distribution.</p>
12264 <p>Keywords expand to the changeset data pertaining to the latest change
12265 relative to the working directory parent of each file.</p>
12266 <p>Configuration is done in the [keyword], [keywordset] and [keywordmaps]
12267 sections of hgrc files.</p>
12268 <p>Example:</p>
12269 <pre class="literal-block">
12270 [keyword]
12271 # expand keywords in every python file except those matching &quot;x*&quot;
12272 **.py =
12273 x* = ignore
12274
12275 [keywordset]
12276 # prefer svn- over cvs-like default keywordmaps
12277 svn = True
12278 </pre>
12279 <div class="admonition note">
12280 <p class="first admonition-title">Note</p>
12281 <p class="last">The more specific you are in your filename patterns the less you
12282 lose speed in huge repositories.</p>
12283 </div>
12284 <p>For [keywordmaps] template mapping and expansion demonstration and
12285 control run <a class="reference external" href="hg.1.html#kwdemo"><tt class="docutils literal">hg kwdemo</tt></a>. See <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help templates</tt></a> for a list of
12286 available templates and filters.</p>
12287 <p>Three additional date template filters are provided:</p>
12288 <table class="docutils field-list" frame="void" rules="none">
12289 <col class="field-name" />
12290 <col class="field-body" />
12291 <tbody valign="top">
12292 <tr class="field"><th class="field-name"><tt class="docutils literal">utcdate</tt>:</th><td class="field-body">&quot;2006/09/18 15:13:13&quot;</td>
12293 </tr>
12294 <tr class="field"><th class="field-name"><tt class="docutils literal">svnutcdate</tt>:</th><td class="field-body">&quot;2006-09-18 15:13:13Z&quot;</td>
12295 </tr>
12296 <tr class="field"><th class="field-name"><tt class="docutils literal">svnisodate</tt>:</th><td class="field-body">&quot;2006-09-18 08:13:13 -700 (Mon, 18 Sep 2006)&quot;</td>
12297 </tr>
12298 </tbody>
12299 </table>
12300 <p>The default template mappings (view with <a class="reference external" href="hg.1.html#kwdemo"><tt class="docutils literal">hg kwdemo <span class="pre">-d</span></tt></a>) can be
12301 replaced with customized keywords and templates. Again, run
12302 <a class="reference external" href="hg.1.html#kwdemo"><tt class="docutils literal">hg kwdemo</tt></a> to control the results of your configuration changes.</p>
12303 <p>Before changing/disabling active keywords, you must run <a class="reference external" href="hg.1.html#kwshrink"><tt class="docutils literal">hg kwshrink</tt></a>
12304 to avoid storing expanded keywords in the change history.</p>
12305 <p>To force expansion after enabling it, or a configuration change, run
12306 <a class="reference external" href="hg.1.html#kwexpand"><tt class="docutils literal">hg kwexpand</tt></a>.</p>
12307 <p>Expansions spanning more than one line and incremental expansions,
12308 like CVS' $Log$, are not supported. A keyword template map &quot;Log =
12309 {desc}&quot; expands to the first line of the changeset description.</p>
12310 <div class="section" id="commands-22">
12311 <h3>Commands</h3>
12312 <div class="section" id="uncategorized-commands-3">
12313 <h4>Uncategorized commands</h4>
12314 <div class="section" id="kwdemo">
12315 <h5>kwdemo</h5>
12316 <p>print [keywordmaps] configuration and an expansion example:</p>
12317 <pre class="literal-block">
12318 hg kwdemo [-d] [-f RCFILE] [TEMPLATEMAP]...
12319 </pre>
12320 <p>Show current, custom, or default keyword template maps and their
12321 expansions.</p>
12322 <p>Extend the current configuration by specifying maps as arguments
12323 and using -f/--rcfile to source an external hgrc file.</p>
12324 <p>Use -d/--default to disable current configuration.</p>
12325 <p>See <a class="reference external" href="hg.1.html#templates"><tt class="docutils literal">hg help templates</tt></a> for information on templates and filters.</p>
12326 <p>Options:</p>
12327 <table class="docutils option-list" frame="void" rules="none">
12328 <col class="option" />
12329 <col class="description" />
12330 <tbody valign="top">
12331 <tr><td class="option-group">
12332 <kbd><span class="option">-d</span>, <span class="option">--default</span></kbd></td>
12333 <td>show default keyword template maps</td></tr>
12334 <tr><td class="option-group" colspan="2">
12335 <kbd><span class="option">-f</span>, <span class="option">--rcfile <var>&lt;FILE&gt;</var></span></kbd></td>
12336 </tr>
12337 <tr><td>&nbsp;</td><td>read maps from rcfile</td></tr>
12338 </tbody>
12339 </table>
12340 </div>
12341 <div class="section" id="kwexpand">
12342 <h5>kwexpand</h5>
12343 <p>expand keywords in the working directory:</p>
12344 <pre class="literal-block">
12345 hg kwexpand [OPTION]... [FILE]...
12346 </pre>
12347 <p>Run after (re)enabling keyword expansion.</p>
12348 <p>kwexpand refuses to run if given files contain local changes.</p>
12349 <p>Options:</p>
12350 <table class="docutils option-list" frame="void" rules="none">
12351 <col class="option" />
12352 <col class="description" />
12353 <tbody valign="top">
12354 <tr><td class="option-group" colspan="2">
12355 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
12356 </tr>
12357 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
12358 <tr><td class="option-group" colspan="2">
12359 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
12360 </tr>
12361 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
12362 </tbody>
12363 </table>
12364 <p>[+] marked option can be specified multiple times</p>
12365 </div>
12366 <div class="section" id="kwfiles">
12367 <h5>kwfiles</h5>
12368 <p>show files configured for keyword expansion:</p>
12369 <pre class="literal-block">
12370 hg kwfiles [OPTION]... [FILE]...
12371 </pre>
12372 <p>List which files in the working directory are matched by the
12373 [keyword] configuration patterns.</p>
12374 <p>Useful to prevent inadvertent keyword expansion and to speed up
12375 execution by including only files that are actual candidates for
12376 expansion.</p>
12377 <p>See <a class="reference external" href="hg.1.html#keyword"><tt class="docutils literal">hg help keyword</tt></a> on how to construct patterns both for
12378 inclusion and exclusion of files.</p>
12379 <p>With -A/--all and -v/--verbose the codes used to show the status
12380 of files are:</p>
12381 <pre class="literal-block">
12382 K = keyword expansion candidate
12383 k = keyword expansion candidate (not tracked)
12384 I = ignored
12385 i = ignored (not tracked)
12386 </pre>
12387 <p>Options:</p>
12388 <table class="docutils option-list" frame="void" rules="none">
12389 <col class="option" />
12390 <col class="description" />
12391 <tbody valign="top">
12392 <tr><td class="option-group">
12393 <kbd><span class="option">-A</span>, <span class="option">--all</span></kbd></td>
12394 <td>show keyword status flags of all files</td></tr>
12395 <tr><td class="option-group">
12396 <kbd><span class="option">-i</span>, <span class="option">--ignore</span></kbd></td>
12397 <td>show files excluded from expansion</td></tr>
12398 <tr><td class="option-group">
12399 <kbd><span class="option">-u</span>, <span class="option">--unknown</span></kbd></td>
12400 <td>only show unknown (not tracked) files</td></tr>
12401 <tr><td class="option-group" colspan="2">
12402 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
12403 </tr>
12404 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
12405 <tr><td class="option-group" colspan="2">
12406 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
12407 </tr>
12408 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
12409 </tbody>
12410 </table>
12411 <p>[+] marked option can be specified multiple times</p>
12412 </div>
12413 <div class="section" id="kwshrink">
12414 <h5>kwshrink</h5>
12415 <p>revert expanded keywords in the working directory:</p>
12416 <pre class="literal-block">
12417 hg kwshrink [OPTION]... [FILE]...
12418 </pre>
12419 <p>Must be run before changing/disabling active keywords.</p>
12420 <p>kwshrink refuses to run if given files contain local changes.</p>
12421 <p>Options:</p>
12422 <table class="docutils option-list" frame="void" rules="none">
12423 <col class="option" />
12424 <col class="description" />
12425 <tbody valign="top">
12426 <tr><td class="option-group" colspan="2">
12427 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
12428 </tr>
12429 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
12430 <tr><td class="option-group" colspan="2">
12431 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
12432 </tr>
12433 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
12434 </tbody>
12435 </table>
12436 <p>[+] marked option can be specified multiple times</p>
12437 </div>
12438 </div>
12439 </div>
12440 </div>
12441 <div class="section" id="largefiles">
12442 <h2><a class="toc-backref" href="#toc-entry-70">largefiles</a></h2>
12443 <p>track large binary files</p>
12444 <p>Large binary files tend to be not very compressible, not very
12445 diffable, and not at all mergeable. Such files are not handled
12446 efficiently by Mercurial's storage format (revlog), which is based on
12447 compressed binary deltas; storing large binary files as regular
12448 Mercurial files wastes bandwidth and disk space and increases
12449 Mercurial's memory usage. The largefiles extension addresses these
12450 problems by adding a centralized client-server layer on top of
12451 Mercurial: largefiles live in a <em>central store</em> out on the network
12452 somewhere, and you only fetch the revisions that you need when you
12453 need them.</p>
12454 <p>largefiles works by maintaining a &quot;standin file&quot; in .hglf/ for each
12455 largefile. The standins are small (41 bytes: an SHA-1 hash plus
12456 newline) and are tracked by Mercurial. Largefile revisions are
12457 identified by the SHA-1 hash of their contents, which is written to
12458 the standin. largefiles uses that revision ID to get/put largefile
12459 revisions from/to the central store. This saves both disk space and
12460 bandwidth, since you don't need to retrieve all historical revisions
12461 of large files when you clone or pull.</p>
12462 <p>To start a new repository or add new large binary files, just add
12463 --large to your <a class="reference external" href="hg.1.html#add"><tt class="docutils literal">hg add</tt></a> command. For example:</p>
12464 <pre class="literal-block">
12465 $ dd if=/dev/urandom of=randomdata count=2000
12466 $ hg add --large randomdata
12467 $ hg commit -m &quot;add randomdata as a largefile&quot;
12468 </pre>
12469 <p>When you push a changeset that adds/modifies largefiles to a remote
12470 repository, its largefile revisions will be uploaded along with it.
12471 Note that the remote Mercurial must also have the largefiles extension
12472 enabled for this to work.</p>
12473 <p>When you pull a changeset that affects largefiles from a remote
12474 repository, the largefiles for the changeset will by default not be
12475 pulled down. However, when you update to such a revision, any
12476 largefiles needed by that revision are downloaded and cached (if
12477 they have never been downloaded before). One way to pull largefiles
12478 when pulling is thus to use --update, which will update your working
12479 copy to the latest pulled revision (and thereby downloading any new
12480 largefiles).</p>
12481 <p>If you want to pull largefiles you don't need for update yet, then
12482 you can use pull with the <cite>--lfrev</cite> option or the <a class="reference external" href="hg.1.html#lfpull"><tt class="docutils literal">hg lfpull</tt></a> command.</p>
12483 <p>If you know you are pulling from a non-default location and want to
12484 download all the largefiles that correspond to the new changesets at
12485 the same time, then you can pull with <cite>--lfrev &quot;pulled()&quot;</cite>.</p>
12486 <p>If you just want to ensure that you will have the largefiles needed to
12487 merge or rebase with new heads that you are pulling, then you can pull
12488 with <cite>--lfrev &quot;head(pulled())&quot;</cite> flag to pre-emptively download any largefiles
12489 that are new in the heads you are pulling.</p>
12490 <p>Keep in mind that network access may now be required to update to
12491 changesets that you have not previously updated to. The nature of the
12492 largefiles extension means that updating is no longer guaranteed to
12493 be a local-only operation.</p>
12494 <p>If you already have large files tracked by Mercurial without the
12495 largefiles extension, you will need to convert your repository in
12496 order to benefit from largefiles. This is done with the
12497 <a class="reference external" href="hg.1.html#lfconvert"><tt class="docutils literal">hg lfconvert</tt></a> command:</p>
12498 <pre class="literal-block">
12499 $ hg lfconvert --size 10 oldrepo newrepo
12500 </pre>
12501 <p>In repositories that already have largefiles in them, any new file
12502 over 10MB will automatically be added as a largefile. To change this
12503 threshold, set <tt class="docutils literal">largefiles.minsize</tt> in your Mercurial config file
12504 to the minimum size in megabytes to track as a largefile, or use the
12505 --lfsize option to the add command (also in megabytes):</p>
12506 <pre class="literal-block">
12507 [largefiles]
12508 minsize = 2
12509
12510 $ hg add --lfsize 2
12511 </pre>
12512 <p>The <tt class="docutils literal">largefiles.patterns</tt> config option allows you to specify a list
12513 of filename patterns (see <a class="reference external" href="hg.1.html#patterns"><tt class="docutils literal">hg help patterns</tt></a>) that should always be
12514 tracked as largefiles:</p>
12515 <pre class="literal-block">
12516 [largefiles]
12517 patterns =
12518 *.jpg
12519 re:.*\.(png|bmp)$
12520 library.zip
12521 content/audio/*
12522 </pre>
12523 <p>Files that match one of these patterns will be added as largefiles
12524 regardless of their size.</p>
12525 <p>The <tt class="docutils literal">largefiles.minsize</tt> and <tt class="docutils literal">largefiles.patterns</tt> config options
12526 will be ignored for any repositories not already containing a
12527 largefile. To add the first largefile to a repository, you must
12528 explicitly do so with the --large flag passed to the <a class="reference external" href="hg.1.html#add"><tt class="docutils literal">hg add</tt></a>
12529 command.</p>
12530 <div class="section" id="commands-23">
12531 <h3>Commands</h3>
12532 <div class="section" id="uncategorized-commands-4">
12533 <h4>Uncategorized commands</h4>
12534 <div class="section" id="lfconvert">
12535 <h5>lfconvert</h5>
12536 <p>convert a normal repository to a largefiles repository:</p>
12537 <pre class="literal-block">
12538 hg lfconvert SOURCE DEST [FILE ...]
12539 </pre>
12540 <p>Convert repository SOURCE to a new repository DEST, identical to
12541 SOURCE except that certain files will be converted as largefiles:
12542 specifically, any file that matches any PATTERN <em>or</em> whose size is
12543 above the minimum size threshold is converted as a largefile. The
12544 size used to determine whether or not to track a file as a
12545 largefile is the size of the first version of the file. The
12546 minimum size can be specified either with --size or in
12547 configuration as <tt class="docutils literal">largefiles.size</tt>.</p>
12548 <p>After running this command you will need to make sure that
12549 largefiles is enabled anywhere you intend to push the new
12550 repository.</p>
12551 <p>Use --to-normal to convert largefiles back to normal files; after
12552 this, the DEST repository can be used without largefiles at all.</p>
12553 <p>Options:</p>
12554 <table class="docutils option-list" frame="void" rules="none">
12555 <col class="option" />
12556 <col class="description" />
12557 <tbody valign="top">
12558 <tr><td class="option-group" colspan="2">
12559 <kbd><span class="option">-s</span>, <span class="option">--size <var>&lt;SIZE&gt;</var></span></kbd></td>
12560 </tr>
12561 <tr><td>&nbsp;</td><td>minimum size (MB) for files to be converted as largefiles</td></tr>
12562 <tr><td class="option-group">
12563 <kbd><span class="option">--to-normal</span></kbd></td>
12564 <td>convert from a largefiles repo to a normal repo</td></tr>
12565 </tbody>
12566 </table>
12567 </div>
12568 <div class="section" id="lfpull">
12569 <h5>lfpull</h5>
12570 <p>pull largefiles for the specified revisions from the specified source:</p>
12571 <pre class="literal-block">
12572 hg lfpull -r REV... [-e CMD] [--remotecmd CMD] [SOURCE]
12573 </pre>
12574 <p>Pull largefiles that are referenced from local changesets but missing
12575 locally, pulling from a remote repository to the local cache.</p>
12576 <p>If SOURCE is omitted, the 'default' path will be used.
12577 See <a class="reference external" href="hg.1.html#urls"><tt class="docutils literal">hg help urls</tt></a> for more information.</p>
12578 <div class="verbose docutils container">
12579 <p>Some examples:</p>
12580 <ul>
12581 <li><p class="first">pull largefiles for all branch heads:</p>
12582 <pre class="literal-block">
12583 hg lfpull -r &quot;head() and not closed()&quot;
12584 </pre>
12585 </li>
12586 <li><p class="first">pull largefiles on the default branch:</p>
12587 <pre class="literal-block">
12588 hg lfpull -r &quot;branch(default)&quot;
12589 </pre>
12590 </li>
12591 </ul>
12592 </div>
12593 <p>Options:</p>
12594 <table class="docutils option-list" frame="void" rules="none">
12595 <col class="option" />
12596 <col class="description" />
12597 <tbody valign="top">
12598 <tr><td class="option-group" colspan="2">
12599 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;VALUE[+]&gt;</var></span></kbd></td>
12600 </tr>
12601 <tr><td>&nbsp;</td><td>pull largefiles for these revisions</td></tr>
12602 <tr><td class="option-group" colspan="2">
12603 <kbd><span class="option">-e</span>, <span class="option">--ssh <var>&lt;CMD&gt;</var></span></kbd></td>
12604 </tr>
12605 <tr><td>&nbsp;</td><td>specify ssh command to use</td></tr>
12606 <tr><td class="option-group" colspan="2">
12607 <kbd><span class="option">--remotecmd <var>&lt;CMD&gt;</var></span></kbd></td>
12608 </tr>
12609 <tr><td>&nbsp;</td><td>specify hg command to run on the remote side</td></tr>
12610 <tr><td class="option-group">
12611 <kbd><span class="option">--insecure</span></kbd></td>
12612 <td>do not verify server certificate (ignoring web.cacerts config)</td></tr>
12613 </tbody>
12614 </table>
12615 <p>[+] marked option can be specified multiple times</p>
12616 </div>
12617 </div>
12618 </div>
12619 </div>
12620 <div class="section" id="lfs">
12621 <h2><a class="toc-backref" href="#toc-entry-71">lfs</a></h2>
12622 <p>lfs - large file support (EXPERIMENTAL)</p>
12623 <p>This extension allows large files to be tracked outside of the normal
12624 repository storage and stored on a centralized server, similar to the
12625 <tt class="docutils literal">largefiles</tt> extension. The <tt class="docutils literal"><span class="pre">git-lfs</span></tt> protocol is used when
12626 communicating with the server, so existing git infrastructure can be
12627 harnessed. Even though the files are stored outside of the repository,
12628 they are still integrity checked in the same manner as normal files.</p>
12629 <p>The files stored outside of the repository are downloaded on demand,
12630 which reduces the time to clone, and possibly the local disk usage.
12631 This changes fundamental workflows in a DVCS, so careful thought
12632 should be given before deploying it. <a class="reference external" href="hg.1.html#convert"><tt class="docutils literal">hg convert</tt></a> can be used to
12633 convert LFS repositories to normal repositories that no longer
12634 require this extension, and do so without changing the commit hashes.
12635 This allows the extension to be disabled if the centralized workflow
12636 becomes burdensome. However, the pre and post convert clones will
12637 not be able to communicate with each other unless the extension is
12638 enabled on both.</p>
12639 <p>To start a new repository, or to add LFS files to an existing one, just
12640 create an <tt class="docutils literal">.hglfs</tt> file as described below in the root directory of
12641 the repository. Typically, this file should be put under version
12642 control, so that the settings will propagate to other repositories with
12643 push and pull. During any commit, Mercurial will consult this file to
12644 determine if an added or modified file should be stored externally. The
12645 type of storage depends on the characteristics of the file at each
12646 commit. A file that is near a size threshold may switch back and forth
12647 between LFS and normal storage, as needed.</p>
12648 <p>Alternately, both normal repositories and largefile controlled
12649 repositories can be converted to LFS by using <a class="reference external" href="hg.1.html#convert"><tt class="docutils literal">hg convert</tt></a> and the
12650 <tt class="docutils literal">lfs.track</tt> config option described below. The <tt class="docutils literal">.hglfs</tt> file
12651 should then be created and added, to control subsequent LFS selection.
12652 The hashes are also unchanged in this case. The LFS and non-LFS
12653 repositories can be distinguished because the LFS repository will
12654 abort any command if this extension is disabled.</p>
12655 <p>Committed LFS files are held locally, until the repository is pushed.
12656 Prior to pushing the normal repository data, the LFS files that are
12657 tracked by the outgoing commits are automatically uploaded to the
12658 configured central server. No LFS files are transferred on
12659 <a class="reference external" href="hg.1.html#pull"><tt class="docutils literal">hg pull</tt></a> or <a class="reference external" href="hg.1.html#clone"><tt class="docutils literal">hg clone</tt></a>. Instead, the files are downloaded on
12660 demand as they need to be read, if a cached copy cannot be found
12661 locally. Both committing and downloading an LFS file will link the
12662 file to a usercache, to speed up future access. See the <cite>usercache</cite>
12663 config setting described below.</p>
12664 <p>The extension reads its configuration from a versioned <tt class="docutils literal">.hglfs</tt>
12665 configuration file found in the root of the working directory. The
12666 <tt class="docutils literal">.hglfs</tt> file uses the same syntax as all other Mercurial
12667 configuration files. It uses a single section, <tt class="docutils literal">[track]</tt>.</p>
12668 <p>The <tt class="docutils literal">[track]</tt> section specifies which files are stored as LFS (or
12669 not). Each line is keyed by a file pattern, with a predicate value.
12670 The first file pattern match is used, so put more specific patterns
12671 first. The available predicates are <tt class="docutils literal">all()</tt>, <tt class="docutils literal">none()</tt>, and
12672 <tt class="docutils literal">size()</tt>. See &quot;hg help filesets.size&quot; for the latter.</p>
12673 <p>Example versioned <tt class="docutils literal">.hglfs</tt> file:</p>
12674 <pre class="literal-block">
12675 [track]
12676 # No Makefile or python file, anywhere, will be LFS
12677 **Makefile = none()
12678 **.py = none()
12679
12680 **.zip = all()
12681 **.exe = size(&quot;&gt;1MB&quot;)
12682
12683 # Catchall for everything not matched above
12684 ** = size(&quot;&gt;10MB&quot;)
12685 </pre>
12686 <p>Configs:</p>
12687 <pre class="literal-block">
12688 [lfs]
12689 # Remote endpoint. Multiple protocols are supported:
12690 # - http(s)://user:pass&#64;example.com/path
12691 # git-lfs endpoint
12692 # - file:///tmp/path
12693 # local filesystem, usually for testing
12694 # if unset, lfs will assume the remote repository also handles blob storage
12695 # for http(s) URLs. Otherwise, lfs will prompt to set this when it must
12696 # use this value.
12697 # (default: unset)
12698 url = https://example.com/repo.git/info/lfs
12699
12700 # Which files to track in LFS. Path tests are &quot;**.extname&quot; for file
12701 # extensions, and &quot;path:under/some/directory&quot; for path prefix. Both
12702 # are relative to the repository root.
12703 # File size can be tested with the &quot;size()&quot; fileset, and tests can be
12704 # joined with fileset operators. (See &quot;hg help filesets.operators&quot;.)
12705 #
12706 # Some examples:
12707 # - all() # everything
12708 # - none() # nothing
12709 # - size(&quot;&gt;20MB&quot;) # larger than 20MB
12710 # - !**.txt # anything not a *.txt file
12711 # - **.zip | **.tar.gz | **.7z # some types of compressed files
12712 # - path:bin # files under &quot;bin&quot; in the project root
12713 # - (**.php &amp; size(&quot;&gt;2MB&quot;)) | (**.js &amp; size(&quot;&gt;5MB&quot;)) | **.tar.gz
12714 # | (path:bin &amp; !path:/bin/README) | size(&quot;&gt;1GB&quot;)
12715 # (default: none())
12716 #
12717 # This is ignored if there is a tracked '.hglfs' file, and this setting
12718 # will eventually be deprecated and removed.
12719 track = size(&quot;&gt;10M&quot;)
12720
12721 # how many times to retry before giving up on transferring an object
12722 retry = 5
12723
12724 # the local directory to store lfs files for sharing across local clones.
12725 # If not set, the cache is located in an OS specific cache location.
12726 usercache = /path/to/global/cache
12727 </pre>
12728 <div class="section" id="commands-24">
12729 <h3>Commands</h3>
12730 </div>
12731 </div>
12732 <div class="section" id="logtoprocess">
12733 <h2><a class="toc-backref" href="#toc-entry-72">logtoprocess</a></h2>
12734 <p>send ui.log() data to a subprocess (EXPERIMENTAL)</p>
12735 <p>This extension lets you specify a shell command per ui.log() event,
12736 sending all remaining arguments to as environment variables to that command.</p>
12737 <p>Positional arguments construct a log message, which is passed in the <cite>MSG1</cite>
12738 environment variables. Each keyword argument is set as a <cite>OPT_UPPERCASE_KEY</cite>
12739 variable (so the key is uppercased, and prefixed with <cite>OPT_</cite>). The original
12740 event name is passed in the <cite>EVENT</cite> environment variable, and the process ID
12741 of mercurial is given in <cite>HGPID</cite>.</p>
12742 <p>So given a call <cite>ui.log('foo', 'bar %s
12743 ', 'baz', spam='eggs'), a script
12744 configured for the `foo</cite> event can expect an environment with <cite>MSG1=bar baz</cite>,
12745 and <cite>OPT_SPAM=eggs</cite>.</p>
12746 <p>Scripts are configured in the <cite>[logtoprocess]</cite> section, each key an event name.
12747 For example:</p>
12748 <pre class="literal-block">
12749 [logtoprocess]
12750 commandexception = echo &quot;$MSG1&quot; &gt; /var/log/mercurial_exceptions.log
12751 </pre>
12752 <p>would log the warning message and traceback of any failed command dispatch.</p>
12753 <p>Scripts are run asynchronously as detached daemon processes; mercurial will
12754 not ensure that they exit cleanly.</p>
12755 </div>
12756 <div class="section" id="mq">
12757 <h2><a class="toc-backref" href="#toc-entry-73">mq</a></h2>
12758 <p>manage a stack of patches</p>
12759 <p>This extension lets you work with a stack of patches in a Mercurial
12760 repository. It manages two stacks of patches - all known patches, and
12761 applied patches (subset of known patches).</p>
12762 <p>Known patches are represented as patch files in the .hg/patches
12763 directory. Applied patches are both patch files and changesets.</p>
12764 <p>Common tasks (use <a class="reference external" href="hg.1.html#COMMAND"><tt class="docutils literal">hg help COMMAND</tt></a> for more details):</p>
12765 <pre class="literal-block">
12766 create new patch qnew
12767 import existing patch qimport
12768
12769 print patch series qseries
12770 print applied patches qapplied
12771
12772 add known patch to applied stack qpush
12773 remove patch from applied stack qpop
12774 refresh contents of top applied patch qrefresh
12775 </pre>
12776 <p>By default, mq will automatically use git patches when required to
12777 avoid losing file mode changes, copy records, binary files or empty
12778 files creations or deletions. This behavior can be configured with:</p>
12779 <pre class="literal-block">
12780 [mq]
12781 git = auto/keep/yes/no
12782 </pre>
12783 <p>If set to 'keep', mq will obey the [diff] section configuration while
12784 preserving existing git patches upon qrefresh. If set to 'yes' or
12785 'no', mq will override the [diff] section and always generate git or
12786 regular patches, possibly losing data in the second case.</p>
12787 <p>It may be desirable for mq changesets to be kept in the secret phase (see
12788 <a class="reference external" href="hg.1.html#phases"><tt class="docutils literal">hg help phases</tt></a>), which can be enabled with the following setting:</p>
12789 <pre class="literal-block">
12790 [mq]
12791 secret = True
12792 </pre>
12793 <p>You will by default be managing a patch queue named &quot;patches&quot;. You can
12794 create other, independent patch queues with the <a class="reference external" href="hg.1.html#qqueue"><tt class="docutils literal">hg qqueue</tt></a> command.</p>
12795 <p>If the working directory contains uncommitted files, qpush, qpop and
12796 qgoto abort immediately. If -f/--force is used, the changes are
12797 discarded. Setting:</p>
12798 <pre class="literal-block">
12799 [mq]
12800 keepchanges = True
12801 </pre>
12802 <p>make them behave as if --keep-changes were passed, and non-conflicting
12803 local changes will be tolerated and preserved. If incompatible options
12804 such as -f/--force or --exact are passed, this setting is ignored.</p>
12805 <p>This extension used to provide a strip command. This command now lives
12806 in the strip extension.</p>
12807 <div class="section" id="commands-25">
12808 <h3>Commands</h3>
12809 <div class="section" id="repository-creation-1">
12810 <h4>Repository creation</h4>
12811 <div class="section" id="qclone">
12812 <h5>qclone</h5>
12813 <p>clone main and patch repository at same time:</p>
12814 <pre class="literal-block">
12815 hg qclone [OPTION]... SOURCE [DEST]
12816 </pre>
12817 <p>If source is local, destination will have no patches applied. If
12818 source is remote, this command can not check if patches are
12819 applied in source, so cannot guarantee that patches are not
12820 applied in destination. If you clone remote repository, be sure
12821 before that it has no patches applied.</p>
12822 <p>Source patch repository is looked for in &lt;src&gt;/.hg/patches by
12823 default. Use -p &lt;url&gt; to change.</p>
12824 <p>The patch directory must be a nested Mercurial repository, as
12825 would be created by <a class="reference external" href="hg.1.html#init"><tt class="docutils literal">hg init <span class="pre">--mq</span></tt></a>.</p>
12826 <p>Return 0 on success.</p>
12827 <p>Options:</p>
12828 <table class="docutils option-list" frame="void" rules="none">
12829 <col class="option" />
12830 <col class="description" />
12831 <tbody valign="top">
12832 <tr><td class="option-group">
12833 <kbd><span class="option">--pull</span></kbd></td>
12834 <td>use pull protocol to copy metadata</td></tr>
12835 <tr><td class="option-group">
12836 <kbd><span class="option">-U</span>, <span class="option">--noupdate</span></kbd></td>
12837 <td>do not update the new working directories</td></tr>
12838 <tr><td class="option-group">
12839 <kbd><span class="option">--uncompressed</span></kbd></td>
12840 <td>use uncompressed transfer (fast over LAN)</td></tr>
12841 <tr><td class="option-group" colspan="2">
12842 <kbd><span class="option">-p</span>, <span class="option">--patches <var>&lt;REPO&gt;</var></span></kbd></td>
12843 </tr>
12844 <tr><td>&nbsp;</td><td>location of source patch repository</td></tr>
12845 <tr><td class="option-group" colspan="2">
12846 <kbd><span class="option">-e</span>, <span class="option">--ssh <var>&lt;CMD&gt;</var></span></kbd></td>
12847 </tr>
12848 <tr><td>&nbsp;</td><td>specify ssh command to use</td></tr>
12849 <tr><td class="option-group" colspan="2">
12850 <kbd><span class="option">--remotecmd <var>&lt;CMD&gt;</var></span></kbd></td>
12851 </tr>
12852 <tr><td>&nbsp;</td><td>specify hg command to run on the remote side</td></tr>
12853 <tr><td class="option-group">
12854 <kbd><span class="option">--insecure</span></kbd></td>
12855 <td>do not verify server certificate (ignoring web.cacerts config)</td></tr>
12856 </tbody>
12857 </table>
12858 </div>
12859 <div class="section" id="qinit">
12860 <h5>qinit</h5>
12861 <p>init a new queue repository (DEPRECATED):</p>
12862 <pre class="literal-block">
12863 hg qinit [-c]
12864 </pre>
12865 <p>The queue repository is unversioned by default. If
12866 -c/--create-repo is specified, qinit will create a separate nested
12867 repository for patches (qinit -c may also be run later to convert
12868 an unversioned patch repository into a versioned one). You can use
12869 qcommit to commit changes to this queue repository.</p>
12870 <p>This command is deprecated. Without -c, it's implied by other relevant
12871 commands. With -c, use <a class="reference external" href="hg.1.html#init"><tt class="docutils literal">hg init <span class="pre">--mq</span></tt></a> instead.</p>
12872 <p>Options:</p>
12873 <table class="docutils option-list" frame="void" rules="none">
12874 <col class="option" />
12875 <col class="description" />
12876 <tbody valign="top">
12877 <tr><td class="option-group" colspan="2">
12878 <kbd><span class="option">-c</span>, <span class="option">--create-repo</span></kbd></td>
12879 </tr>
12880 <tr><td>&nbsp;</td><td>create queue repository</td></tr>
12881 </tbody>
12882 </table>
12883 </div>
12884 </div>
12885 <div class="section" id="change-creation-3">
12886 <h4>Change creation</h4>
12887 <div class="section" id="qcommit">
12888 <h5>qcommit</h5>
12889 <p>commit changes in the queue repository (DEPRECATED):</p>
12890 <pre class="literal-block">
12891 hg qcommit [OPTION]... [FILE]...
12892 </pre>
12893 <p>This command is deprecated; use <a class="reference external" href="hg.1.html#commit"><tt class="docutils literal">hg commit <span class="pre">--mq</span></tt></a> instead.</p>
12894 <p>Options:</p>
12895 <table class="docutils option-list" frame="void" rules="none">
12896 <col class="option" />
12897 <col class="description" />
12898 <tbody valign="top">
12899 <tr><td class="option-group" colspan="2">
12900 <kbd><span class="option">-A</span>, <span class="option">--addremove</span></kbd></td>
12901 </tr>
12902 <tr><td>&nbsp;</td><td>mark new/missing files as added/removed before committing</td></tr>
12903 <tr><td class="option-group">
12904 <kbd><span class="option">--close-branch</span></kbd></td>
12905 <td>mark a branch head as closed</td></tr>
12906 <tr><td class="option-group">
12907 <kbd><span class="option">--amend</span></kbd></td>
12908 <td>amend the parent of the working directory</td></tr>
12909 <tr><td class="option-group">
12910 <kbd><span class="option">-s</span>, <span class="option">--secret</span></kbd></td>
12911 <td>use the secret phase for committing</td></tr>
12912 <tr><td class="option-group">
12913 <kbd><span class="option">--draft</span></kbd></td>
12914 <td>use the draft phase for committing</td></tr>
12915 <tr><td class="option-group">
12916 <kbd><span class="option">-e</span>, <span class="option">--edit</span></kbd></td>
12917 <td>invoke editor on commit messages</td></tr>
12918 <tr><td class="option-group" colspan="2">
12919 <kbd><span class="option">--force-close-branch</span></kbd></td>
12920 </tr>
12921 <tr><td>&nbsp;</td><td>forcibly close branch from a non-head changeset (ADVANCED)</td></tr>
12922 <tr><td class="option-group" colspan="2">
12923 <kbd><span class="option">-i</span>, <span class="option">--interactive</span></kbd></td>
12924 </tr>
12925 <tr><td>&nbsp;</td><td>use interactive mode</td></tr>
12926 <tr><td class="option-group" colspan="2">
12927 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
12928 </tr>
12929 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
12930 <tr><td class="option-group" colspan="2">
12931 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
12932 </tr>
12933 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
12934 <tr><td class="option-group" colspan="2">
12935 <kbd><span class="option">-m</span>, <span class="option">--message <var>&lt;TEXT&gt;</var></span></kbd></td>
12936 </tr>
12937 <tr><td>&nbsp;</td><td>use text as commit message</td></tr>
12938 <tr><td class="option-group" colspan="2">
12939 <kbd><span class="option">-l</span>, <span class="option">--logfile <var>&lt;FILE&gt;</var></span></kbd></td>
12940 </tr>
12941 <tr><td>&nbsp;</td><td>read commit message from file</td></tr>
12942 <tr><td class="option-group" colspan="2">
12943 <kbd><span class="option">-d</span>, <span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
12944 </tr>
12945 <tr><td>&nbsp;</td><td>record the specified date as commit date</td></tr>
12946 <tr><td class="option-group" colspan="2">
12947 <kbd><span class="option">-u</span>, <span class="option">--user <var>&lt;USER&gt;</var></span></kbd></td>
12948 </tr>
12949 <tr><td>&nbsp;</td><td>record the specified user as committer</td></tr>
12950 <tr><td class="option-group">
12951 <kbd><span class="option">-S</span>, <span class="option">--subrepos</span></kbd></td>
12952 <td>recurse into subrepositories</td></tr>
12953 </tbody>
12954 </table>
12955 <p>[+] marked option can be specified multiple times</p>
12956 <!-- -->
12957 <blockquote>
12958 aliases: qci</blockquote>
12959 </div>
12960 <div class="section" id="qnew">
12961 <h5>qnew</h5>
12962 <p>create a new patch:</p>
12963 <pre class="literal-block">
12964 hg qnew [-e] [-m TEXT] [-l FILE] PATCH [FILE]...
12965 </pre>
12966 <p>qnew creates a new patch on top of the currently-applied patch (if
12967 any). The patch will be initialized with any outstanding changes
12968 in the working directory. You may also use -I/--include,
12969 -X/--exclude, and/or a list of files after the patch name to add
12970 only changes to matching files to the new patch, leaving the rest
12971 as uncommitted modifications.</p>
12972 <p>-u/--user and -d/--date can be used to set the (given) user and
12973 date, respectively. -U/--currentuser and -D/--currentdate set user
12974 to current user and date to current date.</p>
12975 <p>-e/--edit, -m/--message or -l/--logfile set the patch header as
12976 well as the commit message. If none is specified, the header is
12977 empty and the commit message is '[mq]: PATCH'.</p>
12978 <p>Use the -g/--git option to keep the patch in the git extended diff
12979 format. Read the diffs help topic for more information on why this
12980 is important for preserving permission changes and copy/rename
12981 information.</p>
12982 <p>Returns 0 on successful creation of a new patch.</p>
12983 <p>Options:</p>
12984 <table class="docutils option-list" frame="void" rules="none">
12985 <col class="option" />
12986 <col class="description" />
12987 <tbody valign="top">
12988 <tr><td class="option-group">
12989 <kbd><span class="option">-e</span>, <span class="option">--edit</span></kbd></td>
12990 <td>invoke editor on commit messages</td></tr>
12991 <tr><td class="option-group">
12992 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
12993 <td>import uncommitted changes (DEPRECATED)</td></tr>
12994 <tr><td class="option-group">
12995 <kbd><span class="option">-g</span>, <span class="option">--git</span></kbd></td>
12996 <td>use git extended diff format</td></tr>
12997 <tr><td class="option-group" colspan="2">
12998 <kbd><span class="option">-U</span>, <span class="option">--currentuser</span></kbd></td>
12999 </tr>
13000 <tr><td>&nbsp;</td><td>add &quot;From: &lt;current user&gt;&quot; to patch</td></tr>
13001 <tr><td class="option-group" colspan="2">
13002 <kbd><span class="option">-u</span>, <span class="option">--user <var>&lt;USER&gt;</var></span></kbd></td>
13003 </tr>
13004 <tr><td>&nbsp;</td><td>add &quot;From: &lt;USER&gt;&quot; to patch</td></tr>
13005 <tr><td class="option-group" colspan="2">
13006 <kbd><span class="option">-D</span>, <span class="option">--currentdate</span></kbd></td>
13007 </tr>
13008 <tr><td>&nbsp;</td><td>add &quot;Date: &lt;current date&gt;&quot; to patch</td></tr>
13009 <tr><td class="option-group" colspan="2">
13010 <kbd><span class="option">-d</span>, <span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
13011 </tr>
13012 <tr><td>&nbsp;</td><td>add &quot;Date: &lt;DATE&gt;&quot; to patch</td></tr>
13013 <tr><td class="option-group" colspan="2">
13014 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
13015 </tr>
13016 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
13017 <tr><td class="option-group" colspan="2">
13018 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
13019 </tr>
13020 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
13021 <tr><td class="option-group" colspan="2">
13022 <kbd><span class="option">-m</span>, <span class="option">--message <var>&lt;TEXT&gt;</var></span></kbd></td>
13023 </tr>
13024 <tr><td>&nbsp;</td><td>use text as commit message</td></tr>
13025 <tr><td class="option-group" colspan="2">
13026 <kbd><span class="option">-l</span>, <span class="option">--logfile <var>&lt;FILE&gt;</var></span></kbd></td>
13027 </tr>
13028 <tr><td>&nbsp;</td><td>read commit message from file</td></tr>
13029 </tbody>
13030 </table>
13031 <p>[+] marked option can be specified multiple times</p>
13032 </div>
13033 <div class="section" id="qrefresh">
13034 <h5>qrefresh</h5>
13035 <p>update the current patch:</p>
13036 <pre class="literal-block">
13037 hg qrefresh [-I] [-X] [-e] [-m TEXT] [-l FILE] [-s] [FILE]...
13038 </pre>
13039 <p>If any file patterns are provided, the refreshed patch will
13040 contain only the modifications that match those patterns; the
13041 remaining modifications will remain in the working directory.</p>
13042 <p>If -s/--short is specified, files currently included in the patch
13043 will be refreshed just like matched files and remain in the patch.</p>
13044 <p>If -e/--edit is specified, Mercurial will start your configured editor for
13045 you to enter a message. In case qrefresh fails, you will find a backup of
13046 your message in <tt class="docutils literal"><span class="pre">.hg/last-message.txt</span></tt>.</p>
13047 <p>hg add/remove/copy/rename work as usual, though you might want to
13048 use git-style patches (-g/--git or [diff] git=1) to track copies
13049 and renames. See the diffs help topic for more information on the
13050 git diff format.</p>
13051 <p>Returns 0 on success.</p>
13052 <p>Options:</p>
13053 <table class="docutils option-list" frame="void" rules="none">
13054 <col class="option" />
13055 <col class="description" />
13056 <tbody valign="top">
13057 <tr><td class="option-group">
13058 <kbd><span class="option">-e</span>, <span class="option">--edit</span></kbd></td>
13059 <td>invoke editor on commit messages</td></tr>
13060 <tr><td class="option-group">
13061 <kbd><span class="option">-g</span>, <span class="option">--git</span></kbd></td>
13062 <td>use git extended diff format</td></tr>
13063 <tr><td class="option-group">
13064 <kbd><span class="option">-s</span>, <span class="option">--short</span></kbd></td>
13065 <td>refresh only files already in the patch and specified files</td></tr>
13066 <tr><td class="option-group" colspan="2">
13067 <kbd><span class="option">-U</span>, <span class="option">--currentuser</span></kbd></td>
13068 </tr>
13069 <tr><td>&nbsp;</td><td>add/update author field in patch with current user</td></tr>
13070 <tr><td class="option-group" colspan="2">
13071 <kbd><span class="option">-u</span>, <span class="option">--user <var>&lt;USER&gt;</var></span></kbd></td>
13072 </tr>
13073 <tr><td>&nbsp;</td><td>add/update author field in patch with given user</td></tr>
13074 <tr><td class="option-group" colspan="2">
13075 <kbd><span class="option">-D</span>, <span class="option">--currentdate</span></kbd></td>
13076 </tr>
13077 <tr><td>&nbsp;</td><td>add/update date field in patch with current date</td></tr>
13078 <tr><td class="option-group" colspan="2">
13079 <kbd><span class="option">-d</span>, <span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
13080 </tr>
13081 <tr><td>&nbsp;</td><td>add/update date field in patch with given date</td></tr>
13082 <tr><td class="option-group" colspan="2">
13083 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
13084 </tr>
13085 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
13086 <tr><td class="option-group" colspan="2">
13087 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
13088 </tr>
13089 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
13090 <tr><td class="option-group" colspan="2">
13091 <kbd><span class="option">-m</span>, <span class="option">--message <var>&lt;TEXT&gt;</var></span></kbd></td>
13092 </tr>
13093 <tr><td>&nbsp;</td><td>use text as commit message</td></tr>
13094 <tr><td class="option-group" colspan="2">
13095 <kbd><span class="option">-l</span>, <span class="option">--logfile <var>&lt;FILE&gt;</var></span></kbd></td>
13096 </tr>
13097 <tr><td>&nbsp;</td><td>read commit message from file</td></tr>
13098 </tbody>
13099 </table>
13100 <p>[+] marked option can be specified multiple times</p>
13101 </div>
13102 </div>
13103 <div class="section" id="change-manipulation-3">
13104 <h4>Change manipulation</h4>
13105 <div class="section" id="qfold">
13106 <h5>qfold</h5>
13107 <p>fold the named patches into the current patch:</p>
13108 <pre class="literal-block">
13109 hg qfold [-e] [-k] [-m TEXT] [-l FILE] PATCH...
13110 </pre>
13111 <p>Patches must not yet be applied. Each patch will be successively
13112 applied to the current patch in the order given. If all the
13113 patches apply successfully, the current patch will be refreshed
13114 with the new cumulative patch, and the folded patches will be
13115 deleted. With -k/--keep, the folded patch files will not be
13116 removed afterwards.</p>
13117 <p>The header for each folded patch will be concatenated with the
13118 current patch header, separated by a line of <tt class="docutils literal">* * *</tt>.</p>
13119 <p>Returns 0 on success.</p>
13120 <p>Options:</p>
13121 <table class="docutils option-list" frame="void" rules="none">
13122 <col class="option" />
13123 <col class="description" />
13124 <tbody valign="top">
13125 <tr><td class="option-group">
13126 <kbd><span class="option">-e</span>, <span class="option">--edit</span></kbd></td>
13127 <td>invoke editor on commit messages</td></tr>
13128 <tr><td class="option-group">
13129 <kbd><span class="option">-k</span>, <span class="option">--keep</span></kbd></td>
13130 <td>keep folded patch files</td></tr>
13131 <tr><td class="option-group" colspan="2">
13132 <kbd><span class="option">-m</span>, <span class="option">--message <var>&lt;TEXT&gt;</var></span></kbd></td>
13133 </tr>
13134 <tr><td>&nbsp;</td><td>use text as commit message</td></tr>
13135 <tr><td class="option-group" colspan="2">
13136 <kbd><span class="option">-l</span>, <span class="option">--logfile <var>&lt;FILE&gt;</var></span></kbd></td>
13137 </tr>
13138 <tr><td>&nbsp;</td><td>read commit message from file</td></tr>
13139 </tbody>
13140 </table>
13141 </div>
13142 </div>
13143 <div class="section" id="change-organization-2">
13144 <h4>Change organization</h4>
13145 <div class="section" id="qapplied">
13146 <h5>qapplied</h5>
13147 <p>print the patches already applied:</p>
13148 <pre class="literal-block">
13149 hg qapplied [-1] [-s] [PATCH]
13150 </pre>
13151 <p>Returns 0 on success.</p>
13152 <p>Options:</p>
13153 <table class="docutils option-list" frame="void" rules="none">
13154 <col class="option" />
13155 <col class="description" />
13156 <tbody valign="top">
13157 <tr><td class="option-group">
13158 <kbd><span class="option">-1</span>, <span class="option">--last</span></kbd></td>
13159 <td>show only the preceding applied patch</td></tr>
13160 <tr><td class="option-group">
13161 <kbd><span class="option">-s</span>, <span class="option">--summary</span></kbd></td>
13162 <td>print first line of patch header</td></tr>
13163 </tbody>
13164 </table>
13165 </div>
13166 <div class="section" id="qdelete">
13167 <h5>qdelete</h5>
13168 <p>remove patches from queue:</p>
13169 <pre class="literal-block">
13170 hg qdelete [-k] [PATCH]...
13171 </pre>
13172 <p>The patches must not be applied, and at least one patch is required. Exact
13173 patch identifiers must be given. With -k/--keep, the patch files are
13174 preserved in the patch directory.</p>
13175 <p>To stop managing a patch and move it into permanent history,
13176 use the <a class="reference external" href="hg.1.html#qfinish"><tt class="docutils literal">hg qfinish</tt></a> command.</p>
13177 <p>Options:</p>
13178 <table class="docutils option-list" frame="void" rules="none">
13179 <col class="option" />
13180 <col class="description" />
13181 <tbody valign="top">
13182 <tr><td class="option-group">
13183 <kbd><span class="option">-k</span>, <span class="option">--keep</span></kbd></td>
13184 <td>keep patch file</td></tr>
13185 <tr><td class="option-group" colspan="2">
13186 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
13187 </tr>
13188 <tr><td>&nbsp;</td><td>stop managing a revision (DEPRECATED)</td></tr>
13189 </tbody>
13190 </table>
13191 <p>[+] marked option can be specified multiple times</p>
13192 <!-- -->
13193 <blockquote>
13194 aliases: qremove qrm</blockquote>
13195 </div>
13196 <div class="section" id="qfinish">
13197 <h5>qfinish</h5>
13198 <p>move applied patches into repository history:</p>
13199 <pre class="literal-block">
13200 hg qfinish [-a] [REV]...
13201 </pre>
13202 <p>Finishes the specified revisions (corresponding to applied
13203 patches) by moving them out of mq control into regular repository
13204 history.</p>
13205 <p>Accepts a revision range or the -a/--applied option. If --applied
13206 is specified, all applied mq revisions are removed from mq
13207 control. Otherwise, the given revisions must be at the base of the
13208 stack of applied patches.</p>
13209 <p>This can be especially useful if your changes have been applied to
13210 an upstream repository, or if you are about to push your changes
13211 to upstream.</p>
13212 <p>Returns 0 on success.</p>
13213 <p>Options:</p>
13214 <table class="docutils option-list" frame="void" rules="none">
13215 <col class="option" />
13216 <col class="description" />
13217 <tbody valign="top">
13218 <tr><td class="option-group">
13219 <kbd><span class="option">-a</span>, <span class="option">--applied</span></kbd></td>
13220 <td>finish all applied changesets</td></tr>
13221 </tbody>
13222 </table>
13223 </div>
13224 <div class="section" id="qgoto">
13225 <h5>qgoto</h5>
13226 <p>push or pop patches until named patch is at top of stack:</p>
13227 <pre class="literal-block">
13228 hg qgoto [OPTION]... PATCH
13229 </pre>
13230 <p>Returns 0 on success.</p>
13231 <p>Options:</p>
13232 <table class="docutils option-list" frame="void" rules="none">
13233 <col class="option" />
13234 <col class="description" />
13235 <tbody valign="top">
13236 <tr><td class="option-group">
13237 <kbd><span class="option">--keep-changes</span></kbd></td>
13238 <td>tolerate non-conflicting local changes</td></tr>
13239 <tr><td class="option-group">
13240 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
13241 <td>overwrite any local changes</td></tr>
13242 <tr><td class="option-group">
13243 <kbd><span class="option">--no-backup</span></kbd></td>
13244 <td>do not save backup copies of files</td></tr>
13245 </tbody>
13246 </table>
13247 </div>
13248 <div class="section" id="qguard">
13249 <h5>qguard</h5>
13250 <p>set or print guards for a patch:</p>
13251 <pre class="literal-block">
13252 hg qguard [-l] [-n] [PATCH] [-- [+GUARD]... [-GUARD]...]
13253 </pre>
13254 <p>Guards control whether a patch can be pushed. A patch with no
13255 guards is always pushed. A patch with a positive guard (&quot;+foo&quot;) is
13256 pushed only if the <a class="reference external" href="hg.1.html#qselect"><tt class="docutils literal">hg qselect</tt></a> command has activated it. A patch with
13257 a negative guard (&quot;-foo&quot;) is never pushed if the <a class="reference external" href="hg.1.html#qselect"><tt class="docutils literal">hg qselect</tt></a> command
13258 has activated it.</p>
13259 <p>With no arguments, print the currently active guards.
13260 With arguments, set guards for the named patch.</p>
13261 <div class="admonition note">
13262 <p class="first admonition-title">Note</p>
13263 <p class="last">Specifying negative guards now requires '--'.</p>
13264 </div>
13265 <p>To set guards on another patch:</p>
13266 <pre class="literal-block">
13267 hg qguard other.patch -- +2.6.17 -stable
13268 </pre>
13269 <p>Returns 0 on success.</p>
13270 <p>Options:</p>
13271 <table class="docutils option-list" frame="void" rules="none">
13272 <col class="option" />
13273 <col class="description" />
13274 <tbody valign="top">
13275 <tr><td class="option-group">
13276 <kbd><span class="option">-l</span>, <span class="option">--list</span></kbd></td>
13277 <td>list all patches and guards</td></tr>
13278 <tr><td class="option-group">
13279 <kbd><span class="option">-n</span>, <span class="option">--none</span></kbd></td>
13280 <td>drop all guards</td></tr>
13281 </tbody>
13282 </table>
13283 </div>
13284 <div class="section" id="qheader">
13285 <h5>qheader</h5>
13286 <p>print the header of the topmost or specified patch:</p>
13287 <pre class="literal-block">
13288 hg qheader [PATCH]
13289 </pre>
13290 <p>Returns 0 on success.</p>
13291 </div>
13292 <div class="section" id="qnext">
13293 <h5>qnext</h5>
13294 <p>print the name of the next pushable patch:</p>
13295 <pre class="literal-block">
13296 hg qnext [-s]
13297 </pre>
13298 <p>Returns 0 on success.</p>
13299 <p>Options:</p>
13300 <table class="docutils option-list" frame="void" rules="none">
13301 <col class="option" />
13302 <col class="description" />
13303 <tbody valign="top">
13304 <tr><td class="option-group">
13305 <kbd><span class="option">-s</span>, <span class="option">--summary</span></kbd></td>
13306 <td>print first line of patch header</td></tr>
13307 </tbody>
13308 </table>
13309 </div>
13310 <div class="section" id="qpop">
13311 <h5>qpop</h5>
13312 <p>pop the current patch off the stack:</p>
13313 <pre class="literal-block">
13314 hg qpop [-a] [-f] [PATCH | INDEX]
13315 </pre>
13316 <p>Without argument, pops off the top of the patch stack. If given a
13317 patch name, keeps popping off patches until the named patch is at
13318 the top of the stack.</p>
13319 <p>By default, abort if the working directory contains uncommitted
13320 changes. With --keep-changes, abort only if the uncommitted files
13321 overlap with patched files. With -f/--force, backup and discard
13322 changes made to such files.</p>
13323 <p>Return 0 on success.</p>
13324 <p>Options:</p>
13325 <table class="docutils option-list" frame="void" rules="none">
13326 <col class="option" />
13327 <col class="description" />
13328 <tbody valign="top">
13329 <tr><td class="option-group">
13330 <kbd><span class="option">-a</span>, <span class="option">--all</span></kbd></td>
13331 <td>pop all patches</td></tr>
13332 <tr><td class="option-group" colspan="2">
13333 <kbd><span class="option">-n</span>, <span class="option">--name <var>&lt;NAME&gt;</var></span></kbd></td>
13334 </tr>
13335 <tr><td>&nbsp;</td><td>queue name to pop (DEPRECATED)</td></tr>
13336 <tr><td class="option-group">
13337 <kbd><span class="option">--keep-changes</span></kbd></td>
13338 <td>tolerate non-conflicting local changes</td></tr>
13339 <tr><td class="option-group">
13340 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
13341 <td>forget any local changes to patched files</td></tr>
13342 <tr><td class="option-group">
13343 <kbd><span class="option">--no-backup</span></kbd></td>
13344 <td>do not save backup copies of files</td></tr>
13345 </tbody>
13346 </table>
13347 </div>
13348 <div class="section" id="qprev">
13349 <h5>qprev</h5>
13350 <p>print the name of the preceding applied patch:</p>
13351 <pre class="literal-block">
13352 hg qprev [-s]
13353 </pre>
13354 <p>Returns 0 on success.</p>
13355 <p>Options:</p>
13356 <table class="docutils option-list" frame="void" rules="none">
13357 <col class="option" />
13358 <col class="description" />
13359 <tbody valign="top">
13360 <tr><td class="option-group">
13361 <kbd><span class="option">-s</span>, <span class="option">--summary</span></kbd></td>
13362 <td>print first line of patch header</td></tr>
13363 </tbody>
13364 </table>
13365 </div>
13366 <div class="section" id="qpush">
13367 <h5>qpush</h5>
13368 <p>push the next patch onto the stack:</p>
13369 <pre class="literal-block">
13370 hg qpush [-f] [-l] [-a] [--move] [PATCH | INDEX]
13371 </pre>
13372 <p>By default, abort if the working directory contains uncommitted
13373 changes. With --keep-changes, abort only if the uncommitted files
13374 overlap with patched files. With -f/--force, backup and patch over
13375 uncommitted changes.</p>
13376 <p>Return 0 on success.</p>
13377 <p>Options:</p>
13378 <table class="docutils option-list" frame="void" rules="none">
13379 <col class="option" />
13380 <col class="description" />
13381 <tbody valign="top">
13382 <tr><td class="option-group">
13383 <kbd><span class="option">--keep-changes</span></kbd></td>
13384 <td>tolerate non-conflicting local changes</td></tr>
13385 <tr><td class="option-group">
13386 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
13387 <td>apply on top of local changes</td></tr>
13388 <tr><td class="option-group">
13389 <kbd><span class="option">-e</span>, <span class="option">--exact</span></kbd></td>
13390 <td>apply the target patch to its recorded parent</td></tr>
13391 <tr><td class="option-group">
13392 <kbd><span class="option">-l</span>, <span class="option">--list</span></kbd></td>
13393 <td>list patch name in commit text</td></tr>
13394 <tr><td class="option-group">
13395 <kbd><span class="option">-a</span>, <span class="option">--all</span></kbd></td>
13396 <td>apply all patches</td></tr>
13397 <tr><td class="option-group">
13398 <kbd><span class="option">-m</span>, <span class="option">--merge</span></kbd></td>
13399 <td>merge from another queue (DEPRECATED)</td></tr>
13400 <tr><td class="option-group" colspan="2">
13401 <kbd><span class="option">-n</span>, <span class="option">--name <var>&lt;NAME&gt;</var></span></kbd></td>
13402 </tr>
13403 <tr><td>&nbsp;</td><td>merge queue name (DEPRECATED)</td></tr>
13404 <tr><td class="option-group">
13405 <kbd><span class="option">--move</span></kbd></td>
13406 <td>reorder patch series and apply only the patch</td></tr>
13407 <tr><td class="option-group">
13408 <kbd><span class="option">--no-backup</span></kbd></td>
13409 <td>do not save backup copies of files</td></tr>
13410 </tbody>
13411 </table>
13412 </div>
13413 <div class="section" id="qqueue">
13414 <h5>qqueue</h5>
13415 <p>manage multiple patch queues:</p>
13416 <pre class="literal-block">
13417 hg qqueue [OPTION] [QUEUE]
13418 </pre>
13419 <p>Supports switching between different patch queues, as well as creating
13420 new patch queues and deleting existing ones.</p>
13421 <p>Omitting a queue name or specifying -l/--list will show you the registered
13422 queues - by default the &quot;normal&quot; patches queue is registered. The currently
13423 active queue will be marked with &quot;(active)&quot;. Specifying --active will print
13424 only the name of the active queue.</p>
13425 <p>To create a new queue, use -c/--create. The queue is automatically made
13426 active, except in the case where there are applied patches from the
13427 currently active queue in the repository. Then the queue will only be
13428 created and switching will fail.</p>
13429 <p>To delete an existing queue, use --delete. You cannot delete the currently
13430 active queue.</p>
13431 <p>Returns 0 on success.</p>
13432 <p>Options:</p>
13433 <table class="docutils option-list" frame="void" rules="none">
13434 <col class="option" />
13435 <col class="description" />
13436 <tbody valign="top">
13437 <tr><td class="option-group">
13438 <kbd><span class="option">-l</span>, <span class="option">--list</span></kbd></td>
13439 <td>list all available queues</td></tr>
13440 <tr><td class="option-group">
13441 <kbd><span class="option">--active</span></kbd></td>
13442 <td>print name of active queue</td></tr>
13443 <tr><td class="option-group">
13444 <kbd><span class="option">-c</span>, <span class="option">--create</span></kbd></td>
13445 <td>create new queue</td></tr>
13446 <tr><td class="option-group">
13447 <kbd><span class="option">--rename</span></kbd></td>
13448 <td>rename active queue</td></tr>
13449 <tr><td class="option-group">
13450 <kbd><span class="option">--delete</span></kbd></td>
13451 <td>delete reference to queue</td></tr>
13452 <tr><td class="option-group">
13453 <kbd><span class="option">--purge</span></kbd></td>
13454 <td>delete queue, and remove patch dir</td></tr>
13455 </tbody>
13456 </table>
13457 </div>
13458 <div class="section" id="qrename">
13459 <h5>qrename</h5>
13460 <p>rename a patch:</p>
13461 <pre class="literal-block">
13462 hg qrename PATCH1 [PATCH2]
13463 </pre>
13464 <p>With one argument, renames the current patch to PATCH1.
13465 With two arguments, renames PATCH1 to PATCH2.</p>
13466 <p>Returns 0 on success.</p>
13467 <!-- -->
13468 <blockquote>
13469 aliases: qmv</blockquote>
13470 </div>
13471 <div class="section" id="qrestore">
13472 <h5>qrestore</h5>
13473 <p>restore the queue state saved by a revision (DEPRECATED):</p>
13474 <pre class="literal-block">
13475 hg qrestore [-d] [-u] REV
13476 </pre>
13477 <p>This command is deprecated, use <a class="reference external" href="hg.1.html#rebase"><tt class="docutils literal">hg rebase</tt></a> instead.</p>
13478 <p>Options:</p>
13479 <table class="docutils option-list" frame="void" rules="none">
13480 <col class="option" />
13481 <col class="description" />
13482 <tbody valign="top">
13483 <tr><td class="option-group">
13484 <kbd><span class="option">-d</span>, <span class="option">--delete</span></kbd></td>
13485 <td>delete save entry</td></tr>
13486 <tr><td class="option-group">
13487 <kbd><span class="option">-u</span>, <span class="option">--update</span></kbd></td>
13488 <td>update queue working directory</td></tr>
13489 </tbody>
13490 </table>
13491 </div>
13492 <div class="section" id="qsave">
13493 <h5>qsave</h5>
13494 <p>save current queue state (DEPRECATED):</p>
13495 <pre class="literal-block">
13496 hg qsave [-m TEXT] [-l FILE] [-c] [-n NAME] [-e] [-f]
13497 </pre>
13498 <p>This command is deprecated, use <a class="reference external" href="hg.1.html#rebase"><tt class="docutils literal">hg rebase</tt></a> instead.</p>
13499 <p>Options:</p>
13500 <table class="docutils option-list" frame="void" rules="none">
13501 <col class="option" />
13502 <col class="description" />
13503 <tbody valign="top">
13504 <tr><td class="option-group">
13505 <kbd><span class="option">-c</span>, <span class="option">--copy</span></kbd></td>
13506 <td>copy patch directory</td></tr>
13507 <tr><td class="option-group" colspan="2">
13508 <kbd><span class="option">-n</span>, <span class="option">--name <var>&lt;NAME&gt;</var></span></kbd></td>
13509 </tr>
13510 <tr><td>&nbsp;</td><td>copy directory name</td></tr>
13511 <tr><td class="option-group">
13512 <kbd><span class="option">-e</span>, <span class="option">--empty</span></kbd></td>
13513 <td>clear queue status file</td></tr>
13514 <tr><td class="option-group">
13515 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
13516 <td>force copy</td></tr>
13517 <tr><td class="option-group" colspan="2">
13518 <kbd><span class="option">-m</span>, <span class="option">--message <var>&lt;TEXT&gt;</var></span></kbd></td>
13519 </tr>
13520 <tr><td>&nbsp;</td><td>use text as commit message</td></tr>
13521 <tr><td class="option-group" colspan="2">
13522 <kbd><span class="option">-l</span>, <span class="option">--logfile <var>&lt;FILE&gt;</var></span></kbd></td>
13523 </tr>
13524 <tr><td>&nbsp;</td><td>read commit message from file</td></tr>
13525 </tbody>
13526 </table>
13527 </div>
13528 <div class="section" id="qselect">
13529 <h5>qselect</h5>
13530 <p>set or print guarded patches to push:</p>
13531 <pre class="literal-block">
13532 hg qselect [OPTION]... [GUARD]...
13533 </pre>
13534 <p>Use the <a class="reference external" href="hg.1.html#qguard"><tt class="docutils literal">hg qguard</tt></a> command to set or print guards on patch, then use
13535 qselect to tell mq which guards to use. A patch will be pushed if
13536 it has no guards or any positive guards match the currently
13537 selected guard, but will not be pushed if any negative guards
13538 match the current guard. For example:</p>
13539 <pre class="literal-block">
13540 qguard foo.patch -- -stable (negative guard)
13541 qguard bar.patch +stable (positive guard)
13542 qselect stable
13543 </pre>
13544 <p>This activates the &quot;stable&quot; guard. mq will skip foo.patch (because
13545 it has a negative match) but push bar.patch (because it has a
13546 positive match).</p>
13547 <p>With no arguments, prints the currently active guards.
13548 With one argument, sets the active guard.</p>
13549 <p>Use -n/--none to deactivate guards (no other arguments needed).
13550 When no guards are active, patches with positive guards are
13551 skipped and patches with negative guards are pushed.</p>
13552 <p>qselect can change the guards on applied patches. It does not pop
13553 guarded patches by default. Use --pop to pop back to the last
13554 applied patch that is not guarded. Use --reapply (which implies
13555 --pop) to push back to the current patch afterwards, but skip
13556 guarded patches.</p>
13557 <p>Use -s/--series to print a list of all guards in the series file
13558 (no other arguments needed). Use -v for more information.</p>
13559 <p>Returns 0 on success.</p>
13560 <p>Options:</p>
13561 <table class="docutils option-list" frame="void" rules="none">
13562 <col class="option" />
13563 <col class="description" />
13564 <tbody valign="top">
13565 <tr><td class="option-group">
13566 <kbd><span class="option">-n</span>, <span class="option">--none</span></kbd></td>
13567 <td>disable all guards</td></tr>
13568 <tr><td class="option-group">
13569 <kbd><span class="option">-s</span>, <span class="option">--series</span></kbd></td>
13570 <td>list all guards in series file</td></tr>
13571 <tr><td class="option-group">
13572 <kbd><span class="option">--pop</span></kbd></td>
13573 <td>pop to before first guarded applied patch</td></tr>
13574 <tr><td class="option-group">
13575 <kbd><span class="option">--reapply</span></kbd></td>
13576 <td>pop, then reapply patches</td></tr>
13577 </tbody>
13578 </table>
13579 </div>
13580 <div class="section" id="qseries">
13581 <h5>qseries</h5>
13582 <p>print the entire series file:</p>
13583 <pre class="literal-block">
13584 hg qseries [-ms]
13585 </pre>
13586 <p>Returns 0 on success.</p>
13587 <p>Options:</p>
13588 <table class="docutils option-list" frame="void" rules="none">
13589 <col class="option" />
13590 <col class="description" />
13591 <tbody valign="top">
13592 <tr><td class="option-group">
13593 <kbd><span class="option">-m</span>, <span class="option">--missing</span></kbd></td>
13594 <td>print patches not in series</td></tr>
13595 <tr><td class="option-group">
13596 <kbd><span class="option">-s</span>, <span class="option">--summary</span></kbd></td>
13597 <td>print first line of patch header</td></tr>
13598 </tbody>
13599 </table>
13600 </div>
13601 <div class="section" id="qtop">
13602 <h5>qtop</h5>
13603 <p>print the name of the current patch:</p>
13604 <pre class="literal-block">
13605 hg qtop [-s]
13606 </pre>
13607 <p>Returns 0 on success.</p>
13608 <p>Options:</p>
13609 <table class="docutils option-list" frame="void" rules="none">
13610 <col class="option" />
13611 <col class="description" />
13612 <tbody valign="top">
13613 <tr><td class="option-group">
13614 <kbd><span class="option">-s</span>, <span class="option">--summary</span></kbd></td>
13615 <td>print first line of patch header</td></tr>
13616 </tbody>
13617 </table>
13618 </div>
13619 <div class="section" id="qunapplied">
13620 <h5>qunapplied</h5>
13621 <p>print the patches not yet applied:</p>
13622 <pre class="literal-block">
13623 hg qunapplied [-1] [-s] [PATCH]
13624 </pre>
13625 <p>Returns 0 on success.</p>
13626 <p>Options:</p>
13627 <table class="docutils option-list" frame="void" rules="none">
13628 <col class="option" />
13629 <col class="description" />
13630 <tbody valign="top">
13631 <tr><td class="option-group">
13632 <kbd><span class="option">-1</span>, <span class="option">--first</span></kbd></td>
13633 <td>show only the first patch</td></tr>
13634 <tr><td class="option-group">
13635 <kbd><span class="option">-s</span>, <span class="option">--summary</span></kbd></td>
13636 <td>print first line of patch header</td></tr>
13637 </tbody>
13638 </table>
13639 </div>
13640 </div>
13641 <div class="section" id="file-content-management-3">
13642 <h4>File content management</h4>
13643 <div class="section" id="qdiff">
13644 <h5>qdiff</h5>
13645 <p>diff of the current patch and subsequent modifications:</p>
13646 <pre class="literal-block">
13647 hg qdiff [OPTION]... [FILE]...
13648 </pre>
13649 <p>Shows a diff which includes the current patch as well as any
13650 changes which have been made in the working directory since the
13651 last refresh (thus showing what the current patch would become
13652 after a qrefresh).</p>
13653 <p>Use <a class="reference external" href="hg.1.html#diff"><tt class="docutils literal">hg diff</tt></a> if you only want to see the changes made since the
13654 last qrefresh, or <a class="reference external" href="hg.1.html#export"><tt class="docutils literal">hg export qtip</tt></a> if you want to see changes
13655 made by the current patch without including changes made since the
13656 qrefresh.</p>
13657 <p>Returns 0 on success.</p>
13658 <p>Options:</p>
13659 <table class="docutils option-list" frame="void" rules="none">
13660 <col class="option" />
13661 <col class="description" />
13662 <tbody valign="top">
13663 <tr><td class="option-group">
13664 <kbd><span class="option">-a</span>, <span class="option">--text</span></kbd></td>
13665 <td>treat all files as text</td></tr>
13666 <tr><td class="option-group">
13667 <kbd><span class="option">-g</span>, <span class="option">--git</span></kbd></td>
13668 <td>use git extended diff format (DEFAULT: diff.git)</td></tr>
13669 <tr><td class="option-group">
13670 <kbd><span class="option">--binary</span></kbd></td>
13671 <td>generate binary diffs in git mode (default)</td></tr>
13672 <tr><td class="option-group">
13673 <kbd><span class="option">--nodates</span></kbd></td>
13674 <td>omit dates from diff headers</td></tr>
13675 <tr><td class="option-group">
13676 <kbd><span class="option">--noprefix</span></kbd></td>
13677 <td>omit a/ and b/ prefixes from filenames</td></tr>
13678 <tr><td class="option-group" colspan="2">
13679 <kbd><span class="option">-p</span>, <span class="option">--show-function</span></kbd></td>
13680 </tr>
13681 <tr><td>&nbsp;</td><td>show which function each change is in (DEFAULT: diff.showfunc)</td></tr>
13682 <tr><td class="option-group">
13683 <kbd><span class="option">--reverse</span></kbd></td>
13684 <td>produce a diff that undoes the changes</td></tr>
13685 <tr><td class="option-group" colspan="2">
13686 <kbd><span class="option">-w</span>, <span class="option">--ignore-all-space</span></kbd></td>
13687 </tr>
13688 <tr><td>&nbsp;</td><td>ignore white space when comparing lines</td></tr>
13689 <tr><td class="option-group" colspan="2">
13690 <kbd><span class="option">-b</span>, <span class="option">--ignore-space-change</span></kbd></td>
13691 </tr>
13692 <tr><td>&nbsp;</td><td>ignore changes in the amount of white space</td></tr>
13693 <tr><td class="option-group" colspan="2">
13694 <kbd><span class="option">-B</span>, <span class="option">--ignore-blank-lines</span></kbd></td>
13695 </tr>
13696 <tr><td>&nbsp;</td><td>ignore changes whose lines are all blank</td></tr>
13697 <tr><td class="option-group" colspan="2">
13698 <kbd><span class="option">-Z</span>, <span class="option">--ignore-space-at-eol</span></kbd></td>
13699 </tr>
13700 <tr><td>&nbsp;</td><td>ignore changes in whitespace at EOL</td></tr>
13701 <tr><td class="option-group" colspan="2">
13702 <kbd><span class="option">-U</span>, <span class="option">--unified <var>&lt;NUM&gt;</var></span></kbd></td>
13703 </tr>
13704 <tr><td>&nbsp;</td><td>number of lines of context to show</td></tr>
13705 <tr><td class="option-group">
13706 <kbd><span class="option">--stat</span></kbd></td>
13707 <td>output diffstat-style summary of changes</td></tr>
13708 <tr><td class="option-group">
13709 <kbd><span class="option">--root <var>&lt;DIR&gt;</var></span></kbd></td>
13710 <td>produce diffs relative to subdirectory</td></tr>
13711 <tr><td class="option-group" colspan="2">
13712 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
13713 </tr>
13714 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
13715 <tr><td class="option-group" colspan="2">
13716 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
13717 </tr>
13718 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
13719 </tbody>
13720 </table>
13721 <p>[+] marked option can be specified multiple times</p>
13722 </div>
13723 </div>
13724 <div class="section" id="change-import-export-2">
13725 <h4>Change import/export</h4>
13726 <div class="section" id="qimport">
13727 <h5>qimport</h5>
13728 <p>import a patch or existing changeset:</p>
13729 <pre class="literal-block">
13730 hg qimport [-e] [-n NAME] [-f] [-g] [-P] [-r REV]... [FILE]...
13731 </pre>
13732 <p>The patch is inserted into the series after the last applied
13733 patch. If no patches have been applied, qimport prepends the patch
13734 to the series.</p>
13735 <p>The patch will have the same name as its source file unless you
13736 give it a new one with -n/--name.</p>
13737 <p>You can register an existing patch inside the patch directory with
13738 the -e/--existing flag.</p>
13739 <p>With -f/--force, an existing patch of the same name will be
13740 overwritten.</p>
13741 <p>An existing changeset may be placed under mq control with -r/--rev
13742 (e.g. qimport --rev . -n patch will place the current revision
13743 under mq control). With -g/--git, patches imported with --rev will
13744 use the git diff format. See the diffs help topic for information
13745 on why this is important for preserving rename/copy information
13746 and permission changes. Use <a class="reference external" href="hg.1.html#qfinish"><tt class="docutils literal">hg qfinish</tt></a> to remove changesets
13747 from mq control.</p>
13748 <p>To import a patch from standard input, pass - as the patch file.
13749 When importing from standard input, a patch name must be specified
13750 using the --name flag.</p>
13751 <p>To import an existing patch while renaming it:</p>
13752 <pre class="literal-block">
13753 hg qimport -e existing-patch -n new-name
13754 </pre>
13755 <p>Returns 0 if import succeeded.</p>
13756 <p>Options:</p>
13757 <table class="docutils option-list" frame="void" rules="none">
13758 <col class="option" />
13759 <col class="description" />
13760 <tbody valign="top">
13761 <tr><td class="option-group">
13762 <kbd><span class="option">-e</span>, <span class="option">--existing</span></kbd></td>
13763 <td>import file in patch directory</td></tr>
13764 <tr><td class="option-group" colspan="2">
13765 <kbd><span class="option">-n</span>, <span class="option">--name <var>&lt;NAME&gt;</var></span></kbd></td>
13766 </tr>
13767 <tr><td>&nbsp;</td><td>name of patch file</td></tr>
13768 <tr><td class="option-group">
13769 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
13770 <td>overwrite existing files</td></tr>
13771 <tr><td class="option-group" colspan="2">
13772 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
13773 </tr>
13774 <tr><td>&nbsp;</td><td>place existing revisions under mq control</td></tr>
13775 <tr><td class="option-group">
13776 <kbd><span class="option">-g</span>, <span class="option">--git</span></kbd></td>
13777 <td>use git extended diff format</td></tr>
13778 <tr><td class="option-group">
13779 <kbd><span class="option">-P</span>, <span class="option">--push</span></kbd></td>
13780 <td>qpush after importing</td></tr>
13781 </tbody>
13782 </table>
13783 <p>[+] marked option can be specified multiple times</p>
13784 </div>
13785 </div>
13786 </div>
13787 </div>
13788 <div class="section" id="narrow">
13789 <h2><a class="toc-backref" href="#toc-entry-74">narrow</a></h2>
13790 <p>create clones which fetch history data for subset of files (EXPERIMENTAL)</p>
13791 <div class="section" id="commands-26">
13792 <h3>Commands</h3>
13793 <div class="section" id="repository-maintenance-4">
13794 <h4>Repository maintenance</h4>
13795 <div class="section" id="tracked">
13796 <h5>tracked</h5>
13797 <p>show or change the current narrowspec:</p>
13798 <pre class="literal-block">
13799 hg tracked [OPTIONS]... [REMOTE]
13800 </pre>
13801 <p>With no argument, shows the current narrowspec entries, one per line. Each
13802 line will be prefixed with 'I' or 'X' for included or excluded patterns,
13803 respectively.</p>
13804 <p>The narrowspec is comprised of expressions to match remote files and/or
13805 directories that should be pulled into your client.
13806 The narrowspec has <em>include</em> and <em>exclude</em> expressions, with excludes always
13807 trumping includes: that is, if a file matches an exclude expression, it will
13808 be excluded even if it also matches an include expression.
13809 Excluding files that were never included has no effect.</p>
13810 <p>Each included or excluded entry is in the format described by
13811 'hg help patterns'.</p>
13812 <p>The options allow you to add or remove included and excluded expressions.</p>
13813 <p>If --clear is specified, then all previous includes and excludes are DROPPED
13814 and replaced by the new ones specified to --addinclude and --addexclude.
13815 If --clear is specified without any further options, the narrowspec will be
13816 empty and will not match any files.</p>
13817 <p>If --auto-remove-includes is specified, then those includes that don't match
13818 any files modified by currently visible local commits (those not shared by
13819 the remote) will be added to the set of explicitly specified includes to
13820 remove.</p>
13821 <p>--import-rules accepts a path to a file containing rules, allowing you to
13822 add --addinclude, --addexclude rules in bulk. Like the other include and
13823 exclude switches, the changes are applied immediately.</p>
13824 <p>Options:</p>
13825 <table class="docutils option-list" frame="void" rules="none">
13826 <col class="option" />
13827 <col class="description" />
13828 <tbody valign="top">
13829 <tr><td class="option-group" colspan="2">
13830 <kbd><span class="option">--addinclude <var>&lt;VALUE[+]&gt;</var></span></kbd></td>
13831 </tr>
13832 <tr><td>&nbsp;</td><td>new paths to include</td></tr>
13833 <tr><td class="option-group" colspan="2">
13834 <kbd><span class="option">--removeinclude <var>&lt;VALUE[+]&gt;</var></span></kbd></td>
13835 </tr>
13836 <tr><td>&nbsp;</td><td>old paths to no longer include</td></tr>
13837 <tr><td class="option-group" colspan="2">
13838 <kbd><span class="option">--auto-remove-includes</span></kbd></td>
13839 </tr>
13840 <tr><td>&nbsp;</td><td>automatically choose unused includes to remove</td></tr>
13841 <tr><td class="option-group" colspan="2">
13842 <kbd><span class="option">--addexclude <var>&lt;VALUE[+]&gt;</var></span></kbd></td>
13843 </tr>
13844 <tr><td>&nbsp;</td><td>new paths to exclude</td></tr>
13845 <tr><td class="option-group" colspan="2">
13846 <kbd><span class="option">--import-rules <var>&lt;VALUE&gt;</var></span></kbd></td>
13847 </tr>
13848 <tr><td>&nbsp;</td><td>import narrowspecs from a file</td></tr>
13849 <tr><td class="option-group" colspan="2">
13850 <kbd><span class="option">--removeexclude <var>&lt;VALUE[+]&gt;</var></span></kbd></td>
13851 </tr>
13852 <tr><td>&nbsp;</td><td>old paths to no longer exclude</td></tr>
13853 <tr><td class="option-group">
13854 <kbd><span class="option">--clear</span></kbd></td>
13855 <td>whether to replace the existing narrowspec</td></tr>
13856 <tr><td class="option-group" colspan="2">
13857 <kbd><span class="option">--force-delete-local-changes</span></kbd></td>
13858 </tr>
13859 <tr><td>&nbsp;</td><td>forces deletion of local changes when narrowing</td></tr>
13860 <tr><td class="option-group">
13861 <kbd><span class="option">--backup</span></kbd></td>
13862 <td>back up local changes when narrowing (default: True)</td></tr>
13863 <tr><td class="option-group" colspan="2">
13864 <kbd><span class="option">--update-working-copy</span></kbd></td>
13865 </tr>
13866 <tr><td>&nbsp;</td><td>update working copy when the store has changed</td></tr>
13867 <tr><td class="option-group" colspan="2">
13868 <kbd><span class="option">-e</span>, <span class="option">--ssh <var>&lt;CMD&gt;</var></span></kbd></td>
13869 </tr>
13870 <tr><td>&nbsp;</td><td>specify ssh command to use</td></tr>
13871 <tr><td class="option-group" colspan="2">
13872 <kbd><span class="option">--remotecmd <var>&lt;CMD&gt;</var></span></kbd></td>
13873 </tr>
13874 <tr><td>&nbsp;</td><td>specify hg command to run on the remote side</td></tr>
13875 <tr><td class="option-group">
13876 <kbd><span class="option">--insecure</span></kbd></td>
13877 <td>do not verify server certificate (ignoring web.cacerts config)</td></tr>
13878 </tbody>
13879 </table>
13880 <p>[+] marked option can be specified multiple times</p>
13881 </div>
13882 </div>
13883 </div>
13884 </div>
13885 <div class="section" id="notify">
13886 <h2><a class="toc-backref" href="#toc-entry-75">notify</a></h2>
13887 <p>hooks for sending email push notifications</p>
13888 <p>This extension implements hooks to send email notifications when
13889 changesets are sent from or received by the local repository.</p>
13890 <p>First, enable the extension as explained in <a class="reference external" href="hg.1.html#extensions"><tt class="docutils literal">hg help extensions</tt></a>, and
13891 register the hook you want to run. <tt class="docutils literal">incoming</tt> and <tt class="docutils literal">changegroup</tt> hooks
13892 are run when changesets are received, while <tt class="docutils literal">outgoing</tt> hooks are for
13893 changesets sent to another repository:</p>
13894 <pre class="literal-block">
13895 [hooks]
13896 # one email for each incoming changeset
13897 incoming.notify = python:hgext.notify.hook
13898 # one email for all incoming changesets
13899 changegroup.notify = python:hgext.notify.hook
13900
13901 # one email for all outgoing changesets
13902 outgoing.notify = python:hgext.notify.hook
13903 </pre>
13904 <p>This registers the hooks. To enable notification, subscribers must
13905 be assigned to repositories. The <tt class="docutils literal">[usersubs]</tt> section maps multiple
13906 repositories to a given recipient. The <tt class="docutils literal">[reposubs]</tt> section maps
13907 multiple recipients to a single repository:</p>
13908 <pre class="literal-block">
13909 [usersubs]
13910 # key is subscriber email, value is a comma-separated list of repo patterns
13911 user&#64;host = pattern
13912
13913 [reposubs]
13914 # key is repo pattern, value is a comma-separated list of subscriber emails
13915 pattern = user&#64;host
13916 </pre>
13917 <p>A <tt class="docutils literal">pattern</tt> is a <tt class="docutils literal">glob</tt> matching the absolute path to a repository,
13918 optionally combined with a revset expression. A revset expression, if
13919 present, is separated from the glob by a hash. Example:</p>
13920 <pre class="literal-block">
13921 [reposubs]
13922 */widgets#branch(release) = qa-team&#64;example.com
13923 </pre>
13924 <p>This sends to <tt class="docutils literal"><span class="pre">qa-team&#64;example.com</span></tt> whenever a changeset on the <tt class="docutils literal">release</tt>
13925 branch triggers a notification in any repository ending in <tt class="docutils literal">widgets</tt>.</p>
13926 <p>In order to place them under direct user management, <tt class="docutils literal">[usersubs]</tt> and
13927 <tt class="docutils literal">[reposubs]</tt> sections may be placed in a separate <tt class="docutils literal">hgrc</tt> file and
13928 incorporated by reference:</p>
13929 <pre class="literal-block">
13930 [notify]
13931 config = /path/to/subscriptionsfile
13932 </pre>
13933 <p>Notifications will not be sent until the <tt class="docutils literal">notify.test</tt> value is set
13934 to <tt class="docutils literal">False</tt>; see below.</p>
13935 <p>Notifications content can be tweaked with the following configuration entries:</p>
13936 <dl class="docutils">
13937 <dt>notify.test</dt>
13938 <dd>If <tt class="docutils literal">True</tt>, print messages to stdout instead of sending them. Default: True.</dd>
13939 <dt>notify.sources</dt>
13940 <dd><p class="first">Space-separated list of change sources. Notifications are activated only
13941 when a changeset's source is in this list. Sources may be:</p>
13942 <table class="docutils field-list" frame="void" rules="none">
13943 <col class="field-name" />
13944 <col class="field-body" />
13945 <tbody valign="top">
13946 <tr class="field"><th class="field-name"><tt class="docutils literal">serve</tt>:</th><td class="field-body">changesets received via http or ssh</td>
13947 </tr>
13948 <tr class="field"><th class="field-name"><tt class="docutils literal">pull</tt>:</th><td class="field-body">changesets received via <tt class="docutils literal">hg pull</tt></td>
13949 </tr>
13950 <tr class="field"><th class="field-name"><tt class="docutils literal">unbundle</tt>:</th><td class="field-body">changesets received via <tt class="docutils literal">hg unbundle</tt></td>
13951 </tr>
13952 <tr class="field"><th class="field-name"><tt class="docutils literal">push</tt>:</th><td class="field-body">changesets sent or received via <tt class="docutils literal">hg push</tt></td>
13953 </tr>
13954 <tr class="field"><th class="field-name"><tt class="docutils literal">bundle</tt>:</th><td class="field-body">changesets sent via <tt class="docutils literal">hg unbundle</tt></td>
13955 </tr>
13956 </tbody>
13957 </table>
13958 <p class="last">Default: serve.</p>
13959 </dd>
13960 <dt>notify.strip</dt>
13961 <dd>Number of leading slashes to strip from url paths. By default, notifications
13962 reference repositories with their absolute path. <tt class="docutils literal">notify.strip</tt> lets you
13963 turn them into relative paths. For example, <tt class="docutils literal">notify.strip=3</tt> will change
13964 <tt class="docutils literal">/long/path/repository</tt> into <tt class="docutils literal">repository</tt>. Default: 0.</dd>
13965 <dt>notify.domain</dt>
13966 <dd>Default email domain for sender or recipients with no explicit domain.
13967 It is also used for the domain part of the <tt class="docutils literal"><span class="pre">Message-Id</span></tt> when using
13968 <tt class="docutils literal">notify.messageidseed</tt>.</dd>
13969 <dt>notify.messageidseed</dt>
13970 <dd>Create deterministic <tt class="docutils literal"><span class="pre">Message-Id</span></tt> headers for the mails based on the seed
13971 and the revision identifier of the first commit in the changeset.</dd>
13972 <dt>notify.style</dt>
13973 <dd>Style file to use when formatting emails.</dd>
13974 <dt>notify.template</dt>
13975 <dd>Template to use when formatting emails.</dd>
13976 <dt>notify.incoming</dt>
13977 <dd>Template to use when run as an incoming hook, overriding <tt class="docutils literal">notify.template</tt>.</dd>
13978 <dt>notify.outgoing</dt>
13979 <dd>Template to use when run as an outgoing hook, overriding <tt class="docutils literal">notify.template</tt>.</dd>
13980 <dt>notify.changegroup</dt>
13981 <dd>Template to use when running as a changegroup hook, overriding
13982 <tt class="docutils literal">notify.template</tt>.</dd>
13983 <dt>notify.maxdiff</dt>
13984 <dd>Maximum number of diff lines to include in notification email. Set to 0
13985 to disable the diff, or -1 to include all of it. Default: 300.</dd>
13986 <dt>notify.maxdiffstat</dt>
13987 <dd>Maximum number of diffstat lines to include in notification email. Set to -1
13988 to include all of it. Default: -1.</dd>
13989 <dt>notify.maxsubject</dt>
13990 <dd>Maximum number of characters in email's subject line. Default: 67.</dd>
13991 <dt>notify.diffstat</dt>
13992 <dd>Set to True to include a diffstat before diff content. Default: True.</dd>
13993 <dt>notify.showfunc</dt>
13994 <dd>If set, override <tt class="docutils literal">diff.showfunc</tt> for the diff content. Default: None.</dd>
13995 <dt>notify.merge</dt>
13996 <dd>If True, send notifications for merge changesets. Default: True.</dd>
13997 <dt>notify.mbox</dt>
13998 <dd>If set, append mails to this mbox file instead of sending. Default: None.</dd>
13999 <dt>notify.fromauthor</dt>
14000 <dd>If set, use the committer of the first changeset in a changegroup for
14001 the &quot;From&quot; field of the notification mail. If not set, take the user
14002 from the pushing repo. Default: False.</dd>
14003 <dt>notify.reply-to-predecessor (EXPERIMENTAL)</dt>
14004 <dd><p class="first">If set and the changeset has a predecessor in the repository, try to thread
14005 the notification mail with the predecessor. This adds the &quot;In-Reply-To&quot; header
14006 to the notification mail with a reference to the predecessor with the smallest
14007 revision number. Mail threads can still be torn, especially when changesets
14008 are folded.</p>
14009 <p class="last">This option must be used in combination with <tt class="docutils literal">notify.messageidseed</tt>.</p>
14010 </dd>
14011 </dl>
14012 <p>If set, the following entries will also be used to customize the
14013 notifications:</p>
14014 <dl class="docutils">
14015 <dt>email.from</dt>
14016 <dd>Email <tt class="docutils literal">From</tt> address to use if none can be found in the generated
14017 email content.</dd>
14018 <dt>web.baseurl</dt>
14019 <dd>Root repository URL to combine with repository paths when making
14020 references. See also <tt class="docutils literal">notify.strip</tt>.</dd>
14021 </dl>
14022 </div>
14023 <div class="section" id="pager-1">
14024 <h2><a class="toc-backref" href="#toc-entry-76">pager</a></h2>
14025 <p>browse command output with an external pager (DEPRECATED)</p>
14026 <p>Forcibly enable paging for individual commands that don't typically
14027 request pagination with the attend-&lt;command&gt; option. This setting
14028 takes precedence over ignore options and defaults:</p>
14029 <pre class="literal-block">
14030 [pager]
14031 attend-cat = false
14032 </pre>
14033 </div>
14034 <div class="section" id="patchbomb">
14035 <h2><a class="toc-backref" href="#toc-entry-77">patchbomb</a></h2>
14036 <p>command to send changesets as (a series of) patch emails</p>
14037 <p>The series is started off with a &quot;[PATCH 0 of N]&quot; introduction, which
14038 describes the series as a whole.</p>
14039 <p>Each patch email has a Subject line of &quot;[PATCH M of N] ...&quot;, using the
14040 first line of the changeset description as the subject text. The
14041 message contains two or three body parts:</p>
14042 <ul class="simple">
14043 <li>The changeset description.</li>
14044 <li>[Optional] The result of running diffstat on the patch.</li>
14045 <li>The patch itself, as generated by <a class="reference external" href="hg.1.html#export"><tt class="docutils literal">hg export</tt></a>.</li>
14046 </ul>
14047 <p>Each message refers to the first in the series using the In-Reply-To
14048 and References headers, so they will show up as a sequence in threaded
14049 mail and news readers, and in mail archives.</p>
14050 <p>To configure other defaults, add a section like this to your
14051 configuration file:</p>
14052 <pre class="literal-block">
14053 [email]
14054 from = My Name &lt;my&#64;email&gt;
14055 to = recipient1, recipient2, ...
14056 cc = cc1, cc2, ...
14057 bcc = bcc1, bcc2, ...
14058 reply-to = address1, address2, ...
14059 </pre>
14060 <p>Use <tt class="docutils literal">[patchbomb]</tt> as configuration section name if you need to
14061 override global <tt class="docutils literal">[email]</tt> address settings.</p>
14062 <p>Then you can use the <a class="reference external" href="hg.1.html#email"><tt class="docutils literal">hg email</tt></a> command to mail a series of
14063 changesets as a patchbomb.</p>
14064 <p>You can also either configure the method option in the email section
14065 to be a sendmail compatible mailer or fill out the [smtp] section so
14066 that the patchbomb extension can automatically send patchbombs
14067 directly from the commandline. See the [email] and [smtp] sections in
14068 hgrc(5) for details.</p>
14069 <p>By default, <a class="reference external" href="hg.1.html#email"><tt class="docutils literal">hg email</tt></a> will prompt for a <tt class="docutils literal">To</tt> or <tt class="docutils literal">CC</tt> header if
14070 you do not supply one via configuration or the command line. You can
14071 override this to never prompt by configuring an empty value:</p>
14072 <pre class="literal-block">
14073 [email]
14074 cc =
14075 </pre>
14076 <p>You can control the default inclusion of an introduction message with the
14077 <tt class="docutils literal">patchbomb.intro</tt> configuration option. The configuration is always
14078 overwritten by command line flags like --intro and --desc:</p>
14079 <pre class="literal-block">
14080 [patchbomb]
14081 intro=auto # include introduction message if more than 1 patch (default)
14082 intro=never # never include an introduction message
14083 intro=always # always include an introduction message
14084 </pre>
14085 <p>You can specify a template for flags to be added in subject prefixes. Flags
14086 specified by --flag option are exported as <tt class="docutils literal">{flags}</tt> keyword:</p>
14087 <pre class="literal-block">
14088 [patchbomb]
14089 flagtemplate = &quot;{separate(' ',
14090 ifeq(branch, 'default', '', branch|upper),
14091 flags)}&quot;
14092 </pre>
14093 <p>You can set patchbomb to always ask for confirmation by setting
14094 <tt class="docutils literal">patchbomb.confirm</tt> to true.</p>
14095 <div class="section" id="commands-27">
14096 <h3>Commands</h3>
14097 <div class="section" id="change-import-export-3">
14098 <h4>Change import/export</h4>
14099 <div class="section" id="email">
14100 <h5>email</h5>
14101 <p>send changesets by email:</p>
14102 <pre class="literal-block">
14103 hg email [OPTION]... [DEST]...
14104 </pre>
14105 <p>By default, diffs are sent in the format generated by
14106 <a class="reference external" href="hg.1.html#export"><tt class="docutils literal">hg export</tt></a>, one per message. The series starts with a &quot;[PATCH 0
14107 of N]&quot; introduction, which describes the series as a whole.</p>
14108 <p>Each patch email has a Subject line of &quot;[PATCH M of N] ...&quot;, using
14109 the first line of the changeset description as the subject text.
14110 The message contains two or three parts. First, the changeset
14111 description.</p>
14112 <p>With the -d/--diffstat option, if the diffstat program is
14113 installed, the result of running diffstat on the patch is inserted.</p>
14114 <p>Finally, the patch itself, as generated by <a class="reference external" href="hg.1.html#export"><tt class="docutils literal">hg export</tt></a>.</p>
14115 <p>With the -d/--diffstat or --confirm options, you will be presented
14116 with a final summary of all messages and asked for confirmation before
14117 the messages are sent.</p>
14118 <p>By default the patch is included as text in the email body for
14119 easy reviewing. Using the -a/--attach option will instead create
14120 an attachment for the patch. With -i/--inline an inline attachment
14121 will be created. You can include a patch both as text in the email
14122 body and as a regular or an inline attachment by combining the
14123 -a/--attach or -i/--inline with the --body option.</p>
14124 <p>With -B/--bookmark changesets reachable by the given bookmark are
14125 selected.</p>
14126 <p>With -o/--outgoing, emails will be generated for patches not found
14127 in the destination repository (or only those which are ancestors
14128 of the specified revisions if any are provided)</p>
14129 <p>With -b/--bundle, changesets are selected as for --outgoing, but a
14130 single email containing a binary Mercurial bundle as an attachment
14131 will be sent. Use the <tt class="docutils literal">patchbomb.bundletype</tt> config option to
14132 control the bundle type as with <a class="reference external" href="hg.1.html#bundle"><tt class="docutils literal">hg bundle <span class="pre">--type</span></tt></a>.</p>
14133 <p>With -m/--mbox, instead of previewing each patchbomb message in a
14134 pager or sending the messages directly, it will create a UNIX
14135 mailbox file with the patch emails. This mailbox file can be
14136 previewed with any mail user agent which supports UNIX mbox
14137 files.</p>
14138 <p>With -n/--test, all steps will run, but mail will not be sent.
14139 You will be prompted for an email recipient address, a subject and
14140 an introductory message describing the patches of your patchbomb.
14141 Then when all is done, patchbomb messages are displayed.</p>
14142 <p>In case email sending fails, you will find a backup of your series
14143 introductory message in <tt class="docutils literal"><span class="pre">.hg/last-email.txt</span></tt>.</p>
14144 <p>The default behavior of this command can be customized through
14145 configuration. (See <a class="reference external" href="hg.1.html#patchbomb"><tt class="docutils literal">hg help patchbomb</tt></a> for details)</p>
14146 <p>Examples:</p>
14147 <pre class="literal-block">
14148 hg email -r 3000 # send patch 3000 only
14149 hg email -r 3000 -r 3001 # send patches 3000 and 3001
14150 hg email -r 3000:3005 # send patches 3000 through 3005
14151 hg email 3000 # send patch 3000 (deprecated)
14152
14153 hg email -o # send all patches not in default
14154 hg email -o DEST # send all patches not in DEST
14155 hg email -o -r 3000 # send all ancestors of 3000 not in default
14156 hg email -o -r 3000 DEST # send all ancestors of 3000 not in DEST
14157
14158 hg email -B feature # send all ancestors of feature bookmark
14159
14160 hg email -b # send bundle of all patches not in default
14161 hg email -b DEST # send bundle of all patches not in DEST
14162 hg email -b -r 3000 # bundle of all ancestors of 3000 not in default
14163 hg email -b -r 3000 DEST # bundle of all ancestors of 3000 not in DEST
14164
14165 hg email -o -m mbox &amp;&amp; # generate an mbox file...
14166 mutt -R -f mbox # ... and view it with mutt
14167 hg email -o -m mbox &amp;&amp; # generate an mbox file ...
14168 formail -s sendmail \ # ... and use formail to send from the mbox
14169 -bm -t &lt; mbox # ... using sendmail
14170 </pre>
14171 <p>Before using this command, you will need to enable email in your
14172 hgrc. See the [email] section in hgrc(5) for details.</p>
14173 <p>Options:</p>
14174 <table class="docutils option-list" frame="void" rules="none">
14175 <col class="option" />
14176 <col class="description" />
14177 <tbody valign="top">
14178 <tr><td class="option-group">
14179 <kbd><span class="option">-g</span>, <span class="option">--git</span></kbd></td>
14180 <td>use git extended diff format</td></tr>
14181 <tr><td class="option-group">
14182 <kbd><span class="option">--plain</span></kbd></td>
14183 <td>omit hg patch header</td></tr>
14184 <tr><td class="option-group">
14185 <kbd><span class="option">-o</span>, <span class="option">--outgoing</span></kbd></td>
14186 <td>send changes not found in the target repository</td></tr>
14187 <tr><td class="option-group">
14188 <kbd><span class="option">-b</span>, <span class="option">--bundle</span></kbd></td>
14189 <td>send changes not in target as a binary bundle</td></tr>
14190 <tr><td class="option-group" colspan="2">
14191 <kbd><span class="option">-B</span>, <span class="option">--bookmark <var>&lt;BOOKMARK&gt;</var></span></kbd></td>
14192 </tr>
14193 <tr><td>&nbsp;</td><td>send changes only reachable by given bookmark</td></tr>
14194 <tr><td class="option-group" colspan="2">
14195 <kbd><span class="option">--bundlename <var>&lt;NAME&gt;</var></span></kbd></td>
14196 </tr>
14197 <tr><td>&nbsp;</td><td>name of the bundle attachment file (default: bundle)</td></tr>
14198 <tr><td class="option-group" colspan="2">
14199 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
14200 </tr>
14201 <tr><td>&nbsp;</td><td>a revision to send</td></tr>
14202 <tr><td class="option-group">
14203 <kbd><span class="option">--force</span></kbd></td>
14204 <td>run even when remote repository is unrelated (with -b/--bundle)</td></tr>
14205 <tr><td class="option-group" colspan="2">
14206 <kbd><span class="option">--base <var>&lt;REV[+]&gt;</var></span></kbd></td>
14207 </tr>
14208 <tr><td>&nbsp;</td><td>a base changeset to specify instead of a destination (with -b/--bundle)</td></tr>
14209 <tr><td class="option-group">
14210 <kbd><span class="option">--intro</span></kbd></td>
14211 <td>send an introduction email for a single patch</td></tr>
14212 <tr><td class="option-group">
14213 <kbd><span class="option">--body</span></kbd></td>
14214 <td>send patches as inline message text (default)</td></tr>
14215 <tr><td class="option-group">
14216 <kbd><span class="option">-a</span>, <span class="option">--attach</span></kbd></td>
14217 <td>send patches as attachments</td></tr>
14218 <tr><td class="option-group">
14219 <kbd><span class="option">-i</span>, <span class="option">--inline</span></kbd></td>
14220 <td>send patches as inline attachments</td></tr>
14221 <tr><td class="option-group" colspan="2">
14222 <kbd><span class="option">--bcc <var>&lt;EMAIL[+]&gt;</var></span></kbd></td>
14223 </tr>
14224 <tr><td>&nbsp;</td><td>email addresses of blind carbon copy recipients</td></tr>
14225 <tr><td class="option-group" colspan="2">
14226 <kbd><span class="option">-c</span>, <span class="option">--cc <var>&lt;EMAIL[+]&gt;</var></span></kbd></td>
14227 </tr>
14228 <tr><td>&nbsp;</td><td>email addresses of copy recipients</td></tr>
14229 <tr><td class="option-group">
14230 <kbd><span class="option">--confirm</span></kbd></td>
14231 <td>ask for confirmation before sending</td></tr>
14232 <tr><td class="option-group">
14233 <kbd><span class="option">-d</span>, <span class="option">--diffstat</span></kbd></td>
14234 <td>add diffstat output to messages</td></tr>
14235 <tr><td class="option-group">
14236 <kbd><span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
14237 <td>use the given date as the sending date</td></tr>
14238 <tr><td class="option-group">
14239 <kbd><span class="option">--desc <var>&lt;FILE&gt;</var></span></kbd></td>
14240 <td>use the given file as the series description</td></tr>
14241 <tr><td class="option-group" colspan="2">
14242 <kbd><span class="option">-f</span>, <span class="option">--from <var>&lt;EMAIL&gt;</var></span></kbd></td>
14243 </tr>
14244 <tr><td>&nbsp;</td><td>email address of sender</td></tr>
14245 <tr><td class="option-group">
14246 <kbd><span class="option">-n</span>, <span class="option">--test</span></kbd></td>
14247 <td>print messages that would be sent</td></tr>
14248 <tr><td class="option-group" colspan="2">
14249 <kbd><span class="option">-m</span>, <span class="option">--mbox <var>&lt;FILE&gt;</var></span></kbd></td>
14250 </tr>
14251 <tr><td>&nbsp;</td><td>write messages to mbox file instead of sending them</td></tr>
14252 <tr><td class="option-group" colspan="2">
14253 <kbd><span class="option">--reply-to <var>&lt;EMAIL[+]&gt;</var></span></kbd></td>
14254 </tr>
14255 <tr><td>&nbsp;</td><td>email addresses replies should be sent to</td></tr>
14256 <tr><td class="option-group" colspan="2">
14257 <kbd><span class="option">-s</span>, <span class="option">--subject <var>&lt;TEXT&gt;</var></span></kbd></td>
14258 </tr>
14259 <tr><td>&nbsp;</td><td>subject of first message (intro or single patch)</td></tr>
14260 <tr><td class="option-group" colspan="2">
14261 <kbd><span class="option">--in-reply-to <var>&lt;MSGID&gt;</var></span></kbd></td>
14262 </tr>
14263 <tr><td>&nbsp;</td><td>message identifier to reply to</td></tr>
14264 <tr><td class="option-group" colspan="2">
14265 <kbd><span class="option">--flag <var>&lt;FLAG[+]&gt;</var></span></kbd></td>
14266 </tr>
14267 <tr><td>&nbsp;</td><td>flags to add in subject prefixes</td></tr>
14268 <tr><td class="option-group" colspan="2">
14269 <kbd><span class="option">-t</span>, <span class="option">--to <var>&lt;EMAIL[+]&gt;</var></span></kbd></td>
14270 </tr>
14271 <tr><td>&nbsp;</td><td>email addresses of recipients</td></tr>
14272 <tr><td class="option-group" colspan="2">
14273 <kbd><span class="option">-e</span>, <span class="option">--ssh <var>&lt;CMD&gt;</var></span></kbd></td>
14274 </tr>
14275 <tr><td>&nbsp;</td><td>specify ssh command to use</td></tr>
14276 <tr><td class="option-group" colspan="2">
14277 <kbd><span class="option">--remotecmd <var>&lt;CMD&gt;</var></span></kbd></td>
14278 </tr>
14279 <tr><td>&nbsp;</td><td>specify hg command to run on the remote side</td></tr>
14280 <tr><td class="option-group">
14281 <kbd><span class="option">--insecure</span></kbd></td>
14282 <td>do not verify server certificate (ignoring web.cacerts config)</td></tr>
14283 </tbody>
14284 </table>
14285 <p>[+] marked option can be specified multiple times</p>
14286 </div>
14287 </div>
14288 </div>
14289 </div>
14290 <div class="section" id="phabricator">
14291 <h2><a class="toc-backref" href="#toc-entry-78">phabricator</a></h2>
14292 <p>simple Phabricator integration (EXPERIMENTAL)</p>
14293 <p>This extension provides a <tt class="docutils literal">phabsend</tt> command which sends a stack of
14294 changesets to Phabricator, and a <tt class="docutils literal">phabread</tt> command which prints a stack of
14295 revisions in a format suitable for <a class="reference external" href="hg.1.html#import"><tt class="docutils literal">hg import</tt></a>, and a <tt class="docutils literal">phabupdate</tt> command
14296 to update statuses in batch.</p>
14297 <p>A &quot;phabstatus&quot; view for <a class="reference external" href="hg.1.html#show"><tt class="docutils literal">hg show</tt></a> is also provided; it displays status
14298 information of Phabricator differentials associated with unfinished
14299 changesets.</p>
14300 <p>By default, Phabricator requires <tt class="docutils literal">Test Plan</tt> which might prevent some
14301 changeset from being sent. The requirement could be disabled by changing
14302 <tt class="docutils literal"><span class="pre">differential.require-test-plan-field</span></tt> config server side.</p>
14303 <p>Config:</p>
14304 <pre class="literal-block">
14305 [phabricator]
14306 # Phabricator URL
14307 url = https://phab.example.com/
14308
14309 # Repo callsign. If a repo has a URL https://$HOST/diffusion/FOO, then its
14310 # callsign is &quot;FOO&quot;.
14311 callsign = FOO
14312
14313 # curl command to use. If not set (default), use builtin HTTP library to
14314 # communicate. If set, use the specified curl command. This could be useful
14315 # if you need to specify advanced options that is not easily supported by
14316 # the internal library.
14317 curlcmd = curl --connect-timeout 2 --retry 3 --silent
14318
14319 # retry failed command N time (default 0). Useful when using the extension
14320 # over flakly connection.
14321 #
14322 # We wait `retry.interval` between each retry, in seconds.
14323 # (default 1 second).
14324 retry = 3
14325 retry.interval = 10
14326
14327 # the retry option can combine well with the http.timeout one.
14328 #
14329 # For example to give up on http request after 20 seconds:
14330 [http]
14331 timeout=20
14332
14333 [auth]
14334 example.schemes = https
14335 example.prefix = phab.example.com
14336
14337 # API token. Get it from https://$HOST/conduit/login/
14338 example.phabtoken = cli-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
14339 </pre>
14340 <div class="section" id="commands-28">
14341 <h3>Commands</h3>
14342 <div class="section" id="change-import-export-4">
14343 <h4>Change import/export</h4>
14344 <div class="section" id="phabimport">
14345 <h5>phabimport</h5>
14346 <p>import patches from Phabricator for the specified Differential Revisions:</p>
14347 <pre class="literal-block">
14348 hg phabimport DREVSPEC... [OPTIONS]
14349 </pre>
14350 <p>The patches are read and applied starting at the parent of the working
14351 directory.</p>
14352 <p>See <tt class="docutils literal">hg help phabread</tt> for how to specify DREVSPEC.</p>
14353 <p>Options:</p>
14354 <table class="docutils option-list" frame="void" rules="none">
14355 <col class="option" />
14356 <col class="description" />
14357 <tbody valign="top">
14358 <tr><td class="option-group">
14359 <kbd><span class="option">--stack</span></kbd></td>
14360 <td>import dependencies as well</td></tr>
14361 <tr><td class="option-group" colspan="2">
14362 <kbd><span class="option">--test-vcr <var>&lt;VALUE&gt;</var></span></kbd></td>
14363 </tr>
14364 <tr><td>&nbsp;</td><td>Path to a vcr file. If nonexistent, will record a new vcr transcript, otherwise will mock all http requests using the specified vcr file. (ADVANCED)</td></tr>
14365 </tbody>
14366 </table>
14367 </div>
14368 <div class="section" id="phabread">
14369 <h5>phabread</h5>
14370 <p>print patches from Phabricator suitable for importing:</p>
14371 <pre class="literal-block">
14372 hg phabread DREVSPEC... [OPTIONS]
14373 </pre>
14374 <p>DREVSPEC could be a Differential Revision identity, like <tt class="docutils literal">D123</tt>, or just
14375 the number <tt class="docutils literal">123</tt>. It could also have common operators like <tt class="docutils literal">+</tt>, <tt class="docutils literal">-</tt>,
14376 <tt class="docutils literal">&amp;</tt>, <tt class="docutils literal">(</tt>, <tt class="docutils literal">)</tt> for complex queries. Prefix <tt class="docutils literal">:</tt> could be used to
14377 select a stack. If multiple DREVSPEC values are given, the result is the
14378 union of each individually evaluated value. No attempt is currently made
14379 to reorder the values to run from parent to child.</p>
14380 <p><tt class="docutils literal">abandoned</tt>, <tt class="docutils literal">accepted</tt>, <tt class="docutils literal">closed</tt>, <tt class="docutils literal">needsreview</tt>, <tt class="docutils literal">needsrevision</tt>
14381 could be used to filter patches by status. For performance reason, they
14382 only represent a subset of non-status selections and cannot be used alone.</p>
14383 <p>For example, <tt class="docutils literal"><span class="pre">:D6+8-(2+D4)</span></tt> selects a stack up to D6, plus D8 and exclude
14384 D2 and D4. <tt class="docutils literal">:D9 &amp; needsreview</tt> selects &quot;Needs Review&quot; revisions in a
14385 stack up to D9.</p>
14386 <p>If --stack is given, follow dependencies information and read all patches.
14387 It is equivalent to the <tt class="docutils literal">:</tt> operator.</p>
14388 <p>Options:</p>
14389 <table class="docutils option-list" frame="void" rules="none">
14390 <col class="option" />
14391 <col class="description" />
14392 <tbody valign="top">
14393 <tr><td class="option-group">
14394 <kbd><span class="option">--stack</span></kbd></td>
14395 <td>read dependencies</td></tr>
14396 <tr><td class="option-group" colspan="2">
14397 <kbd><span class="option">--test-vcr <var>&lt;VALUE&gt;</var></span></kbd></td>
14398 </tr>
14399 <tr><td>&nbsp;</td><td>Path to a vcr file. If nonexistent, will record a new vcr transcript, otherwise will mock all http requests using the specified vcr file. (ADVANCED)</td></tr>
14400 </tbody>
14401 </table>
14402 </div>
14403 <div class="section" id="phabsend">
14404 <h5>phabsend</h5>
14405 <p>upload changesets to Phabricator:</p>
14406 <pre class="literal-block">
14407 hg phabsend REV [OPTIONS]
14408 </pre>
14409 <p>If there are multiple revisions specified, they will be send as a stack
14410 with a linear dependencies relationship using the order specified by the
14411 revset.</p>
14412 <p>For the first time uploading changesets, local tags will be created to
14413 maintain the association. After the first time, phabsend will check
14414 obsstore and tags information so it can figure out whether to update an
14415 existing Differential Revision, or create a new one.</p>
14416 <p>If --amend is set, update commit messages so they have the
14417 <tt class="docutils literal">Differential Revision</tt> URL, remove related tags. This is similar to what
14418 arcanist will do, and is more desired in author-push workflows. Otherwise,
14419 use local tags to record the <tt class="docutils literal">Differential Revision</tt> association.</p>
14420 <p>The --confirm option lets you confirm changesets before sending them. You
14421 can also add following to your configuration file to make it default
14422 behaviour:</p>
14423 <pre class="literal-block">
14424 [phabsend]
14425 confirm = true
14426 </pre>
14427 <p>By default, a separate review will be created for each commit that is
14428 selected, and will have the same parent/child relationship in Phabricator.
14429 If <tt class="docutils literal"><span class="pre">--fold</span></tt> is set, multiple commits are rolled up into a single review
14430 as if diffed from the parent of the first revision to the last. The commit
14431 messages are concatenated in the summary field on Phabricator.</p>
14432 <p>phabsend will check obsstore and the above association to decide whether to
14433 update an existing Differential Revision, or create a new one.</p>
14434 <p>Options:</p>
14435 <table class="docutils option-list" frame="void" rules="none">
14436 <col class="option" />
14437 <col class="description" />
14438 <tbody valign="top">
14439 <tr><td class="option-group" colspan="2">
14440 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
14441 </tr>
14442 <tr><td>&nbsp;</td><td>revisions to send</td></tr>
14443 <tr><td class="option-group">
14444 <kbd><span class="option">--amend</span></kbd></td>
14445 <td>update commit messages (default: True)</td></tr>
14446 <tr><td class="option-group" colspan="2">
14447 <kbd><span class="option">--reviewer <var>&lt;VALUE[+]&gt;</var></span></kbd></td>
14448 </tr>
14449 <tr><td>&nbsp;</td><td>specify reviewers</td></tr>
14450 <tr><td class="option-group" colspan="2">
14451 <kbd><span class="option">--blocker <var>&lt;VALUE[+]&gt;</var></span></kbd></td>
14452 </tr>
14453 <tr><td>&nbsp;</td><td>specify blocking reviewers</td></tr>
14454 <tr><td class="option-group" colspan="2">
14455 <kbd><span class="option">-m</span>, <span class="option">--comment <var>&lt;VALUE&gt;</var></span></kbd></td>
14456 </tr>
14457 <tr><td>&nbsp;</td><td>add a comment to Revisions with new/updated Diffs</td></tr>
14458 <tr><td class="option-group">
14459 <kbd><span class="option">--confirm</span></kbd></td>
14460 <td>ask for confirmation before sending</td></tr>
14461 <tr><td class="option-group">
14462 <kbd><span class="option">--fold</span></kbd></td>
14463 <td>combine the revisions into one review</td></tr>
14464 <tr><td class="option-group" colspan="2">
14465 <kbd><span class="option">--test-vcr <var>&lt;VALUE&gt;</var></span></kbd></td>
14466 </tr>
14467 <tr><td>&nbsp;</td><td>Path to a vcr file. If nonexistent, will record a new vcr transcript, otherwise will mock all http requests using the specified vcr file. (ADVANCED)</td></tr>
14468 </tbody>
14469 </table>
14470 <p>[+] marked option can be specified multiple times</p>
14471 </div>
14472 <div class="section" id="phabupdate">
14473 <h5>phabupdate</h5>
14474 <p>update Differential Revision in batch:</p>
14475 <pre class="literal-block">
14476 hg phabupdate [DREVSPEC...| -r REV...] [OPTIONS]
14477 </pre>
14478 <p>DREVSPEC selects revisions. See <a class="reference external" href="hg.1.html#phabread"><tt class="docutils literal">hg help phabread</tt></a> for its usage.</p>
14479 <p>Options:</p>
14480 <table class="docutils option-list" frame="void" rules="none">
14481 <col class="option" />
14482 <col class="description" />
14483 <tbody valign="top">
14484 <tr><td class="option-group">
14485 <kbd><span class="option">--accept</span></kbd></td>
14486 <td>accept revisions</td></tr>
14487 <tr><td class="option-group">
14488 <kbd><span class="option">--reject</span></kbd></td>
14489 <td>reject revisions</td></tr>
14490 <tr><td class="option-group" colspan="2">
14491 <kbd><span class="option">--request-review</span></kbd></td>
14492 </tr>
14493 <tr><td>&nbsp;</td><td>request review on revisions</td></tr>
14494 <tr><td class="option-group">
14495 <kbd><span class="option">--abandon</span></kbd></td>
14496 <td>abandon revisions</td></tr>
14497 <tr><td class="option-group">
14498 <kbd><span class="option">--reclaim</span></kbd></td>
14499 <td>reclaim revisions</td></tr>
14500 <tr><td class="option-group">
14501 <kbd><span class="option">--close</span></kbd></td>
14502 <td>close revisions</td></tr>
14503 <tr><td class="option-group">
14504 <kbd><span class="option">--reopen</span></kbd></td>
14505 <td>reopen revisions</td></tr>
14506 <tr><td class="option-group">
14507 <kbd><span class="option">--plan-changes</span></kbd></td>
14508 <td>plan changes for revisions</td></tr>
14509 <tr><td class="option-group">
14510 <kbd><span class="option">--resign</span></kbd></td>
14511 <td>resign as a reviewer from revisions</td></tr>
14512 <tr><td class="option-group">
14513 <kbd><span class="option">--commandeer</span></kbd></td>
14514 <td>commandeer revisions</td></tr>
14515 <tr><td class="option-group" colspan="2">
14516 <kbd><span class="option">-m</span>, <span class="option">--comment <var>&lt;VALUE&gt;</var></span></kbd></td>
14517 </tr>
14518 <tr><td>&nbsp;</td><td>comment on the last revision</td></tr>
14519 <tr><td class="option-group" colspan="2">
14520 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV&gt;</var></span></kbd></td>
14521 </tr>
14522 <tr><td>&nbsp;</td><td>local revision to update</td></tr>
14523 <tr><td class="option-group" colspan="2">
14524 <kbd><span class="option">--test-vcr <var>&lt;VALUE&gt;</var></span></kbd></td>
14525 </tr>
14526 <tr><td>&nbsp;</td><td>Path to a vcr file. If nonexistent, will record a new vcr transcript, otherwise will mock all http requests using the specified vcr file. (ADVANCED)</td></tr>
14527 </tbody>
14528 </table>
14529 </div>
14530 </div>
14531 </div>
14532 </div>
14533 <div class="section" id="purge-1">
14534 <h2><a class="toc-backref" href="#toc-entry-79">purge</a></h2>
14535 <p>command to delete untracked files from the working directory (DEPRECATED)</p>
14536 <p>The functionality of this extension has been included in core Mercurial since
14537 version 5.7. Please use <a class="reference external" href="hg.1.html#purge"><tt class="docutils literal">hg purge ...</tt></a> instead. <a class="reference external" href="hg.1.html#purge"><tt class="docutils literal">hg purge <span class="pre">--confirm</span></tt></a> is now
14538 the default, unless the extension is enabled for backward compatibility.</p>
14539 </div>
14540 <div class="section" id="rebase">
14541 <h2><a class="toc-backref" href="#toc-entry-80">rebase</a></h2>
14542 <p>command to move sets of revisions to a different ancestor</p>
14543 <p>This extension lets you rebase changesets in an existing Mercurial
14544 repository.</p>
14545 <p>For more information:
14546 <a class="reference external" href="https://mercurial-scm.org/wiki/RebaseExtension">https://mercurial-scm.org/wiki/RebaseExtension</a></p>
14547 <div class="section" id="commands-29">
14548 <h3>Commands</h3>
14549 <div class="section" id="change-manipulation-4">
14550 <h4>Change manipulation</h4>
14551 <div class="section" id="rebase-1">
14552 <h5>rebase</h5>
14553 <p>move changeset (and descendants) to a different branch:</p>
14554 <pre class="literal-block">
14555 hg rebase [[-s REV]... | [-b REV]... | [-r REV]...] [-d REV] [OPTION]...
14556 </pre>
14557 <p>Rebase uses repeated merging to graft changesets from one part of
14558 history (the source) onto another (the destination). This can be
14559 useful for linearizing <em>local</em> changes relative to a master
14560 development tree.</p>
14561 <p>Published commits cannot be rebased (see <a class="reference external" href="hg.1.html#phases"><tt class="docutils literal">hg help phases</tt></a>).
14562 To copy commits, see <a class="reference external" href="hg.1.html#graft"><tt class="docutils literal">hg help graft</tt></a>.</p>
14563 <p>If you don't specify a destination changeset (<tt class="docutils literal"><span class="pre">-d/--dest</span></tt>), rebase
14564 will use the same logic as <a class="reference external" href="hg.1.html#merge"><tt class="docutils literal">hg merge</tt></a> to pick a destination. if
14565 the current branch contains exactly one other head, the other head
14566 is merged with by default. Otherwise, an explicit revision with
14567 which to merge with must be provided. (destination changeset is not
14568 modified by rebasing, but new changesets are added as its
14569 descendants.)</p>
14570 <p>Here are the ways to select changesets:</p>
14571 <blockquote>
14572 <ol class="arabic simple">
14573 <li>Explicitly select them using <tt class="docutils literal"><span class="pre">--rev</span></tt>.</li>
14574 <li>Use <tt class="docutils literal"><span class="pre">--source</span></tt> to select a root changeset and include all of its
14575 descendants.</li>
14576 <li>Use <tt class="docutils literal"><span class="pre">--base</span></tt> to select a changeset; rebase will find ancestors
14577 and their descendants which are not also ancestors of the destination.</li>
14578 <li>If you do not specify any of <tt class="docutils literal"><span class="pre">--rev</span></tt>, <tt class="docutils literal"><span class="pre">--source</span></tt>, or <tt class="docutils literal"><span class="pre">--base</span></tt>,
14579 rebase will use <tt class="docutils literal"><span class="pre">--base</span> .</tt> as above.</li>
14580 </ol>
14581 </blockquote>
14582 <p>If <tt class="docutils literal"><span class="pre">--source</span></tt> or <tt class="docutils literal"><span class="pre">--rev</span></tt> is used, special names <tt class="docutils literal">SRC</tt> and <tt class="docutils literal">ALLSRC</tt>
14583 can be used in <tt class="docutils literal"><span class="pre">--dest</span></tt>. Destination would be calculated per source
14584 revision with <tt class="docutils literal">SRC</tt> substituted by that single source revision and
14585 <tt class="docutils literal">ALLSRC</tt> substituted by all source revisions.</p>
14586 <p>Rebase will destroy original changesets unless you use <tt class="docutils literal"><span class="pre">--keep</span></tt>.
14587 It will also move your bookmarks (even if you do).</p>
14588 <p>Some changesets may be dropped if they do not contribute changes
14589 (e.g. merges from the destination branch).</p>
14590 <p>Unlike <tt class="docutils literal">merge</tt>, rebase will do nothing if you are at the branch tip of
14591 a named branch with two heads. You will need to explicitly specify source
14592 and/or destination.</p>
14593 <p>If you need to use a tool to automate merge/conflict decisions, you
14594 can specify one with <tt class="docutils literal"><span class="pre">--tool</span></tt>, see <a class="reference external" href="hg.1.html#merge-tools"><tt class="docutils literal">hg help <span class="pre">merge-tools</span></tt></a>.
14595 As a caveat: the tool will not be used to mediate when a file was
14596 deleted, there is no hook presently available for this.</p>
14597 <p>If a rebase is interrupted to manually resolve a conflict, it can be
14598 continued with --continue/-c, aborted with --abort/-a, or stopped with
14599 --stop.</p>
14600 <div class="verbose docutils container">
14601 <p>Examples:</p>
14602 <ul>
14603 <li><p class="first">move &quot;local changes&quot; (current commit back to branching point)
14604 to the current branch tip after a pull:</p>
14605 <pre class="literal-block">
14606 hg rebase
14607 </pre>
14608 </li>
14609 <li><p class="first">move a single changeset to the stable branch:</p>
14610 <pre class="literal-block">
14611 hg rebase -r 5f493448 -d stable
14612 </pre>
14613 </li>
14614 <li><p class="first">splice a commit and all its descendants onto another part of history:</p>
14615 <pre class="literal-block">
14616 hg rebase --source c0c3 --dest 4cf9
14617 </pre>
14618 </li>
14619 <li><p class="first">rebase everything on a branch marked by a bookmark onto the
14620 default branch:</p>
14621 <pre class="literal-block">
14622 hg rebase --base myfeature --dest default
14623 </pre>
14624 </li>
14625 <li><p class="first">collapse a sequence of changes into a single commit:</p>
14626 <pre class="literal-block">
14627 hg rebase --collapse -r 1520:1525 -d .
14628 </pre>
14629 </li>
14630 <li><p class="first">move a named branch while preserving its name:</p>
14631 <pre class="literal-block">
14632 hg rebase -r &quot;branch(featureX)&quot; -d 1.3 --keepbranches
14633 </pre>
14634 </li>
14635 <li><p class="first">stabilize orphaned changesets so history looks linear:</p>
14636 <pre class="literal-block">
14637 hg rebase -r 'orphan()-obsolete()' -d 'first(max((successors(max(roots(ALLSRC) &amp; ::SRC)^)-obsolete())::) + max(::((roots(ALLSRC) &amp; ::SRC)^)-obsolete()))'
14638 </pre>
14639 </li>
14640 </ul>
14641 </div>
14642 <p>Configuration Options:</p>
14643 <p>You can make rebase require a destination if you set the following config
14644 option:</p>
14645 <pre class="literal-block">
14646 [commands]
14647 rebase.requiredest = True
14648 </pre>
14649 <p>By default, rebase will close the transaction after each commit. For
14650 performance purposes, you can configure rebase to use a single transaction
14651 across the entire rebase. WARNING: This setting introduces a significant
14652 risk of losing the work you've done in a rebase if the rebase aborts
14653 unexpectedly:</p>
14654 <pre class="literal-block">
14655 [rebase]
14656 singletransaction = True
14657 </pre>
14658 <p>By default, rebase writes to the working copy, but you can configure it to
14659 run in-memory for better performance. When the rebase is not moving the
14660 parent(s) of the working copy (AKA the &quot;currently checked out changesets&quot;),
14661 this may also allow it to run even if the working copy is dirty:</p>
14662 <pre class="literal-block">
14663 [rebase]
14664 experimental.inmemory = True
14665 </pre>
14666 <p>Return Values:</p>
14667 <p>Returns 0 on success, 1 if nothing to rebase or there are
14668 unresolved conflicts.</p>
14669 <p>Options:</p>
14670 <table class="docutils option-list" frame="void" rules="none">
14671 <col class="option" />
14672 <col class="description" />
14673 <tbody valign="top">
14674 <tr><td class="option-group" colspan="2">
14675 <kbd><span class="option">-s</span>, <span class="option">--source <var>&lt;REV[+]&gt;</var></span></kbd></td>
14676 </tr>
14677 <tr><td>&nbsp;</td><td>rebase the specified changesets and their descendants</td></tr>
14678 <tr><td class="option-group" colspan="2">
14679 <kbd><span class="option">-b</span>, <span class="option">--base <var>&lt;REV[+]&gt;</var></span></kbd></td>
14680 </tr>
14681 <tr><td>&nbsp;</td><td>rebase everything from branching point of specified changeset</td></tr>
14682 <tr><td class="option-group" colspan="2">
14683 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
14684 </tr>
14685 <tr><td>&nbsp;</td><td>rebase these revisions</td></tr>
14686 <tr><td class="option-group" colspan="2">
14687 <kbd><span class="option">-d</span>, <span class="option">--dest <var>&lt;REV&gt;</var></span></kbd></td>
14688 </tr>
14689 <tr><td>&nbsp;</td><td>rebase onto the specified changeset</td></tr>
14690 <tr><td class="option-group">
14691 <kbd><span class="option">--collapse</span></kbd></td>
14692 <td>collapse the rebased changesets</td></tr>
14693 <tr><td class="option-group" colspan="2">
14694 <kbd><span class="option">-m</span>, <span class="option">--message <var>&lt;TEXT&gt;</var></span></kbd></td>
14695 </tr>
14696 <tr><td>&nbsp;</td><td>use text as collapse commit message</td></tr>
14697 <tr><td class="option-group">
14698 <kbd><span class="option">-e</span>, <span class="option">--edit</span></kbd></td>
14699 <td>invoke editor on commit messages</td></tr>
14700 <tr><td class="option-group" colspan="2">
14701 <kbd><span class="option">-l</span>, <span class="option">--logfile <var>&lt;FILE&gt;</var></span></kbd></td>
14702 </tr>
14703 <tr><td>&nbsp;</td><td>read collapse commit message from file</td></tr>
14704 <tr><td class="option-group">
14705 <kbd><span class="option">-k</span>, <span class="option">--keep</span></kbd></td>
14706 <td>keep original changesets</td></tr>
14707 <tr><td class="option-group">
14708 <kbd><span class="option">--keepbranches</span></kbd></td>
14709 <td>keep original branch names</td></tr>
14710 <tr><td class="option-group">
14711 <kbd><span class="option">-D</span>, <span class="option">--detach</span></kbd></td>
14712 <td>(DEPRECATED)</td></tr>
14713 <tr><td class="option-group" colspan="2">
14714 <kbd><span class="option">-i</span>, <span class="option">--interactive</span></kbd></td>
14715 </tr>
14716 <tr><td>&nbsp;</td><td>(DEPRECATED)</td></tr>
14717 <tr><td class="option-group" colspan="2">
14718 <kbd><span class="option">-t</span>, <span class="option">--tool <var>&lt;VALUE&gt;</var></span></kbd></td>
14719 </tr>
14720 <tr><td>&nbsp;</td><td>specify merge tool</td></tr>
14721 <tr><td class="option-group">
14722 <kbd><span class="option">--stop</span></kbd></td>
14723 <td>stop interrupted rebase</td></tr>
14724 <tr><td class="option-group">
14725 <kbd><span class="option">-c</span>, <span class="option">--continue</span></kbd></td>
14726 <td>continue an interrupted rebase</td></tr>
14727 <tr><td class="option-group">
14728 <kbd><span class="option">-a</span>, <span class="option">--abort</span></kbd></td>
14729 <td>abort an interrupted rebase</td></tr>
14730 <tr><td class="option-group" colspan="2">
14731 <kbd><span class="option">--auto-orphans <var>&lt;VALUE&gt;</var></span></kbd></td>
14732 </tr>
14733 <tr><td>&nbsp;</td><td>automatically rebase orphan revisions in the specified revset (EXPERIMENTAL)</td></tr>
14734 <tr><td class="option-group">
14735 <kbd><span class="option">-n</span>, <span class="option">--dry-run</span></kbd></td>
14736 <td>do not perform actions, just print output</td></tr>
14737 <tr><td class="option-group" colspan="2">
14738 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
14739 </tr>
14740 <tr><td>&nbsp;</td><td>display with template</td></tr>
14741 <tr><td class="option-group">
14742 <kbd><span class="option">--confirm</span></kbd></td>
14743 <td>ask before applying actions</td></tr>
14744 </tbody>
14745 </table>
14746 <p>[+] marked option can be specified multiple times</p>
14747 </div>
14748 </div>
14749 </div>
14750 </div>
14751 <div class="section" id="record">
14752 <h2><a class="toc-backref" href="#toc-entry-81">record</a></h2>
14753 <p>commands to interactively select changes for commit/qrefresh (DEPRECATED)</p>
14754 <p>The feature provided by this extension has been moved into core Mercurial as
14755 <a class="reference external" href="hg.1.html#commit"><tt class="docutils literal">hg commit <span class="pre">--interactive</span></tt></a>.</p>
14756 <div class="section" id="commands-30">
14757 <h3>Commands</h3>
14758 <div class="section" id="change-creation-4">
14759 <h4>Change creation</h4>
14760 <div class="section" id="qrecord">
14761 <h5>qrecord</h5>
14762 <p>interactively record a new patch:</p>
14763 <pre class="literal-block">
14764 hg qrecord [OPTION]... PATCH [FILE]...
14765 </pre>
14766 <p>See <a class="reference external" href="hg.1.html#qnew"><tt class="docutils literal">hg help qnew</tt></a> &amp; <a class="reference external" href="hg.1.html#record"><tt class="docutils literal">hg help record</tt></a> for more information and
14767 usage.</p>
14768 </div>
14769 <div class="section" id="record-1">
14770 <h5>record</h5>
14771 <p>interactively select changes to commit:</p>
14772 <pre class="literal-block">
14773 hg record [OPTION]... [FILE]...
14774 </pre>
14775 <p>If a list of files is omitted, all changes reported by <a class="reference external" href="hg.1.html#status"><tt class="docutils literal">hg status</tt></a>
14776 will be candidates for recording.</p>
14777 <p>See <a class="reference external" href="hg.1.html#dates"><tt class="docutils literal">hg help dates</tt></a> for a list of formats valid for -d/--date.</p>
14778 <p>If using the text interface (see <a class="reference external" href="hgrc.5.html"><tt class="docutils literal">hg help config</tt></a>),
14779 you will be prompted for whether to record changes to each
14780 modified file, and for files with multiple changes, for each
14781 change to use. For each query, the following responses are
14782 possible:</p>
14783 <pre class="literal-block">
14784 y - record this change
14785 n - skip this change
14786 e - edit this change manually
14787
14788 s - skip remaining changes to this file
14789 f - record remaining changes to this file
14790
14791 d - done, skip remaining changes and files
14792 a - record all changes to all remaining files
14793 q - quit, recording no changes
14794
14795 ? - display help
14796 </pre>
14797 <p>This command is not available when committing a merge.</p>
14798 <p>Options:</p>
14799 <table class="docutils option-list" frame="void" rules="none">
14800 <col class="option" />
14801 <col class="description" />
14802 <tbody valign="top">
14803 <tr><td class="option-group" colspan="2">
14804 <kbd><span class="option">-A</span>, <span class="option">--addremove</span></kbd></td>
14805 </tr>
14806 <tr><td>&nbsp;</td><td>mark new/missing files as added/removed before committing</td></tr>
14807 <tr><td class="option-group">
14808 <kbd><span class="option">--close-branch</span></kbd></td>
14809 <td>mark a branch head as closed</td></tr>
14810 <tr><td class="option-group">
14811 <kbd><span class="option">--amend</span></kbd></td>
14812 <td>amend the parent of the working directory</td></tr>
14813 <tr><td class="option-group">
14814 <kbd><span class="option">-s</span>, <span class="option">--secret</span></kbd></td>
14815 <td>use the secret phase for committing</td></tr>
14816 <tr><td class="option-group">
14817 <kbd><span class="option">--draft</span></kbd></td>
14818 <td>use the draft phase for committing</td></tr>
14819 <tr><td class="option-group">
14820 <kbd><span class="option">-e</span>, <span class="option">--edit</span></kbd></td>
14821 <td>invoke editor on commit messages</td></tr>
14822 <tr><td class="option-group" colspan="2">
14823 <kbd><span class="option">--force-close-branch</span></kbd></td>
14824 </tr>
14825 <tr><td>&nbsp;</td><td>forcibly close branch from a non-head changeset (ADVANCED)</td></tr>
14826 <tr><td class="option-group" colspan="2">
14827 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
14828 </tr>
14829 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
14830 <tr><td class="option-group" colspan="2">
14831 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
14832 </tr>
14833 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
14834 <tr><td class="option-group" colspan="2">
14835 <kbd><span class="option">-m</span>, <span class="option">--message <var>&lt;TEXT&gt;</var></span></kbd></td>
14836 </tr>
14837 <tr><td>&nbsp;</td><td>use text as commit message</td></tr>
14838 <tr><td class="option-group" colspan="2">
14839 <kbd><span class="option">-l</span>, <span class="option">--logfile <var>&lt;FILE&gt;</var></span></kbd></td>
14840 </tr>
14841 <tr><td>&nbsp;</td><td>read commit message from file</td></tr>
14842 <tr><td class="option-group" colspan="2">
14843 <kbd><span class="option">-d</span>, <span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
14844 </tr>
14845 <tr><td>&nbsp;</td><td>record the specified date as commit date</td></tr>
14846 <tr><td class="option-group" colspan="2">
14847 <kbd><span class="option">-u</span>, <span class="option">--user <var>&lt;USER&gt;</var></span></kbd></td>
14848 </tr>
14849 <tr><td>&nbsp;</td><td>record the specified user as committer</td></tr>
14850 <tr><td class="option-group">
14851 <kbd><span class="option">-S</span>, <span class="option">--subrepos</span></kbd></td>
14852 <td>recurse into subrepositories</td></tr>
14853 <tr><td class="option-group" colspan="2">
14854 <kbd><span class="option">-w</span>, <span class="option">--ignore-all-space</span></kbd></td>
14855 </tr>
14856 <tr><td>&nbsp;</td><td>ignore white space when comparing lines</td></tr>
14857 <tr><td class="option-group" colspan="2">
14858 <kbd><span class="option">-b</span>, <span class="option">--ignore-space-change</span></kbd></td>
14859 </tr>
14860 <tr><td>&nbsp;</td><td>ignore changes in the amount of white space</td></tr>
14861 <tr><td class="option-group" colspan="2">
14862 <kbd><span class="option">-B</span>, <span class="option">--ignore-blank-lines</span></kbd></td>
14863 </tr>
14864 <tr><td>&nbsp;</td><td>ignore changes whose lines are all blank</td></tr>
14865 <tr><td class="option-group" colspan="2">
14866 <kbd><span class="option">-Z</span>, <span class="option">--ignore-space-at-eol</span></kbd></td>
14867 </tr>
14868 <tr><td>&nbsp;</td><td>ignore changes in whitespace at EOL</td></tr>
14869 </tbody>
14870 </table>
14871 <p>[+] marked option can be specified multiple times</p>
14872 </div>
14873 </div>
14874 </div>
14875 </div>
14876 <div class="section" id="releasenotes">
14877 <h2><a class="toc-backref" href="#toc-entry-82">releasenotes</a></h2>
14878 <p>generate release notes from commit messages (EXPERIMENTAL)</p>
14879 <p>It is common to maintain files detailing changes in a project between
14880 releases. Maintaining these files can be difficult and time consuming.
14881 The <a class="reference external" href="hg.1.html#releasenotes"><tt class="docutils literal">hg releasenotes</tt></a> command provided by this extension makes the
14882 process simpler by automating it.</p>
14883 <div class="section" id="commands-31">
14884 <h3>Commands</h3>
14885 <div class="section" id="change-navigation-4">
14886 <h4>Change navigation</h4>
14887 <div class="section" id="releasenotes-1">
14888 <h5>releasenotes</h5>
14889 <p>parse release notes from commit messages into an output file:</p>
14890 <pre class="literal-block">
14891 hg releasenotes [-r REV] [-c] FILE
14892 </pre>
14893 <p>Given an output file and set of revisions, this command will parse commit
14894 messages for release notes then add them to the output file.</p>
14895 <p>Release notes are defined in commit messages as ReStructuredText
14896 directives. These have the form:</p>
14897 <pre class="literal-block">
14898 .. directive:: title
14899
14900 content
14901 </pre>
14902 <p>Each <tt class="docutils literal">directive</tt> maps to an output section in a generated release notes
14903 file, which itself is ReStructuredText. For example, the <tt class="docutils literal">.. feature::</tt>
14904 directive would map to a <tt class="docutils literal">New Features</tt> section.</p>
14905 <p>Release note directives can be either short-form or long-form. In short-
14906 form, <tt class="docutils literal">title</tt> is omitted and the release note is rendered as a bullet
14907 list. In long form, a sub-section with the title <tt class="docutils literal">title</tt> is added to the
14908 section.</p>
14909 <p>The <tt class="docutils literal">FILE</tt> argument controls the output file to write gathered release
14910 notes to. The format of the file is:</p>
14911 <pre class="literal-block">
14912 Section 1
14913 =========
14914
14915 ...
14916
14917 Section 2
14918 =========
14919
14920 ...
14921 </pre>
14922 <p>Only sections with defined release notes are emitted.</p>
14923 <p>If a section only has short-form notes, it will consist of bullet list:</p>
14924 <pre class="literal-block">
14925 Section
14926 =======
14927
14928 * Release note 1
14929 * Release note 2
14930 </pre>
14931 <p>If a section has long-form notes, sub-sections will be emitted:</p>
14932 <pre class="literal-block">
14933 Section
14934 =======
14935
14936 Note 1 Title
14937 ------------
14938
14939 Description of the first long-form note.
14940
14941 Note 2 Title
14942 ------------
14943
14944 Description of the second long-form note.
14945 </pre>
14946 <p>If the <tt class="docutils literal">FILE</tt> argument points to an existing file, that file will be
14947 parsed for release notes having the format that would be generated by this
14948 command. The notes from the processed commit messages will be <em>merged</em>
14949 into this parsed set.</p>
14950 <p>During release notes merging:</p>
14951 <ul class="simple">
14952 <li>Duplicate items are automatically ignored</li>
14953 <li>Items that are different are automatically ignored if the similarity is
14954 greater than a threshold.</li>
14955 </ul>
14956 <p>This means that the release notes file can be updated independently from
14957 this command and changes should not be lost when running this command on
14958 that file. A particular use case for this is to tweak the wording of a
14959 release note after it has been added to the release notes file.</p>
14960 <p>The -c/--check option checks the commit message for invalid admonitions.</p>
14961 <p>The -l/--list option, presents the user with a list of existing available
14962 admonitions along with their title. This also includes the custom
14963 admonitions (if any).</p>
14964 <p>Options:</p>
14965 <table class="docutils option-list" frame="void" rules="none">
14966 <col class="option" />
14967 <col class="description" />
14968 <tbody valign="top">
14969 <tr><td class="option-group" colspan="2">
14970 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV&gt;</var></span></kbd></td>
14971 </tr>
14972 <tr><td>&nbsp;</td><td>revisions to process for release notes</td></tr>
14973 <tr><td class="option-group">
14974 <kbd><span class="option">-c</span>, <span class="option">--check</span></kbd></td>
14975 <td>checks for validity of admonitions (if any)</td></tr>
14976 <tr><td class="option-group">
14977 <kbd><span class="option">-l</span>, <span class="option">--list</span></kbd></td>
14978 <td>list the available admonitions with their title</td></tr>
14979 </tbody>
14980 </table>
14981 </div>
14982 </div>
14983 </div>
14984 </div>
14985 <div class="section" id="relink">
14986 <h2><a class="toc-backref" href="#toc-entry-83">relink</a></h2>
14987 <p>recreates hardlinks between repository clones</p>
14988 <div class="section" id="commands-32">
14989 <h3>Commands</h3>
14990 <div class="section" id="repository-maintenance-5">
14991 <h4>Repository maintenance</h4>
14992 <div class="section" id="relink-1">
14993 <h5>relink</h5>
14994 <p>recreate hardlinks between two repositories:</p>
14995 <pre class="literal-block">
14996 hg relink [ORIGIN]
14997 </pre>
14998 <p>When repositories are cloned locally, their data files will be
14999 hardlinked so that they only use the space of a single repository.</p>
15000 <p>Unfortunately, subsequent pulls into either repository will break
15001 hardlinks for any files touched by the new changesets, even if
15002 both repositories end up pulling the same changes.</p>
15003 <p>Similarly, passing --rev to &quot;hg clone&quot; will fail to use any
15004 hardlinks, falling back to a complete copy of the source
15005 repository.</p>
15006 <p>This command lets you recreate those hardlinks and reclaim that
15007 wasted space.</p>
15008 <p>This repository will be relinked to share space with ORIGIN, which
15009 must be on the same local disk. If ORIGIN is omitted, looks for
15010 &quot;default-relink&quot;, then &quot;default&quot;, in [paths].</p>
15011 <p>Do not attempt any read operations on this repository while the
15012 command is running. (Both repositories will be locked against
15013 writes.)</p>
15014 </div>
15015 </div>
15016 </div>
15017 </div>
15018 <div class="section" id="remotefilelog">
15019 <h2><a class="toc-backref" href="#toc-entry-84">remotefilelog</a></h2>
15020 <p>remotefilelog causes Mercurial to lazilly fetch file contents (EXPERIMENTAL)</p>
15021 <p>This extension is HIGHLY EXPERIMENTAL. There are NO BACKWARDS COMPATIBILITY
15022 GUARANTEES. This means that repositories created with this extension may
15023 only be usable with the exact version of this extension/Mercurial that was
15024 used. The extension attempts to enforce this in order to prevent repository
15025 corruption.</p>
15026 <p>remotefilelog works by fetching file contents lazily and storing them
15027 in a cache on the client rather than in revlogs. This allows enormous
15028 histories to be transferred only partially, making them easier to
15029 operate on.</p>
15030 <p>Configs:</p>
15031 <blockquote>
15032 <p><tt class="docutils literal">packs.maxchainlen</tt> specifies the maximum delta chain length in pack files</p>
15033 <p><tt class="docutils literal">packs.maxpacksize</tt> specifies the maximum pack file size</p>
15034 <dl class="docutils">
15035 <dt><tt class="docutils literal">packs.maxpackfilecount</tt> specifies the maximum number of packs in the</dt>
15036 <dd>shared cache (trees only for now)</dd>
15037 </dl>
15038 <p><tt class="docutils literal">remotefilelog.backgroundprefetch</tt> runs prefetch in background when True</p>
15039 <dl class="docutils">
15040 <dt><tt class="docutils literal">remotefilelog.bgprefetchrevs</tt> specifies revisions to fetch on commit and</dt>
15041 <dd>update, and on other commands that use them. Different from pullprefetch.</dd>
15042 </dl>
15043 <p><tt class="docutils literal">remotefilelog.gcrepack</tt> does garbage collection during repack when True</p>
15044 <dl class="docutils">
15045 <dt><tt class="docutils literal">remotefilelog.nodettl</tt> specifies maximum TTL of a node in seconds before</dt>
15046 <dd>it is garbage collected</dd>
15047 </dl>
15048 <p><tt class="docutils literal">remotefilelog.repackonhggc</tt> runs repack on hg gc when True</p>
15049 <dl class="docutils">
15050 <dt><tt class="docutils literal">remotefilelog.prefetchdays</tt> specifies the maximum age of a commit in</dt>
15051 <dd>days after which it is no longer prefetched.</dd>
15052 <dt><tt class="docutils literal">remotefilelog.prefetchdelay</tt> specifies delay between background</dt>
15053 <dd>prefetches in seconds after operations that change the working copy parent</dd>
15054 <dt><tt class="docutils literal">remotefilelog.data.gencountlimit</tt> constraints the minimum number of data</dt>
15055 <dd>pack files required to be considered part of a generation. In particular,
15056 minimum number of packs files &gt; gencountlimit.</dd>
15057 <dt><tt class="docutils literal">remotefilelog.data.generations</tt> list for specifying the lower bound of</dt>
15058 <dd>each generation of the data pack files. For example, list ['100MB','1MB']
15059 or ['1MB', '100MB'] will lead to three generations: [0, 1MB), [
15060 1MB, 100MB) and [100MB, infinity).</dd>
15061 <dt><tt class="docutils literal">remotefilelog.data.maxrepackpacks</tt> the maximum number of pack files to</dt>
15062 <dd>include in an incremental data repack.</dd>
15063 <dt><tt class="docutils literal">remotefilelog.data.repackmaxpacksize</tt> the maximum size of a pack file for</dt>
15064 <dd>it to be considered for an incremental data repack.</dd>
15065 <dt><tt class="docutils literal">remotefilelog.data.repacksizelimit</tt> the maximum total size of pack files</dt>
15066 <dd>to include in an incremental data repack.</dd>
15067 <dt><tt class="docutils literal">remotefilelog.history.gencountlimit</tt> constraints the minimum number of</dt>
15068 <dd>history pack files required to be considered part of a generation. In
15069 particular, minimum number of packs files &gt; gencountlimit.</dd>
15070 <dt><tt class="docutils literal">remotefilelog.history.generations</tt> list for specifying the lower bound of</dt>
15071 <dd>each generation of the history pack files. For example, list [
15072 '100MB', '1MB'] or ['1MB', '100MB'] will lead to three generations: [
15073 0, 1MB), [1MB, 100MB) and [100MB, infinity).</dd>
15074 <dt><tt class="docutils literal">remotefilelog.history.maxrepackpacks</tt> the maximum number of pack files to</dt>
15075 <dd>include in an incremental history repack.</dd>
15076 <dt><tt class="docutils literal">remotefilelog.history.repackmaxpacksize</tt> the maximum size of a pack file</dt>
15077 <dd>for it to be considered for an incremental history repack.</dd>
15078 <dt><tt class="docutils literal">remotefilelog.history.repacksizelimit</tt> the maximum total size of pack</dt>
15079 <dd>files to include in an incremental history repack.</dd>
15080 <dt><tt class="docutils literal">remotefilelog.backgroundrepack</tt> automatically consolidate packs in the</dt>
15081 <dd>background</dd>
15082 </dl>
15083 <p><tt class="docutils literal">remotefilelog.cachepath</tt> path to cache</p>
15084 <dl class="docutils">
15085 <dt><tt class="docutils literal">remotefilelog.cachegroup</tt> if set, make cache directory sgid to this</dt>
15086 <dd>group</dd>
15087 </dl>
15088 <p><tt class="docutils literal">remotefilelog.cacheprocess</tt> binary to invoke for fetching file data</p>
15089 <p><tt class="docutils literal">remotefilelog.debug</tt> turn on remotefilelog-specific debug output</p>
15090 <p><tt class="docutils literal">remotefilelog.excludepattern</tt> pattern of files to exclude from pulls</p>
15091 <p><tt class="docutils literal">remotefilelog.includepattern</tt> pattern of files to include in pulls</p>
15092 <dl class="docutils">
15093 <dt><tt class="docutils literal">remotefilelog.fetchwarning</tt>: message to print when too many</dt>
15094 <dd>single-file fetches occur</dd>
15095 </dl>
15096 <p><tt class="docutils literal">remotefilelog.getfilesstep</tt> number of files to request in a single RPC</p>
15097 <dl class="docutils">
15098 <dt><tt class="docutils literal">remotefilelog.getfilestype</tt> if set to 'threaded' use threads to fetch</dt>
15099 <dd>files, otherwise use optimistic fetching</dd>
15100 <dt><tt class="docutils literal">remotefilelog.pullprefetch</tt> revset for selecting files that should be</dt>
15101 <dd>eagerly downloaded rather than lazily</dd>
15102 <dt><tt class="docutils literal">remotefilelog.reponame</tt> name of the repo. If set, used to partition</dt>
15103 <dd>data from other repos in a shared store.</dd>
15104 </dl>
15105 <p><tt class="docutils literal">remotefilelog.server</tt> if true, enable server-side functionality</p>
15106 <p><tt class="docutils literal">remotefilelog.servercachepath</tt> path for caching blobs on the server</p>
15107 <dl class="docutils">
15108 <dt><tt class="docutils literal">remotefilelog.serverexpiration</tt> number of days to keep cached server</dt>
15109 <dd>blobs</dd>
15110 <dt><tt class="docutils literal">remotefilelog.validatecache</tt> if set, check cache entries for corruption</dt>
15111 <dd>before returning blobs</dd>
15112 <dt><tt class="docutils literal">remotefilelog.validatecachelog</tt> if set, check cache entries for</dt>
15113 <dd>corruption before returning metadata</dd>
15114 </dl>
15115 </blockquote>
15116 <div class="section" id="commands-33">
15117 <h3>Commands</h3>
15118 <div class="section" id="repository-maintenance-6">
15119 <h4>Repository maintenance</h4>
15120 <div class="section" id="prefetch">
15121 <h5>prefetch</h5>
15122 <p>prefetch file revisions from the server:</p>
15123 <pre class="literal-block">
15124 hg prefetch [OPTIONS] [FILE...]
15125 </pre>
15126 <p>Prefetchs file revisions for the specified revs and stores them in the
15127 local remotefilelog cache. If no rev is specified, the default rev is
15128 used which is the union of dot, draft, pullprefetch and bgprefetchrev.
15129 File names or patterns can be used to limit which files are downloaded.</p>
15130 <p>Return 0 on success.</p>
15131 <p>Options:</p>
15132 <table class="docutils option-list" frame="void" rules="none">
15133 <col class="option" />
15134 <col class="description" />
15135 <tbody valign="top">
15136 <tr><td class="option-group" colspan="2">
15137 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
15138 </tr>
15139 <tr><td>&nbsp;</td><td>prefetch the specified revisions</td></tr>
15140 <tr><td class="option-group">
15141 <kbd><span class="option">--repack</span></kbd></td>
15142 <td>run repack after prefetch</td></tr>
15143 <tr><td class="option-group" colspan="2">
15144 <kbd><span class="option">-b</span>, <span class="option">--base <var>&lt;VALUE&gt;</var></span></kbd></td>
15145 </tr>
15146 <tr><td>&nbsp;</td><td>rev that is assumed to already be local</td></tr>
15147 <tr><td class="option-group" colspan="2">
15148 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
15149 </tr>
15150 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
15151 <tr><td class="option-group" colspan="2">
15152 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
15153 </tr>
15154 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
15155 </tbody>
15156 </table>
15157 <p>[+] marked option can be specified multiple times</p>
15158 </div>
15159 </div>
15160 <div class="section" id="uncategorized-commands-5">
15161 <h4>Uncategorized commands</h4>
15162 <div class="section" id="gc">
15163 <h5>gc</h5>
15164 <p>garbage collect the client and server filelog caches:</p>
15165 <pre class="literal-block">
15166 hg gc [REPO...]
15167 </pre>
15168 <p>garbage collect the client and server filelog caches</p>
15169 </div>
15170 <div class="section" id="repack">
15171 <h5>repack</h5>
15172 <pre class="literal-block">
15173 hg repack [OPTIONS]
15174 </pre>
15175 <p>Options:</p>
15176 <table class="docutils option-list" frame="void" rules="none">
15177 <col class="option" />
15178 <col class="description" />
15179 <tbody valign="top">
15180 <tr><td class="option-group">
15181 <kbd><span class="option">--background</span></kbd></td>
15182 <td>run in a background process</td></tr>
15183 <tr><td class="option-group">
15184 <kbd><span class="option">--incremental</span></kbd></td>
15185 <td>do an incremental repack</td></tr>
15186 <tr><td class="option-group">
15187 <kbd><span class="option">--packsonly</span></kbd></td>
15188 <td>only repack packs (skip loose objects)</td></tr>
15189 </tbody>
15190 </table>
15191 </div>
15192 <div class="section" id="verifyremotefilelog">
15193 <h5>verifyremotefilelog</h5>
15194 <pre class="literal-block">
15195 hg verifyremotefilelogs &lt;directory&gt;
15196 </pre>
15197 <p>Options:</p>
15198 <table class="docutils option-list" frame="void" rules="none">
15199 <col class="option" />
15200 <col class="description" />
15201 <tbody valign="top">
15202 <tr><td class="option-group" colspan="2">
15203 <kbd><span class="option">-d</span>, <span class="option">--decompress</span></kbd></td>
15204 </tr>
15205 <tr><td>&nbsp;</td><td>decompress the filelogs first</td></tr>
15206 </tbody>
15207 </table>
15208 </div>
15209 </div>
15210 </div>
15211 </div>
15212 <div class="section" id="remotenames">
15213 <h2><a class="toc-backref" href="#toc-entry-85">remotenames</a></h2>
15214 <p>showing remotebookmarks and remotebranches in UI (EXPERIMENTAL)</p>
15215 <p>By default both remotebookmarks and remotebranches are turned on. Config knob to
15216 control the individually are as follows.</p>
15217 <p>Config options to tweak the default behaviour:</p>
15218 <dl class="docutils">
15219 <dt>remotenames.bookmarks</dt>
15220 <dd>Boolean value to enable or disable showing of remotebookmarks (default: True)</dd>
15221 <dt>remotenames.branches</dt>
15222 <dd>Boolean value to enable or disable showing of remotebranches (default: True)</dd>
15223 <dt>remotenames.hoistedpeer</dt>
15224 <dd>Name of the peer whose remotebookmarks should be hoisted into the top-level
15225 namespace (default: 'default')</dd>
15226 </dl>
15227 </div>
15228 <div class="section" id="schemes">
15229 <h2><a class="toc-backref" href="#toc-entry-86">schemes</a></h2>
15230 <p>extend schemes with shortcuts to repository swarms</p>
15231 <p>This extension allows you to specify shortcuts for parent URLs with a
15232 lot of repositories to act like a scheme, for example:</p>
15233 <pre class="literal-block">
15234 [schemes]
15235 py = http://code.python.org/hg/
15236 </pre>
15237 <p>After that you can use it like:</p>
15238 <pre class="literal-block">
15239 hg clone py://trunk/
15240 </pre>
15241 <p>Additionally there is support for some more complex schemas, for
15242 example used by Google Code:</p>
15243 <pre class="literal-block">
15244 [schemes]
15245 gcode = http://{1}.googlecode.com/hg/
15246 </pre>
15247 <p>The syntax is taken from Mercurial templates, and you have unlimited
15248 number of variables, starting with <tt class="docutils literal">{1}</tt> and continuing with
15249 <tt class="docutils literal">{2}</tt>, <tt class="docutils literal">{3}</tt> and so on. This variables will receive parts of URL
15250 supplied, split by <tt class="docutils literal">/</tt>. Anything not specified as <tt class="docutils literal">{part}</tt> will be
15251 just appended to an URL.</p>
15252 <p>For convenience, the extension adds these schemes by default:</p>
15253 <pre class="literal-block">
15254 [schemes]
15255 py = http://hg.python.org/
15256 bb = https://bitbucket.org/
15257 bb+ssh = ssh://hg&#64;bitbucket.org/
15258 gcode = https://{1}.googlecode.com/hg/
15259 kiln = https://{1}.kilnhg.com/Repo/
15260 </pre>
15261 <p>You can override a predefined scheme by defining a new scheme with the
15262 same name.</p>
15263 <div class="section" id="commands-34">
15264 <h3>Commands</h3>
15265 </div>
15266 </div>
15267 <div class="section" id="share">
15268 <h2><a class="toc-backref" href="#toc-entry-87">share</a></h2>
15269 <p>share a common history between several working directories</p>
15270 <p>The share extension introduces a new command <a class="reference external" href="hg.1.html#share"><tt class="docutils literal">hg share</tt></a> to create a new
15271 working directory. This is similar to <a class="reference external" href="hg.1.html#clone"><tt class="docutils literal">hg clone</tt></a>, but doesn't involve
15272 copying or linking the storage of the repository. This allows working on
15273 different branches or changes in parallel without the associated cost in
15274 terms of disk space.</p>
15275 <p>Note: destructive operations or extensions like <a class="reference external" href="hg.1.html#rollback"><tt class="docutils literal">hg rollback</tt></a> should be
15276 used with care as they can result in confusing problems.</p>
15277 <div class="section" id="automatic-pooled-storage-for-clones">
15278 <h3>Automatic Pooled Storage for Clones</h3>
15279 <p>When this extension is active, <a class="reference external" href="hg.1.html#clone"><tt class="docutils literal">hg clone</tt></a> can be configured to
15280 automatically share/pool storage across multiple clones. This
15281 mode effectively converts <a class="reference external" href="hg.1.html#clone"><tt class="docutils literal">hg clone</tt></a> to <a class="reference external" href="hg.1.html#clone"><tt class="docutils literal">hg clone</tt></a> + <a class="reference external" href="hg.1.html#share"><tt class="docutils literal">hg share</tt></a>.
15282 The benefit of using this mode is the automatic management of
15283 store paths and intelligent pooling of related repositories.</p>
15284 <p>The following <tt class="docutils literal">share.</tt> config options influence this feature:</p>
15285 <dl class="docutils">
15286 <dt><tt class="docutils literal">share.pool</tt></dt>
15287 <dd>Filesystem path where shared repository data will be stored. When
15288 defined, <a class="reference external" href="hg.1.html#clone"><tt class="docutils literal">hg clone</tt></a> will automatically use shared repository
15289 storage instead of creating a store inside each clone.</dd>
15290 <dt><tt class="docutils literal">share.poolnaming</tt></dt>
15291 <dd><p class="first">How directory names in <tt class="docutils literal">share.pool</tt> are constructed.</p>
15292 <p>&quot;identity&quot; means the name is derived from the first changeset in the
15293 repository. In this mode, different remotes share storage if their
15294 root/initial changeset is identical. In this mode, the local shared
15295 repository is an aggregate of all encountered remote repositories.</p>
15296 <p>&quot;remote&quot; means the name is derived from the source repository's
15297 path or URL. In this mode, storage is only shared if the path or URL
15298 requested in the <a class="reference external" href="hg.1.html#clone"><tt class="docutils literal">hg clone</tt></a> command matches exactly to a repository
15299 that was cloned before.</p>
15300 <p class="last">The default naming mode is &quot;identity&quot;.</p>
15301 </dd>
15302 </dl>
15303 <div class="verbose docutils container">
15304 <p>Sharing requirements and configs of source repository with shares:</p>
15305 <p>By default creating a shared repository only enables sharing a common
15306 history and does not share requirements and configs between them. This
15307 may lead to problems in some cases, for example when you upgrade the
15308 storage format from one repository but does not set related configs
15309 in the shares.</p>
15310 <p>Setting <cite>format.exp-share-safe = True</cite> enables sharing configs and
15311 requirements. This only applies to shares which are done after enabling
15312 the config option.</p>
15313 <p>For enabling this in existing shares, enable the config option and reshare.</p>
15314 <p>For resharing existing shares, make sure your working directory is clean
15315 and there are no untracked files, delete that share and create a new share.</p>
15316 </div>
15317 </div>
15318 <div class="section" id="commands-35">
15319 <h3>Commands</h3>
15320 <div class="section" id="repository-creation-2">
15321 <h4>Repository creation</h4>
15322 <div class="section" id="share-1">
15323 <h5>share</h5>
15324 <p>create a new shared repository:</p>
15325 <pre class="literal-block">
15326 hg share [-U] [-B] SOURCE [DEST]
15327 </pre>
15328 <p>Initialize a new repository and working directory that shares its
15329 history (and optionally bookmarks) with another repository.</p>
15330 <div class="admonition note">
15331 <p class="first admonition-title">Note</p>
15332 <p class="last">using rollback or extensions that destroy/modify history (mq,
15333 rebase, etc.) can cause considerable confusion with shared
15334 clones. In particular, if two shared clones are both updated to
15335 the same changeset, and one of them destroys that changeset
15336 with rollback, the other clone will suddenly stop working: all
15337 operations will fail with &quot;abort: working directory has unknown
15338 parent&quot;. The only known workaround is to use debugsetparents on
15339 the broken clone to reset it to a changeset that still exists.</p>
15340 </div>
15341 <p>Options:</p>
15342 <table class="docutils option-list" frame="void" rules="none">
15343 <col class="option" />
15344 <col class="description" />
15345 <tbody valign="top">
15346 <tr><td class="option-group">
15347 <kbd><span class="option">-U</span>, <span class="option">--noupdate</span></kbd></td>
15348 <td>do not create a working directory</td></tr>
15349 <tr><td class="option-group" colspan="2">
15350 <kbd><span class="option">-B</span>, <span class="option">--bookmarks</span></kbd></td>
15351 </tr>
15352 <tr><td>&nbsp;</td><td>also share bookmarks</td></tr>
15353 <tr><td class="option-group">
15354 <kbd><span class="option">--relative</span></kbd></td>
15355 <td>point to source using a relative path</td></tr>
15356 </tbody>
15357 </table>
15358 </div>
15359 </div>
15360 <div class="section" id="repository-maintenance-7">
15361 <h4>Repository maintenance</h4>
15362 <div class="section" id="unshare">
15363 <h5>unshare</h5>
15364 <p>convert a shared repository to a normal one:</p>
15365 <pre class="literal-block">
15366 hg unshare
15367 </pre>
15368 <p>Copy the store data to the repo and remove the sharedpath data.</p>
15369 </div>
15370 </div>
15371 </div>
15372 </div>
15373 <div class="section" id="show">
15374 <h2><a class="toc-backref" href="#toc-entry-88">show</a></h2>
15375 <p>unified command to show various repository information (EXPERIMENTAL)</p>
15376 <p>This extension provides the <a class="reference external" href="hg.1.html#show"><tt class="docutils literal">hg show</tt></a> command, which provides a central
15377 command for displaying commonly-accessed repository data and views of that
15378 data.</p>
15379 <p>The following config options can influence operation.</p>
15380 <div class="section" id="commands-36">
15381 <h3><tt class="docutils literal">commands</tt></h3>
15382 <dl class="docutils">
15383 <dt><tt class="docutils literal">show.aliasprefix</tt></dt>
15384 <dd><p class="first">List of strings that will register aliases for views. e.g. <tt class="docutils literal">s</tt> will
15385 effectively set config options <tt class="docutils literal">alias.s&lt;view&gt; = show &lt;view&gt;</tt> for all
15386 views. i.e. <cite>hg swork</cite> would execute <cite>hg show work</cite>.</p>
15387 <p class="last">Aliases that would conflict with existing registrations will not be
15388 performed.</p>
15389 </dd>
15390 </dl>
15391 </div>
15392 <div class="section" id="commands-37">
15393 <h3>Commands</h3>
15394 <div class="section" id="change-navigation-5">
15395 <h4>Change navigation</h4>
15396 <div class="section" id="show-1">
15397 <h5>show</h5>
15398 <p>show various repository information:</p>
15399 <pre class="literal-block">
15400 hg show VIEW
15401 </pre>
15402 <p>A requested view of repository data is displayed.</p>
15403 <p>If no view is requested, the list of available views is shown and the
15404 command aborts.</p>
15405 <div class="admonition note">
15406 <p class="first admonition-title">Note</p>
15407 <p>There are no backwards compatibility guarantees for the output of this
15408 command. Output may change in any future Mercurial release.</p>
15409 <p class="last">Consumers wanting stable command output should specify a template via
15410 <tt class="docutils literal"><span class="pre">-T/--template</span></tt>.</p>
15411 </div>
15412 <p>List of available views:</p>
15413 <p>bookmarks bookmarks and their associated changeset</p>
15414 <p>stack current line of work</p>
15415 <p>work changesets that aren't finished</p>
15416 <p>Options:</p>
15417 <table class="docutils option-list" frame="void" rules="none">
15418 <col class="option" />
15419 <col class="description" />
15420 <tbody valign="top">
15421 <tr><td class="option-group" colspan="2">
15422 <kbd><span class="option">-T</span>, <span class="option">--template <var>&lt;TEMPLATE&gt;</var></span></kbd></td>
15423 </tr>
15424 <tr><td>&nbsp;</td><td>display with template</td></tr>
15425 </tbody>
15426 </table>
15427 </div>
15428 </div>
15429 </div>
15430 </div>
15431 <div class="section" id="sparse">
15432 <h2><a class="toc-backref" href="#toc-entry-89">sparse</a></h2>
15433 <p>allow sparse checkouts of the working directory (EXPERIMENTAL)</p>
15434 <p>(This extension is not yet protected by backwards compatibility
15435 guarantees. Any aspect may break in future releases until this
15436 notice is removed.)</p>
15437 <p>This extension allows the working directory to only consist of a
15438 subset of files for the revision. This allows specific files or
15439 directories to be explicitly included or excluded. Many repository
15440 operations have performance proportional to the number of files in
15441 the working directory. So only realizing a subset of files in the
15442 working directory can improve performance.</p>
15443 <div class="section" id="sparse-config-files">
15444 <h3>Sparse Config Files</h3>
15445 <p>The set of files that are part of a sparse checkout are defined by
15446 a sparse config file. The file defines 3 things: includes (files to
15447 include in the sparse checkout), excludes (files to exclude from the
15448 sparse checkout), and profiles (links to other config files).</p>
15449 <p>The file format is newline delimited. Empty lines and lines beginning
15450 with <tt class="docutils literal">#</tt> are ignored.</p>
15451 <p>Lines beginning with <tt class="docutils literal">%include `` denote another sparse config file
15452 to include. e.g. <span class="pre">``%include</span> tests.sparse</tt>. The filename is relative
15453 to the repository root.</p>
15454 <p>The special lines <tt class="docutils literal">[include]</tt> and <tt class="docutils literal">[exclude]</tt> denote the section
15455 for includes and excludes that follow, respectively. It is illegal to
15456 have <tt class="docutils literal">[include]</tt> after <tt class="docutils literal">[exclude]</tt>.</p>
15457 <p>Non-special lines resemble file patterns to be added to either includes
15458 or excludes. The syntax of these lines is documented by <a class="reference external" href="hg.1.html#patterns"><tt class="docutils literal">hg help patterns</tt></a>.
15459 Patterns are interpreted as <tt class="docutils literal">glob:</tt> by default and match against the
15460 root of the repository.</p>
15461 <p>Exclusion patterns take precedence over inclusion patterns. So even
15462 if a file is explicitly included, an <tt class="docutils literal">[exclude]</tt> entry can remove it.</p>
15463 <p>For example, say you have a repository with 3 directories, <tt class="docutils literal">frontend/</tt>,
15464 <tt class="docutils literal">backend/</tt>, and <tt class="docutils literal">tools/</tt>. <tt class="docutils literal">frontend/</tt> and <tt class="docutils literal">backend/</tt> correspond
15465 to different projects and it is uncommon for someone working on one
15466 to need the files for the other. But <tt class="docutils literal">tools/</tt> contains files shared
15467 between both projects. Your sparse config files may resemble:</p>
15468 <pre class="literal-block">
15469 # frontend.sparse
15470 frontend/**
15471 tools/**
15472
15473 # backend.sparse
15474 backend/**
15475 tools/**
15476 </pre>
15477 <p>Say the backend grows in size. Or there's a directory with thousands
15478 of files you wish to exclude. You can modify the profile to exclude
15479 certain files:</p>
15480 <pre class="literal-block">
15481 [include]
15482 backend/**
15483 tools/**
15484
15485 [exclude]
15486 tools/tests/**
15487 </pre>
15488 </div>
15489 <div class="section" id="commands-38">
15490 <h3>Commands</h3>
15491 </div>
15492 </div>
15493 <div class="section" id="split">
15494 <h2><a class="toc-backref" href="#toc-entry-90">split</a></h2>
15495 <p>command to split a changeset into smaller ones (EXPERIMENTAL)</p>
15496 <div class="section" id="commands-39">
15497 <h3>Commands</h3>
15498 <div class="section" id="change-manipulation-5">
15499 <h4>Change manipulation</h4>
15500 <div class="section" id="split-1">
15501 <h5>split</h5>
15502 <p>split a changeset into smaller ones:</p>
15503 <pre class="literal-block">
15504 hg split [--no-rebase] [[-r] REV]
15505 </pre>
15506 <p>Repeatedly prompt changes and commit message for new changesets until there
15507 is nothing left in the original changeset.</p>
15508 <p>If --rev was not given, split the working directory parent.</p>
15509 <p>By default, rebase connected non-obsoleted descendants onto the new
15510 changeset. Use --no-rebase to avoid the rebase.</p>
15511 <p>Options:</p>
15512 <table class="docutils option-list" frame="void" rules="none">
15513 <col class="option" />
15514 <col class="description" />
15515 <tbody valign="top">
15516 <tr><td class="option-group" colspan="2">
15517 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV&gt;</var></span></kbd></td>
15518 </tr>
15519 <tr><td>&nbsp;</td><td>revision to split</td></tr>
15520 <tr><td class="option-group">
15521 <kbd><span class="option">--rebase</span></kbd></td>
15522 <td>rebase descendants after split (default: True)</td></tr>
15523 <tr><td class="option-group" colspan="2">
15524 <kbd><span class="option">-d</span>, <span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
15525 </tr>
15526 <tr><td>&nbsp;</td><td>record the specified date as commit date</td></tr>
15527 <tr><td class="option-group" colspan="2">
15528 <kbd><span class="option">-u</span>, <span class="option">--user <var>&lt;USER&gt;</var></span></kbd></td>
15529 </tr>
15530 <tr><td>&nbsp;</td><td>record the specified user as committer</td></tr>
15531 </tbody>
15532 </table>
15533 </div>
15534 </div>
15535 </div>
15536 </div>
15537 <div class="section" id="strip">
15538 <h2><a class="toc-backref" href="#toc-entry-91">strip</a></h2>
15539 <p>strip changesets and their descendants from history (DEPRECATED)</p>
15540 <p>The functionality of this extension has been included in core Mercurial
15541 since version 5.7. Please use <a class="reference external" href="hg.1.html#debugstrip"><tt class="docutils literal">hg debugstrip ...</tt></a> instead.</p>
15542 <p>This extension allows you to strip changesets and all their descendants from the
15543 repository. See the command help for details.</p>
15544 <div class="section" id="commands-40">
15545 <h3>Commands</h3>
15546 <div class="section" id="repository-maintenance-8">
15547 <h4>Repository maintenance</h4>
15548 <div class="section" id="strip-1">
15549 <h5>strip</h5>
15550 <pre class="literal-block">
15551 hg strip [-k] [-f] [-B bookmark] [-r] REV...
15552 </pre>
15553 <p>Options:</p>
15554 <table class="docutils option-list" frame="void" rules="none">
15555 <col class="option" />
15556 <col class="description" />
15557 <tbody valign="top">
15558 <tr><td class="option-group" colspan="2">
15559 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV[+]&gt;</var></span></kbd></td>
15560 </tr>
15561 <tr><td>&nbsp;</td><td>strip specified revision (optional, can specify revisions without this option)</td></tr>
15562 <tr><td class="option-group">
15563 <kbd><span class="option">-f</span>, <span class="option">--force</span></kbd></td>
15564 <td>force removal of changesets, discard uncommitted changes (no backup)</td></tr>
15565 <tr><td class="option-group">
15566 <kbd><span class="option">--no-backup</span></kbd></td>
15567 <td>do not save backup bundle</td></tr>
15568 <tr><td class="option-group">
15569 <kbd><span class="option">--nobackup</span></kbd></td>
15570 <td>do not save backup bundle (DEPRECATED)</td></tr>
15571 <tr><td class="option-group">
15572 <kbd><span class="option">-n</span></kbd></td>
15573 <td>ignored (DEPRECATED)</td></tr>
15574 <tr><td class="option-group">
15575 <kbd><span class="option">-k</span>, <span class="option">--keep</span></kbd></td>
15576 <td>do not modify working directory during strip</td></tr>
15577 <tr><td class="option-group" colspan="2">
15578 <kbd><span class="option">-B</span>, <span class="option">--bookmark <var>&lt;BOOKMARK[+]&gt;</var></span></kbd></td>
15579 </tr>
15580 <tr><td>&nbsp;</td><td>remove revs only reachable from given bookmark</td></tr>
15581 <tr><td class="option-group">
15582 <kbd><span class="option">--soft</span></kbd></td>
15583 <td>simply drop changesets from visible history (EXPERIMENTAL)</td></tr>
15584 <tr><td class="option-group" colspan="2">
15585 <kbd><span class="option">--permit-empty-revset</span></kbd></td>
15586 </tr>
15587 <tr><td>&nbsp;</td><td>return success even if no revision was stripped</td></tr>
15588 </tbody>
15589 </table>
15590 <p>[+] marked option can be specified multiple times</p>
15591 </div>
15592 </div>
15593 </div>
15594 </div>
15595 <div class="section" id="transplant">
15596 <h2><a class="toc-backref" href="#toc-entry-92">transplant</a></h2>
15597 <p>command to transplant changesets from another branch</p>
15598 <p>This extension allows you to transplant changes to another parent revision,
15599 possibly in another repository. The transplant is done using 'diff' patches.</p>
15600 <p>Transplanted patches are recorded in .hg/transplant/transplants, as a
15601 map from a changeset hash to its hash in the source repository.</p>
15602 <div class="section" id="commands-41">
15603 <h3>Commands</h3>
15604 <div class="section" id="change-manipulation-6">
15605 <h4>Change manipulation</h4>
15606 <div class="section" id="transplant-1">
15607 <h5>transplant</h5>
15608 <p>transplant changesets from another branch:</p>
15609 <pre class="literal-block">
15610 hg transplant [-s REPO] [-b BRANCH [-a]] [-p REV] [-m REV] [REV]...
15611 </pre>
15612 <p>Selected changesets will be applied on top of the current working
15613 directory with the log of the original changeset. The changesets
15614 are copied and will thus appear twice in the history with different
15615 identities.</p>
15616 <p>Consider using the graft command if everything is inside the same
15617 repository - it will use merges and will usually give a better result.
15618 Use the rebase extension if the changesets are unpublished and you want
15619 to move them instead of copying them.</p>
15620 <p>If --log is specified, log messages will have a comment appended
15621 of the form:</p>
15622 <pre class="literal-block">
15623 (transplanted from CHANGESETHASH)
15624 </pre>
15625 <p>You can rewrite the changelog message with the --filter option.
15626 Its argument will be invoked with the current changelog message as
15627 $1 and the patch as $2.</p>
15628 <p>--source/-s specifies another repository to use for selecting changesets,
15629 just as if it temporarily had been pulled.
15630 If --branch/-b is specified, these revisions will be used as
15631 heads when deciding which changesets to transplant, just as if only
15632 these revisions had been pulled.
15633 If --all/-a is specified, all the revisions up to the heads specified
15634 with --branch will be transplanted.</p>
15635 <p>Example:</p>
15636 <ul>
15637 <li><p class="first">transplant all changes up to REV on top of your current revision:</p>
15638 <pre class="literal-block">
15639 hg transplant --branch REV --all
15640 </pre>
15641 </li>
15642 </ul>
15643 <p>You can optionally mark selected transplanted changesets as merge
15644 changesets. You will not be prompted to transplant any ancestors
15645 of a merged transplant, and you can merge descendants of them
15646 normally instead of transplanting them.</p>
15647 <p>Merge changesets may be transplanted directly by specifying the
15648 proper parent changeset by calling <a class="reference external" href="hg.1.html#transplant"><tt class="docutils literal">hg transplant <span class="pre">--parent</span></tt></a>.</p>
15649 <p>If no merges or revisions are provided, <a class="reference external" href="hg.1.html#transplant"><tt class="docutils literal">hg transplant</tt></a> will
15650 start an interactive changeset browser.</p>
15651 <p>If a changeset application fails, you can fix the merge by hand
15652 and then resume where you left off by calling <a class="reference external" href="hg.1.html#transplant"><tt class="docutils literal">hg transplant
15653 <span class="pre">--continue/-c</span></tt></a>.</p>
15654 <p>Options:</p>
15655 <table class="docutils option-list" frame="void" rules="none">
15656 <col class="option" />
15657 <col class="description" />
15658 <tbody valign="top">
15659 <tr><td class="option-group" colspan="2">
15660 <kbd><span class="option">-s</span>, <span class="option">--source <var>&lt;REPO&gt;</var></span></kbd></td>
15661 </tr>
15662 <tr><td>&nbsp;</td><td>transplant changesets from REPO</td></tr>
15663 <tr><td class="option-group" colspan="2">
15664 <kbd><span class="option">-b</span>, <span class="option">--branch <var>&lt;REV[+]&gt;</var></span></kbd></td>
15665 </tr>
15666 <tr><td>&nbsp;</td><td>use this source changeset as head</td></tr>
15667 <tr><td class="option-group">
15668 <kbd><span class="option">-a</span>, <span class="option">--all</span></kbd></td>
15669 <td>pull all changesets up to the --branch revisions</td></tr>
15670 <tr><td class="option-group" colspan="2">
15671 <kbd><span class="option">-p</span>, <span class="option">--prune <var>&lt;REV[+]&gt;</var></span></kbd></td>
15672 </tr>
15673 <tr><td>&nbsp;</td><td>skip over REV</td></tr>
15674 <tr><td class="option-group" colspan="2">
15675 <kbd><span class="option">-m</span>, <span class="option">--merge <var>&lt;REV[+]&gt;</var></span></kbd></td>
15676 </tr>
15677 <tr><td>&nbsp;</td><td>merge at REV</td></tr>
15678 <tr><td class="option-group">
15679 <kbd><span class="option">--parent <var>&lt;REV&gt;</var></span></kbd></td>
15680 <td>parent to choose when transplanting merge</td></tr>
15681 <tr><td class="option-group">
15682 <kbd><span class="option">-e</span>, <span class="option">--edit</span></kbd></td>
15683 <td>invoke editor on commit messages</td></tr>
15684 <tr><td class="option-group">
15685 <kbd><span class="option">--log</span></kbd></td>
15686 <td>append transplant info to log message</td></tr>
15687 <tr><td class="option-group">
15688 <kbd><span class="option">--stop</span></kbd></td>
15689 <td>stop interrupted transplant</td></tr>
15690 <tr><td class="option-group">
15691 <kbd><span class="option">-c</span>, <span class="option">--continue</span></kbd></td>
15692 <td>continue last transplant session after fixing conflicts</td></tr>
15693 <tr><td class="option-group">
15694 <kbd><span class="option">--filter <var>&lt;CMD&gt;</var></span></kbd></td>
15695 <td>filter changesets through command</td></tr>
15696 </tbody>
15697 </table>
15698 <p>[+] marked option can be specified multiple times</p>
15699 </div>
15700 </div>
15701 </div>
15702 </div>
15703 <div class="section" id="uncommit">
15704 <h2><a class="toc-backref" href="#toc-entry-93">uncommit</a></h2>
15705 <p>uncommit part or all of a local changeset (EXPERIMENTAL)</p>
15706 <p>This command undoes the effect of a local commit, returning the affected
15707 files to their uncommitted state. This means that files modified, added or
15708 removed in the changeset will be left unchanged, and so will remain modified,
15709 added and removed in the working directory.</p>
15710 <div class="section" id="commands-42">
15711 <h3>Commands</h3>
15712 <div class="section" id="change-manipulation-7">
15713 <h4>Change manipulation</h4>
15714 <div class="section" id="unamend">
15715 <h5>unamend</h5>
15716 <p>undo the most recent amend operation on a current changeset:</p>
15717 <pre class="literal-block">
15718 hg unamend
15719 </pre>
15720 <p>This command will roll back to the previous version of a changeset,
15721 leaving working directory in state in which it was before running
15722 <cite>hg amend</cite> (e.g. files modified as part of an amend will be
15723 marked as modified <cite>hg status</cite>)</p>
15724 </div>
15725 <div class="section" id="uncommit-1">
15726 <h5>uncommit</h5>
15727 <p>uncommit part or all of a local changeset:</p>
15728 <pre class="literal-block">
15729 hg uncommit [OPTION]... [FILE]...
15730 </pre>
15731 <p>This command undoes the effect of a local commit, returning the affected
15732 files to their uncommitted state. This means that files modified or
15733 deleted in the changeset will be left unchanged, and so will remain
15734 modified in the working directory.</p>
15735 <p>If no files are specified, the commit will be pruned, unless --keep is
15736 given.</p>
15737 <p>Options:</p>
15738 <table class="docutils option-list" frame="void" rules="none">
15739 <col class="option" />
15740 <col class="description" />
15741 <tbody valign="top">
15742 <tr><td class="option-group">
15743 <kbd><span class="option">--keep</span></kbd></td>
15744 <td>allow an empty commit after uncommitting</td></tr>
15745 <tr><td class="option-group" colspan="2">
15746 <kbd><span class="option">--allow-dirty-working-copy</span></kbd></td>
15747 </tr>
15748 <tr><td>&nbsp;</td><td>allow uncommit with outstanding changes</td></tr>
15749 <tr><td class="option-group" colspan="2">
15750 <kbd><span class="option">-n</span>, <span class="option">--note <var>&lt;TEXT&gt;</var></span></kbd></td>
15751 </tr>
15752 <tr><td>&nbsp;</td><td>store a note on uncommit</td></tr>
15753 <tr><td class="option-group" colspan="2">
15754 <kbd><span class="option">-I</span>, <span class="option">--include <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
15755 </tr>
15756 <tr><td>&nbsp;</td><td>include names matching the given patterns</td></tr>
15757 <tr><td class="option-group" colspan="2">
15758 <kbd><span class="option">-X</span>, <span class="option">--exclude <var>&lt;PATTERN[+]&gt;</var></span></kbd></td>
15759 </tr>
15760 <tr><td>&nbsp;</td><td>exclude names matching the given patterns</td></tr>
15761 <tr><td class="option-group" colspan="2">
15762 <kbd><span class="option">-m</span>, <span class="option">--message <var>&lt;TEXT&gt;</var></span></kbd></td>
15763 </tr>
15764 <tr><td>&nbsp;</td><td>use text as commit message</td></tr>
15765 <tr><td class="option-group" colspan="2">
15766 <kbd><span class="option">-l</span>, <span class="option">--logfile <var>&lt;FILE&gt;</var></span></kbd></td>
15767 </tr>
15768 <tr><td>&nbsp;</td><td>read commit message from file</td></tr>
15769 <tr><td class="option-group" colspan="2">
15770 <kbd><span class="option">-d</span>, <span class="option">--date <var>&lt;DATE&gt;</var></span></kbd></td>
15771 </tr>
15772 <tr><td>&nbsp;</td><td>record the specified date as commit date</td></tr>
15773 <tr><td class="option-group" colspan="2">
15774 <kbd><span class="option">-u</span>, <span class="option">--user <var>&lt;USER&gt;</var></span></kbd></td>
15775 </tr>
15776 <tr><td>&nbsp;</td><td>record the specified user as committer</td></tr>
15777 <tr><td class="option-group" colspan="2">
15778 <kbd><span class="option">-D</span>, <span class="option">--currentdate</span></kbd></td>
15779 </tr>
15780 <tr><td>&nbsp;</td><td>record the current date as commit date</td></tr>
15781 <tr><td class="option-group" colspan="2">
15782 <kbd><span class="option">-U</span>, <span class="option">--currentuser</span></kbd></td>
15783 </tr>
15784 <tr><td>&nbsp;</td><td>record the current user as committer</td></tr>
15785 </tbody>
15786 </table>
15787 <p>[+] marked option can be specified multiple times</p>
15788 </div>
15789 </div>
15790 </div>
15791 </div>
15792 <div class="section" id="win32mbcs">
15793 <h2><a class="toc-backref" href="#toc-entry-94">win32mbcs</a></h2>
15794 <p>allow the use of MBCS paths with problematic encodings</p>
15795 <p>Some MBCS encodings are not good for some path operations (i.e.
15796 splitting path, case conversion, etc.) with its encoded bytes. We call
15797 such a encoding (i.e. shift_jis and big5) as &quot;problematic encoding&quot;.
15798 This extension can be used to fix the issue with those encodings by
15799 wrapping some functions to convert to Unicode string before path
15800 operation.</p>
15801 <p>This extension is useful for:</p>
15802 <ul class="simple">
15803 <li>Japanese Windows users using shift_jis encoding.</li>
15804 <li>Chinese Windows users using big5 encoding.</li>
15805 <li>All users who use a repository with one of problematic encodings on
15806 case-insensitive file system.</li>
15807 </ul>
15808 <p>This extension is not needed for:</p>
15809 <ul class="simple">
15810 <li>Any user who use only ASCII chars in path.</li>
15811 <li>Any user who do not use any of problematic encodings.</li>
15812 </ul>
15813 <p>Note that there are some limitations on using this extension:</p>
15814 <ul class="simple">
15815 <li>You should use single encoding in one repository.</li>
15816 <li>If the repository path ends with 0x5c, .hg/hgrc cannot be read.</li>
15817 <li>win32mbcs is not compatible with fixutf8 extension.</li>
15818 </ul>
15819 <p>By default, win32mbcs uses encoding.encoding decided by Mercurial.
15820 You can specify the encoding by config option:</p>
15821 <pre class="literal-block">
15822 [win32mbcs]
15823 encoding = sjis
15824 </pre>
15825 <p>It is useful for the users who want to commit with UTF-8 log message.</p>
15826 </div>
15827 <div class="section" id="win32text">
15828 <h2><a class="toc-backref" href="#toc-entry-95">win32text</a></h2>
15829 <p>perform automatic newline conversion (DEPRECATED)</p>
15830 <blockquote>
15831 <p>Deprecation: The win32text extension requires each user to configure
15832 the extension again and again for each clone since the configuration
15833 is not copied when cloning.</p>
15834 <p>We have therefore made the <tt class="docutils literal">eol</tt> as an alternative. The <tt class="docutils literal">eol</tt>
15835 uses a version controlled file for its configuration and each clone
15836 will therefore use the right settings from the start.</p>
15837 </blockquote>
15838 <p>To perform automatic newline conversion, use:</p>
15839 <pre class="literal-block">
15840 [extensions]
15841 win32text =
15842 [encode]
15843 ** = cleverencode:
15844 # or ** = macencode:
15845
15846 [decode]
15847 ** = cleverdecode:
15848 # or ** = macdecode:
15849 </pre>
15850 <p>If not doing conversion, to make sure you do not commit CRLF/CR by accident:</p>
15851 <pre class="literal-block">
15852 [hooks]
15853 pretxncommit.crlf = python:hgext.win32text.forbidcrlf
15854 # or pretxncommit.cr = python:hgext.win32text.forbidcr
15855 </pre>
15856 <p>To do the same check on a server to prevent CRLF/CR from being
15857 pushed or pulled:</p>
15858 <pre class="literal-block">
15859 [hooks]
15860 pretxnchangegroup.crlf = python:hgext.win32text.forbidcrlf
15861 # or pretxnchangegroup.cr = python:hgext.win32text.forbidcr
15862 </pre>
15863 </div>
15864 <div class="section" id="zeroconf">
15865 <h2><a class="toc-backref" href="#toc-entry-96">zeroconf</a></h2>
15866 <p>discover and advertise repositories on the local network</p>
15867 <p>The zeroconf extension will advertise <a class="reference external" href="hg.1.html#serve"><tt class="docutils literal">hg serve</tt></a> instances over
15868 DNS-SD so that they can be discovered using the <a class="reference external" href="hg.1.html#paths"><tt class="docutils literal">hg paths</tt></a> command
15869 without knowing the server's IP address.</p>
15870 <p>To allow other people to discover your repository using run
15871 <a class="reference external" href="hg.1.html#serve"><tt class="docutils literal">hg serve</tt></a> in your repository:</p>
15872 <pre class="literal-block">
15873 $ cd test
15874 $ hg serve
15875 </pre>
15876 <p>You can discover Zeroconf-enabled repositories by running
15877 <a class="reference external" href="hg.1.html#paths"><tt class="docutils literal">hg paths</tt></a>:</p>
15878 <pre class="literal-block">
15879 $ hg paths
15880 zc-test = http://example.com:8000/test
15881 </pre>
15882 </div>
15883 </div>
15884 <div class="section" id="files-1">
15885 <h1><a class="toc-backref" href="#contents">Files</a></h1>
15886 <dl class="docutils">
15887 <dt><tt class="docutils literal">/etc/mercurial/hgrc</tt>, <tt class="docutils literal"><span class="pre">$HOME/.hgrc</span></tt>, <tt class="docutils literal">.hg/hgrc</tt></dt>
15888 <dd>This file contains defaults and configuration. Values in
15889 <tt class="docutils literal">.hg/hgrc</tt> override those in <tt class="docutils literal"><span class="pre">$HOME/.hgrc</span></tt>, and these override
15890 settings made in the global <tt class="docutils literal">/etc/mercurial/hgrc</tt> configuration.
15891 See <a class="reference external" href="hgrc.5.html"><strong>hgrc</strong>(5)</a> for details of the contents and format of these
15892 files.</dd>
15893 <dt><tt class="docutils literal">.hgignore</tt></dt>
15894 <dd>This file contains regular expressions (one per line) that
15895 describe file names that should be ignored by <strong>hg</strong>. For details,
15896 see <a class="reference external" href="hgignore.5.html"><strong>hgignore</strong>(5)</a>.</dd>
15897 <dt><tt class="docutils literal">.hgsub</tt></dt>
15898 <dd>This file defines the locations of all subrepositories, and
15899 tells where the subrepository checkouts came from. For details, see
15900 <a class="reference external" href="hg.1.html#subrepos"><tt class="docutils literal">hg help subrepos</tt></a>.</dd>
15901 <dt><tt class="docutils literal">.hgsubstate</tt></dt>
15902 <dd>This file is where Mercurial stores all nested repository states. <em>NB: This
15903 file should not be edited manually.</em></dd>
15904 <dt><tt class="docutils literal">.hgtags</tt></dt>
15905 <dd>This file contains changeset hash values and text tag names (one
15906 of each separated by spaces) that correspond to tagged versions of
15907 the repository contents. The file content is encoded using UTF-8.</dd>
15908 <dt><tt class="docutils literal"><span class="pre">.hg/last-message.txt</span></tt></dt>
15909 <dd>This file is used by <a class="reference external" href="hg.1.html#commit"><tt class="docutils literal">hg commit</tt></a> to store a backup of the commit message
15910 in case the commit fails.</dd>
15911 <dt><tt class="docutils literal">.hg/localtags</tt></dt>
15912 <dd>This file can be used to define local tags which are not shared among
15913 repositories. The file format is the same as for <tt class="docutils literal">.hgtags</tt>, but it is
15914 encoded using the local system encoding.</dd>
15915 </dl>
15916 <p>Some commands (e.g. revert) produce backup files ending in <tt class="docutils literal">.orig</tt>,
15917 if the <tt class="docutils literal">.orig</tt> file already exists and is not tracked by Mercurial,
15918 it will be overwritten.</p>
15919 </div>
15920 <div class="section" id="bugs">
15921 <h1><a class="toc-backref" href="#contents">Bugs</a></h1>
15922 <p>Probably lots, please post them to the mailing list (see <a class="reference internal" href="#resources">Resources</a>
15923 below) when you find them.</p>
15924 </div>
15925 <div class="section" id="see-also">
15926 <h1><a class="toc-backref" href="#contents">See Also</a></h1>
15927 <p><a class="reference external" href="hgignore.5.html"><strong>hgignore</strong>(5)</a>, <a class="reference external" href="hgrc.5.html"><strong>hgrc</strong>(5)</a></p>
15928 </div>
15929 <div class="section" id="author">
15930 <h1><a class="toc-backref" href="#contents">Author</a></h1>
15931 <p>Written by Olivia Mackall &lt;<a class="reference external" href="mailto:olivia&#64;selenic.com">olivia&#64;selenic.com</a>&gt;</p>
15932 </div>
15933 <div class="section" id="resources">
15934 <h1><a class="toc-backref" href="#contents">Resources</a></h1>
15935 <p>Main Web Site: <a class="reference external" href="https://mercurial-scm.org/">https://mercurial-scm.org/</a></p>
15936 <p>Source code repository: <a class="reference external" href="https://www.mercurial-scm.org/repo/hg">https://www.mercurial-scm.org/repo/hg</a></p>
15937 <p>Mailing list: <a class="reference external" href="https://www.mercurial-scm.org/mailman/listinfo/mercurial/">https://www.mercurial-scm.org/mailman/listinfo/mercurial/</a></p>
15938 </div>
15939 <div class="section" id="copying">
15940 <h1><a class="toc-backref" href="#contents">Copying</a></h1>
15941 <p>Copyright (C) 2005-2026 Olivia Mackall.
15942 Free use of this software is granted under the terms of the GNU General
15943 Public License version 2 or any later version.</p>
15944 <span class="target" id="common"></span><!-- Common link and substitution definitions. -->
15945 </div>
15946 </div>
15947 </body>
15948 </html>