##// END OF EJS Templates
help: move part of hgrc.5 man page config help topic
Yun Lee -
r14456:ff4126ce default
parent child Browse files
Show More
This diff has been collapsed as it changes many lines, (1158 lines changed) Show them Hide them
@@ -1,1200 +1,44 b''
1 ======
1 ======
2 hgrc
2 hgrc
3 ======
3 ======
4
4
5 ---------------------------------
5 ---------------------------------
6 configuration files for Mercurial
6 configuration files for Mercurial
7 ---------------------------------
7 ---------------------------------
8
8
9 :Author: Bryan O'Sullivan <bos@serpentine.com>
9 :Author: Bryan O'Sullivan <bos@serpentine.com>
10 :Organization: Mercurial
10 :Organization: Mercurial
11 :Manual section: 5
11 :Manual section: 5
12 :Manual group: Mercurial Manual
12 :Manual group: Mercurial Manual
13
13
14 .. contents::
14 .. contents::
15 :backlinks: top
15 :backlinks: top
16 :class: htmlonly
16 :class: htmlonly
17
17
18
18
19 Synopsis
19 Synopsis
20 --------
20 --------
21
21
22 The Mercurial system uses a set of configuration files to control
22 The Mercurial system uses a set of configuration files to control
23 aspects of its behavior.
23 aspects of its behavior.
24
24
25 Files
25 .. include:: ../mercurial/help/config.txt
26 -----
27
28 Mercurial reads configuration data from several files, if they exist.
29 The names of these files depend on the system on which Mercurial is
30 installed. ``*.rc`` files from a single directory are read in
31 alphabetical order, later ones overriding earlier ones. Where multiple
32 paths are given below, settings from earlier paths override later
33 ones.
34
35 | (Unix, Windows) ``<repo>/.hg/hgrc``
36
37 Per-repository configuration options that only apply in a
38 particular repository. This file is not version-controlled, and
39 will not get transferred during a "clone" operation. Options in
40 this file override options in all other configuration files. On
41 Unix, most of this file will be ignored if it doesn't belong to a
42 trusted user or to a trusted group. See the documentation for the
43 trusted_ section below for more details.
44
45 | (Unix) ``$HOME/.hgrc``
46 | (Windows) ``%USERPROFILE%\.hgrc``
47 | (Windows) ``%USERPROFILE%\Mercurial.ini``
48 | (Windows) ``%HOME%\.hgrc``
49 | (Windows) ``%HOME%\Mercurial.ini``
50
51 Per-user configuration file(s), for the user running Mercurial. On
52 Windows 9x, ``%HOME%`` is replaced by ``%APPDATA%``. Options in these
53 files apply to all Mercurial commands executed by this user in any
54 directory. Options in these files override per-system and per-installation
55 options.
56
57 | (Unix) ``/etc/mercurial/hgrc``
58 | (Unix) ``/etc/mercurial/hgrc.d/*.rc``
59
60 Per-system configuration files, for the system on which Mercurial
61 is running. Options in these files apply to all Mercurial commands
62 executed by any user in any directory. Options in these files
63 override per-installation options.
64
65 | (Unix) ``<install-root>/etc/mercurial/hgrc``
66 | (Unix) ``<install-root>/etc/mercurial/hgrc.d/*.rc``
67
68 Per-installation configuration files, searched for in the
69 directory where Mercurial is installed. ``<install-root>`` is the
70 parent directory of the **hg** executable (or symlink) being run. For
71 example, if installed in ``/shared/tools/bin/hg``, Mercurial will look
72 in ``/shared/tools/etc/mercurial/hgrc``. Options in these files apply
73 to all Mercurial commands executed by any user in any directory.
74
75 | (Windows) ``<install-dir>\Mercurial.ini``
76 | (Windows) ``<install-dir>\hgrc.d\*.rc``
77 | (Windows) ``HKEY_LOCAL_MACHINE\SOFTWARE\Mercurial``
78
79 Per-installation/system configuration files, for the system on
80 which Mercurial is running. Options in these files apply to all
81 Mercurial commands executed by any user in any directory. Registry
82 keys contain PATH-like strings, every part of which must reference
83 a ``Mercurial.ini`` file or be a directory where ``*.rc`` files will
84 be read. Mercurial checks each of these locations in the specified
85 order until one or more configuration files are detected. If the
86 pywin32 extensions are not installed, Mercurial will only look for
87 site-wide configuration in ``C:\Mercurial\Mercurial.ini``.
88
89 Syntax
90 ------
91
92 A configuration file consists of sections, led by a ``[section]`` header
93 and followed by ``name = value`` entries (sometimes called
94 ``configuration keys``)::
95
96 [spam]
97 eggs=ham
98 green=
99 eggs
100
101 Each line contains one entry. If the lines that follow are indented,
102 they are treated as continuations of that entry. Leading whitespace is
103 removed from values. Empty lines are skipped. Lines beginning with
104 ``#`` or ``;`` are ignored and may be used to provide comments.
105
106 Configuration keys can be set multiple times, in which case mercurial
107 will use the value that was configured last. As an example::
108
109 [spam]
110 eggs=large
111 ham=serrano
112 eggs=small
113
114 This would set the configuration key named ``eggs`` to ``small``.
115
116 It is also possible to define a section multiple times. A section can
117 be redefined on the same and/or on different hgrc files. For example::
118
119 [foo]
120 eggs=large
121 ham=serrano
122 eggs=small
123
124 [bar]
125 eggs=ham
126 green=
127 eggs
128
129 [foo]
130 ham=prosciutto
131 eggs=medium
132 bread=toasted
133
134 This would set the ``eggs``, ``ham``, and ``bread`` configuration keys
135 of the ``foo`` section to ``medium``, ``prosciutto``, and ``toasted``,
136 respectively. As you can see there only thing that matters is the last
137 value that was set for each of the configuration keys.
138
139 If a configuration key is set multiple times in different
140 configuration files the final value will depend on the order in which
141 the different configuration files are read, with settings from earlier
142 paths overriding later ones as described on the ``Files`` section
143 above.
144
145 A line of the form ``%include file`` will include ``file`` into the
146 current configuration file. The inclusion is recursive, which means
147 that included files can include other files. Filenames are relative to
148 the configuration file in which the ``%include`` directive is found.
149 Environment variables and ``~user`` constructs are expanded in
150 ``file``. This lets you do something like::
151
152 %include ~/.hgrc.d/$HOST.rc
153
154 to include a different configuration file on each computer you use.
155
156 A line with ``%unset name`` will remove ``name`` from the current
157 section, if it has been set previously.
158
159 The values are either free-form text strings, lists of text strings,
160 or Boolean values. Boolean values can be set to true using any of "1",
161 "yes", "true", or "on" and to false using "0", "no", "false", or "off"
162 (all case insensitive).
163
164 List values are separated by whitespace or comma, except when values are
165 placed in double quotation marks::
166
167 allow_read = "John Doe, PhD", brian, betty
168
169 Quotation marks can be escaped by prefixing them with a backslash. Only
170 quotation marks at the beginning of a word is counted as a quotation
171 (e.g., ``foo"bar baz`` is the list of ``foo"bar`` and ``baz``).
172
173 Sections
174 --------
175
176 This section describes the different sections that may appear in a
177 Mercurial "hgrc" file, the purpose of each section, its possible keys,
178 and their possible values.
179
180 ``alias``
181 """""""""
182
183 Defines command aliases.
184 Aliases allow you to define your own commands in terms of other
185 commands (or aliases), optionally including arguments. Positional
186 arguments in the form of ``$1``, ``$2``, etc in the alias definition
187 are expanded by Mercurial before execution. Positional arguments not
188 already used by ``$N`` in the definition are put at the end of the
189 command to be executed.
190
191 Alias definitions consist of lines of the form::
192
193 <alias> = <command> [<argument]...
194
195 For example, this definition::
196
197 latest = log --limit 5
198
199 creates a new command ``latest`` that shows only the five most recent
200 changesets. You can define subsequent aliases using earlier ones::
201
202 stable5 = latest -b stable
203
204 .. note:: It is possible to create aliases with the same names as
205 existing commands, which will then override the original
206 definitions. This is almost always a bad idea!
207
208 An alias can start with an exclamation point (``!``) to make it a
209 shell alias. A shell alias is executed with the shell and will let you
210 run arbitrary commands. As an example, ::
211
212 echo = !echo
213
214 will let you do ``hg echo foo`` to have ``foo`` printed in your
215 terminal. A better example might be::
216
217 purge = !$HG status --no-status --unknown -0 | xargs -0 rm
218
219 which will make ``hg purge`` delete all unknown files in the
220 repository in the same manner as the purge extension.
221
222 Shell aliases are executed in an environment where ``$HG`` expand to
223 the path of the Mercurial that was used to execute the alias. This is
224 useful when you want to call further Mercurial commands in a shell
225 alias, as was done above for the purge alias. In addition,
226 ``$HG_ARGS`` expand to the arguments given to Mercurial. In the ``hg
227 echo foo`` call above, ``$HG_ARGS`` would expand to ``echo foo``.
228
229 ``auth``
230 """"""""
231
232 Authentication credentials for HTTP authentication. This section
233 allows you to store usernames and passwords for use when logging
234 *into* HTTP servers. See the web_ configuration section if you want to
235 configure *who* can login to your HTTP server.
236
237 Each line has the following format::
238
239 <name>.<argument> = <value>
240
241 where ``<name>`` is used to group arguments into authentication
242 entries. Example::
243
244 foo.prefix = hg.intevation.org/mercurial
245 foo.username = foo
246 foo.password = bar
247 foo.schemes = http https
248
249 bar.prefix = secure.example.org
250 bar.key = path/to/file.key
251 bar.cert = path/to/file.cert
252 bar.schemes = https
253
254 Supported arguments:
255
256 ``prefix``
257 Either ``*`` or a URI prefix with or without the scheme part.
258 The authentication entry with the longest matching prefix is used
259 (where ``*`` matches everything and counts as a match of length
260 1). If the prefix doesn't include a scheme, the match is performed
261 against the URI with its scheme stripped as well, and the schemes
262 argument, q.v., is then subsequently consulted.
263 ``username``
264 Optional. Username to authenticate with. If not given, and the
265 remote site requires basic or digest authentication, the user will
266 be prompted for it. Environment variables are expanded in the
267 username letting you do ``foo.username = $USER``.
268 ``password``
269 Optional. Password to authenticate with. If not given, and the
270 remote site requires basic or digest authentication, the user
271 will be prompted for it.
272 ``key``
273 Optional. PEM encoded client certificate key file. Environment
274 variables are expanded in the filename.
275 ``cert``
276 Optional. PEM encoded client certificate chain file. Environment
277 variables are expanded in the filename.
278 ``schemes``
279 Optional. Space separated list of URI schemes to use this
280 authentication entry with. Only used if the prefix doesn't include
281 a scheme. Supported schemes are http and https. They will match
282 static-http and static-https respectively, as well.
283 Default: https.
284
285 If no suitable authentication entry is found, the user is prompted
286 for credentials as usual if required by the remote.
287
288
289 ``decode/encode``
290 """""""""""""""""
291
292 Filters for transforming files on checkout/checkin. This would
293 typically be used for newline processing or other
294 localization/canonicalization of files.
295
296 Filters consist of a filter pattern followed by a filter command.
297 Filter patterns are globs by default, rooted at the repository root.
298 For example, to match any file ending in ``.txt`` in the root
299 directory only, use the pattern ``*.txt``. To match any file ending
300 in ``.c`` anywhere in the repository, use the pattern ``**.c``.
301 For each file only the first matching filter applies.
302
303 The filter command can start with a specifier, either ``pipe:`` or
304 ``tempfile:``. If no specifier is given, ``pipe:`` is used by default.
305
306 A ``pipe:`` command must accept data on stdin and return the transformed
307 data on stdout.
308
309 Pipe example::
310
311 [encode]
312 # uncompress gzip files on checkin to improve delta compression
313 # note: not necessarily a good idea, just an example
314 *.gz = pipe: gunzip
315
316 [decode]
317 # recompress gzip files when writing them to the working dir (we
318 # can safely omit "pipe:", because it's the default)
319 *.gz = gzip
320
321 A ``tempfile:`` command is a template. The string ``INFILE`` is replaced
322 with the name of a temporary file that contains the data to be
323 filtered by the command. The string ``OUTFILE`` is replaced with the name
324 of an empty temporary file, where the filtered data must be written by
325 the command.
326
327 .. note:: The tempfile mechanism is recommended for Windows systems,
328 where the standard shell I/O redirection operators often have
329 strange effects and may corrupt the contents of your files.
330
331 This filter mechanism is used internally by the ``eol`` extension to
332 translate line ending characters between Windows (CRLF) and Unix (LF)
333 format. We suggest you use the ``eol`` extension for convenience.
334
335
336 ``defaults``
337 """"""""""""
338
339 (defaults are deprecated. Don't use them. Use aliases instead)
340
341 Use the ``[defaults]`` section to define command defaults, i.e. the
342 default options/arguments to pass to the specified commands.
343
344 The following example makes :hg:`log` run in verbose mode, and
345 :hg:`status` show only the modified files, by default::
346
347 [defaults]
348 log = -v
349 status = -m
350
351 The actual commands, instead of their aliases, must be used when
352 defining command defaults. The command defaults will also be applied
353 to the aliases of the commands defined.
354
355
356 ``diff``
357 """"""""
358
359 Settings used when displaying diffs. Everything except for ``unified`` is a
360 Boolean and defaults to False.
361
362 ``git``
363 Use git extended diff format.
364 ``nodates``
365 Don't include dates in diff headers.
366 ``showfunc``
367 Show which function each change is in.
368 ``ignorews``
369 Ignore white space when comparing lines.
370 ``ignorewsamount``
371 Ignore changes in the amount of white space.
372 ``ignoreblanklines``
373 Ignore changes whose lines are all blank.
374 ``unified``
375 Number of lines of context to show.
376
377 ``email``
378 """""""""
379
380 Settings for extensions that send email messages.
381
382 ``from``
383 Optional. Email address to use in "From" header and SMTP envelope
384 of outgoing messages.
385 ``to``
386 Optional. Comma-separated list of recipients' email addresses.
387 ``cc``
388 Optional. Comma-separated list of carbon copy recipients'
389 email addresses.
390 ``bcc``
391 Optional. Comma-separated list of blind carbon copy recipients'
392 email addresses.
393 ``method``
394 Optional. Method to use to send email messages. If value is ``smtp``
395 (default), use SMTP (see the SMTP_ section for configuration).
396 Otherwise, use as name of program to run that acts like sendmail
397 (takes ``-f`` option for sender, list of recipients on command line,
398 message on stdin). Normally, setting this to ``sendmail`` or
399 ``/usr/sbin/sendmail`` is enough to use sendmail to send messages.
400 ``charsets``
401 Optional. Comma-separated list of character sets considered
402 convenient for recipients. Addresses, headers, and parts not
403 containing patches of outgoing messages will be encoded in the
404 first character set to which conversion from local encoding
405 (``$HGENCODING``, ``ui.fallbackencoding``) succeeds. If correct
406 conversion fails, the text in question is sent as is. Defaults to
407 empty (explicit) list.
408
409 Order of outgoing email character sets:
410
411 1. ``us-ascii``: always first, regardless of settings
412 2. ``email.charsets``: in order given by user
413 3. ``ui.fallbackencoding``: if not in email.charsets
414 4. ``$HGENCODING``: if not in email.charsets
415 5. ``utf-8``: always last, regardless of settings
416
417 Email example::
418
419 [email]
420 from = Joseph User <joe.user@example.com>
421 method = /usr/sbin/sendmail
422 # charsets for western Europeans
423 # us-ascii, utf-8 omitted, as they are tried first and last
424 charsets = iso-8859-1, iso-8859-15, windows-1252
425
426
427 ``extensions``
428 """"""""""""""
429
430 Mercurial has an extension mechanism for adding new features. To
431 enable an extension, create an entry for it in this section.
432
433 If you know that the extension is already in Python's search path,
434 you can give the name of the module, followed by ``=``, with nothing
435 after the ``=``.
436
437 Otherwise, give a name that you choose, followed by ``=``, followed by
438 the path to the ``.py`` file (including the file name extension) that
439 defines the extension.
440
441 To explicitly disable an extension that is enabled in an hgrc of
442 broader scope, prepend its path with ``!``, as in ``foo = !/ext/path``
443 or ``foo = !`` when path is not supplied.
444
445 Example for ``~/.hgrc``::
446
447 [extensions]
448 # (the mq extension will get loaded from Mercurial's path)
449 mq =
450 # (this extension will get loaded from the file specified)
451 myfeature = ~/.hgext/myfeature.py
452
453
454 ``hostfingerprints``
455 """"""""""""""""""""
456
457 Fingerprints of the certificates of known HTTPS servers.
458 A HTTPS connection to a server with a fingerprint configured here will
459 only succeed if the servers certificate matches the fingerprint.
460 This is very similar to how ssh known hosts works.
461 The fingerprint is the SHA-1 hash value of the DER encoded certificate.
462 The CA chain and web.cacerts is not used for servers with a fingerprint.
463
464 For example::
465
466 [hostfingerprints]
467 hg.intevation.org = 38:76:52:7c:87:26:9a:8f:4a:f8:d3:de:08:45:3b:ea:d6:4b:ee:cc
468
469 This feature is only supported when using Python 2.6 or later.
470
471
472 ``format``
473 """"""""""
474
475 ``usestore``
476 Enable or disable the "store" repository format which improves
477 compatibility with systems that fold case or otherwise mangle
478 filenames. Enabled by default. Disabling this option will allow
479 you to store longer filenames in some situations at the expense of
480 compatibility and ensures that the on-disk format of newly created
481 repositories will be compatible with Mercurial before version 0.9.4.
482
483 ``usefncache``
484 Enable or disable the "fncache" repository format which enhances
485 the "store" repository format (which has to be enabled to use
486 fncache) to allow longer filenames and avoids using Windows
487 reserved names, e.g. "nul". Enabled by default. Disabling this
488 option ensures that the on-disk format of newly created
489 repositories will be compatible with Mercurial before version 1.1.
490
491 ``dotencode``
492 Enable or disable the "dotencode" repository format which enhances
493 the "fncache" repository format (which has to be enabled to use
494 dotencode) to avoid issues with filenames starting with ._ on
495 Mac OS X and spaces on Windows. Enabled by default. Disabling this
496 option ensures that the on-disk format of newly created
497 repositories will be compatible with Mercurial before version 1.7.
498
499 ``merge-patterns``
500 """"""""""""""""""
501
502 This section specifies merge tools to associate with particular file
503 patterns. Tools matched here will take precedence over the default
504 merge tool. Patterns are globs by default, rooted at the repository
505 root.
506
507 Example::
508
509 [merge-patterns]
510 **.c = kdiff3
511 **.jpg = myimgmerge
512
513 ``merge-tools``
514 """""""""""""""
515
516 This section configures external merge tools to use for file-level
517 merges.
518
519 Example ``~/.hgrc``::
520
521 [merge-tools]
522 # Override stock tool location
523 kdiff3.executable = ~/bin/kdiff3
524 # Specify command line
525 kdiff3.args = $base $local $other -o $output
526 # Give higher priority
527 kdiff3.priority = 1
528
529 # Define new tool
530 myHtmlTool.args = -m $local $other $base $output
531 myHtmlTool.regkey = Software\FooSoftware\HtmlMerge
532 myHtmlTool.priority = 1
533
534 Supported arguments:
535
536 ``priority``
537 The priority in which to evaluate this tool.
538 Default: 0.
539 ``executable``
540 Either just the name of the executable or its pathname. On Windows,
541 the path can use environment variables with ${ProgramFiles} syntax.
542 Default: the tool name.
543 ``args``
544 The arguments to pass to the tool executable. You can refer to the
545 files being merged as well as the output file through these
546 variables: ``$base``, ``$local``, ``$other``, ``$output``.
547 Default: ``$local $base $other``
548 ``premerge``
549 Attempt to run internal non-interactive 3-way merge tool before
550 launching external tool. Options are ``true``, ``false``, or ``keep``
551 to leave markers in the file if the premerge fails.
552 Default: True
553 ``binary``
554 This tool can merge binary files. Defaults to False, unless tool
555 was selected by file pattern match.
556 ``symlink``
557 This tool can merge symlinks. Defaults to False, even if tool was
558 selected by file pattern match.
559 ``check``
560 A list of merge success-checking options:
561
562 ``changed``
563 Ask whether merge was successful when the merged file shows no changes.
564 ``conflicts``
565 Check whether there are conflicts even though the tool reported success.
566 ``prompt``
567 Always prompt for merge success, regardless of success reported by tool.
568
569 ``checkchanged``
570 True is equivalent to ``check = changed``.
571 Default: False
572 ``checkconflicts``
573 True is equivalent to ``check = conflicts``.
574 Default: False
575 ``fixeol``
576 Attempt to fix up EOL changes caused by the merge tool.
577 Default: False
578 ``gui``
579 This tool requires a graphical interface to run. Default: False
580 ``regkey``
581 Windows registry key which describes install location of this
582 tool. Mercurial will search for this key first under
583 ``HKEY_CURRENT_USER`` and then under ``HKEY_LOCAL_MACHINE``.
584 Default: None
585 ``regkeyalt``
586 An alternate Windows registry key to try if the first key is not
587 found. The alternate key uses the same ``regname`` and ``regappend``
588 semantics of the primary key. The most common use for this key
589 is to search for 32bit applications on 64bit operating systems.
590 Default: None
591 ``regname``
592 Name of value to read from specified registry key. Defaults to the
593 unnamed (default) value.
594 ``regappend``
595 String to append to the value read from the registry, typically
596 the executable name of the tool.
597 Default: None
598
599
600 ``hooks``
601 """""""""
602
603 Commands or Python functions that get automatically executed by
604 various actions such as starting or finishing a commit. Multiple
605 hooks can be run for the same action by appending a suffix to the
606 action. Overriding a site-wide hook can be done by changing its
607 value or setting it to an empty string.
608
609 Example ``.hg/hgrc``::
610
611 [hooks]
612 # update working directory after adding changesets
613 changegroup.update = hg update
614 # do not use the site-wide hook
615 incoming =
616 incoming.email = /my/email/hook
617 incoming.autobuild = /my/build/hook
618
619 Most hooks are run with environment variables set that give useful
620 additional information. For each hook below, the environment
621 variables it is passed are listed with names of the form ``$HG_foo``.
622
623 ``changegroup``
624 Run after a changegroup has been added via push, pull or unbundle.
625 ID of the first new changeset is in ``$HG_NODE``. URL from which
626 changes came is in ``$HG_URL``.
627 ``commit``
628 Run after a changeset has been created in the local repository. ID
629 of the newly created changeset is in ``$HG_NODE``. Parent changeset
630 IDs are in ``$HG_PARENT1`` and ``$HG_PARENT2``.
631 ``incoming``
632 Run after a changeset has been pulled, pushed, or unbundled into
633 the local repository. The ID of the newly arrived changeset is in
634 ``$HG_NODE``. URL that was source of changes came is in ``$HG_URL``.
635 ``outgoing``
636 Run after sending changes from local repository to another. ID of
637 first changeset sent is in ``$HG_NODE``. Source of operation is in
638 ``$HG_SOURCE``; see "preoutgoing" hook for description.
639 ``post-<command>``
640 Run after successful invocations of the associated command. The
641 contents of the command line are passed as ``$HG_ARGS`` and the result
642 code in ``$HG_RESULT``. Parsed command line arguments are passed as
643 ``$HG_PATS`` and ``$HG_OPTS``. These contain string representations of
644 the python data internally passed to <command>. ``$HG_OPTS`` is a
645 dictionary of options (with unspecified options set to their defaults).
646 ``$HG_PATS`` is a list of arguments. Hook failure is ignored.
647 ``pre-<command>``
648 Run before executing the associated command. The contents of the
649 command line are passed as ``$HG_ARGS``. Parsed command line arguments
650 are passed as ``$HG_PATS`` and ``$HG_OPTS``. These contain string
651 representations of the data internally passed to <command>. ``$HG_OPTS``
652 is a dictionary of options (with unspecified options set to their
653 defaults). ``$HG_PATS`` is a list of arguments. If the hook returns
654 failure, the command doesn't execute and Mercurial returns the failure
655 code.
656 ``prechangegroup``
657 Run before a changegroup is added via push, pull or unbundle. Exit
658 status 0 allows the changegroup to proceed. Non-zero status will
659 cause the push, pull or unbundle to fail. URL from which changes
660 will come is in ``$HG_URL``.
661 ``precommit``
662 Run before starting a local commit. Exit status 0 allows the
663 commit to proceed. Non-zero status will cause the commit to fail.
664 Parent changeset IDs are in ``$HG_PARENT1`` and ``$HG_PARENT2``.
665 ``prelistkeys``
666 Run before listing pushkeys (like bookmarks) in the
667 repository. Non-zero status will cause failure. The key namespace is
668 in ``$HG_NAMESPACE``.
669 ``preoutgoing``
670 Run before collecting changes to send from the local repository to
671 another. Non-zero status will cause failure. This lets you prevent
672 pull over HTTP or SSH. Also prevents against local pull, push
673 (outbound) or bundle commands, but not effective, since you can
674 just copy files instead then. Source of operation is in
675 ``$HG_SOURCE``. If "serve", operation is happening on behalf of remote
676 SSH or HTTP repository. If "push", "pull" or "bundle", operation
677 is happening on behalf of repository on same system.
678 ``prepushkey``
679 Run before a pushkey (like a bookmark) is added to the
680 repository. Non-zero status will cause the key to be rejected. The
681 key namespace is in ``$HG_NAMESPACE``, the key is in ``$HG_KEY``,
682 the old value (if any) is in ``$HG_OLD``, and the new value is in
683 ``$HG_NEW``.
684 ``pretag``
685 Run before creating a tag. Exit status 0 allows the tag to be
686 created. Non-zero status will cause the tag to fail. ID of
687 changeset to tag is in ``$HG_NODE``. Name of tag is in ``$HG_TAG``. Tag is
688 local if ``$HG_LOCAL=1``, in repository if ``$HG_LOCAL=0``.
689 ``pretxnchangegroup``
690 Run after a changegroup has been added via push, pull or unbundle,
691 but before the transaction has been committed. Changegroup is
692 visible to hook program. This lets you validate incoming changes
693 before accepting them. Passed the ID of the first new changeset in
694 ``$HG_NODE``. Exit status 0 allows the transaction to commit. Non-zero
695 status will cause the transaction to be rolled back and the push,
696 pull or unbundle will fail. URL that was source of changes is in
697 ``$HG_URL``.
698 ``pretxncommit``
699 Run after a changeset has been created but the transaction not yet
700 committed. Changeset is visible to hook program. This lets you
701 validate commit message and changes. Exit status 0 allows the
702 commit to proceed. Non-zero status will cause the transaction to
703 be rolled back. ID of changeset is in ``$HG_NODE``. Parent changeset
704 IDs are in ``$HG_PARENT1`` and ``$HG_PARENT2``.
705 ``preupdate``
706 Run before updating the working directory. Exit status 0 allows
707 the update to proceed. Non-zero status will prevent the update.
708 Changeset ID of first new parent is in ``$HG_PARENT1``. If merge, ID
709 of second new parent is in ``$HG_PARENT2``.
710 ``listkeys``
711 Run after listing pushkeys (like bookmarks) in the repository. The
712 key namespace is in ``$HG_NAMESPACE``. ``$HG_VALUES`` is a
713 dictionary containing the keys and values.
714 ``pushkey``
715 Run after a pushkey (like a bookmark) is added to the
716 repository. The key namespace is in ``$HG_NAMESPACE``, the key is in
717 ``$HG_KEY``, the old value (if any) is in ``$HG_OLD``, and the new
718 value is in ``$HG_NEW``.
719 ``tag``
720 Run after a tag is created. ID of tagged changeset is in ``$HG_NODE``.
721 Name of tag is in ``$HG_TAG``. Tag is local if ``$HG_LOCAL=1``, in
722 repository if ``$HG_LOCAL=0``.
723 ``update``
724 Run after updating the working directory. Changeset ID of first
725 new parent is in ``$HG_PARENT1``. If merge, ID of second new parent is
726 in ``$HG_PARENT2``. If the update succeeded, ``$HG_ERROR=0``. If the
727 update failed (e.g. because conflicts not resolved), ``$HG_ERROR=1``.
728
729 .. note:: It is generally better to use standard hooks rather than the
730 generic pre- and post- command hooks as they are guaranteed to be
731 called in the appropriate contexts for influencing transactions.
732 Also, hooks like "commit" will be called in all contexts that
733 generate a commit (e.g. tag) and not just the commit command.
734
735 .. note:: Environment variables with empty values may not be passed to
736 hooks on platforms such as Windows. As an example, ``$HG_PARENT2``
737 will have an empty value under Unix-like platforms for non-merge
738 changesets, while it will not be available at all under Windows.
739
740 The syntax for Python hooks is as follows::
741
742 hookname = python:modulename.submodule.callable
743 hookname = python:/path/to/python/module.py:callable
744
745 Python hooks are run within the Mercurial process. Each hook is
746 called with at least three keyword arguments: a ui object (keyword
747 ``ui``), a repository object (keyword ``repo``), and a ``hooktype``
748 keyword that tells what kind of hook is used. Arguments listed as
749 environment variables above are passed as keyword arguments, with no
750 ``HG_`` prefix, and names in lower case.
751
752 If a Python hook returns a "true" value or raises an exception, this
753 is treated as a failure.
754
755
756 ``http_proxy``
757 """"""""""""""
758
759 Used to access web-based Mercurial repositories through a HTTP
760 proxy.
761
762 ``host``
763 Host name and (optional) port of the proxy server, for example
764 "myproxy:8000".
765 ``no``
766 Optional. Comma-separated list of host names that should bypass
767 the proxy.
768 ``passwd``
769 Optional. Password to authenticate with at the proxy server.
770 ``user``
771 Optional. User name to authenticate with at the proxy server.
772 ``always``
773 Optional. Always use the proxy, even for localhost and any entries
774 in ``http_proxy.no``. True or False. Default: False.
775
776 ``smtp``
777 """"""""
778
779 Configuration for extensions that need to send email messages.
780
781 ``host``
782 Host name of mail server, e.g. "mail.example.com".
783 ``port``
784 Optional. Port to connect to on mail server. Default: 25.
785 ``tls``
786 Optional. Method to enable TLS when connecting to mail server: starttls,
787 smtps or none. Default: none.
788 ``username``
789 Optional. User name for authenticating with the SMTP server.
790 Default: none.
791 ``password``
792 Optional. Password for authenticating with the SMTP server. If not
793 specified, interactive sessions will prompt the user for a
794 password; non-interactive sessions will fail. Default: none.
795 ``local_hostname``
796 Optional. It's the hostname that the sender can use to identify
797 itself to the MTA.
798
799
800 ``patch``
801 """""""""
802
803 Settings used when applying patches, for instance through the 'import'
804 command or with Mercurial Queues extension.
805
806 ``eol``
807 When set to 'strict' patch content and patched files end of lines
808 are preserved. When set to ``lf`` or ``crlf``, both files end of
809 lines are ignored when patching and the result line endings are
810 normalized to either LF (Unix) or CRLF (Windows). When set to
811 ``auto``, end of lines are again ignored while patching but line
812 endings in patched files are normalized to their original setting
813 on a per-file basis. If target file does not exist or has no end
814 of line, patch line endings are preserved.
815 Default: strict.
816
817
818 ``paths``
819 """""""""
820
821 Assigns symbolic names to repositories. The left side is the
822 symbolic name, and the right gives the directory or URL that is the
823 location of the repository. Default paths can be declared by setting
824 the following entries.
825
826 ``default``
827 Directory or URL to use when pulling if no source is specified.
828 Default is set to repository from which the current repository was
829 cloned.
830 ``default-push``
831 Optional. Directory or URL to use when pushing if no destination
832 is specified.
833
834
835 ``profiling``
836 """""""""""""
837
838 Specifies profiling format and file output. In this section
839 description, 'profiling data' stands for the raw data collected
840 during profiling, while 'profiling report' stands for a statistical
841 text report generated from the profiling data. The profiling is done
842 using lsprof.
843
844 ``format``
845 Profiling format.
846 Default: text.
847
848 ``text``
849 Generate a profiling report. When saving to a file, it should be
850 noted that only the report is saved, and the profiling data is
851 not kept.
852 ``kcachegrind``
853 Format profiling data for kcachegrind use: when saving to a
854 file, the generated file can directly be loaded into
855 kcachegrind.
856 ``output``
857 File path where profiling data or report should be saved. If the
858 file exists, it is replaced. Default: None, data is printed on
859 stderr
860
861 ``server``
862 """"""""""
863
864 Controls generic server settings.
865
866 ``uncompressed``
867 Whether to allow clients to clone a repository using the
868 uncompressed streaming protocol. This transfers about 40% more
869 data than a regular clone, but uses less memory and CPU on both
870 server and client. Over a LAN (100 Mbps or better) or a very fast
871 WAN, an uncompressed streaming clone is a lot faster (~10x) than a
872 regular clone. Over most WAN connections (anything slower than
873 about 6 Mbps), uncompressed streaming is slower, because of the
874 extra data transfer overhead. This mode will also temporarily hold
875 the write lock while determining what data to transfer.
876 Default is True.
877
878 ``validate``
879 Whether to validate the completeness of pushed changesets by
880 checking that all new file revisions specified in manifests are
881 present. Default is False.
882
883 ``subpaths``
884 """"""""""""
885
886 Defines subrepositories source locations rewriting rules of the form::
887
888 <pattern> = <replacement>
889
890 Where ``pattern`` is a regular expression matching the source and
891 ``replacement`` is the replacement string used to rewrite it. Groups
892 can be matched in ``pattern`` and referenced in ``replacements``. For
893 instance::
894
895 http://server/(.*)-hg/ = http://hg.server/\1/
896
897 rewrites ``http://server/foo-hg/`` into ``http://hg.server/foo/``.
898
899 All patterns are applied in definition order.
900
901 ``trusted``
902 """""""""""
903
904 Mercurial will not use the settings in the
905 ``.hg/hgrc`` file from a repository if it doesn't belong to a trusted
906 user or to a trusted group, as various hgrc features allow arbitrary
907 commands to be run. This issue is often encountered when configuring
908 hooks or extensions for shared repositories or servers. However,
909 the web interface will use some safe settings from the ``[web]``
910 section.
911
912 This section specifies what users and groups are trusted. The
913 current user is always trusted. To trust everybody, list a user or a
914 group with name ``*``. These settings must be placed in an
915 *already-trusted file* to take effect, such as ``$HOME/.hgrc`` of the
916 user or service running Mercurial.
917
918 ``users``
919 Comma-separated list of trusted users.
920 ``groups``
921 Comma-separated list of trusted groups.
922
923
924 ``ui``
925 """"""
926
927 User interface controls.
928
929 ``archivemeta``
930 Whether to include the .hg_archival.txt file containing meta data
931 (hashes for the repository base and for tip) in archives created
932 by the :hg:`archive` command or downloaded via hgweb.
933 Default is True.
934 ``askusername``
935 Whether to prompt for a username when committing. If True, and
936 neither ``$HGUSER`` nor ``$EMAIL`` has been specified, then the user will
937 be prompted to enter a username. If no username is entered, the
938 default ``USER@HOST`` is used instead.
939 Default is False.
940 ``commitsubrepos``
941 Whether to commit modified subrepositories when committing the
942 parent repository. If False and one subrepository has uncommitted
943 changes, abort the commit.
944 Default is True.
945 ``debug``
946 Print debugging information. True or False. Default is False.
947 ``editor``
948 The editor to use during a commit. Default is ``$EDITOR`` or ``vi``.
949 ``fallbackencoding``
950 Encoding to try if it's not possible to decode the changelog using
951 UTF-8. Default is ISO-8859-1.
952 ``ignore``
953 A file to read per-user ignore patterns from. This file should be
954 in the same format as a repository-wide .hgignore file. This
955 option supports hook syntax, so if you want to specify multiple
956 ignore files, you can do so by setting something like
957 ``ignore.other = ~/.hgignore2``. For details of the ignore file
958 format, see the |hgignore(5)|_ man page.
959 ``interactive``
960 Allow to prompt the user. True or False. Default is True.
961 ``logtemplate``
962 Template string for commands that print changesets.
963 ``merge``
964 The conflict resolution program to use during a manual merge.
965 For more information on merge tools see :hg:`help merge-tools`.
966 For configuring merge tools see the merge-tools_ section.
967 ``portablefilenames``
968 Check for portable filenames. Can be ``warn``, ``ignore`` or ``abort``.
969 Default is ``warn``.
970 If set to ``warn`` (or ``true``), a warning message is printed on POSIX
971 platforms, if a file with a non-portable filename is added (e.g. a file
972 with a name that can't be created on Windows because it contains reserved
973 parts like ``AUX``, reserved characters like ``:``, or would cause a case
974 collision with an existing file).
975 If set to ``ignore`` (or ``false``), no warning is printed.
976 If set to ``abort``, the command is aborted.
977 On Windows, this configuration option is ignored and the command aborted.
978 ``quiet``
979 Reduce the amount of output printed. True or False. Default is False.
980 ``remotecmd``
981 remote command to use for clone/push/pull operations. Default is ``hg``.
982 ``report_untrusted``
983 Warn if a ``.hg/hgrc`` file is ignored due to not being owned by a
984 trusted user or group. True or False. Default is True.
985 ``slash``
986 Display paths using a slash (``/``) as the path separator. This
987 only makes a difference on systems where the default path
988 separator is not the slash character (e.g. Windows uses the
989 backslash character (``\``)).
990 Default is False.
991 ``ssh``
992 command to use for SSH connections. Default is ``ssh``.
993 ``strict``
994 Require exact command names, instead of allowing unambiguous
995 abbreviations. True or False. Default is False.
996 ``style``
997 Name of style to use for command output.
998 ``timeout``
999 The timeout used when a lock is held (in seconds), a negative value
1000 means no timeout. Default is 600.
1001 ``traceback``
1002 Mercurial always prints a traceback when an unknown exception
1003 occurs. Setting this to True will make Mercurial print a traceback
1004 on all exceptions, even those recognized by Mercurial (such as
1005 IOError or MemoryError). Default is False.
1006 ``username``
1007 The committer of a changeset created when running "commit".
1008 Typically a person's name and email address, e.g. ``Fred Widget
1009 <fred@example.com>``. Default is ``$EMAIL`` or ``username@hostname``. If
1010 the username in hgrc is empty, it has to be specified manually or
1011 in a different hgrc file (e.g. ``$HOME/.hgrc``, if the admin set
1012 ``username =`` in the system hgrc). Environment variables in the
1013 username are expanded.
1014 ``verbose``
1015 Increase the amount of output printed. True or False. Default is False.
1016
1017
1018 ``web``
1019 """""""
1020
1021 Web interface configuration. The settings in this section apply to
1022 both the builtin webserver (started by :hg:`serve`) and the script you
1023 run through a webserver (``hgweb.cgi`` and the derivatives for FastCGI
1024 and WSGI).
1025
1026 The Mercurial webserver does no authentication (it does not prompt for
1027 usernames and passwords to validate *who* users are), but it does do
1028 authorization (it grants or denies access for *authenticated users*
1029 based on settings in this section). You must either configure your
1030 webserver to do authentication for you, or disable the authorization
1031 checks.
1032
1033 For a quick setup in a trusted environment, e.g., a private LAN, where
1034 you want it to accept pushes from anybody, you can use the following
1035 command line::
1036
1037 $ hg --config web.allow_push=* --config web.push_ssl=False serve
1038
1039 Note that this will allow anybody to push anything to the server and
1040 that this should not be used for public servers.
1041
1042 The full set of options is:
1043
1044 ``accesslog``
1045 Where to output the access log. Default is stdout.
1046 ``address``
1047 Interface address to bind to. Default is all.
1048 ``allow_archive``
1049 List of archive format (bz2, gz, zip) allowed for downloading.
1050 Default is empty.
1051 ``allowbz2``
1052 (DEPRECATED) Whether to allow .tar.bz2 downloading of repository
1053 revisions.
1054 Default is False.
1055 ``allowgz``
1056 (DEPRECATED) Whether to allow .tar.gz downloading of repository
1057 revisions.
1058 Default is False.
1059 ``allowpull``
1060 Whether to allow pulling from the repository. Default is True.
1061 ``allow_push``
1062 Whether to allow pushing to the repository. If empty or not set,
1063 push is not allowed. If the special value ``*``, any remote user can
1064 push, including unauthenticated users. Otherwise, the remote user
1065 must have been authenticated, and the authenticated user name must
1066 be present in this list. The contents of the allow_push list are
1067 examined after the deny_push list.
1068 ``allow_read``
1069 If the user has not already been denied repository access due to
1070 the contents of deny_read, this list determines whether to grant
1071 repository access to the user. If this list is not empty, and the
1072 user is unauthenticated or not present in the list, then access is
1073 denied for the user. If the list is empty or not set, then access
1074 is permitted to all users by default. Setting allow_read to the
1075 special value ``*`` is equivalent to it not being set (i.e. access
1076 is permitted to all users). The contents of the allow_read list are
1077 examined after the deny_read list.
1078 ``allowzip``
1079 (DEPRECATED) Whether to allow .zip downloading of repository
1080 revisions. Default is False. This feature creates temporary files.
1081 ``baseurl``
1082 Base URL to use when publishing URLs in other locations, so
1083 third-party tools like email notification hooks can construct
1084 URLs. Example: ``http://hgserver/repos/``.
1085 ``cacerts``
1086 Path to file containing a list of PEM encoded certificate
1087 authority certificates. Environment variables and ``~user``
1088 constructs are expanded in the filename. If specified on the
1089 client, then it will verify the identity of remote HTTPS servers
1090 with these certificates. The form must be as follows::
1091
1092 -----BEGIN CERTIFICATE-----
1093 ... (certificate in base64 PEM encoding) ...
1094 -----END CERTIFICATE-----
1095 -----BEGIN CERTIFICATE-----
1096 ... (certificate in base64 PEM encoding) ...
1097 -----END CERTIFICATE-----
1098
1099 This feature is only supported when using Python 2.6 or later. If you wish
1100 to use it with earlier versions of Python, install the backported
1101 version of the ssl library that is available from
1102 ``http://pypi.python.org``.
1103
1104 You can use OpenSSL's CA certificate file if your platform has one.
1105 On most Linux systems this will be ``/etc/ssl/certs/ca-certificates.crt``.
1106 Otherwise you will have to generate this file manually.
1107
1108 To disable SSL verification temporarily, specify ``--insecure`` from
1109 command line.
1110 ``cache``
1111 Whether to support caching in hgweb. Defaults to True.
1112 ``contact``
1113 Name or email address of the person in charge of the repository.
1114 Defaults to ui.username or ``$EMAIL`` or "unknown" if unset or empty.
1115 ``deny_push``
1116 Whether to deny pushing to the repository. If empty or not set,
1117 push is not denied. If the special value ``*``, all remote users are
1118 denied push. Otherwise, unauthenticated users are all denied, and
1119 any authenticated user name present in this list is also denied. The
1120 contents of the deny_push list are examined before the allow_push list.
1121 ``deny_read``
1122 Whether to deny reading/viewing of the repository. If this list is
1123 not empty, unauthenticated users are all denied, and any
1124 authenticated user name present in this list is also denied access to
1125 the repository. If set to the special value ``*``, all remote users
1126 are denied access (rarely needed ;). If deny_read is empty or not set,
1127 the determination of repository access depends on the presence and
1128 content of the allow_read list (see description). If both
1129 deny_read and allow_read are empty or not set, then access is
1130 permitted to all users by default. If the repository is being
1131 served via hgwebdir, denied users will not be able to see it in
1132 the list of repositories. The contents of the deny_read list have
1133 priority over (are examined before) the contents of the allow_read
1134 list.
1135 ``descend``
1136 hgwebdir indexes will not descend into subdirectories. Only repositories
1137 directly in the current path will be shown (other repositories are still
1138 available from the index corresponding to their containing path).
1139 ``description``
1140 Textual description of the repository's purpose or contents.
1141 Default is "unknown".
1142 ``encoding``
1143 Character encoding name. Default is the current locale charset.
1144 Example: "UTF-8"
1145 ``errorlog``
1146 Where to output the error log. Default is stderr.
1147 ``hidden``
1148 Whether to hide the repository in the hgwebdir index.
1149 Default is False.
1150 ``ipv6``
1151 Whether to use IPv6. Default is False.
1152 ``logourl``
1153 Base URL to use for logos. If unset, ``http://mercurial.selenic.com/``
1154 will be used.
1155 ``name``
1156 Repository name to use in the web interface. Default is current
1157 working directory.
1158 ``maxchanges``
1159 Maximum number of changes to list on the changelog. Default is 10.
1160 ``maxfiles``
1161 Maximum number of files to list per changeset. Default is 10.
1162 ``port``
1163 Port to listen on. Default is 8000.
1164 ``prefix``
1165 Prefix path to serve from. Default is '' (server root).
1166 ``push_ssl``
1167 Whether to require that inbound pushes be transported over SSL to
1168 prevent password sniffing. Default is True.
1169 ``staticurl``
1170 Base URL to use for static files. If unset, static files (e.g. the
1171 hgicon.png favicon) will be served by the CGI script itself. Use
1172 this setting to serve them directly with the HTTP server.
1173 Example: ``http://hgserver/static/``.
1174 ``stripes``
1175 How many lines a "zebra stripe" should span in multiline output.
1176 Default is 1; set to 0 to disable.
1177 ``style``
1178 Which template map style to use.
1179 ``templates``
1180 Where to find the HTML templates. Default is install path.
1181
1182
26
1183 Author
27 Author
1184 ------
28 ------
1185 Bryan O'Sullivan <bos@serpentine.com>.
29 Bryan O'Sullivan <bos@serpentine.com>.
1186
30
1187 Mercurial was written by Matt Mackall <mpm@selenic.com>.
31 Mercurial was written by Matt Mackall <mpm@selenic.com>.
1188
32
1189 See Also
33 See Also
1190 --------
34 --------
1191 |hg(1)|_, |hgignore(5)|_
35 |hg(1)|_, |hgignore(5)|_
1192
36
1193 Copying
37 Copying
1194 -------
38 -------
1195 This manual page is copyright 2005 Bryan O'Sullivan.
39 This manual page is copyright 2005 Bryan O'Sullivan.
1196 Mercurial is copyright 2005-2010 Matt Mackall.
40 Mercurial is copyright 2005-2010 Matt Mackall.
1197 Free use of this software is granted under the terms of the GNU General
41 Free use of this software is granted under the terms of the GNU General
1198 Public License version 2 or any later version.
42 Public License version 2 or any later version.
1199
43
1200 .. include:: common.txt
44 .. include:: common.txt
This diff has been collapsed as it changes many lines, (1157 lines changed) Show them Hide them
@@ -1,57 +1,1214 b''
1 Mercurial reads configuration data from several files, if they exist.
1 Mercurial reads configuration data from several files, if they exist.
2 Below we list the most specific file first.
2 Below we list the most specific file first.
3
3
4 On Windows, these configuration files are read:
4 On Windows, these configuration files are read:
5
5
6 - ``<repo>\.hg\hgrc``
6 - ``<repo>\.hg\hgrc``
7 - ``%USERPROFILE%\.hgrc``
7 - ``%USERPROFILE%\.hgrc``
8 - ``%USERPROFILE%\mercurial.ini``
8 - ``%USERPROFILE%\mercurial.ini``
9 - ``%HOME%\.hgrc``
9 - ``%HOME%\.hgrc``
10 - ``%HOME%\mercurial.ini``
10 - ``%HOME%\mercurial.ini``
11 - ``C:\mercurial\mercurial.ini`` (unless regkey or hgrc.d\ or mercurial.ini found)
11 - ``C:\mercurial\mercurial.ini`` (unless regkey or hgrc.d\ or mercurial.ini found)
12 - ``HKEY_LOCAL_MACHINE\SOFTWARE\Mercurial`` (unless hgrc.d\ or mercurial.ini found)
12 - ``HKEY_LOCAL_MACHINE\SOFTWARE\Mercurial`` (unless hgrc.d\ or mercurial.ini found)
13 - ``<hg.exe-dir>\hgrc.d\*.rc`` (unless mercurial.ini found)
13 - ``<hg.exe-dir>\hgrc.d\*.rc`` (unless mercurial.ini found)
14 - ``<hg.exe-dir>\mercurial.ini``
14 - ``<hg.exe-dir>\mercurial.ini``
15
15
16 On Unix, these files are read:
16 On Unix, these files are read:
17
17
18 - ``<repo>/.hg/hgrc``
18 - ``<repo>/.hg/hgrc``
19 - ``$HOME/.hgrc``
19 - ``$HOME/.hgrc``
20 - ``/etc/mercurial/hgrc``
20 - ``/etc/mercurial/hgrc``
21 - ``/etc/mercurial/hgrc.d/*.rc``
21 - ``/etc/mercurial/hgrc.d/*.rc``
22 - ``<install-root>/etc/mercurial/hgrc``
22 - ``<install-root>/etc/mercurial/hgrc``
23 - ``<install-root>/etc/mercurial/hgrc.d/*.rc``
23 - ``<install-root>/etc/mercurial/hgrc.d/*.rc``
24
24
25 These files do not exist by default and you will have to create the
25 These files do not exist by default and you will have to create the
26 appropriate configuration files yourself: global configuration like
26 appropriate configuration files yourself: global configuration like
27 the username setting is typically put into
27 the username setting is typically put into
28 ``%USERPROFILE%\mercurial.ini`` or ``$HOME/.hgrc`` and local
28 ``%USERPROFILE%\mercurial.ini`` or ``$HOME/.hgrc`` and local
29 configuration is put into the per-repository ``<repo>/.hg/hgrc`` file.
29 configuration is put into the per-repository ``<repo>/.hg/hgrc`` file.
30
30
31 If there is a per-repository configuration file which is not owned by
31 If there is a per-repository configuration file which is not owned by
32 the active user, Mercurial will warn you that the file is skipped::
32 the active user, Mercurial will warn you that the file is skipped::
33
33
34 not trusting file <repo>/.hg/hgrc from untrusted user USER, group GROUP
34 not trusting file <repo>/.hg/hgrc from untrusted user USER, group GROUP
35
35
36 If this bothers you, the warning can be silenced (the file would still
36 If this bothers you, the warning can be silenced (the file would still
37 be ignored) or trust can be established. Use one of the following
37 be ignored) or trust can be established. Use one of the following
38 settings, the syntax is explained below:
38 settings, the syntax is explained below:
39
39
40 - ``ui.report_untrusted = False``
40 - ``ui.report_untrusted = False``
41 - ``trusted.users = USER``
41 - ``trusted.users = USER``
42 - ``trusted.groups = GROUP``
42 - ``trusted.groups = GROUP``
43
43
44 The configuration files for Mercurial use a simple ini-file format. A
44 The configuration files for Mercurial use a simple ini-file format. A
45 configuration file consists of sections, led by a ``[section]`` header
45 configuration file consists of sections, led by a ``[section]`` header
46 and followed by ``name = value`` entries::
46 and followed by ``name = value`` entries::
47
47
48 [ui]
48 [ui]
49 username = Firstname Lastname <firstname.lastname@example.net>
49 username = Firstname Lastname <firstname.lastname@example.net>
50 verbose = True
50 verbose = True
51
51
52 The above entries will be referred to as ``ui.username`` and
52 The above entries will be referred to as ``ui.username`` and
53 ``ui.verbose``, respectively. Please see the hgrc man page for a full
53 ``ui.verbose``, respectively. Please see the hgrc man page for a full
54 description of the possible configuration values:
54 description of the possible configuration values:
55
55
56 - on Unix-like systems: ``man hgrc``
56 - on Unix-like systems: ``man hgrc``
57 - online: http://www.selenic.com/mercurial/hgrc.5.html
57 - online: http://www.selenic.com/mercurial/hgrc.5.html
58
59 Files
60 -----
61
62 Mercurial reads configuration data from several files, if they exist.
63 The names of these files depend on the system on which Mercurial is
64 installed. ``*.rc`` files from a single directory are read in
65 alphabetical order, later ones overriding earlier ones. Where multiple
66 paths are given below, settings from earlier paths override later
67 ones.
68
69 | (Unix, Windows) ``<repo>/.hg/hgrc``
70
71 Per-repository configuration options that only apply in a
72 particular repository. This file is not version-controlled, and
73 will not get transferred during a "clone" operation. Options in
74 this file override options in all other configuration files. On
75 Unix, most of this file will be ignored if it doesn't belong to a
76 trusted user or to a trusted group. See the documentation for the
77 trusted_ section below for more details.
78
79 | (Unix) ``$HOME/.hgrc``
80 | (Windows) ``%USERPROFILE%\.hgrc``
81 | (Windows) ``%USERPROFILE%\Mercurial.ini``
82 | (Windows) ``%HOME%\.hgrc``
83 | (Windows) ``%HOME%\Mercurial.ini``
84
85 Per-user configuration file(s), for the user running Mercurial. On
86 Windows 9x, ``%HOME%`` is replaced by ``%APPDATA%``. Options in these
87 files apply to all Mercurial commands executed by this user in any
88 directory. Options in these files override per-system and per-installation
89 options.
90
91 | (Unix) ``/etc/mercurial/hgrc``
92 | (Unix) ``/etc/mercurial/hgrc.d/*.rc``
93
94 Per-system configuration files, for the system on which Mercurial
95 is running. Options in these files apply to all Mercurial commands
96 executed by any user in any directory. Options in these files
97 override per-installation options.
98
99 | (Unix) ``<install-root>/etc/mercurial/hgrc``
100 | (Unix) ``<install-root>/etc/mercurial/hgrc.d/*.rc``
101
102 Per-installation configuration files, searched for in the
103 directory where Mercurial is installed. ``<install-root>`` is the
104 parent directory of the **hg** executable (or symlink) being run. For
105 example, if installed in ``/shared/tools/bin/hg``, Mercurial will look
106 in ``/shared/tools/etc/mercurial/hgrc``. Options in these files apply
107 to all Mercurial commands executed by any user in any directory.
108
109 | (Windows) ``<install-dir>\Mercurial.ini``
110 | (Windows) ``<install-dir>\hgrc.d\*.rc``
111 | (Windows) ``HKEY_LOCAL_MACHINE\SOFTWARE\Mercurial``
112
113 Per-installation/system configuration files, for the system on
114 which Mercurial is running. Options in these files apply to all
115 Mercurial commands executed by any user in any directory. Registry
116 keys contain PATH-like strings, every part of which must reference
117 a ``Mercurial.ini`` file or be a directory where ``*.rc`` files will
118 be read. Mercurial checks each of these locations in the specified
119 order until one or more configuration files are detected. If the
120 pywin32 extensions are not installed, Mercurial will only look for
121 site-wide configuration in ``C:\Mercurial\Mercurial.ini``.
122
123 Syntax
124 ------
125
126 A configuration file consists of sections, led by a ``[section]`` header
127 and followed by ``name = value`` entries (sometimes called
128 ``configuration keys``)::
129
130 [spam]
131 eggs=ham
132 green=
133 eggs
134
135 Each line contains one entry. If the lines that follow are indented,
136 they are treated as continuations of that entry. Leading whitespace is
137 removed from values. Empty lines are skipped. Lines beginning with
138 ``#`` or ``;`` are ignored and may be used to provide comments.
139
140 Configuration keys can be set multiple times, in which case mercurial
141 will use the value that was configured last. As an example::
142
143 [spam]
144 eggs=large
145 ham=serrano
146 eggs=small
147
148 This would set the configuration key named ``eggs`` to ``small``.
149
150 It is also possible to define a section multiple times. A section can
151 be redefined on the same and/or on different hgrc files. For example::
152
153 [foo]
154 eggs=large
155 ham=serrano
156 eggs=small
157
158 [bar]
159 eggs=ham
160 green=
161 eggs
162
163 [foo]
164 ham=prosciutto
165 eggs=medium
166 bread=toasted
167
168 This would set the ``eggs``, ``ham``, and ``bread`` configuration keys
169 of the ``foo`` section to ``medium``, ``prosciutto``, and ``toasted``,
170 respectively. As you can see there only thing that matters is the last
171 value that was set for each of the configuration keys.
172
173 If a configuration key is set multiple times in different
174 configuration files the final value will depend on the order in which
175 the different configuration files are read, with settings from earlier
176 paths overriding later ones as described on the ``Files`` section
177 above.
178
179 A line of the form ``%include file`` will include ``file`` into the
180 current configuration file. The inclusion is recursive, which means
181 that included files can include other files. Filenames are relative to
182 the configuration file in which the ``%include`` directive is found.
183 Environment variables and ``~user`` constructs are expanded in
184 ``file``. This lets you do something like::
185
186 %include ~/.hgrc.d/$HOST.rc
187
188 to include a different configuration file on each computer you use.
189
190 A line with ``%unset name`` will remove ``name`` from the current
191 section, if it has been set previously.
192
193 The values are either free-form text strings, lists of text strings,
194 or Boolean values. Boolean values can be set to true using any of "1",
195 "yes", "true", or "on" and to false using "0", "no", "false", or "off"
196 (all case insensitive).
197
198 List values are separated by whitespace or comma, except when values are
199 placed in double quotation marks::
200
201 allow_read = "John Doe, PhD", brian, betty
202
203 Quotation marks can be escaped by prefixing them with a backslash. Only
204 quotation marks at the beginning of a word is counted as a quotation
205 (e.g., ``foo"bar baz`` is the list of ``foo"bar`` and ``baz``).
206
207 Sections
208 --------
209
210 This section describes the different sections that may appear in a
211 Mercurial "hgrc" file, the purpose of each section, its possible keys,
212 and their possible values.
213
214 ``alias``
215 """""""""
216
217 Defines command aliases.
218 Aliases allow you to define your own commands in terms of other
219 commands (or aliases), optionally including arguments. Positional
220 arguments in the form of ``$1``, ``$2``, etc in the alias definition
221 are expanded by Mercurial before execution. Positional arguments not
222 already used by ``$N`` in the definition are put at the end of the
223 command to be executed.
224
225 Alias definitions consist of lines of the form::
226
227 <alias> = <command> [<argument]...
228
229 For example, this definition::
230
231 latest = log --limit 5
232
233 creates a new command ``latest`` that shows only the five most recent
234 changesets. You can define subsequent aliases using earlier ones::
235
236 stable5 = latest -b stable
237
238 .. note:: It is possible to create aliases with the same names as
239 existing commands, which will then override the original
240 definitions. This is almost always a bad idea!
241
242 An alias can start with an exclamation point (``!``) to make it a
243 shell alias. A shell alias is executed with the shell and will let you
244 run arbitrary commands. As an example, ::
245
246 echo = !echo
247
248 will let you do ``hg echo foo`` to have ``foo`` printed in your
249 terminal. A better example might be::
250
251 purge = !$HG status --no-status --unknown -0 | xargs -0 rm
252
253 which will make ``hg purge`` delete all unknown files in the
254 repository in the same manner as the purge extension.
255
256 Shell aliases are executed in an environment where ``$HG`` expand to
257 the path of the Mercurial that was used to execute the alias. This is
258 useful when you want to call further Mercurial commands in a shell
259 alias, as was done above for the purge alias. In addition,
260 ``$HG_ARGS`` expand to the arguments given to Mercurial. In the ``hg
261 echo foo`` call above, ``$HG_ARGS`` would expand to ``echo foo``.
262
263 ``auth``
264 """"""""
265
266 Authentication credentials for HTTP authentication. This section
267 allows you to store usernames and passwords for use when logging
268 *into* HTTP servers. See the web_ configuration section if you want to
269 configure *who* can login to your HTTP server.
270
271 Each line has the following format::
272
273 <name>.<argument> = <value>
274
275 where ``<name>`` is used to group arguments into authentication
276 entries. Example::
277
278 foo.prefix = hg.intevation.org/mercurial
279 foo.username = foo
280 foo.password = bar
281 foo.schemes = http https
282
283 bar.prefix = secure.example.org
284 bar.key = path/to/file.key
285 bar.cert = path/to/file.cert
286 bar.schemes = https
287
288 Supported arguments:
289
290 ``prefix``
291 Either ``*`` or a URI prefix with or without the scheme part.
292 The authentication entry with the longest matching prefix is used
293 (where ``*`` matches everything and counts as a match of length
294 1). If the prefix doesn't include a scheme, the match is performed
295 against the URI with its scheme stripped as well, and the schemes
296 argument, q.v., is then subsequently consulted.
297 ``username``
298 Optional. Username to authenticate with. If not given, and the
299 remote site requires basic or digest authentication, the user will
300 be prompted for it. Environment variables are expanded in the
301 username letting you do ``foo.username = $USER``.
302 ``password``
303 Optional. Password to authenticate with. If not given, and the
304 remote site requires basic or digest authentication, the user
305 will be prompted for it.
306 ``key``
307 Optional. PEM encoded client certificate key file. Environment
308 variables are expanded in the filename.
309 ``cert``
310 Optional. PEM encoded client certificate chain file. Environment
311 variables are expanded in the filename.
312 ``schemes``
313 Optional. Space separated list of URI schemes to use this
314 authentication entry with. Only used if the prefix doesn't include
315 a scheme. Supported schemes are http and https. They will match
316 static-http and static-https respectively, as well.
317 Default: https.
318
319 If no suitable authentication entry is found, the user is prompted
320 for credentials as usual if required by the remote.
321
322
323 ``decode/encode``
324 """""""""""""""""
325
326 Filters for transforming files on checkout/checkin. This would
327 typically be used for newline processing or other
328 localization/canonicalization of files.
329
330 Filters consist of a filter pattern followed by a filter command.
331 Filter patterns are globs by default, rooted at the repository root.
332 For example, to match any file ending in ``.txt`` in the root
333 directory only, use the pattern ``*.txt``. To match any file ending
334 in ``.c`` anywhere in the repository, use the pattern ``**.c``.
335 For each file only the first matching filter applies.
336
337 The filter command can start with a specifier, either ``pipe:`` or
338 ``tempfile:``. If no specifier is given, ``pipe:`` is used by default.
339
340 A ``pipe:`` command must accept data on stdin and return the transformed
341 data on stdout.
342
343 Pipe example::
344
345 [encode]
346 # uncompress gzip files on checkin to improve delta compression
347 # note: not necessarily a good idea, just an example
348 *.gz = pipe: gunzip
349
350 [decode]
351 # recompress gzip files when writing them to the working dir (we
352 # can safely omit "pipe:", because it's the default)
353 *.gz = gzip
354
355 A ``tempfile:`` command is a template. The string ``INFILE`` is replaced
356 with the name of a temporary file that contains the data to be
357 filtered by the command. The string ``OUTFILE`` is replaced with the name
358 of an empty temporary file, where the filtered data must be written by
359 the command.
360
361 .. note:: The tempfile mechanism is recommended for Windows systems,
362 where the standard shell I/O redirection operators often have
363 strange effects and may corrupt the contents of your files.
364
365 This filter mechanism is used internally by the ``eol`` extension to
366 translate line ending characters between Windows (CRLF) and Unix (LF)
367 format. We suggest you use the ``eol`` extension for convenience.
368
369
370 ``defaults``
371 """"""""""""
372
373 (defaults are deprecated. Don't use them. Use aliases instead)
374
375 Use the ``[defaults]`` section to define command defaults, i.e. the
376 default options/arguments to pass to the specified commands.
377
378 The following example makes :hg:`log` run in verbose mode, and
379 :hg:`status` show only the modified files, by default::
380
381 [defaults]
382 log = -v
383 status = -m
384
385 The actual commands, instead of their aliases, must be used when
386 defining command defaults. The command defaults will also be applied
387 to the aliases of the commands defined.
388
389
390 ``diff``
391 """"""""
392
393 Settings used when displaying diffs. Everything except for ``unified`` is a
394 Boolean and defaults to False.
395
396 ``git``
397 Use git extended diff format.
398 ``nodates``
399 Don't include dates in diff headers.
400 ``showfunc``
401 Show which function each change is in.
402 ``ignorews``
403 Ignore white space when comparing lines.
404 ``ignorewsamount``
405 Ignore changes in the amount of white space.
406 ``ignoreblanklines``
407 Ignore changes whose lines are all blank.
408 ``unified``
409 Number of lines of context to show.
410
411 ``email``
412 """""""""
413
414 Settings for extensions that send email messages.
415
416 ``from``
417 Optional. Email address to use in "From" header and SMTP envelope
418 of outgoing messages.
419 ``to``
420 Optional. Comma-separated list of recipients' email addresses.
421 ``cc``
422 Optional. Comma-separated list of carbon copy recipients'
423 email addresses.
424 ``bcc``
425 Optional. Comma-separated list of blind carbon copy recipients'
426 email addresses.
427 ``method``
428 Optional. Method to use to send email messages. If value is ``smtp``
429 (default), use SMTP (see the SMTP_ section for configuration).
430 Otherwise, use as name of program to run that acts like sendmail
431 (takes ``-f`` option for sender, list of recipients on command line,
432 message on stdin). Normally, setting this to ``sendmail`` or
433 ``/usr/sbin/sendmail`` is enough to use sendmail to send messages.
434 ``charsets``
435 Optional. Comma-separated list of character sets considered
436 convenient for recipients. Addresses, headers, and parts not
437 containing patches of outgoing messages will be encoded in the
438 first character set to which conversion from local encoding
439 (``$HGENCODING``, ``ui.fallbackencoding``) succeeds. If correct
440 conversion fails, the text in question is sent as is. Defaults to
441 empty (explicit) list.
442
443 Order of outgoing email character sets:
444
445 1. ``us-ascii``: always first, regardless of settings
446 2. ``email.charsets``: in order given by user
447 3. ``ui.fallbackencoding``: if not in email.charsets
448 4. ``$HGENCODING``: if not in email.charsets
449 5. ``utf-8``: always last, regardless of settings
450
451 Email example::
452
453 [email]
454 from = Joseph User <joe.user@example.com>
455 method = /usr/sbin/sendmail
456 # charsets for western Europeans
457 # us-ascii, utf-8 omitted, as they are tried first and last
458 charsets = iso-8859-1, iso-8859-15, windows-1252
459
460
461 ``extensions``
462 """"""""""""""
463
464 Mercurial has an extension mechanism for adding new features. To
465 enable an extension, create an entry for it in this section.
466
467 If you know that the extension is already in Python's search path,
468 you can give the name of the module, followed by ``=``, with nothing
469 after the ``=``.
470
471 Otherwise, give a name that you choose, followed by ``=``, followed by
472 the path to the ``.py`` file (including the file name extension) that
473 defines the extension.
474
475 To explicitly disable an extension that is enabled in an hgrc of
476 broader scope, prepend its path with ``!``, as in ``foo = !/ext/path``
477 or ``foo = !`` when path is not supplied.
478
479 Example for ``~/.hgrc``::
480
481 [extensions]
482 # (the mq extension will get loaded from Mercurial's path)
483 mq =
484 # (this extension will get loaded from the file specified)
485 myfeature = ~/.hgext/myfeature.py
486
487
488 ``hostfingerprints``
489 """"""""""""""""""""
490
491 Fingerprints of the certificates of known HTTPS servers.
492 A HTTPS connection to a server with a fingerprint configured here will
493 only succeed if the servers certificate matches the fingerprint.
494 This is very similar to how ssh known hosts works.
495 The fingerprint is the SHA-1 hash value of the DER encoded certificate.
496 The CA chain and web.cacerts is not used for servers with a fingerprint.
497
498 For example::
499
500 [hostfingerprints]
501 hg.intevation.org = 38:76:52:7c:87:26:9a:8f:4a:f8:d3:de:08:45:3b:ea:d6:4b:ee:cc
502
503 This feature is only supported when using Python 2.6 or later.
504
505
506 ``format``
507 """"""""""
508
509 ``usestore``
510 Enable or disable the "store" repository format which improves
511 compatibility with systems that fold case or otherwise mangle
512 filenames. Enabled by default. Disabling this option will allow
513 you to store longer filenames in some situations at the expense of
514 compatibility and ensures that the on-disk format of newly created
515 repositories will be compatible with Mercurial before version 0.9.4.
516
517 ``usefncache``
518 Enable or disable the "fncache" repository format which enhances
519 the "store" repository format (which has to be enabled to use
520 fncache) to allow longer filenames and avoids using Windows
521 reserved names, e.g. "nul". Enabled by default. Disabling this
522 option ensures that the on-disk format of newly created
523 repositories will be compatible with Mercurial before version 1.1.
524
525 ``dotencode``
526 Enable or disable the "dotencode" repository format which enhances
527 the "fncache" repository format (which has to be enabled to use
528 dotencode) to avoid issues with filenames starting with ._ on
529 Mac OS X and spaces on Windows. Enabled by default. Disabling this
530 option ensures that the on-disk format of newly created
531 repositories will be compatible with Mercurial before version 1.7.
532
533 ``merge-patterns``
534 """"""""""""""""""
535
536 This section specifies merge tools to associate with particular file
537 patterns. Tools matched here will take precedence over the default
538 merge tool. Patterns are globs by default, rooted at the repository
539 root.
540
541 Example::
542
543 [merge-patterns]
544 **.c = kdiff3
545 **.jpg = myimgmerge
546
547 ``merge-tools``
548 """""""""""""""
549
550 This section configures external merge tools to use for file-level
551 merges.
552
553 Example ``~/.hgrc``::
554
555 [merge-tools]
556 # Override stock tool location
557 kdiff3.executable = ~/bin/kdiff3
558 # Specify command line
559 kdiff3.args = $base $local $other -o $output
560 # Give higher priority
561 kdiff3.priority = 1
562
563 # Define new tool
564 myHtmlTool.args = -m $local $other $base $output
565 myHtmlTool.regkey = Software\FooSoftware\HtmlMerge
566 myHtmlTool.priority = 1
567
568 Supported arguments:
569
570 ``priority``
571 The priority in which to evaluate this tool.
572 Default: 0.
573 ``executable``
574 Either just the name of the executable or its pathname. On Windows,
575 the path can use environment variables with ${ProgramFiles} syntax.
576 Default: the tool name.
577 ``args``
578 The arguments to pass to the tool executable. You can refer to the
579 files being merged as well as the output file through these
580 variables: ``$base``, ``$local``, ``$other``, ``$output``.
581 Default: ``$local $base $other``
582 ``premerge``
583 Attempt to run internal non-interactive 3-way merge tool before
584 launching external tool. Options are ``true``, ``false``, or ``keep``
585 to leave markers in the file if the premerge fails.
586 Default: True
587 ``binary``
588 This tool can merge binary files. Defaults to False, unless tool
589 was selected by file pattern match.
590 ``symlink``
591 This tool can merge symlinks. Defaults to False, even if tool was
592 selected by file pattern match.
593 ``check``
594 A list of merge success-checking options:
595
596 ``changed``
597 Ask whether merge was successful when the merged file shows no changes.
598 ``conflicts``
599 Check whether there are conflicts even though the tool reported success.
600 ``prompt``
601 Always prompt for merge success, regardless of success reported by tool.
602
603 ``checkchanged``
604 True is equivalent to ``check = changed``.
605 Default: False
606 ``checkconflicts``
607 True is equivalent to ``check = conflicts``.
608 Default: False
609 ``fixeol``
610 Attempt to fix up EOL changes caused by the merge tool.
611 Default: False
612 ``gui``
613 This tool requires a graphical interface to run. Default: False
614 ``regkey``
615 Windows registry key which describes install location of this
616 tool. Mercurial will search for this key first under
617 ``HKEY_CURRENT_USER`` and then under ``HKEY_LOCAL_MACHINE``.
618 Default: None
619 ``regkeyalt``
620 An alternate Windows registry key to try if the first key is not
621 found. The alternate key uses the same ``regname`` and ``regappend``
622 semantics of the primary key. The most common use for this key
623 is to search for 32bit applications on 64bit operating systems.
624 Default: None
625 ``regname``
626 Name of value to read from specified registry key. Defaults to the
627 unnamed (default) value.
628 ``regappend``
629 String to append to the value read from the registry, typically
630 the executable name of the tool.
631 Default: None
632
633
634 ``hooks``
635 """""""""
636
637 Commands or Python functions that get automatically executed by
638 various actions such as starting or finishing a commit. Multiple
639 hooks can be run for the same action by appending a suffix to the
640 action. Overriding a site-wide hook can be done by changing its
641 value or setting it to an empty string.
642
643 Example ``.hg/hgrc``::
644
645 [hooks]
646 # update working directory after adding changesets
647 changegroup.update = hg update
648 # do not use the site-wide hook
649 incoming =
650 incoming.email = /my/email/hook
651 incoming.autobuild = /my/build/hook
652
653 Most hooks are run with environment variables set that give useful
654 additional information. For each hook below, the environment
655 variables it is passed are listed with names of the form ``$HG_foo``.
656
657 ``changegroup``
658 Run after a changegroup has been added via push, pull or unbundle.
659 ID of the first new changeset is in ``$HG_NODE``. URL from which
660 changes came is in ``$HG_URL``.
661 ``commit``
662 Run after a changeset has been created in the local repository. ID
663 of the newly created changeset is in ``$HG_NODE``. Parent changeset
664 IDs are in ``$HG_PARENT1`` and ``$HG_PARENT2``.
665 ``incoming``
666 Run after a changeset has been pulled, pushed, or unbundled into
667 the local repository. The ID of the newly arrived changeset is in
668 ``$HG_NODE``. URL that was source of changes came is in ``$HG_URL``.
669 ``outgoing``
670 Run after sending changes from local repository to another. ID of
671 first changeset sent is in ``$HG_NODE``. Source of operation is in
672 ``$HG_SOURCE``; see "preoutgoing" hook for description.
673 ``post-<command>``
674 Run after successful invocations of the associated command. The
675 contents of the command line are passed as ``$HG_ARGS`` and the result
676 code in ``$HG_RESULT``. Parsed command line arguments are passed as
677 ``$HG_PATS`` and ``$HG_OPTS``. These contain string representations of
678 the python data internally passed to <command>. ``$HG_OPTS`` is a
679 dictionary of options (with unspecified options set to their defaults).
680 ``$HG_PATS`` is a list of arguments. Hook failure is ignored.
681 ``pre-<command>``
682 Run before executing the associated command. The contents of the
683 command line are passed as ``$HG_ARGS``. Parsed command line arguments
684 are passed as ``$HG_PATS`` and ``$HG_OPTS``. These contain string
685 representations of the data internally passed to <command>. ``$HG_OPTS``
686 is a dictionary of options (with unspecified options set to their
687 defaults). ``$HG_PATS`` is a list of arguments. If the hook returns
688 failure, the command doesn't execute and Mercurial returns the failure
689 code.
690 ``prechangegroup``
691 Run before a changegroup is added via push, pull or unbundle. Exit
692 status 0 allows the changegroup to proceed. Non-zero status will
693 cause the push, pull or unbundle to fail. URL from which changes
694 will come is in ``$HG_URL``.
695 ``precommit``
696 Run before starting a local commit. Exit status 0 allows the
697 commit to proceed. Non-zero status will cause the commit to fail.
698 Parent changeset IDs are in ``$HG_PARENT1`` and ``$HG_PARENT2``.
699 ``prelistkeys``
700 Run before listing pushkeys (like bookmarks) in the
701 repository. Non-zero status will cause failure. The key namespace is
702 in ``$HG_NAMESPACE``.
703 ``preoutgoing``
704 Run before collecting changes to send from the local repository to
705 another. Non-zero status will cause failure. This lets you prevent
706 pull over HTTP or SSH. Also prevents against local pull, push
707 (outbound) or bundle commands, but not effective, since you can
708 just copy files instead then. Source of operation is in
709 ``$HG_SOURCE``. If "serve", operation is happening on behalf of remote
710 SSH or HTTP repository. If "push", "pull" or "bundle", operation
711 is happening on behalf of repository on same system.
712 ``prepushkey``
713 Run before a pushkey (like a bookmark) is added to the
714 repository. Non-zero status will cause the key to be rejected. The
715 key namespace is in ``$HG_NAMESPACE``, the key is in ``$HG_KEY``,
716 the old value (if any) is in ``$HG_OLD``, and the new value is in
717 ``$HG_NEW``.
718 ``pretag``
719 Run before creating a tag. Exit status 0 allows the tag to be
720 created. Non-zero status will cause the tag to fail. ID of
721 changeset to tag is in ``$HG_NODE``. Name of tag is in ``$HG_TAG``. Tag is
722 local if ``$HG_LOCAL=1``, in repository if ``$HG_LOCAL=0``.
723 ``pretxnchangegroup``
724 Run after a changegroup has been added via push, pull or unbundle,
725 but before the transaction has been committed. Changegroup is
726 visible to hook program. This lets you validate incoming changes
727 before accepting them. Passed the ID of the first new changeset in
728 ``$HG_NODE``. Exit status 0 allows the transaction to commit. Non-zero
729 status will cause the transaction to be rolled back and the push,
730 pull or unbundle will fail. URL that was source of changes is in
731 ``$HG_URL``.
732 ``pretxncommit``
733 Run after a changeset has been created but the transaction not yet
734 committed. Changeset is visible to hook program. This lets you
735 validate commit message and changes. Exit status 0 allows the
736 commit to proceed. Non-zero status will cause the transaction to
737 be rolled back. ID of changeset is in ``$HG_NODE``. Parent changeset
738 IDs are in ``$HG_PARENT1`` and ``$HG_PARENT2``.
739 ``preupdate``
740 Run before updating the working directory. Exit status 0 allows
741 the update to proceed. Non-zero status will prevent the update.
742 Changeset ID of first new parent is in ``$HG_PARENT1``. If merge, ID
743 of second new parent is in ``$HG_PARENT2``.
744 ``listkeys``
745 Run after listing pushkeys (like bookmarks) in the repository. The
746 key namespace is in ``$HG_NAMESPACE``. ``$HG_VALUES`` is a
747 dictionary containing the keys and values.
748 ``pushkey``
749 Run after a pushkey (like a bookmark) is added to the
750 repository. The key namespace is in ``$HG_NAMESPACE``, the key is in
751 ``$HG_KEY``, the old value (if any) is in ``$HG_OLD``, and the new
752 value is in ``$HG_NEW``.
753 ``tag``
754 Run after a tag is created. ID of tagged changeset is in ``$HG_NODE``.
755 Name of tag is in ``$HG_TAG``. Tag is local if ``$HG_LOCAL=1``, in
756 repository if ``$HG_LOCAL=0``.
757 ``update``
758 Run after updating the working directory. Changeset ID of first
759 new parent is in ``$HG_PARENT1``. If merge, ID of second new parent is
760 in ``$HG_PARENT2``. If the update succeeded, ``$HG_ERROR=0``. If the
761 update failed (e.g. because conflicts not resolved), ``$HG_ERROR=1``.
762
763 .. note:: It is generally better to use standard hooks rather than the
764 generic pre- and post- command hooks as they are guaranteed to be
765 called in the appropriate contexts for influencing transactions.
766 Also, hooks like "commit" will be called in all contexts that
767 generate a commit (e.g. tag) and not just the commit command.
768
769 .. note:: Environment variables with empty values may not be passed to
770 hooks on platforms such as Windows. As an example, ``$HG_PARENT2``
771 will have an empty value under Unix-like platforms for non-merge
772 changesets, while it will not be available at all under Windows.
773
774 The syntax for Python hooks is as follows::
775
776 hookname = python:modulename.submodule.callable
777 hookname = python:/path/to/python/module.py:callable
778
779 Python hooks are run within the Mercurial process. Each hook is
780 called with at least three keyword arguments: a ui object (keyword
781 ``ui``), a repository object (keyword ``repo``), and a ``hooktype``
782 keyword that tells what kind of hook is used. Arguments listed as
783 environment variables above are passed as keyword arguments, with no
784 ``HG_`` prefix, and names in lower case.
785
786 If a Python hook returns a "true" value or raises an exception, this
787 is treated as a failure.
788
789
790 ``http_proxy``
791 """"""""""""""
792
793 Used to access web-based Mercurial repositories through a HTTP
794 proxy.
795
796 ``host``
797 Host name and (optional) port of the proxy server, for example
798 "myproxy:8000".
799 ``no``
800 Optional. Comma-separated list of host names that should bypass
801 the proxy.
802 ``passwd``
803 Optional. Password to authenticate with at the proxy server.
804 ``user``
805 Optional. User name to authenticate with at the proxy server.
806 ``always``
807 Optional. Always use the proxy, even for localhost and any entries
808 in ``http_proxy.no``. True or False. Default: False.
809
810 ``smtp``
811 """"""""
812
813 Configuration for extensions that need to send email messages.
814
815 ``host``
816 Host name of mail server, e.g. "mail.example.com".
817 ``port``
818 Optional. Port to connect to on mail server. Default: 25.
819 ``tls``
820 Optional. Method to enable TLS when connecting to mail server: starttls,
821 smtps or none. Default: none.
822 ``username``
823 Optional. User name for authenticating with the SMTP server.
824 Default: none.
825 ``password``
826 Optional. Password for authenticating with the SMTP server. If not
827 specified, interactive sessions will prompt the user for a
828 password; non-interactive sessions will fail. Default: none.
829 ``local_hostname``
830 Optional. It's the hostname that the sender can use to identify
831 itself to the MTA.
832
833
834 ``patch``
835 """""""""
836
837 Settings used when applying patches, for instance through the 'import'
838 command or with Mercurial Queues extension.
839
840 ``eol``
841 When set to 'strict' patch content and patched files end of lines
842 are preserved. When set to ``lf`` or ``crlf``, both files end of
843 lines are ignored when patching and the result line endings are
844 normalized to either LF (Unix) or CRLF (Windows). When set to
845 ``auto``, end of lines are again ignored while patching but line
846 endings in patched files are normalized to their original setting
847 on a per-file basis. If target file does not exist or has no end
848 of line, patch line endings are preserved.
849 Default: strict.
850
851
852 ``paths``
853 """""""""
854
855 Assigns symbolic names to repositories. The left side is the
856 symbolic name, and the right gives the directory or URL that is the
857 location of the repository. Default paths can be declared by setting
858 the following entries.
859
860 ``default``
861 Directory or URL to use when pulling if no source is specified.
862 Default is set to repository from which the current repository was
863 cloned.
864 ``default-push``
865 Optional. Directory or URL to use when pushing if no destination
866 is specified.
867
868
869 ``profiling``
870 """""""""""""
871
872 Specifies profiling format and file output. In this section
873 description, 'profiling data' stands for the raw data collected
874 during profiling, while 'profiling report' stands for a statistical
875 text report generated from the profiling data. The profiling is done
876 using lsprof.
877
878 ``format``
879 Profiling format.
880 Default: text.
881
882 ``text``
883 Generate a profiling report. When saving to a file, it should be
884 noted that only the report is saved, and the profiling data is
885 not kept.
886 ``kcachegrind``
887 Format profiling data for kcachegrind use: when saving to a
888 file, the generated file can directly be loaded into
889 kcachegrind.
890 ``output``
891 File path where profiling data or report should be saved. If the
892 file exists, it is replaced. Default: None, data is printed on
893 stderr
894
895 ``server``
896 """"""""""
897
898 Controls generic server settings.
899
900 ``uncompressed``
901 Whether to allow clients to clone a repository using the
902 uncompressed streaming protocol. This transfers about 40% more
903 data than a regular clone, but uses less memory and CPU on both
904 server and client. Over a LAN (100 Mbps or better) or a very fast
905 WAN, an uncompressed streaming clone is a lot faster (~10x) than a
906 regular clone. Over most WAN connections (anything slower than
907 about 6 Mbps), uncompressed streaming is slower, because of the
908 extra data transfer overhead. This mode will also temporarily hold
909 the write lock while determining what data to transfer.
910 Default is True.
911
912 ``validate``
913 Whether to validate the completeness of pushed changesets by
914 checking that all new file revisions specified in manifests are
915 present. Default is False.
916
917 ``subpaths``
918 """"""""""""
919
920 Defines subrepositories source locations rewriting rules of the form::
921
922 <pattern> = <replacement>
923
924 Where ``pattern`` is a regular expression matching the source and
925 ``replacement`` is the replacement string used to rewrite it. Groups
926 can be matched in ``pattern`` and referenced in ``replacements``. For
927 instance::
928
929 http://server/(.*)-hg/ = http://hg.server/\1/
930
931 rewrites ``http://server/foo-hg/`` into ``http://hg.server/foo/``.
932
933 All patterns are applied in definition order.
934
935 ``trusted``
936 """""""""""
937
938 Mercurial will not use the settings in the
939 ``.hg/hgrc`` file from a repository if it doesn't belong to a trusted
940 user or to a trusted group, as various hgrc features allow arbitrary
941 commands to be run. This issue is often encountered when configuring
942 hooks or extensions for shared repositories or servers. However,
943 the web interface will use some safe settings from the ``[web]``
944 section.
945
946 This section specifies what users and groups are trusted. The
947 current user is always trusted. To trust everybody, list a user or a
948 group with name ``*``. These settings must be placed in an
949 *already-trusted file* to take effect, such as ``$HOME/.hgrc`` of the
950 user or service running Mercurial.
951
952 ``users``
953 Comma-separated list of trusted users.
954 ``groups``
955 Comma-separated list of trusted groups.
956
957
958 ``ui``
959 """"""
960
961 User interface controls.
962
963 ``archivemeta``
964 Whether to include the .hg_archival.txt file containing meta data
965 (hashes for the repository base and for tip) in archives created
966 by the :hg:`archive` command or downloaded via hgweb.
967 Default is True.
968 ``askusername``
969 Whether to prompt for a username when committing. If True, and
970 neither ``$HGUSER`` nor ``$EMAIL`` has been specified, then the user will
971 be prompted to enter a username. If no username is entered, the
972 default ``USER@HOST`` is used instead.
973 Default is False.
974 ``commitsubrepos``
975 Whether to commit modified subrepositories when committing the
976 parent repository. If False and one subrepository has uncommitted
977 changes, abort the commit.
978 Default is True.
979 ``debug``
980 Print debugging information. True or False. Default is False.
981 ``editor``
982 The editor to use during a commit. Default is ``$EDITOR`` or ``vi``.
983 ``fallbackencoding``
984 Encoding to try if it's not possible to decode the changelog using
985 UTF-8. Default is ISO-8859-1.
986 ``ignore``
987 A file to read per-user ignore patterns from. This file should be
988 in the same format as a repository-wide .hgignore file. This
989 option supports hook syntax, so if you want to specify multiple
990 ignore files, you can do so by setting something like
991 ``ignore.other = ~/.hgignore2``. For details of the ignore file
992 format, see the |hgignore(5)|_ man page.
993 ``interactive``
994 Allow to prompt the user. True or False. Default is True.
995 ``logtemplate``
996 Template string for commands that print changesets.
997 ``merge``
998 The conflict resolution program to use during a manual merge.
999 For more information on merge tools see :hg:`help merge-tools`.
1000 For configuring merge tools see the merge-tools_ section.
1001 ``portablefilenames``
1002 Check for portable filenames. Can be ``warn``, ``ignore`` or ``abort``.
1003 Default is ``warn``.
1004 If set to ``warn`` (or ``true``), a warning message is printed on POSIX
1005 platforms, if a file with a non-portable filename is added (e.g. a file
1006 with a name that can't be created on Windows because it contains reserved
1007 parts like ``AUX``, reserved characters like ``:``, or would cause a case
1008 collision with an existing file).
1009 If set to ``ignore`` (or ``false``), no warning is printed.
1010 If set to ``abort``, the command is aborted.
1011 On Windows, this configuration option is ignored and the command aborted.
1012 ``quiet``
1013 Reduce the amount of output printed. True or False. Default is False.
1014 ``remotecmd``
1015 remote command to use for clone/push/pull operations. Default is ``hg``.
1016 ``report_untrusted``
1017 Warn if a ``.hg/hgrc`` file is ignored due to not being owned by a
1018 trusted user or group. True or False. Default is True.
1019 ``slash``
1020 Display paths using a slash (``/``) as the path separator. This
1021 only makes a difference on systems where the default path
1022 separator is not the slash character (e.g. Windows uses the
1023 backslash character (``\``)).
1024 Default is False.
1025 ``ssh``
1026 command to use for SSH connections. Default is ``ssh``.
1027 ``strict``
1028 Require exact command names, instead of allowing unambiguous
1029 abbreviations. True or False. Default is False.
1030 ``style``
1031 Name of style to use for command output.
1032 ``timeout``
1033 The timeout used when a lock is held (in seconds), a negative value
1034 means no timeout. Default is 600.
1035 ``traceback``
1036 Mercurial always prints a traceback when an unknown exception
1037 occurs. Setting this to True will make Mercurial print a traceback
1038 on all exceptions, even those recognized by Mercurial (such as
1039 IOError or MemoryError). Default is False.
1040 ``username``
1041 The committer of a changeset created when running "commit".
1042 Typically a person's name and email address, e.g. ``Fred Widget
1043 <fred@example.com>``. Default is ``$EMAIL`` or ``username@hostname``. If
1044 the username in hgrc is empty, it has to be specified manually or
1045 in a different hgrc file (e.g. ``$HOME/.hgrc``, if the admin set
1046 ``username =`` in the system hgrc). Environment variables in the
1047 username are expanded.
1048 ``verbose``
1049 Increase the amount of output printed. True or False. Default is False.
1050
1051
1052 ``web``
1053 """""""
1054
1055 Web interface configuration. The settings in this section apply to
1056 both the builtin webserver (started by :hg:`serve`) and the script you
1057 run through a webserver (``hgweb.cgi`` and the derivatives for FastCGI
1058 and WSGI).
1059
1060 The Mercurial webserver does no authentication (it does not prompt for
1061 usernames and passwords to validate *who* users are), but it does do
1062 authorization (it grants or denies access for *authenticated users*
1063 based on settings in this section). You must either configure your
1064 webserver to do authentication for you, or disable the authorization
1065 checks.
1066
1067 For a quick setup in a trusted environment, e.g., a private LAN, where
1068 you want it to accept pushes from anybody, you can use the following
1069 command line::
1070
1071 $ hg --config web.allow_push=* --config web.push_ssl=False serve
1072
1073 Note that this will allow anybody to push anything to the server and
1074 that this should not be used for public servers.
1075
1076 The full set of options is:
1077
1078 ``accesslog``
1079 Where to output the access log. Default is stdout.
1080 ``address``
1081 Interface address to bind to. Default is all.
1082 ``allow_archive``
1083 List of archive format (bz2, gz, zip) allowed for downloading.
1084 Default is empty.
1085 ``allowbz2``
1086 (DEPRECATED) Whether to allow .tar.bz2 downloading of repository
1087 revisions.
1088 Default is False.
1089 ``allowgz``
1090 (DEPRECATED) Whether to allow .tar.gz downloading of repository
1091 revisions.
1092 Default is False.
1093 ``allowpull``
1094 Whether to allow pulling from the repository. Default is True.
1095 ``allow_push``
1096 Whether to allow pushing to the repository. If empty or not set,
1097 push is not allowed. If the special value ``*``, any remote user can
1098 push, including unauthenticated users. Otherwise, the remote user
1099 must have been authenticated, and the authenticated user name must
1100 be present in this list. The contents of the allow_push list are
1101 examined after the deny_push list.
1102 ``allow_read``
1103 If the user has not already been denied repository access due to
1104 the contents of deny_read, this list determines whether to grant
1105 repository access to the user. If this list is not empty, and the
1106 user is unauthenticated or not present in the list, then access is
1107 denied for the user. If the list is empty or not set, then access
1108 is permitted to all users by default. Setting allow_read to the
1109 special value ``*`` is equivalent to it not being set (i.e. access
1110 is permitted to all users). The contents of the allow_read list are
1111 examined after the deny_read list.
1112 ``allowzip``
1113 (DEPRECATED) Whether to allow .zip downloading of repository
1114 revisions. Default is False. This feature creates temporary files.
1115 ``baseurl``
1116 Base URL to use when publishing URLs in other locations, so
1117 third-party tools like email notification hooks can construct
1118 URLs. Example: ``http://hgserver/repos/``.
1119 ``cacerts``
1120 Path to file containing a list of PEM encoded certificate
1121 authority certificates. Environment variables and ``~user``
1122 constructs are expanded in the filename. If specified on the
1123 client, then it will verify the identity of remote HTTPS servers
1124 with these certificates. The form must be as follows::
1125
1126 -----BEGIN CERTIFICATE-----
1127 ... (certificate in base64 PEM encoding) ...
1128 -----END CERTIFICATE-----
1129 -----BEGIN CERTIFICATE-----
1130 ... (certificate in base64 PEM encoding) ...
1131 -----END CERTIFICATE-----
1132
1133 This feature is only supported when using Python 2.6 or later. If you wish
1134 to use it with earlier versions of Python, install the backported
1135 version of the ssl library that is available from
1136 ``http://pypi.python.org``.
1137
1138 You can use OpenSSL's CA certificate file if your platform has one.
1139 On most Linux systems this will be ``/etc/ssl/certs/ca-certificates.crt``.
1140 Otherwise you will have to generate this file manually.
1141
1142 To disable SSL verification temporarily, specify ``--insecure`` from
1143 command line.
1144 ``cache``
1145 Whether to support caching in hgweb. Defaults to True.
1146 ``contact``
1147 Name or email address of the person in charge of the repository.
1148 Defaults to ui.username or ``$EMAIL`` or "unknown" if unset or empty.
1149 ``deny_push``
1150 Whether to deny pushing to the repository. If empty or not set,
1151 push is not denied. If the special value ``*``, all remote users are
1152 denied push. Otherwise, unauthenticated users are all denied, and
1153 any authenticated user name present in this list is also denied. The
1154 contents of the deny_push list are examined before the allow_push list.
1155 ``deny_read``
1156 Whether to deny reading/viewing of the repository. If this list is
1157 not empty, unauthenticated users are all denied, and any
1158 authenticated user name present in this list is also denied access to
1159 the repository. If set to the special value ``*``, all remote users
1160 are denied access (rarely needed ;). If deny_read is empty or not set,
1161 the determination of repository access depends on the presence and
1162 content of the allow_read list (see description). If both
1163 deny_read and allow_read are empty or not set, then access is
1164 permitted to all users by default. If the repository is being
1165 served via hgwebdir, denied users will not be able to see it in
1166 the list of repositories. The contents of the deny_read list have
1167 priority over (are examined before) the contents of the allow_read
1168 list.
1169 ``descend``
1170 hgwebdir indexes will not descend into subdirectories. Only repositories
1171 directly in the current path will be shown (other repositories are still
1172 available from the index corresponding to their containing path).
1173 ``description``
1174 Textual description of the repository's purpose or contents.
1175 Default is "unknown".
1176 ``encoding``
1177 Character encoding name. Default is the current locale charset.
1178 Example: "UTF-8"
1179 ``errorlog``
1180 Where to output the error log. Default is stderr.
1181 ``hidden``
1182 Whether to hide the repository in the hgwebdir index.
1183 Default is False.
1184 ``ipv6``
1185 Whether to use IPv6. Default is False.
1186 ``logourl``
1187 Base URL to use for logos. If unset, ``http://mercurial.selenic.com/``
1188 will be used.
1189 ``name``
1190 Repository name to use in the web interface. Default is current
1191 working directory.
1192 ``maxchanges``
1193 Maximum number of changes to list on the changelog. Default is 10.
1194 ``maxfiles``
1195 Maximum number of files to list per changeset. Default is 10.
1196 ``port``
1197 Port to listen on. Default is 8000.
1198 ``prefix``
1199 Prefix path to serve from. Default is '' (server root).
1200 ``push_ssl``
1201 Whether to require that inbound pushes be transported over SSL to
1202 prevent password sniffing. Default is True.
1203 ``staticurl``
1204 Base URL to use for static files. If unset, static files (e.g. the
1205 hgicon.png favicon) will be served by the CGI script itself. Use
1206 this setting to serve them directly with the HTTP server.
1207 Example: ``http://hgserver/static/``.
1208 ``stripes``
1209 How many lines a "zebra stripe" should span in multiline output.
1210 Default is 1; set to 0 to disable.
1211 ``style``
1212 Which template map style to use.
1213 ``templates``
1214 Where to find the HTML templates. Default is install path.
General Comments 0
You need to be logged in to leave comments. Login now