1HGRC(5) Mercurial Manual HGRC(5)
2
6 hgrc - configuration files for Mercurial
7
9 The Mercurial system uses a set of configuration files to control
10 aspects of its behavior.
11 The configuration files use a simple ini-file format. A configuration
13 file consists of sections, led by a [section] header and followed by
14 name = value entries:
15 [ui]
17 username = Firstname Lastname <firstname.lastname@example.net>
18 verbose = True
19 The above entries will be referred to as ui.username and ui.verbose,
21 respectively. See the Syntax section below.
22
24 Mercurial reads configuration data from several files, if they exist.
25 These files do not exist by default and you will have to create the
26 appropriate configuration files yourself: global configuration like the
27 username setting is typically put into %USERPROFILE%\mercurial.ini or
28 $HOME/.hgrc and local configuration is put into the per-repository
29 <repo>/.hg/hgrc file.
30 The names of these files depend on the system on which Mercurial is
32 installed. *.rc files from a single directory are read in alphabetical
33 order, later ones overriding earlier ones. Where multiple paths are
34 given below, settings from earlier paths override later ones.
35 (All) <repo>/.hg/hgrc
37 Per-repository configuration options that only apply in a particular
40 repository. This file is not version-controlled, and will not get
41 transferred during a "clone" operation. Options in this file over‐
42 ride options in all other configuration files. On Plan 9 and Unix,
43 most of this file will be ignored if it doesn't belong to a trusted
44 user or to a trusted group. See the documentation for the [trusted]
45 section below for more details.
46 (Plan 9) $home/lib/hgrc
48 (Unix) $HOME/.hgrc
49 (Windows) %USERPROFILE%\.hgrc
50 (Windows) %USERPROFILE%\Mercurial.ini
51 (Windows) %HOME%\.hgrc
52 (Windows) %HOME%\Mercurial.ini
53 Per-user configuration file(s), for the user running Mercurial. On
56 Windows 9x, %HOME% is replaced by %APPDATA%. Options in these files
57 apply to all Mercurial commands executed by this user in any direc‐
58 tory. Options in these files override per-system and per-installa‐
59 tion options.
60 (Plan 9) /lib/mercurial/hgrc
62 (Plan 9) /lib/mercurial/hgrc.d/*.rc
63 (Unix) /etc/mercurial/hgrc
64 (Unix) /etc/mercurial/hgrc.d/*.rc
65 Per-system configuration files, for the system on which Mercurial is
68 running. Options in these files apply to all Mercurial commands exe‐
69 cuted by any user in any directory. Options in these files override
70 per-installation options.
71 (Plan 9) <install-root>/lib/mercurial/hgrc
73 (Plan 9) <install-root>/lib/mercurial/hgrc.d/*.rc
74 (Unix) <install-root>/etc/mercurial/hgrc
75 (Unix) <install-root>/etc/mercurial/hgrc.d/*.rc
76 Per-installation configuration files, searched for in the directory
79 where Mercurial is installed. <install-root> is the parent directory
80 of the hg executable (or symlink) being run. For example, if
81 installed in /shared/tools/bin/hg, Mercurial will look in
82 /shared/tools/etc/mercurial/hgrc. Options in these files apply to
83 all Mercurial commands executed by any user in any directory.
84 (Windows) <install-dir>\Mercurial.ini or
86 (Windows) <install-dir>\hgrc.d\*.rc or
87 (Windows) HKEY_LOCAL_MACHINE\SOFTWARE\Mercurial
88 Per-installation/system configuration files, for the system on which
91 Mercurial is running. Options in these files apply to all Mercurial
92 commands executed by any user in any directory. Registry keys con‐
93 tain PATH-like strings, every part of which must reference a Mercu‐
94 rial.ini file or be a directory where *.rc files will be read. Mer‐
95 curial checks each of these locations in the specified order until
96 one or more configuration files are detected.
97 Note The registry key HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Mercu‐
99 rial is used when running 32-bit Python on 64-bit Windows.
100
102 A configuration file consists of sections, led by a [section] header
103 and followed by name = value entries (sometimes called configuration
104 keys):
105 [spam]
107 eggs=ham
108 green=
109 eggs
110 Each line contains one entry. If the lines that follow are indented,
112 they are treated as continuations of that entry. Leading whitespace is
113 removed from values. Empty lines are skipped. Lines beginning with # or
114 ; are ignored and may be used to provide comments.
115 Configuration keys can be set multiple times, in which case Mercurial
117 will use the value that was configured last. As an example:
118 [spam]
120 eggs=large
121 ham=serrano
122 eggs=small
123 This would set the configuration key named eggs to small.
125 It is also possible to define a section multiple times. A section can
127 be redefined on the same and/or on different configuration files. For
128 example:
129 [foo]
131 eggs=large
132 ham=serrano
133 eggs=small
134 [bar]
136 eggs=ham
137 green=
138 eggs
139 [foo]
141 ham=prosciutto
142 eggs=medium
143 bread=toasted
144 This would set the eggs, ham, and bread configuration keys of the foo
146 section to medium, prosciutto, and toasted, respectively. As you can
147 see there only thing that matters is the last value that was set for
148 each of the configuration keys.
149 If a configuration key is set multiple times in different configuration
151 files the final value will depend on the order in which the different
152 configuration files are read, with settings from earlier paths overrid‐
153 ing later ones as described on the Files section above.
154 A line of the form %include file will include file into the current
156 configuration file. The inclusion is recursive, which means that
157 included files can include other files. Filenames are relative to the
158 configuration file in which the %include directive is found. Environ‐
159 ment variables and ~user constructs are expanded in file. This lets you
160 do something like:
161 %include ~/.hgrc.d/$HOST.rc
163 to include a different configuration file on each computer you use.
165 A line with %unset name will remove name from the current section, if
167 it has been set previously.
168 The values are either free-form text strings, lists of text strings, or
170 Boolean values. Boolean values can be set to true using any of "1",
171 "yes", "true", or "on" and to false using "0", "no", "false", or "off"
172 (all case insensitive).
173 List values are separated by whitespace or comma, except when values
175 are placed in double quotation marks:
176 allow_read = "John Doe, PhD", brian, betty
178 Quotation marks can be escaped by prefixing them with a backslash. Only
180 quotation marks at the beginning of a word is counted as a quotation
181 (e.g., foo"bar baz is the list of foo"bar and baz).
182
184 This section describes the different sections that may appear in a Mer‐
185 curial configuration file, the purpose of each section, its possible
186 keys, and their possible values.
187 alias
189 Defines command aliases. Aliases allow you to define your own commands
190 in terms of other commands (or aliases), optionally including argu‐
191 ments. Positional arguments in the form of $1, $2, etc in the alias
192 definition are expanded by Mercurial before execution. Positional argu‐
193 ments not already used by $N in the definition are put at the end of
194 the command to be executed.
195 Alias definitions consist of lines of the form:
197 <alias> = <command> [<argument>]...
199 For example, this definition:
201 latest = log --limit 5
203 creates a new command latest that shows only the five most recent
205 changesets. You can define subsequent aliases using earlier ones:
206 stable5 = latest -b stable
208 Note It is possible to create aliases with the same names as existing
210 commands, which will then override the original definitions.
211 This is almost always a bad idea!
212 An alias can start with an exclamation point (!) to make it a shell
214 alias. A shell alias is executed with the shell and will let you run
215 arbitrary commands. As an example,
216 echo = !echo $@
218 will let you do hg echo foo to have foo printed in your terminal. A
220 better example might be:
221 purge = !$HG status --no-status --unknown -0 | xargs -0 rm
223 which will make hg purge delete all unknown files in the repository in
225 the same manner as the purge extension.
226 Positional arguments like $1, $2, etc. in the alias definition expand
228 to the command arguments. Unmatched arguments are removed. $0 expands
229 to the alias name and $@ expands to all arguments separated by a space.
230 These expansions happen before the command is passed to the shell.
231 Shell aliases are executed in an environment where $HG expands to the
233 path of the Mercurial that was used to execute the alias. This is use‐
234 ful when you want to call further Mercurial commands in a shell alias,
235 as was done above for the purge alias. In addition, $HG_ARGS expands to
236 the arguments given to Mercurial. In the hg echo foo call above,
237 $HG_ARGS would expand to echo foo.
238 Note Some global configuration options such as -R are processed
240 before shell aliases and will thus not be passed to aliases.
241 annotate
243 Settings used when displaying file annotations. All values are Booleans
244 and default to False. See diff section for related options for the diff
245 command.
246 ignorews
248 Ignore white space when comparing lines.
250 ignorewsamount
252 Ignore changes in the amount of white space.
254 ignoreblanklines
256 Ignore changes whose lines are all blank.
258 auth
260 Authentication credentials for HTTP authentication. This section allows
261 you to store usernames and passwords for use when logging into HTTP
262 servers. See the [web] configuration section if you want to configure
263 who can login to your HTTP server.
264 Each line has the following format:
266 <name>.<argument> = <value>
268 where <name> is used to group arguments into authentication entries.
270 Example:
271 foo.prefix = hg.intevation.org/mercurial
273 foo.username = foo
274 foo.password = bar
275 foo.schemes = http https
276 bar.prefix = secure.example.org
278 bar.key = path/to/file.key
279 bar.cert = path/to/file.cert
280 bar.schemes = https
281 Supported arguments:
283 prefix
285 Either * or a URI prefix with or without the scheme part. The
287 authentication entry with the longest matching prefix is used
288 (where * matches everything and counts as a match of length 1).
289 If the prefix doesn't include a scheme, the match is performed
290 against the URI with its scheme stripped as well, and the
291 schemes argument, q.v., is then subsequently consulted.
292 username
294 Optional. Username to authenticate with. If not given, and the
296 remote site requires basic or digest authentication, the user
297 will be prompted for it. Environment variables are expanded in
298 the username letting you do foo.username = $USER. If the URI
299 includes a username, only [auth] entries with a matching user‐
300 name or without a username will be considered.
301 password
303 Optional. Password to authenticate with. If not given, and the
305 remote site requires basic or digest authentication, the user
306 will be prompted for it.
307 key
309 Optional. PEM encoded client certificate key file. Environment
311 variables are expanded in the filename.
312 cert
314 Optional. PEM encoded client certificate chain file. Environment
316 variables are expanded in the filename.
317 schemes
319 Optional. Space separated list of URI schemes to use this
321 authentication entry with. Only used if the prefix doesn't
322 include a scheme. Supported schemes are http and https. They
323 will match static-http and static-https respectively, as well.
324 Default: https.
325 If no suitable authentication entry is found, the user is prompted for
327 credentials as usual if required by the remote.
328 decode/encode
330 Filters for transforming files on checkout/checkin. This would typi‐
331 cally be used for newline processing or other localization/canonical‐
332 ization of files.
333 Filters consist of a filter pattern followed by a filter command. Fil‐
335 ter patterns are globs by default, rooted at the repository root. For
336 example, to match any file ending in .txt in the root directory only,
337 use the pattern *.txt. To match any file ending in .c anywhere in the
338 repository, use the pattern **.c. For each file only the first match‐
339 ing filter applies.
340 The filter command can start with a specifier, either pipe: or temp‐
342 file:. If no specifier is given, pipe: is used by default.
343 A pipe: command must accept data on stdin and return the transformed
345 data on stdout.
346 Pipe example:
348 [encode]
350 # uncompress gzip files on checkin to improve delta compression
351 # note: not necessarily a good idea, just an example
352 *.gz = pipe: gunzip
353 [decode]
355 # recompress gzip files when writing them to the working dir (we
356 # can safely omit "pipe:", because it's the default)
357 *.gz = gzip
358 A tempfile: command is a template. The string INFILE is replaced with
360 the name of a temporary file that contains the data to be filtered by
361 the command. The string OUTFILE is replaced with the name of an empty
362 temporary file, where the filtered data must be written by the command.
363 Note The tempfile mechanism is recommended for Windows systems, where
365 the standard shell I/O redirection operators often have strange
366 effects and may corrupt the contents of your files.
367 This filter mechanism is used internally by the eol extension to trans‐
369 late line ending characters between Windows (CRLF) and Unix (LF) for‐
370 mat. We suggest you use the eol extension for convenience.
371 defaults
373 (defaults are deprecated. Don't use them. Use aliases instead)
374 Use the [defaults] section to define command defaults, i.e. the default
376 options/arguments to pass to the specified commands.
377 The following example makes hg log run in verbose mode, and hg status
379 show only the modified files, by default:
380 [defaults]
382 log = -v
383 status = -m
384 The actual commands, instead of their aliases, must be used when defin‐
386 ing command defaults. The command defaults will also be applied to the
387 aliases of the commands defined.
388 diff
390 Settings used when displaying diffs. Everything except for unified is a
391 Boolean and defaults to False. See annotate section for related options
392 for the annotate command.
393 git
395 Use git extended diff format.
397 nodates
399 Don't include dates in diff headers.
401 showfunc
403 Show which function each change is in.
405 ignorews
407 Ignore white space when comparing lines.
409 ignorewsamount
411 Ignore changes in the amount of white space.
413 ignoreblanklines
415 Ignore changes whose lines are all blank.
417 unified
419 Number of lines of context to show.
421 email
423 Settings for extensions that send email messages.
424 from
426 Optional. Email address to use in "From" header and SMTP enve‐
428 lope of outgoing messages.
429 to
431 Optional. Comma-separated list of recipients' email addresses.
433 cc
435 Optional. Comma-separated list of carbon copy recipients' email
437 addresses.
438 bcc
440 Optional. Comma-separated list of blind carbon copy recipients'
442 email addresses.
443 method
445 Optional. Method to use to send email messages. If value is smtp
447 (default), use SMTP (see the [smtp] section for configuration).
448 Otherwise, use as name of program to run that acts like sendmail
449 (takes -f option for sender, list of recipients on command line,
450 message on stdin). Normally, setting this to sendmail or
451 /usr/sbin/sendmail is enough to use sendmail to send messages.
452 charsets
454 Optional. Comma-separated list of character sets considered con‐
456 venient for recipients. Addresses, headers, and parts not con‐
457 taining patches of outgoing messages will be encoded in the
458 first character set to which conversion from local encoding
459 ($HGENCODING, ui.fallbackencoding) succeeds. If correct conver‐
460 sion fails, the text in question is sent as is. Defaults to
461 empty (explicit) list.
462 Order of outgoing email character sets:
464 1. us-ascii: always first, regardless of settings
466 2. email.charsets: in order given by user
468 3. ui.fallbackencoding: if not in email.charsets
470 4. $HGENCODING: if not in email.charsets
472 5. utf-8: always last, regardless of settings
474 Email example:
476 [email]
478 from = Joseph User <joe.user@example.com>
479 method = /usr/sbin/sendmail
480 # charsets for western Europeans
481 # us-ascii, utf-8 omitted, as they are tried first and last
482 charsets = iso-8859-1, iso-8859-15, windows-1252
483 extensions
485 Mercurial has an extension mechanism for adding new features. To enable
486 an extension, create an entry for it in this section.
487 If you know that the extension is already in Python's search path, you
489 can give the name of the module, followed by =, with nothing after the
490 =.
491 Otherwise, give a name that you choose, followed by =, followed by the
493 path to the .py file (including the file name extension) that defines
494 the extension.
495 To explicitly disable an extension that is enabled in an hgrc of
497 broader scope, prepend its path with !, as in foo = !/ext/path or foo =
498 ! when path is not supplied.
499 Example for ~/.hgrc:
501 [extensions]
503 # (the mq extension will get loaded from Mercurial's path)
504 mq =
505 # (this extension will get loaded from the file specified)
506 myfeature = ~/.hgext/myfeature.py
507 format
509 usestore
510 Enable or disable the "store" repository format which improves
512 compatibility with systems that fold case or otherwise mangle
513 filenames. Enabled by default. Disabling this option will allow
514 you to store longer filenames in some situations at the expense
515 of compatibility and ensures that the on-disk format of newly
516 created repositories will be compatible with Mercurial before
517 version 0.9.4.
518 usefncache
520 Enable or disable the "fncache" repository format which enhances
522 the "store" repository format (which has to be enabled to use
523 fncache) to allow longer filenames and avoids using Windows
524 reserved names, e.g. "nul". Enabled by default. Disabling this
525 option ensures that the on-disk format of newly created reposi‐
526 tories will be compatible with Mercurial before version 1.1.
527 dotencode
529 Enable or disable the "dotencode" repository format which
531 enhances the "fncache" repository format (which has to be
532 enabled to use dotencode) to avoid issues with filenames start‐
533 ing with ._ on Mac OS X and spaces on Windows. Enabled by
534 default. Disabling this option ensures that the on-disk format
535 of newly created repositories will be compatible with Mercurial
536 before version 1.7.
537 graph
539 Web graph view configuration. This section let you change graph ele‐
540 ments display properties by branches, for instance to make the default
541 branch stand out.
542 Each line has the following format:
544 <branch>.<argument> = <value>
546 where <branch> is the name of the branch being customized. Example:
548 [graph]
550 # 2px width
551 default.width = 2
552 # red color
553 default.color = FF0000
554 Supported arguments:
556 width
558 Set branch edges width in pixels.
560 color
562 Set branch edges color in hexadecimal RGB notation.
564 hooks
566 Commands or Python functions that get automatically executed by various
567 actions such as starting or finishing a commit. Multiple hooks can be
568 run for the same action by appending a suffix to the action. Overriding
569 a site-wide hook can be done by changing its value or setting it to an
570 empty string. Hooks can be prioritized by adding a prefix of priority
571 to the hook name on a new line and setting the priority. The default
572 priority is 0 if not specified.
573 Example .hg/hgrc:
575 [hooks]
577 # update working directory after adding changesets
578 changegroup.update = hg update
579 # do not use the site-wide hook
580 incoming =
581 incoming.email = /my/email/hook
582 incoming.autobuild = /my/build/hook
583 # force autobuild hook to run before other incoming hooks
584 priority.incoming.autobuild = 1
585 Most hooks are run with environment variables set that give useful
587 additional information. For each hook below, the environment variables
588 it is passed are listed with names of the form $HG_foo.
589 changegroup
591 Run after a changegroup has been added via push, pull or unbun‐
593 dle. ID of the first new changeset is in $HG_NODE. URL from
594 which changes came is in $HG_URL.
595 commit
597 Run after a changeset has been created in the local repository.
599 ID of the newly created changeset is in $HG_NODE. Parent change‐
600 set IDs are in $HG_PARENT1 and $HG_PARENT2.
601 incoming
603 Run after a changeset has been pulled, pushed, or unbundled into
605 the local repository. The ID of the newly arrived changeset is
606 in $HG_NODE. URL that was source of changes came is in $HG_URL.
607 outgoing
609 Run after sending changes from local repository to another. ID
611 of first changeset sent is in $HG_NODE. Source of operation is
612 in $HG_SOURCE; see "preoutgoing" hook for description.
613 post-<command>
615 Run after successful invocations of the associated command. The
617 contents of the command line are passed as $HG_ARGS and the
618 result code in $HG_RESULT. Parsed command line arguments are
619 passed as $HG_PATS and $HG_OPTS. These contain string represen‐
620 tations of the python data internally passed to <command>.
621 $HG_OPTS is a dictionary of options (with unspecified options
622 set to their defaults). $HG_PATS is a list of arguments. Hook
623 failure is ignored.
624 pre-<command>
626 Run before executing the associated command. The contents of the
628 command line are passed as $HG_ARGS. Parsed command line argu‐
629 ments are passed as $HG_PATS and $HG_OPTS. These contain string
630 representations of the data internally passed to <command>.
631 $HG_OPTS is a dictionary of options (with unspecified options
632 set to their defaults). $HG_PATS is a list of arguments. If the
633 hook returns failure, the command doesn't execute and Mercurial
634 returns the failure code.
635 prechangegroup
637 Run before a changegroup is added via push, pull or unbundle.
639 Exit status 0 allows the changegroup to proceed. Non-zero status
640 will cause the push, pull or unbundle to fail. URL from which
641 changes will come is in $HG_URL.
642 precommit
644 Run before starting a local commit. Exit status 0 allows the
646 commit to proceed. Non-zero status will cause the commit to
647 fail. Parent changeset IDs are in $HG_PARENT1 and $HG_PARENT2.
648 prelistkeys
650 Run before listing pushkeys (like bookmarks) in the repository.
652 Non-zero status will cause failure. The key namespace is in
653 $HG_NAMESPACE.
654 preoutgoing
656 Run before collecting changes to send from the local repository
658 to another. Non-zero status will cause failure. This lets you
659 prevent pull over HTTP or SSH. Also prevents against local pull,
660 push (outbound) or bundle commands, but not effective, since you
661 can just copy files instead then. Source of operation is in
662 $HG_SOURCE. If "serve", operation is happening on behalf of
663 remote SSH or HTTP repository. If "push", "pull" or "bundle",
664 operation is happening on behalf of repository on same system.
665 prepushkey
667 Run before a pushkey (like a bookmark) is added to the reposi‐
669 tory. Non-zero status will cause the key to be rejected. The key
670 namespace is in $HG_NAMESPACE, the key is in $HG_KEY, the old
671 value (if any) is in $HG_OLD, and the new value is in $HG_NEW.
672 pretag
674 Run before creating a tag. Exit status 0 allows the tag to be
676 created. Non-zero status will cause the tag to fail. ID of
677 changeset to tag is in $HG_NODE. Name of tag is in $HG_TAG. Tag
678 is local if $HG_LOCAL=1, in repository if $HG_LOCAL=0.
679 pretxnchangegroup
681 Run after a changegroup has been added via push, pull or unbun‐
683 dle, but before the transaction has been committed. Changegroup
684 is visible to hook program. This lets you validate incoming
685 changes before accepting them. Passed the ID of the first new
686 changeset in $HG_NODE. Exit status 0 allows the transaction to
687 commit. Non-zero status will cause the transaction to be rolled
688 back and the push, pull or unbundle will fail. URL that was
689 source of changes is in $HG_URL.
690 pretxncommit
692 Run after a changeset has been created but the transaction not
694 yet committed. Changeset is visible to hook program. This lets
695 you validate commit message and changes. Exit status 0 allows
696 the commit to proceed. Non-zero status will cause the transac‐
697 tion to be rolled back. ID of changeset is in $HG_NODE. Parent
698 changeset IDs are in $HG_PARENT1 and $HG_PARENT2.
699 preupdate
701 Run before updating the working directory. Exit status 0 allows
703 the update to proceed. Non-zero status will prevent the update.
704 Changeset ID of first new parent is in $HG_PARENT1. If merge, ID
705 of second new parent is in $HG_PARENT2.
706 listkeys
708 Run after listing pushkeys (like bookmarks) in the repository.
710 The key namespace is in $HG_NAMESPACE. $HG_VALUES is a dictio‐
711 nary containing the keys and values.
712 pushkey
714 Run after a pushkey (like a bookmark) is added to the reposi‐
716 tory. 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 value
718 is in $HG_NEW.
719 tag
721 Run after a tag is created. ID of tagged changeset is in
723 $HG_NODE. Name of tag is in $HG_TAG. Tag is local if
724 $HG_LOCAL=1, in repository if $HG_LOCAL=0.
725 update
727 Run after updating the working directory. Changeset ID of first
729 new parent is in $HG_PARENT1. If merge, ID of second new parent
730 is in $HG_PARENT2. If the update succeeded, $HG_ERROR=0. If the
731 update failed (e.g. because conflicts not resolved),
732 $HG_ERROR=1.
733 Note It is generally better to use standard hooks rather than the
735 generic pre- and post- command hooks as they are guaranteed to
736 be called in the appropriate contexts for influencing transac‐
737 tions. Also, hooks like "commit" will be called in all contexts
738 that generate a commit (e.g. tag) and not just the commit com‐
739 mand.
740 Note Environment variables with empty values may not be passed to
742 hooks on platforms such as Windows. As an example, $HG_PARENT2
743 will have an empty value under Unix-like platforms for non-merge
744 changesets, while it will not be available at all under Windows.
745 The syntax for Python hooks is as follows:
747 hookname = python:modulename.submodule.callable
749 hookname = python:/path/to/python/module.py:callable
750 Python hooks are run within the Mercurial process. Each hook is called
752 with at least three keyword arguments: a ui object (keyword ui), a
753 repository object (keyword repo), and a hooktype keyword that tells
754 what kind of hook is used. Arguments listed as environment variables
755 above are passed as keyword arguments, with no HG_ prefix, and names in
756 lower case.
757 If a Python hook returns a "true" value or raises an exception, this is
759 treated as a failure.
760 hostfingerprints
762 Fingerprints of the certificates of known HTTPS servers. A HTTPS con‐
763 nection to a server with a fingerprint configured here will only suc‐
764 ceed if the servers certificate matches the fingerprint. This is very
765 similar to how ssh known hosts works. The fingerprint is the SHA-1
766 hash value of the DER encoded certificate. The CA chain and web.cac‐
767 erts is not used for servers with a fingerprint.
768 For example:
770 [hostfingerprints]
772 hg.intevation.org = 44:ed:af:1f:97:11:b6:01:7a:48:45:fc:10:3c:b7:f9:d4:89:2a:9d
773 This feature is only supported when using Python 2.6 or later.
775 http_proxy
777 Used to access web-based Mercurial repositories through a HTTP proxy.
778 host
780 Host name and (optional) port of the proxy server, for example
782 "myproxy:8000".
783 no
785 Optional. Comma-separated list of host names that should bypass
787 the proxy.
788 passwd
790 Optional. Password to authenticate with at the proxy server.
792 user
794 Optional. User name to authenticate with at the proxy server.
796 always
798 Optional. Always use the proxy, even for localhost and any
800 entries in http_proxy.no. True or False. Default: False.
801 merge-patterns
803 This section specifies merge tools to associate with particular file
804 patterns. Tools matched here will take precedence over the default
805 merge tool. Patterns are globs by default, rooted at the repository
806 root.
807 Example:
809 [merge-patterns]
811 **.c = kdiff3
812 **.jpg = myimgmerge
813 merge-tools
815 This section configures external merge tools to use for file-level
816 merges.
817 Example ~/.hgrc:
819 [merge-tools]
821 # Override stock tool location
822 kdiff3.executable = ~/bin/kdiff3
823 # Specify command line
824 kdiff3.args = $base $local $other -o $output
825 # Give higher priority
826 kdiff3.priority = 1
827 # Define new tool
829 myHtmlTool.args = -m $local $other $base $output
830 myHtmlTool.regkey = Software\FooSoftware\HtmlMerge
831 myHtmlTool.priority = 1
832 Supported arguments:
834 priority
836 The priority in which to evaluate this tool. Default: 0.
838 executable
840 Either just the name of the executable or its pathname. On Win‐
842 dows, the path can use environment variables with ${Program‐
843 Files} syntax. Default: the tool name.
844 args
846 The arguments to pass to the tool executable. You can refer to
848 the files being merged as well as the output file through these
849 variables: $base, $local, $other, $output. Default: $local
850 $base $other
851 premerge
853 Attempt to run internal non-interactive 3-way merge tool before
855 launching external tool. Options are true, false, or keep to
856 leave markers in the file if the premerge fails. Default: True
857 binary
859 This tool can merge binary files. Defaults to False, unless tool
861 was selected by file pattern match.
862 symlink
864 This tool can merge symlinks. Defaults to False, even if tool
866 was selected by file pattern match.
867 check
869 A list of merge success-checking options:
871 changed
873 Ask whether merge was successful when the merged file
875 shows no changes.
876 conflicts
878 Check whether there are conflicts even though the tool
880 reported success.
881 prompt
883 Always prompt for merge success, regardless of success
885 reported by tool.
886 fixeol
888 Attempt to fix up EOL changes caused by the merge tool.
890 Default: False
891 gui
893 This tool requires a graphical interface to run. Default: False
895 regkey
897 Windows registry key which describes install location of this
899 tool. Mercurial will search for this key first under HKEY_CUR‐
900 RENT_USER and then under HKEY_LOCAL_MACHINE. Default: None
901 regkeyalt
903 An alternate Windows registry key to try if the first key is not
905 found. The alternate key uses the same regname and regappend
906 semantics of the primary key. The most common use for this key
907 is to search for 32bit applications on 64bit operating systems.
908 Default: None
909 regname
911 Name of value to read from specified registry key. Defaults to
913 the unnamed (default) value.
914 regappend
916 String to append to the value read from the registry, typically
918 the executable name of the tool. Default: None
919 patch
921 Settings used when applying patches, for instance through the 'import'
922 command or with Mercurial Queues extension.
923 eol
925 When set to 'strict' patch content and patched files end of
927 lines are preserved. When set to lf or crlf, both files end of
928 lines are ignored when patching and the result line endings are
929 normalized to either LF (Unix) or CRLF (Windows). When set to
930 auto, end of lines are again ignored while patching but line
931 endings in patched files are normalized to their original set‐
932 ting on a per-file basis. If target file does not exist or has
933 no end of line, patch line endings are preserved. Default:
934 strict.
935 paths
937 Assigns symbolic names to repositories. The left side is the symbolic
938 name, and the right gives the directory or URL that is the location of
939 the repository. Default paths can be declared by setting the following
940 entries.
941 default
943 Directory or URL to use when pulling if no source is specified.
945 Default is set to repository from which the current repository
946 was cloned.
947 default-push
949 Optional. Directory or URL to use when pushing if no destination
951 is specified.
952 Custom paths can be defined by assigning the path to a name that later
954 can be used from the command line. Example:
955 [paths]
957 my_path = http://example.com/path
958 To push to the path defined in my_path run the command:
960 hg push my_path
962 phases
964 Specifies default handling of phases. See hg help phases for more
965 information about working with phases.
966 publish
968 Controls draft phase behavior when working as a server. When
970 true, pushed changesets are set to public in both client and
971 server and pulled or cloned changesets are set to public in the
972 client. Default: True
973 new-commit
975 Phase of newly-created commits. Default: draft
977 profiling
979 Specifies profiling type, format, and file output. Two profilers are
980 supported: an instrumenting profiler (named ls), and a sampling pro‐
981 filer (named stat).
982 In this section description, 'profiling data' stands for the raw data
984 collected during profiling, while 'profiling report' stands for a sta‐
985 tistical text report generated from the profiling data. The profiling
986 is done using lsprof.
987 type
989 The type of profiler to use. Default: ls.
991 ls
993 Use Python's built-in instrumenting profiler. This pro‐
995 filer works on all platforms, but each line number it
996 reports is the first line of a function. This restriction
997 makes it difficult to identify the expensive parts of a
998 non-trivial function.
999 stat
1001 Use a third-party statistical profiler, statprof. This
1003 profiler currently runs only on Unix systems, and is most
1004 useful for profiling commands that run for longer than
1005 about 0.1 seconds.
1006 format
1008 Profiling format. Specific to the ls instrumenting profiler.
1010 Default: text.
1011 text
1013 Generate a profiling report. When saving to a file, it
1015 should be noted that only the report is saved, and the
1016 profiling data is not kept.
1017 kcachegrind
1019 Format profiling data for kcachegrind use: when saving to
1021 a file, the generated file can directly be loaded into
1022 kcachegrind.
1023 frequency
1025 Sampling frequency. Specific to the stat sampling profiler.
1027 Default: 1000.
1028 output
1030 File path where profiling data or report should be saved. If the
1032 file exists, it is replaced. Default: None, data is printed on
1033 stderr
1034 sort
1036 Sort field. Specific to the ls instrumenting profiler. One of
1038 callcount, reccallcount, totaltime and inlinetime. Default:
1039 inlinetime.
1040 limit
1042 Number of lines to show. Specific to the ls instrumenting pro‐
1044 filer. Default: 30.
1045 nested
1047 Show at most this number of lines of drill-down info after each
1049 main entry. This can help explain the difference between Total
1050 and Inline. Specific to the ls instrumenting profiler.
1051 Default: 5.
1052 revsetalias
1054 Alias definitions for revsets. See hg help revsets for details.
1055 server
1057 Controls generic server settings.
1058 uncompressed
1060 Whether to allow clients to clone a repository using the uncom‐
1062 pressed streaming protocol. This transfers about 40% more data
1063 than a regular clone, but uses less memory and CPU on both
1064 server and client. Over a LAN (100 Mbps or better) or a very
1065 fast WAN, an uncompressed streaming clone is a lot faster (~10x)
1066 than a regular clone. Over most WAN connections (anything slower
1067 than about 6 Mbps), uncompressed streaming is slower, because of
1068 the extra data transfer overhead. This mode will also temporar‐
1069 ily hold the write lock while determining what data to transfer.
1070 Default is True.
1071 preferuncompressed
1073 When set, clients will try to use the uncompressed streaming
1075 protocol. Default is False.
1076 validate
1078 Whether to validate the completeness of pushed changesets by
1080 checking that all new file revisions specified in manifests are
1081 present. Default is False.
1082 smtp
1084 Configuration for extensions that need to send email messages.
1085 host
1087 Host name of mail server, e.g. "mail.example.com".
1089 port
1091 Optional. Port to connect to on mail server. Default: 465 (if
1093 tls is smtps) or 25 (otherwise).
1094 tls
1096 Optional. Method to enable TLS when connecting to mail server:
1098 starttls, smtps or none. Default: none.
1099 verifycert
1101 Optional. Verification for the certificate of mail server, when
1103 tls is starttls or smtps. "strict", "loose" or False. For
1104 "strict" or "loose", the certificate is verified as same as the
1105 verification for HTTPS connections (see [hostfingerprints] and
1106 [web] cacerts also). For "strict", sending email is also
1107 aborted, if there is no configuration for mail server in
1108 [hostfingerprints] and [web] cacerts. --insecure for hg email
1109 overwrites this as "loose". Default: "strict".
1110 username
1112 Optional. User name for authenticating with the SMTP server.
1114 Default: none.
1115 password
1117 Optional. Password for authenticating with the SMTP server. If
1119 not specified, interactive sessions will prompt the user for a
1120 password; non-interactive sessions will fail. Default: none.
1121 local_hostname
1123 Optional. It's the hostname that the sender can use to identify
1125 itself to the MTA.
1126 subpaths
1128 Subrepository source URLs can go stale if a remote server changes name
1129 or becomes temporarily unavailable. This section lets you define re‐
1130 write rules of the form:
1131 <pattern> = <replacement>
1133 where pattern is a regular expression matching a subrepository source
1135 URL and replacement is the replacement string used to rewrite it.
1136 Groups can be matched in pattern and referenced in replacements. For
1137 instance:
1138 http://server/(.*)-hg/ = http://hg.server/\1/
1140 rewrites http://server/foo-hg/ into http://hg.server/foo/.
1142 Relative subrepository paths are first made absolute, and the rewrite
1144 rules are then applied on the full (absolute) path. The rules are
1145 applied in definition order.
1146 trusted
1148 Mercurial will not use the settings in the .hg/hgrc file from a reposi‐
1149 tory if it doesn't belong to a trusted user or to a trusted group, as
1150 various hgrc features allow arbitrary commands to be run. This issue is
1151 often encountered when configuring hooks or extensions for shared
1152 repositories or servers. However, the web interface will use some safe
1153 settings from the [web] section.
1154 This section specifies what users and groups are trusted. The current
1156 user is always trusted. To trust everybody, list a user or a group with
1157 name *. These settings must be placed in an already-trusted file to
1158 take effect, such as $HOME/.hgrc of the user or service running Mercu‐
1159 rial.
1160 users
1162 Comma-separated list of trusted users.
1164 groups
1166 Comma-separated list of trusted groups.
1168 ui
1170 User interface controls.
1171 archivemeta
1173 Whether to include the .hg_archival.txt file containing meta
1175 data (hashes for the repository base and for tip) in archives
1176 created by the hg archive command or downloaded via hgweb.
1177 Default is True.
1178 askusername
1180 Whether to prompt for a username when committing. If True, and
1182 neither $HGUSER nor $EMAIL has been specified, then the user
1183 will be prompted to enter a username. If no username is entered,
1184 the default USER@HOST is used instead. Default is False.
1185 commitsubrepos
1187 Whether to commit modified subrepositories when committing the
1189 parent repository. If False and one subrepository has uncommit‐
1190 ted changes, abort the commit. Default is False.
1191 debug
1193 Print debugging information. True or False. Default is False.
1195 editor
1197 The editor to use during a commit. Default is $EDITOR or vi.
1199 fallbackencoding
1201 Encoding to try if it's not possible to decode the changelog
1203 using UTF-8. Default is ISO-8859-1.
1204 ignore
1206 A file to read per-user ignore patterns from. This file should
1208 be in the same format as a repository-wide .hgignore file. This
1209 option supports hook syntax, so if you want to specify multiple
1210 ignore files, you can do so by setting something like
1211 ignore.other = ~/.hgignore2. For details of the ignore file for‐
1212 mat, see the hgignore(5) man page.
1213 interactive
1215 Allow to prompt the user. True or False. Default is True.
1217 logtemplate
1219 Template string for commands that print changesets.
1221 merge
1223 The conflict resolution program to use during a manual merge.
1225 For more information on merge tools see hg help merge-tools.
1226 For configuring merge tools see the [merge-tools] section.
1227 portablefilenames
1229 Check for portable filenames. Can be warn, ignore or abort.
1231 Default is warn. If set to warn (or true), a warning message is
1232 printed on POSIX platforms, if a file with a non-portable file‐
1233 name is added (e.g. a file with a name that can't be created on
1234 Windows because it contains reserved parts like AUX, reserved
1235 characters like :, or would cause a case collision with an
1236 existing file). If set to ignore (or false), no warning is
1237 printed. If set to abort, the command is aborted. On Windows,
1238 this configuration option is ignored and the command aborted.
1239 quiet
1241 Reduce the amount of output printed. True or False. Default is
1243 False.
1244 remotecmd
1246 remote command to use for clone/push/pull operations. Default is
1248 hg.
1249 reportoldssl
1251 Warn if an SSL certificate is unable to be due to using Python
1253 2.5 or earlier. True or False. Default is True.
1254 report_untrusted
1256 Warn if a .hg/hgrc file is ignored due to not being owned by a
1258 trusted user or group. True or False. Default is True.
1259 slash
1261 Display paths using a slash (/) as the path separator. This only
1263 makes a difference on systems where the default path separator
1264 is not the slash character (e.g. Windows uses the backslash
1265 character (\)). Default is False.
1266 ssh
1268 command to use for SSH connections. Default is ssh.
1270 strict
1272 Require exact command names, instead of allowing unambiguous
1274 abbreviations. True or False. Default is False.
1275 style
1277 Name of style to use for command output.
1279 timeout
1281 The timeout used when a lock is held (in seconds), a negative
1283 value means no timeout. Default is 600.
1284 traceback
1286 Mercurial always prints a traceback when an unknown exception
1288 occurs. Setting this to True will make Mercurial print a trace‐
1289 back on all exceptions, even those recognized by Mercurial (such
1290 as IOError or MemoryError). Default is False.
1291 username
1293 The committer of a changeset created when running "commit".
1295 Typically a person's name and email address, e.g. Fred Widget
1296 <fred@example.com>. Default is $EMAIL or username@hostname. If
1297 the username in hgrc is empty, it has to be specified manually
1298 or in a different hgrc file (e.g. $HOME/.hgrc, if the admin set
1299 username = in the system hgrc). Environment variables in the
1300 username are expanded.
1301 verbose
1303 Increase the amount of output printed. True or False. Default is
1305 False.
1306 web
1308 Web interface configuration. The settings in this section apply to both
1309 the builtin webserver (started by hg serve) and the script you run
1310 through a webserver (hgweb.cgi and the derivatives for FastCGI and
1311 WSGI).
1312 The Mercurial webserver does no authentication (it does not prompt for
1314 usernames and passwords to validate who users are), but it does do
1315 authorization (it grants or denies access for authenticated users based
1316 on settings in this section). You must either configure your webserver
1317 to do authentication for you, or disable the authorization checks.
1318 For a quick setup in a trusted environment, e.g., a private LAN, where
1320 you want it to accept pushes from anybody, you can use the following
1321 command line:
1322 $ hg --config web.allow_push=* --config web.push_ssl=False serve
1324 Note that this will allow anybody to push anything to the server and
1326 that this should not be used for public servers.
1327 The full set of options is:
1329 accesslog
1331 Where to output the access log. Default is stdout.
1333 address
1335 Interface address to bind to. Default is all.
1337 allow_archive
1339 List of archive format (bz2, gz, zip) allowed for downloading.
1341 Default is empty.
1342 allowbz2
1344 (DEPRECATED) Whether to allow .tar.bz2 downloading of repository
1346 revisions. Default is False.
1347 allowgz
1349 (DEPRECATED) Whether to allow .tar.gz downloading of repository
1351 revisions. Default is False.
1352 allowpull
1354 Whether to allow pulling from the repository. Default is True.
1356 allow_push
1358 Whether to allow pushing to the repository. If empty or not set,
1360 push is not allowed. If the special value *, any remote user can
1361 push, including unauthenticated users. Otherwise, the remote
1362 user must have been authenticated, and the authenticated user
1363 name must be present in this list. The contents of the
1364 allow_push list are examined after the deny_push list.
1365 allow_read
1367 If the user has not already been denied repository access due to
1369 the contents of deny_read, this list determines whether to grant
1370 repository access to the user. If this list is not empty, and
1371 the user is unauthenticated or not present in the list, then
1372 access is denied for the user. If the list is empty or not set,
1373 then access is permitted to all users by default. Setting
1374 allow_read to the special value * is equivalent to it not being
1375 set (i.e. access is permitted to all users). The contents of the
1376 allow_read list are examined after the deny_read list.
1377 allowzip
1379 (DEPRECATED) Whether to allow .zip downloading of repository
1381 revisions. Default is False. This feature creates temporary
1382 files.
1383 archivesubrepos
1385 Whether to recurse into subrepositories when archiving. Default
1387 is False.
1388 baseurl
1390 Base URL to use when publishing URLs in other locations, so
1392 third-party tools like email notification hooks can construct
1393 URLs. Example: http://hgserver/repos/.
1394 cacerts
1396 Path to file containing a list of PEM encoded certificate
1398 authority certificates. Environment variables and ~user con‐
1399 structs are expanded in the filename. If specified on the
1400 client, then it will verify the identity of remote HTTPS servers
1401 with these certificates.
1402 This feature is only supported when using Python 2.6 or later.
1404 If you wish to use it with earlier versions of Python, install
1405 the backported version of the ssl library that is available from
1406 http://pypi.python.org.
1407 To disable SSL verification temporarily, specify --insecure from
1409 command line.
1410 You can use OpenSSL's CA certificate file if your platform has
1412 one. On most Linux systems this will be /etc/ssl/certs/ca-cer‐
1413 tificates.crt. Otherwise you will have to generate this file
1414 manually. The form must be as follows:
1415 -----BEGIN CERTIFICATE-----
1417 ... (certificate in base64 PEM encoding) ...
1418 -----END CERTIFICATE-----
1419 -----BEGIN CERTIFICATE-----
1420 ... (certificate in base64 PEM encoding) ...
1421 -----END CERTIFICATE-----
1422 cache
1424 Whether to support caching in hgweb. Defaults to True.
1426 collapse
1428 With descend enabled, repositories in subdirectories are shown
1430 at a single level alongside repositories in the current path.
1431 With collapse also enabled, repositories residing at a deeper
1432 level than the current path are grouped behind navigable direc‐
1433 tory entries that lead to the locations of these repositories.
1434 In effect, this setting collapses each collection of reposito‐
1435 ries found within a subdirectory into a single entry for that
1436 subdirectory. Default is False.
1437 comparisoncontext
1439 Number of lines of context to show in side-by-side file compari‐
1441 son. If negative or the value full, whole files are shown.
1442 Default is 5. This setting can be overridden by a context
1443 request parameter to the comparison command, taking the same
1444 values.
1445 contact
1447 Name or email address of the person in charge of the repository.
1449 Defaults to ui.username or $EMAIL or "unknown" if unset or
1450 empty.
1451 deny_push
1453 Whether to deny pushing to the repository. If empty or not set,
1455 push is not denied. If the special value *, all remote users are
1456 denied push. Otherwise, unauthenticated users are all denied,
1457 and any authenticated user name present in this list is also
1458 denied. The contents of the deny_push list are examined before
1459 the allow_push list.
1460 deny_read
1462 Whether to deny reading/viewing of the repository. If this list
1464 is not empty, unauthenticated users are all denied, and any
1465 authenticated user name present in this list is also denied
1466 access to the repository. If set to the special value *, all
1467 remote users are denied access (rarely needed ;). If deny_read
1468 is empty or not set, the determination of repository access
1469 depends on the presence and content of the allow_read list (see
1470 description). If both deny_read and allow_read are empty or not
1471 set, then access is permitted to all users by default. If the
1472 repository is being served via hgwebdir, denied users will not
1473 be able to see it in the list of repositories. The contents of
1474 the deny_read list have priority over (are examined before) the
1475 contents of the allow_read list.
1476 descend
1478 hgwebdir indexes will not descend into subdirectories. Only
1480 repositories directly in the current path will be shown (other
1481 repositories are still available from the index corresponding to
1482 their containing path).
1483 description
1485 Textual description of the repository's purpose or contents.
1487 Default is "unknown".
1488 encoding
1490 Character encoding name. Default is the current locale charset.
1492 Example: "UTF-8"
1493 errorlog
1495 Where to output the error log. Default is stderr.
1497 guessmime
1499 Control MIME types for raw download of file content. Set to
1501 True to let hgweb guess the content type from the file exten‐
1502 sion. This will serve HTML files as text/html and might allow
1503 cross-site scripting attacks when serving untrusted reposito‐
1504 ries. Default is False.
1505 hidden
1507 Whether to hide the repository in the hgwebdir index. Default
1509 is False.
1510 ipv6
1512 Whether to use IPv6. Default is False.
1514 logoimg
1516 File name of the logo image that some templates display on each
1518 page. The file name is relative to staticurl. That is, the full
1519 path to the logo image is "staticurl/logoimg". If unset, hgl‐
1520 ogo.png will be used.
1521 logourl
1523 Base URL to use for logos. If unset, http://mercu‐
1525 rial.selenic.com/ will be used.
1526 maxchanges
1528 Maximum number of changes to list on the changelog. Default is
1530 10.
1531 maxfiles
1533 Maximum number of files to list per changeset. Default is 10.
1535 maxshortchanges
1537 Maximum number of changes to list on the shortlog, graph or
1539 filelog pages. Default is 60.
1540 name
1542 Repository name to use in the web interface. Default is current
1544 working directory.
1545 port
1547 Port to listen on. Default is 8000.
1549 prefix
1551 Prefix path to serve from. Default is '' (server root).
1553 push_ssl
1555 Whether to require that inbound pushes be transported over SSL
1557 to prevent password sniffing. Default is True.
1558 staticurl
1560 Base URL to use for static files. If unset, static files (e.g.
1562 the hgicon.png favicon) will be served by the CGI script itself.
1563 Use this setting to serve them directly with the HTTP server.
1564 Example: http://hgserver/static/.
1565 stripes
1567 How many lines a "zebra stripe" should span in multi-line out‐
1569 put. Default is 1; set to 0 to disable.
1570 style
1572 Which template map style to use.
1574 templates
1576 Where to find the HTML templates. Default is install path.
1578 websub
1580 Web substitution filter definition. You can use this section to define
1581 a set of regular expression substitution patterns which let you auto‐
1582 matically modify the hgweb server output.
1583 The default hgweb templates only apply these substitution patterns on
1585 the revision description fields. You can apply them anywhere you want
1586 when you create your own templates by adding calls to the "websub" fil‐
1587 ter (usually after calling the "escape" filter).
1588 This can be used, for example, to convert issue references to links to
1590 your issue tracker, or to convert "markdown-like" syntax into HTML (see
1591 the examples below).
1592 Each entry in this section names a substitution filter. The value of
1594 each entry defines the substitution expression itself. The websub
1595 expressions follow the old interhg extension syntax, which in turn imi‐
1596 tates the Unix sed replacement syntax:
1597 patternname = s/SEARCH_REGEX/REPLACE_EXPRESSION/[i]
1599 You can use any separator other than "/". The final "i" is optional and
1601 indicates that the search must be case insensitive.
1602 Examples:
1604 [websub]
1606 issues = s|issue(\d+)|<a href="http://bts.example.org/issue\1">issue\1</a>|i
1607 italic = s/\b_(\S+)_\b/<i>\1<\/i>/
1608 bold = s/\*\b(\S+)\b\*/<b>\1<\/b>/
1609 worker
1611 Parallel master/worker configuration. We currently perform working
1612 directory updates in parallel on Unix-like systems, which greatly helps
1613 performance.
1614 numcpus
1616 Number of CPUs to use for parallel operations. Default is 4 or
1618 the number of CPUs on the system, whichever is larger. A zero or
1619 negative value is treated as use the default.
1620
1622 Bryan O'Sullivan <bos@serpentine.com>.
1623 Mercurial was written by Matt Mackall <mpm@selenic.com>.
1625
1627 hg(1), hgignore(5)
1628
1630 This manual page is copyright 2005 Bryan O'Sullivan. Mercurial is
1631 copyright 2005-2012 Matt Mackall. Free use of this software is granted
1632 under the terms of the GNU General Public License version 2 or any
1633 later version.
1634
1636 Bryan O'Sullivan <bos@serpentine.com>
1637 Organization: Mercurial
1639 HGRC(5)