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
13 If you're having problems with your configuration, hg config --debug
14 can help you understand what is introducing a setting into your envi‐
15 ronment.
16 See hg help config.syntax and hg help config.files for information
18 about how and where to override things.
19
21 The configuration files use a simple ini-file format. A configuration
22 file consists of sections, led by a [section] header and followed by
23 name = value entries:
24 [ui]
26 username = Firstname Lastname <firstname.lastname@example.net>
27 verbose = True
28 The above entries will be referred to as ui.username and ui.verbose,
30 respectively. See hg help config.syntax.
31
33 Mercurial reads configuration data from several files, if they exist.
34 These files do not exist by default and you will have to create the
35 appropriate configuration files yourself:
36 Local configuration is put into the per-repository <repo>/.hg/hgrc
38 file.
39 Global configuration like the username setting is typically put into:
41 · %USERPROFILE%\mercurial.ini (on Windows)
43 · $HOME/.hgrc (on Unix, Plan9)
45 The names of these files depend on the system on which Mercurial is
47 installed. *.rc files from a single directory are read in alphabetical
48 order, later ones overriding earlier ones. Where multiple paths are
49 given below, settings from earlier paths override later ones.
50 On Unix, the following files are consulted:
52 · <repo>/.hg/hgrc (per-repository)
54 · $HOME/.hgrc (per-user)
56 · ${XDG_CONFIG_HOME:-$HOME/.config}/hg/hgrc (per-user)
58 · <install-root>/etc/mercurial/hgrc (per-installation)
60 · <install-root>/etc/mercurial/hgrc.d/*.rc (per-installation)
62 · /etc/mercurial/hgrc (per-system)
64 · /etc/mercurial/hgrc.d/*.rc (per-system)
66 · <internal>/default.d/*.rc (defaults)
68 On Windows, the following files are consulted:
70 · <repo>/.hg/hgrc (per-repository)
72 · %USERPROFILE%\.hgrc (per-user)
74 · %USERPROFILE%\Mercurial.ini (per-user)
76 · %HOME%\.hgrc (per-user)
78 · %HOME%\Mercurial.ini (per-user)
80 · HKEY_LOCAL_MACHINE\SOFTWARE\Mercurial (per-installation)
82 · <install-dir>\hgrc.d\*.rc (per-installation)
84 · <install-dir>\Mercurial.ini (per-installation)
86 · <internal>/default.d/*.rc (defaults)
88 Note The registry key HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Mercu‐
90 rial is used when running 32-bit Python on 64-bit Windows.
91 On Windows 9x, %HOME% is replaced by %APPDATA%.
93 On Plan9, the following files are consulted:
95 · <repo>/.hg/hgrc (per-repository)
97 · $home/lib/hgrc (per-user)
99 · <install-root>/lib/mercurial/hgrc (per-installation)
101 · <install-root>/lib/mercurial/hgrc.d/*.rc (per-installation)
103 · /lib/mercurial/hgrc (per-system)
105 · /lib/mercurial/hgrc.d/*.rc (per-system)
107 · <internal>/default.d/*.rc (defaults)
109 Per-repository configuration options only apply in a particular reposi‐
111 tory. This file is not version-controlled, and will not get transferred
112 during a "clone" operation. Options in this file override options in
113 all other configuration files.
114 On Plan 9 and Unix, most of this file will be ignored if it doesn't
116 belong to a trusted user or to a trusted group. See hg help con‐
117 fig.trusted for more details.
118 Per-user configuration file(s) are for the user running Mercurial.
120 Options in these files apply to all Mercurial commands executed by this
121 user in any directory. Options in these files override per-system and
122 per-installation options.
123 Per-installation configuration files are searched for in the directory
125 where Mercurial is installed. <install-root> is the parent directory of
126 the hg executable (or symlink) being run.
127 For example, if installed in /shared/tools/bin/hg, Mercurial will look
129 in /shared/tools/etc/mercurial/hgrc. Options in these files apply to
130 all Mercurial commands executed by any user in any directory.
131 Per-installation configuration files are for the system on which Mercu‐
133 rial is running. Options in these files apply to all Mercurial commands
134 executed by any user in any directory. Registry keys contain PATH-like
135 strings, every part of which must reference a Mercurial.ini file or be
136 a directory where *.rc files will be read. Mercurial checks each of
137 these locations in the specified order until one or more configuration
138 files are detected.
139 Per-system configuration files are for the system on which Mercurial is
141 running. Options in these files apply to all Mercurial commands exe‐
142 cuted by any user in any directory. Options in these files override
143 per-installation options.
144 Mercurial comes with some default configuration. The default configura‐
146 tion files are installed with Mercurial and will be overwritten on
147 upgrades. Default configuration files should never be edited by users
148 or administrators but can be overridden in other configuration files.
149 So far the directory only contains merge tool configuration but pack‐
150 agers can also put other default configuration there.
151
153 A configuration file consists of sections, led by a [section] header
154 and followed by name = value entries (sometimes called configuration
155 keys):
156 [spam]
158 eggs=ham
159 green=
160 eggs
161 Each line contains one entry. If the lines that follow are indented,
163 they are treated as continuations of that entry. Leading whitespace is
164 removed from values. Empty lines are skipped. Lines beginning with # or
165 ; are ignored and may be used to provide comments.
166 Configuration keys can be set multiple times, in which case Mercurial
168 will use the value that was configured last. As an example:
169 [spam]
171 eggs=large
172 ham=serrano
173 eggs=small
174 This would set the configuration key named eggs to small.
176 It is also possible to define a section multiple times. A section can
178 be redefined on the same and/or on different configuration files. For
179 example:
180 [foo]
182 eggs=large
183 ham=serrano
184 eggs=small
185 [bar]
187 eggs=ham
188 green=
189 eggs
190 [foo]
192 ham=prosciutto
193 eggs=medium
194 bread=toasted
195 This would set the eggs, ham, and bread configuration keys of the foo
197 section to medium, prosciutto, and toasted, respectively. As you can
198 see there only thing that matters is the last value that was set for
199 each of the configuration keys.
200 If a configuration key is set multiple times in different configuration
202 files the final value will depend on the order in which the different
203 configuration files are read, with settings from earlier paths overrid‐
204 ing later ones as described on the Files section above.
205 A line of the form %include file will include file into the current
207 configuration file. The inclusion is recursive, which means that
208 included files can include other files. Filenames are relative to the
209 configuration file in which the %include directive is found. Environ‐
210 ment variables and ~user constructs are expanded in file. This lets you
211 do something like:
212 %include ~/.hgrc.d/$HOST.rc
214 to include a different configuration file on each computer you use.
216 A line with %unset name will remove name from the current section, if
218 it has been set previously.
219 The values are either free-form text strings, lists of text strings, or
221 Boolean values. Boolean values can be set to true using any of "1",
222 "yes", "true", or "on" and to false using "0", "no", "false", or "off"
223 (all case insensitive).
224 List values are separated by whitespace or comma, except when values
226 are placed in double quotation marks:
227 allow_read = "John Doe, PhD", brian, betty
229 Quotation marks can be escaped by prefixing them with a backslash. Only
231 quotation marks at the beginning of a word is counted as a quotation
232 (e.g., foo"bar baz is the list of foo"bar and baz).
233
235 This section describes the different sections that may appear in a Mer‐
236 curial configuration file, the purpose of each section, its possible
237 keys, and their possible values.
238 alias
240 Defines command aliases.
241 Aliases allow you to define your own commands in terms of other com‐
243 mands (or aliases), optionally including arguments. Positional argu‐
244 ments in the form of $1, $2, etc. in the alias definition are expanded
245 by Mercurial before execution. Positional arguments not already used by
246 $N in the definition are put at the end of the command to be executed.
247 Alias definitions consist of lines of the form:
249 <alias> = <command> [<argument>]...
251 For example, this definition:
253 latest = log --limit 5
255 creates a new command latest that shows only the five most recent
257 changesets. You can define subsequent aliases using earlier ones:
258 stable5 = latest -b stable
260 Note It is possible to create aliases with the same names as existing
262 commands, which will then override the original definitions.
263 This is almost always a bad idea!
264 An alias can start with an exclamation point (!) to make it a shell
266 alias. A shell alias is executed with the shell and will let you run
267 arbitrary commands. As an example,
268 echo = !echo $@
270 will let you do hg echo foo to have foo printed in your terminal. A
272 better example might be:
273 purge = !$HG status --no-status --unknown -0 re: | xargs -0 rm -f
275 which will make hg purge delete all unknown files in the repository in
277 the same manner as the purge extension.
278 Positional arguments like $1, $2, etc. in the alias definition expand
280 to the command arguments. Unmatched arguments are removed. $0 expands
281 to the alias name and $@ expands to all arguments separated by a space.
282 "$@" (with quotes) expands to all arguments quoted individually and
283 separated by a space. These expansions happen before the command is
284 passed to the shell.
285 Shell aliases are executed in an environment where $HG expands to the
287 path of the Mercurial that was used to execute the alias. This is use‐
288 ful when you want to call further Mercurial commands in a shell alias,
289 as was done above for the purge alias. In addition, $HG_ARGS expands to
290 the arguments given to Mercurial. In the hg echo foo call above,
291 $HG_ARGS would expand to echo foo.
292 Note Some global configuration options such as -R are processed
294 before shell aliases and will thus not be passed to aliases.
295 annotate
297 Settings used when displaying file annotations. All values are Booleans
298 and default to False. See hg help config.diff for related options for
299 the diff command.
300 ignorews
302 Ignore white space when comparing lines.
304 ignorewseol
306 Ignore white space at the end of a line when comparing lines.
308 ignorewsamount
310 Ignore changes in the amount of white space.
312 ignoreblanklines
314 Ignore changes whose lines are all blank.
316 auth
318 Authentication credentials and other authentication-like configuration
319 for HTTP connections. This section allows you to store usernames and
320 passwords for use when logging into HTTP servers. See hg help con‐
321 fig.web if you want to configure who can login to your HTTP server.
322 The following options apply to all hosts.
324 cookiefile
326 Path to a file containing HTTP cookie lines. Cookies matching a
328 host will be sent automatically.
329 The file format uses the Mozilla cookies.txt format, which
331 defines cookies on their own lines. Each line contains 7 fields
332 delimited by the tab character (domain, is_domain_cookie, path,
333 is_secure, expires, name, value). For more info, do an Internet
334 search for "Netscape cookies.txt format."
335 Note: the cookies parser does not handle port numbers on
337 domains. You will need to remove ports from the domain for the
338 cookie to be recognized. This could result in a cookie being
339 disclosed to an unwanted server.
340 The cookies file is read-only.
342 Other options in this section are grouped by name and have the follow‐
344 ing format:
345 <name>.<argument> = <value>
347 where <name> is used to group arguments into authentication entries.
349 Example:
350 foo.prefix = hg.intevation.de/mercurial
352 foo.username = foo
353 foo.password = bar
354 foo.schemes = http https
355 bar.prefix = secure.example.org
357 bar.key = path/to/file.key
358 bar.cert = path/to/file.cert
359 bar.schemes = https
360 Supported arguments:
362 prefix
364 Either * or a URI prefix with or without the scheme part. The
366 authentication entry with the longest matching prefix is used
367 (where * matches everything and counts as a match of length 1).
368 If the prefix doesn't include a scheme, the match is performed
369 against the URI with its scheme stripped as well, and the
370 schemes argument, q.v., is then subsequently consulted.
371 username
373 Optional. Username to authenticate with. If not given, and the
375 remote site requires basic or digest authentication, the user
376 will be prompted for it. Environment variables are expanded in
377 the username letting you do foo.username = $USER. If the URI
378 includes a username, only [auth] entries with a matching user‐
379 name or without a username will be considered.
380 password
382 Optional. Password to authenticate with. If not given, and the
384 remote site requires basic or digest authentication, the user
385 will be prompted for it.
386 key
388 Optional. PEM encoded client certificate key file. Environment
390 variables are expanded in the filename.
391 cert
393 Optional. PEM encoded client certificate chain file. Environment
395 variables are expanded in the filename.
396 schemes
398 Optional. Space separated list of URI schemes to use this
400 authentication entry with. Only used if the prefix doesn't
401 include a scheme. Supported schemes are http and https. They
402 will match static-http and static-https respectively, as well.
403 (default: https)
404 If no suitable authentication entry is found, the user is prompted for
406 credentials as usual if required by the remote.
407 color
409 Configure the Mercurial color mode. For details about how to define
410 your custom effect and style see hg help color.
411 mode
413 String: control the method used to output color. One of auto,
415 ansi, win32, terminfo or debug. In auto mode, Mercurial will use
416 ANSI mode by default (or win32 mode prior to Windows 10) if it
417 detects a terminal. Any invalid value will disable color.
418 pagermode
420 String: optional override of color.mode used with pager.
422 On some systems, terminfo mode may cause problems when using
424 color with less -R as a pager program. less with the -R option
425 will only display ECMA-48 color codes, and terminfo mode may
426 sometimes emit codes that less doesn't understand. You can work
427 around this by either using ansi mode (or auto mode), or by
428 using less -r (which will pass through all terminal control
429 codes, not just color control codes).
430 On some systems (such as MSYS in Windows), the terminal may sup‐
432 port a different color mode than the pager program.
433 commands
435 resolve.confirm
436 Confirm before performing action if no filename is passed.
438 (default: False)
439 resolve.explicit-re-merge
441 Require uses of hg resolve to specify which action it should
443 perform, instead of re-merging files by default. (default:
444 False)
445 resolve.mark-check
447 Determines what level of checking hg resolve --mark will perform
449 before marking files as resolved. Valid values are none`,
450 ``warn, and abort. warn will output a warning listing the
451 file(s) that still have conflict markers in them, but will still
452 mark everything resolved. abort will output the same warning
453 but will not mark things as resolved. If --all is passed and
454 this is set to abort, only a warning will be shown (an error
455 will not be raised). (default: none)
456 status.relative
458 Make paths in hg status output relative to the current direc‐
460 tory. (default: False)
461 status.terse
463 Default value for the --terse flag, which condenses status out‐
465 put. (default: empty)
466 update.check
468 Determines what level of checking hg update will perform before
470 moving to a destination revision. Valid values are abort, none,
471 linear, and noconflict. abort always fails if the working direc‐
472 tory has uncommitted changes. none performs no checking, and may
473 result in a merge with uncommitted changes. linear allows any
474 update as long as it follows a straight line in the revision
475 history, and may trigger a merge with uncommitted changes.
476 noconflict will allow any update which would not trigger a merge
477 with uncommitted changes, if any are present. (default: linear)
478 update.requiredest
480 Require that the user pass a destination when running hg update.
482 For example, hg update .:: will be allowed, but a plain hg
483 update will be disallowed. (default: False)
484 committemplate
486 changeset
487 String: configuration in this section is used as the template to
489 customize the text shown in the editor when committing.
490 In addition to pre-defined template keywords, commit log specific one
492 below can be used for customization:
493 extramsg
495 String: Extra message (typically 'Leave message empty to abort
497 commit.'). This may be changed by some commands or extensions.
498 For example, the template configuration below shows as same text as one
500 shown by default:
501 [committemplate]
503 changeset = {desc}\n\n
504 HG: Enter commit message. Lines beginning with 'HG:' are removed.
505 HG: {extramsg}
506 HG: --
507 HG: user: {author}\n{ifeq(p2rev, "-1", "",
508 "HG: branch merge\n")
509 }HG: branch '{branch}'\n{if(activebookmark,
510 "HG: bookmark '{activebookmark}'\n") }{subrepos %
511 "HG: subrepo {subrepo}\n" }{file_adds %
512 "HG: added {file}\n" }{file_mods %
513 "HG: changed {file}\n" }{file_dels %
514 "HG: removed {file}\n" }{if(files, "",
515 "HG: no files changed\n")}
516 diff()
518 String: show the diff (see hg help templates for detail)
520 Sometimes it is helpful to show the diff of the changeset in the editor
522 without having to prefix 'HG: ' to each line so that highlighting works
523 correctly. For this, Mercurial provides a special string which will
524 ignore everything below it:
525 HG: ------------------------ >8 ------------------------
527 For example, the template configuration below will show the diff below
529 the extra message:
530 [committemplate]
532 changeset = {desc}\n\n
533 HG: Enter commit message. Lines beginning with 'HG:' are removed.
534 HG: {extramsg}
535 HG: ------------------------ >8 ------------------------
536 HG: Do not touch the line above.
537 HG: Everything below will be removed.
538 {diff()}
539 Note For some problematic encodings (see hg help win32mbcs for
541 detail), this customization should be configured carefully, to
542 avoid showing broken characters.
543 For example, if a multibyte character ending with backslash
545 (0x5c) is followed by the ASCII character 'n' in the customized
546 template, the sequence of backslash and 'n' is treated as
547 line-feed unexpectedly (and the multibyte character is broken,
548 too).
549 Customized template is used for commands below (--edit may be
551 required):
552 · hg backout
554 · hg commit
556 · hg fetch (for merge commit only)
558 · hg graft
560 · hg histedit
562 · hg import
564 · hg qfold, hg qnew and hg qrefresh
566 · hg rebase
568 · hg shelve
570 · hg sign
572 · hg tag
574 · hg transplant
576 Configuring items below instead of changeset allows showing customized
578 message only for specific actions, or showing different messages for
579 each action.
580 · changeset.backout for hg backout
582 · changeset.commit.amend.merge for hg commit --amend on merges
584 · changeset.commit.amend.normal for hg commit --amend on other
586 · changeset.commit.normal.merge for hg commit on merges
588 · changeset.commit.normal.normal for hg commit on other
590 · changeset.fetch for hg fetch (impling merge commit)
592 · changeset.gpg.sign for hg sign
594 · changeset.graft for hg graft
596 · changeset.histedit.edit for edit of hg histedit
598 · changeset.histedit.fold for fold of hg histedit
600 · changeset.histedit.mess for mess of hg histedit
602 · changeset.histedit.pick for pick of hg histedit
604 · changeset.import.bypass for hg import --bypass
606 · changeset.import.normal.merge for hg import on merges
608 · changeset.import.normal.normal for hg import on other
610 · changeset.mq.qnew for hg qnew
612 · changeset.mq.qfold for hg qfold
614 · changeset.mq.qrefresh for hg qrefresh
616 · changeset.rebase.collapse for hg rebase --collapse
618 · changeset.rebase.merge for hg rebase on merges
620 · changeset.rebase.normal for hg rebase on other
622 · changeset.shelve.shelve for hg shelve
624 · changeset.tag.add for hg tag without --remove
626 · changeset.tag.remove for hg tag --remove
628 · changeset.transplant.merge for hg transplant on merges
630 · changeset.transplant.normal for hg transplant on other
632 These dot-separated lists of names are treated as hierarchical ones.
634 For example, changeset.tag.remove customizes the commit message only
635 for hg tag --remove, but changeset.tag customizes the commit message
636 for hg tag regardless of --remove option.
637 When the external editor is invoked for a commit, the corresponding
639 dot-separated list of names without the changeset. prefix (e.g. com‐
640 mit.normal.normal) is in the HGEDITFORM environment variable.
641 In this section, items other than changeset can be referred from oth‐
643 ers. For example, the configuration to list committed files up below
644 can be referred as {listupfiles}:
645 [committemplate]
647 listupfiles = {file_adds %
648 "HG: added {file}\n" }{file_mods %
649 "HG: changed {file}\n" }{file_dels %
650 "HG: removed {file}\n" }{if(files, "",
651 "HG: no files changed\n")}
652 decode/encode
654 Filters for transforming files on checkout/checkin. This would typi‐
655 cally be used for newline processing or other localization/canonical‐
656 ization of files.
657 Filters consist of a filter pattern followed by a filter command. Fil‐
659 ter patterns are globs by default, rooted at the repository root. For
660 example, to match any file ending in .txt in the root directory only,
661 use the pattern *.txt. To match any file ending in .c anywhere in the
662 repository, use the pattern **.c. For each file only the first match‐
663 ing filter applies.
664 The filter command can start with a specifier, either pipe: or temp‐
666 file:. If no specifier is given, pipe: is used by default.
667 A pipe: command must accept data on stdin and return the transformed
669 data on stdout.
670 Pipe example:
672 [encode]
674 # uncompress gzip files on checkin to improve delta compression
675 # note: not necessarily a good idea, just an example
676 *.gz = pipe: gunzip
677 [decode]
679 # recompress gzip files when writing them to the working dir (we
680 # can safely omit "pipe:", because it's the default)
681 *.gz = gzip
682 A tempfile: command is a template. The string INFILE is replaced with
684 the name of a temporary file that contains the data to be filtered by
685 the command. The string OUTFILE is replaced with the name of an empty
686 temporary file, where the filtered data must be written by the command.
687 Note The tempfile mechanism is recommended for Windows systems, where
689 the standard shell I/O redirection operators often have strange
690 effects and may corrupt the contents of your files.
691 This filter mechanism is used internally by the eol extension to trans‐
693 late line ending characters between Windows (CRLF) and Unix (LF) for‐
694 mat. We suggest you use the eol extension for convenience.
695 defaults
697 (defaults are deprecated. Don't use them. Use aliases instead.)
698 Use the [defaults] section to define command defaults, i.e. the default
700 options/arguments to pass to the specified commands.
701 The following example makes hg log run in verbose mode, and hg status
703 show only the modified files, by default:
704 [defaults]
706 log = -v
707 status = -m
708 The actual commands, instead of their aliases, must be used when defin‐
710 ing command defaults. The command defaults will also be applied to the
711 aliases of the commands defined.
712 diff
714 Settings used when displaying diffs. Everything except for unified is a
715 Boolean and defaults to False. See hg help config.annotate for related
716 options for the annotate command.
717 git
719 Use git extended diff format.
721 nobinary
723 Omit git binary patches.
725 nodates
727 Don't include dates in diff headers.
729 noprefix
731 Omit 'a/' and 'b/' prefixes from filenames. Ignored in plain
733 mode.
734 showfunc
736 Show which function each change is in.
738 ignorews
740 Ignore white space when comparing lines.
742 ignorewsamount
744 Ignore changes in the amount of white space.
746 ignoreblanklines
748 Ignore changes whose lines are all blank.
750 unified
752 Number of lines of context to show.
754 word-diff
756 Highlight changed words.
758 email
760 Settings for extensions that send email messages.
761 from
763 Optional. Email address to use in "From" header and SMTP enve‐
765 lope of outgoing messages.
766 to
768 Optional. Comma-separated list of recipients' email addresses.
770 cc
772 Optional. Comma-separated list of carbon copy recipients' email
774 addresses.
775 bcc
777 Optional. Comma-separated list of blind carbon copy recipients'
779 email addresses.
780 method
782 Optional. Method to use to send email messages. If value is smtp
784 (default), use SMTP (see the [smtp] section for configuration).
785 Otherwise, use as name of program to run that acts like sendmail
786 (takes -f option for sender, list of recipients on command line,
787 message on stdin). Normally, setting this to sendmail or
788 /usr/sbin/sendmail is enough to use sendmail to send messages.
789 charsets
791 Optional. Comma-separated list of character sets considered con‐
793 venient for recipients. Addresses, headers, and parts not con‐
794 taining patches of outgoing messages will be encoded in the
795 first character set to which conversion from local encoding
796 ($HGENCODING, ui.fallbackencoding) succeeds. If correct conver‐
797 sion fails, the text in question is sent as is. (default: '')
798 Order of outgoing email character sets:
800 1. us-ascii: always first, regardless of settings
802 2. email.charsets: in order given by user
804 3. ui.fallbackencoding: if not in email.charsets
806 4. $HGENCODING: if not in email.charsets
808 5. utf-8: always last, regardless of settings
810 Email example:
812 [email]
814 from = Joseph User <joe.user@example.com>
815 method = /usr/sbin/sendmail
816 # charsets for western Europeans
817 # us-ascii, utf-8 omitted, as they are tried first and last
818 charsets = iso-8859-1, iso-8859-15, windows-1252
819 extensions
821 Mercurial has an extension mechanism for adding new features. To enable
822 an extension, create an entry for it in this section.
823 If you know that the extension is already in Python's search path, you
825 can give the name of the module, followed by =, with nothing after the
826 =.
827 Otherwise, give a name that you choose, followed by =, followed by the
829 path to the .py file (including the file name extension) that defines
830 the extension.
831 To explicitly disable an extension that is enabled in an hgrc of
833 broader scope, prepend its path with !, as in foo = !/ext/path or foo =
834 ! when path is not supplied.
835 Example for ~/.hgrc:
837 [extensions]
839 # (the churn extension will get loaded from Mercurial's path)
840 churn =
841 # (this extension will get loaded from the file specified)
842 myfeature = ~/.hgext/myfeature.py
843 format
845 Configuration that controls the repository format. Newer format options
846 are more powerful but incompatible with some older versions of Mercu‐
847 rial. Format options are considered at repository initialization only.
848 You need to make a new clone for config change to be taken into
849 account.
850 For more details about repository format and version compatibility, see
852 https://www.mercurial-scm.org/wiki/MissingRequirement
853 usegeneraldelta
855 Enable or disable the "generaldelta" repository format which
857 improves repository compression by allowing "revlog" to store
858 delta against arbitrary revision instead of the previous stored
859 one. This provides significant improvement for repositories with
860 branches.
861 Repositories with this on-disk format require Mercurial version
863 1.9.
864 Enabled by default.
866 dotencode
868 Enable or disable the "dotencode" repository format which
870 enhances the "fncache" repository format (which has to be
871 enabled to use dotencode) to avoid issues with filenames start‐
872 ing with ._ on Mac OS X and spaces on Windows.
873 Repositories with this on-disk format require Mercurial version
875 1.7.
876 Enabled by default.
878 usefncache
880 Enable or disable the "fncache" repository format which enhances
882 the "store" repository format (which has to be enabled to use
883 fncache) to allow longer filenames and avoids using Windows
884 reserved names, e.g. "nul".
885 Repositories with this on-disk format require Mercurial version
887 1.1.
888 Enabled by default.
890 usestore
892 Enable or disable the "store" repository format which improves
894 compatibility with systems that fold case or otherwise mangle
895 filenames. Disabling this option will allow you to store longer
896 filenames in some situations at the expense of compatibility.
897 Repositories with this on-disk format require Mercurial version
899 0.9.4.
900 Enabled by default.
902 sparse-revlog
904 Enable or disable the sparse-revlog delta strategy. This format
906 improves delta re-use inside revlog. For very branchy reposito‐
907 ries, it results in a smaller store. For repositories with many
908 revisions, it also helps performance (by using shortened delta
909 chains.)
910 Repositories with this on-disk format require Mercurial version
912 4.7
913 Enabled by default.
915 graph
917 Web graph view configuration. This section let you change graph ele‐
918 ments display properties by branches, for instance to make the default
919 branch stand out.
920 Each line has the following format:
922 <branch>.<argument> = <value>
924 where <branch> is the name of the branch being customized. Example:
926 [graph]
928 # 2px width
929 default.width = 2
930 # red color
931 default.color = FF0000
932 Supported arguments:
934 width
936 Set branch edges width in pixels.
938 color
940 Set branch edges color in hexadecimal RGB notation.
942 hooks
944 Commands or Python functions that get automatically executed by various
945 actions such as starting or finishing a commit. Multiple hooks can be
946 run for the same action by appending a suffix to the action. Overriding
947 a site-wide hook can be done by changing its value or setting it to an
948 empty string. Hooks can be prioritized by adding a prefix of priority.
949 to the hook name on a new line and setting the priority. The default
950 priority is 0.
951 Example .hg/hgrc:
953 [hooks]
955 # update working directory after adding changesets
956 changegroup.update = hg update
957 # do not use the site-wide hook
958 incoming =
959 incoming.email = /my/email/hook
960 incoming.autobuild = /my/build/hook
961 # force autobuild hook to run before other incoming hooks
962 priority.incoming.autobuild = 1
963 Most hooks are run with environment variables set that give useful
965 additional information. For each hook below, the environment variables
966 it is passed are listed with names in the form $HG_foo. The $HG_HOOK‐
967 TYPE and $HG_HOOKNAME variables are set for all hooks. They contain
968 the type of hook which triggered the run and the full name of the hook
969 in the config, respectively. In the example above, this will be
970 $HG_HOOKTYPE=incoming and $HG_HOOKNAME=incoming.email.
971 Some basic Unix syntax can be enabled for portability, including $VAR
973 and ${VAR} style variables. A ~ followed by \ or / will be expanded to
974 %USERPROFILE% to simulate a subset of tilde expansion on Unix. To use
975 a literal $ or ~, it must be escaped with a back slash or inside of a
976 strong quote. Strong quotes will be replaced by double quotes after
977 processing.
978 This feature is enabled by adding a prefix of tonative. to the hook
980 name on a new line, and setting it to True. For example:
981 [hooks]
983 incoming.autobuild = /my/build/hook
984 # enable translation to cmd.exe syntax for autobuild hook
985 tonative.incoming.autobuild = True
986 changegroup
988 Run after a changegroup has been added via push, pull or unbun‐
990 dle. The ID of the first new changeset is in $HG_NODE and last
991 is in $HG_NODE_LAST. The URL from which changes came is in
992 $HG_URL.
993 commit
995 Run after a changeset has been created in the local repository.
997 The ID of the newly created changeset is in $HG_NODE. Parent
998 changeset IDs are in $HG_PARENT1 and $HG_PARENT2.
999 incoming
1001 Run after a changeset has been pulled, pushed, or unbundled into
1003 the local repository. The ID of the newly arrived changeset is
1004 in $HG_NODE. The URL that was source of the changes is in
1005 $HG_URL.
1006 outgoing
1008 Run after sending changes from the local repository to another.
1010 The ID of first changeset sent is in $HG_NODE. The source of
1011 operation is in $HG_SOURCE. Also see hg help config.hooks.pre‐
1012 outgoing.
1013 post-<command>
1015 Run after successful invocations of the associated command. The
1017 contents of the command line are passed as $HG_ARGS and the
1018 result code in $HG_RESULT. Parsed command line arguments are
1019 passed as $HG_PATS and $HG_OPTS. These contain string represen‐
1020 tations of the python data internally passed to <command>.
1021 $HG_OPTS is a dictionary of options (with unspecified options
1022 set to their defaults). $HG_PATS is a list of arguments. Hook
1023 failure is ignored.
1024 fail-<command>
1026 Run after a failed invocation of an associated command. The con‐
1028 tents of the command line are passed as $HG_ARGS. Parsed command
1029 line arguments are passed as $HG_PATS and $HG_OPTS. These con‐
1030 tain string representations of the python data internally passed
1031 to <command>. $HG_OPTS is a dictionary of options (with unspeci‐
1032 fied options set to their defaults). $HG_PATS is a list of argu‐
1033 ments. Hook failure is ignored.
1034 pre-<command>
1036 Run before executing the associated command. The contents of the
1038 command line are passed as $HG_ARGS. Parsed command line argu‐
1039 ments are passed as $HG_PATS and $HG_OPTS. These contain string
1040 representations of the data internally passed to <command>.
1041 $HG_OPTS is a dictionary of options (with unspecified options
1042 set to their defaults). $HG_PATS is a list of arguments. If the
1043 hook returns failure, the command doesn't execute and Mercurial
1044 returns the failure code.
1045 prechangegroup
1047 Run before a changegroup is added via push, pull or unbundle.
1049 Exit status 0 allows the changegroup to proceed. A non-zero sta‐
1050 tus will cause the push, pull or unbundle to fail. The URL from
1051 which changes will come is in $HG_URL.
1052 precommit
1054 Run before starting a local commit. Exit status 0 allows the
1056 commit to proceed. A non-zero status will cause the commit to
1057 fail. Parent changeset IDs are in $HG_PARENT1 and $HG_PARENT2.
1058 prelistkeys
1060 Run before listing pushkeys (like bookmarks) in the repository.
1062 A non-zero status will cause failure. The key namespace is in
1063 $HG_NAMESPACE.
1064 preoutgoing
1066 Run before collecting changes to send from the local repository
1068 to another. A non-zero status will cause failure. This lets you
1069 prevent pull over HTTP or SSH. It can also prevent propagating
1070 commits (via local pull, push (outbound) or bundle commands),
1071 but not completely, since you can just copy files instead. The
1072 source of operation is in $HG_SOURCE. If "serve", the operation
1073 is happening on behalf of a remote SSH or HTTP repository. If
1074 "push", "pull" or "bundle", the operation is happening on behalf
1075 of a repository on same system.
1076 prepushkey
1078 Run before a pushkey (like a bookmark) is added to the reposi‐
1080 tory. A non-zero status will cause the key to be rejected. The
1081 key namespace is in $HG_NAMESPACE, the key is in $HG_KEY, the
1082 old value (if any) is in $HG_OLD, and the new value is in
1083 $HG_NEW.
1084 pretag
1086 Run before creating a tag. Exit status 0 allows the tag to be
1088 created. A non-zero status will cause the tag to fail. The ID of
1089 the changeset to tag is in $HG_NODE. The name of tag is in
1090 $HG_TAG. The tag is local if $HG_LOCAL=1, or in the repository
1091 if $HG_LOCAL=0.
1092 pretxnopen
1094 Run before any new repository transaction is open. The reason
1096 for the transaction will be in $HG_TXNNAME, and a unique identi‐
1097 fier for the transaction will be in HG_TXNID. A non-zero status
1098 will prevent the transaction from being opened.
1099 pretxnclose
1101 Run right before the transaction is actually finalized. Any
1103 repository change will be visible to the hook program. This lets
1104 you validate the transaction content or change it. Exit status 0
1105 allows the commit to proceed. A non-zero status will cause the
1106 transaction to be rolled back. The reason for the transaction
1107 opening will be in $HG_TXNNAME, and a unique identifier for the
1108 transaction will be in HG_TXNID. The rest of the available data
1109 will vary according the transaction type. New changesets will
1110 add $HG_NODE (the ID of the first added changeset),
1111 $HG_NODE_LAST (the ID of the last added changeset), $HG_URL and
1112 $HG_SOURCE variables. Bookmark and phase changes will set
1113 HG_BOOKMARK_MOVED and HG_PHASES_MOVED to 1 respectively, etc.
1114 pretxnclose-bookmark
1116 Run right before a bookmark change is actually finalized. Any
1118 repository change will be visible to the hook program. This lets
1119 you validate the transaction content or change it. Exit status 0
1120 allows the commit to proceed. A non-zero status will cause the
1121 transaction to be rolled back. The name of the bookmark will be
1122 available in $HG_BOOKMARK, the new bookmark location will be
1123 available in $HG_NODE while the previous location will be avail‐
1124 able in $HG_OLDNODE. In case of a bookmark creation $HG_OLDNODE
1125 will be empty. In case of deletion $HG_NODE will be empty. In
1126 addition, the reason for the transaction opening will be in
1127 $HG_TXNNAME, and a unique identifier for the transaction will be
1128 in HG_TXNID.
1129 pretxnclose-phase
1131 Run right before a phase change is actually finalized. Any
1133 repository change will be visible to the hook program. This lets
1134 you validate the transaction content or change it. Exit status 0
1135 allows the commit to proceed. A non-zero status will cause the
1136 transaction to be rolled back. The hook is called multiple
1137 times, once for each revision affected by a phase change. The
1138 affected node is available in $HG_NODE, the phase in $HG_PHASE
1139 while the previous $HG_OLDPHASE. In case of new node, $HG_OLD‐
1140 PHASE will be empty. In addition, the reason for the transac‐
1141 tion opening will be in $HG_TXNNAME, and a unique identifier for
1142 the transaction will be in HG_TXNID. The hook is also run for
1143 newly added revisions. In this case the $HG_OLDPHASE entry will
1144 be empty.
1145 txnclose
1147 Run after any repository transaction has been committed. At this
1149 point, the transaction can no longer be rolled back. The hook
1150 will run after the lock is released. See hg help con‐
1151 fig.hooks.pretxnclose for details about available variables.
1152 txnclose-bookmark
1154 Run after any bookmark change has been committed. At this point,
1156 the transaction can no longer be rolled back. The hook will run
1157 after the lock is released. See hg help config.hooks.pretxn‐
1158 close-bookmark for details about available variables.
1159 txnclose-phase
1161 Run after any phase change has been committed. At this point,
1163 the transaction can no longer be rolled back. The hook will run
1164 after the lock is released. See hg help config.hooks.pretxn‐
1165 close-phase for details about available variables.
1166 txnabort
1168 Run when a transaction is aborted. See hg help con‐
1170 fig.hooks.pretxnclose for details about available variables.
1171 pretxnchangegroup
1173 Run after a changegroup has been added via push, pull or unbun‐
1175 dle, but before the transaction has been committed. The change‐
1176 group is visible to the hook program. This allows validation of
1177 incoming changes before accepting them. The ID of the first new
1178 changeset is in $HG_NODE and last is in $HG_NODE_LAST. Exit sta‐
1179 tus 0 allows the transaction to commit. A non-zero status will
1180 cause the transaction to be rolled back, and the push, pull or
1181 unbundle will fail. The URL that was the source of changes is in
1182 $HG_URL.
1183 pretxncommit
1185 Run after a changeset has been created, but before the transac‐
1187 tion is committed. The changeset is visible to the hook program.
1188 This allows validation of the commit message and changes. Exit
1189 status 0 allows the commit to proceed. A non-zero status will
1190 cause the transaction to be rolled back. The ID of the new
1191 changeset is in $HG_NODE. The parent changeset IDs are in
1192 $HG_PARENT1 and $HG_PARENT2.
1193 preupdate
1195 Run before updating the working directory. Exit status 0 allows
1197 the update to proceed. A non-zero status will prevent the
1198 update. The changeset ID of first new parent is in $HG_PARENT1.
1199 If updating to a merge, the ID of second new parent is in
1200 $HG_PARENT2.
1201 listkeys
1203 Run after listing pushkeys (like bookmarks) in the repository.
1205 The key namespace is in $HG_NAMESPACE. $HG_VALUES is a dictio‐
1206 nary containing the keys and values.
1207 pushkey
1209 Run after a pushkey (like a bookmark) is added to the reposi‐
1211 tory. The key namespace is in $HG_NAMESPACE, the key is in
1212 $HG_KEY, the old value (if any) is in $HG_OLD, and the new value
1213 is in $HG_NEW.
1214 tag
1216 Run after a tag is created. The ID of the tagged changeset is in
1218 $HG_NODE. The name of tag is in $HG_TAG. The tag is local if
1219 $HG_LOCAL=1, or in the repository if $HG_LOCAL=0.
1220 update
1222 Run after updating the working directory. The changeset ID of
1224 first new parent is in $HG_PARENT1. If updating to a merge, the
1225 ID of second new parent is in $HG_PARENT2. If the update suc‐
1226 ceeded, $HG_ERROR=0. If the update failed (e.g. because con‐
1227 flicts were not resolved), $HG_ERROR=1.
1228 Note It is generally better to use standard hooks rather than the
1230 generic pre- and post- command hooks, as they are guaranteed to
1231 be called in the appropriate contexts for influencing transac‐
1232 tions. Also, hooks like "commit" will be called in all contexts
1233 that generate a commit (e.g. tag) and not just the commit com‐
1234 mand.
1235 Note Environment variables with empty values may not be passed to
1237 hooks on platforms such as Windows. As an example, $HG_PARENT2
1238 will have an empty value under Unix-like platforms for non-merge
1239 changesets, while it will not be available at all under Windows.
1240 The syntax for Python hooks is as follows:
1242 hookname = python:modulename.submodule.callable
1244 hookname = python:/path/to/python/module.py:callable
1245 Python hooks are run within the Mercurial process. Each hook is called
1247 with at least three keyword arguments: a ui object (keyword ui), a
1248 repository object (keyword repo), and a hooktype keyword that tells
1249 what kind of hook is used. Arguments listed as environment variables
1250 above are passed as keyword arguments, with no HG_ prefix, and names in
1251 lower case.
1252 If a Python hook returns a "true" value or raises an exception, this is
1254 treated as a failure.
1255 hostfingerprints
1257 (Deprecated. Use [hostsecurity]'s fingerprints options instead.)
1258 Fingerprints of the certificates of known HTTPS servers.
1260 A HTTPS connection to a server with a fingerprint configured here will
1262 only succeed if the servers certificate matches the fingerprint. This
1263 is very similar to how ssh known hosts works.
1264 The fingerprint is the SHA-1 hash value of the DER encoded certificate.
1266 Multiple values can be specified (separated by spaces or commas). This
1267 can be used to define both old and new fingerprints while a host tran‐
1268 sitions to a new certificate.
1269 The CA chain and web.cacerts is not used for servers with a finger‐
1271 print.
1272 For example:
1274 [hostfingerprints]
1276 hg.intevation.de = fc:e2:8d:d9:51:cd:cb:c1:4d:18:6b:b7:44:8d:49:72:57:e6:cd:33
1277 hg.intevation.org = fc:e2:8d:d9:51:cd:cb:c1:4d:18:6b:b7:44:8d:49:72:57:e6:cd:33
1278 hostsecurity
1280 Used to specify global and per-host security settings for connecting to
1281 other machines.
1282 The following options control default behavior for all hosts.
1284 ciphers
1286 Defines the cryptographic ciphers to use for connections.
1288 Value must be a valid OpenSSL Cipher List Format as documented
1290 at
1291 https://www.openssl.org/docs/manmaster/apps/ciphers.html#CIPHER-LIST-FORMAT
1292 .
1293 This setting is for advanced users only. Setting to incorrect
1295 values can significantly lower connection security or decrease
1296 performance. You have been warned.
1297 This option requires Python 2.7.
1299 minimumprotocol
1301 Defines the minimum channel encryption protocol to use.
1303 By default, the highest version of TLS supported by both client
1305 and server is used.
1306 Allowed values are: tls1.0, tls1.1, tls1.2.
1308 When running on an old Python version, only tls1.0 is allowed
1310 since old versions of Python only support up to TLS 1.0.
1311 When running a Python that supports modern TLS versions, the
1313 default is tls1.1. tls1.0 can still be used to allow TLS 1.0.
1314 However, this weakens security and should only be used as a fea‐
1315 ture of last resort if a server does not support TLS 1.1+.
1316 Options in the [hostsecurity] section can have the form hostname:set‐
1318 ting. This allows multiple settings to be defined on a per-host basis.
1319 The following per-host settings can be defined.
1321 ciphers
1323 This behaves like ciphers as described above except it only
1325 applies to the host on which it is defined.
1326 fingerprints
1328 A list of hashes of the DER encoded peer/remote certificate.
1330 Values have the form algorithm:fingerprint. e.g.
1331 sha256:c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2.
1332 In addition, colons (:) can appear in the fingerprint part.
1333 The following algorithms/prefixes are supported: sha1, sha256,
1335 sha512.
1336 Use of sha256 or sha512 is preferred.
1338 If a fingerprint is specified, the CA chain is not validated for
1340 this host and Mercurial will require the remote certificate to
1341 match one of the fingerprints specified. This means if the
1342 server updates its certificate, Mercurial will abort until a new
1343 fingerprint is defined. This can provide stronger security than
1344 traditional CA-based validation at the expense of convenience.
1345 This option takes precedence over verifycertsfile.
1347 minimumprotocol
1349 This behaves like minimumprotocol as described above except it
1351 only applies to the host on which it is defined.
1352 verifycertsfile
1354 Path to file a containing a list of PEM encoded certificates
1356 used to verify the server certificate. Environment variables and
1357 ~user constructs are expanded in the filename.
1358 The server certificate or the certificate's certificate author‐
1360 ity (CA) must match a certificate from this file or certificate
1361 verification will fail and connections to the server will be
1362 refused.
1363 If defined, only certificates provided by this file will be
1365 used: web.cacerts and any system/default certificates will not
1366 be used.
1367 This option has no effect if the per-host fingerprints option is
1369 set.
1370 The format of the file is as follows:
1372 -----BEGIN CERTIFICATE-----
1374 ... (certificate in base64 PEM encoding) ...
1375 -----END CERTIFICATE-----
1376 -----BEGIN CERTIFICATE-----
1377 ... (certificate in base64 PEM encoding) ...
1378 -----END CERTIFICATE-----
1379 For example:
1381 [hostsecurity]
1383 hg.example.com:fingerprints = sha256:c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2
1384 hg2.example.com:fingerprints = sha1:914f1aff87249c09b6859b88b1906d30756491ca, sha1:fc:e2:8d:d9:51:cd:cb:c1:4d:18:6b:b7:44:8d:49:72:57:e6:cd:33
1385 hg3.example.com:fingerprints = sha256:9a:b0:dc:e2:75:ad:8a:b7:84:58:e5:1f:07:32:f1:87:e6:bd:24:22:af:b7:ce:8e:9c:b4:10:cf:b9:f4:0e:d2
1386 foo.example.com:verifycertsfile = /etc/ssl/trusted-ca-certs.pem
1387 To change the default minimum protocol version to TLS 1.2 but to allow
1389 TLS 1.1 when connecting to hg.example.com:
1390 [hostsecurity]
1392 minimumprotocol = tls1.2
1393 hg.example.com:minimumprotocol = tls1.1
1394 http_proxy
1396 Used to access web-based Mercurial repositories through a HTTP proxy.
1397 host
1399 Host name and (optional) port of the proxy server, for example
1401 "myproxy:8000".
1402 no
1404 Optional. Comma-separated list of host names that should bypass
1406 the proxy.
1407 passwd
1409 Optional. Password to authenticate with at the proxy server.
1411 user
1413 Optional. User name to authenticate with at the proxy server.
1415 always
1417 Optional. Always use the proxy, even for localhost and any
1419 entries in http_proxy.no. (default: False)
1420 http
1422 Used to configure access to Mercurial repositories via HTTP.
1423 timeout
1425 If set, blocking operations will timeout after that many sec‐
1427 onds. (default: None)
1428 merge
1430 This section specifies behavior during merges and updates.
1431 checkignored
1433 Controls behavior when an ignored file on disk has the same name
1435 as a tracked file in the changeset being merged or updated to,
1436 and has different contents. Options are abort, warn and ignore.
1437 With abort, abort on such files. With warn, warn on such files
1438 and back them up as .orig. With ignore, don't print a warning
1439 and back them up as .orig. (default: abort)
1440 checkunknown
1442 Controls behavior when an unknown file that isn't ignored has
1444 the same name as a tracked file in the changeset being merged or
1445 updated to, and has different contents. Similar to merge.check‐
1446 ignored, except for files that are not ignored. (default: abort)
1447 on-failure
1449 When set to continue (the default), the merge process attempts
1451 to merge all unresolved files using the merge chosen tool,
1452 regardless of whether previous file merge attempts during the
1453 process succeeded or not. Setting this to prompt will prompt
1454 after any merge failure continue or halt the merge process. Set‐
1455 ting this to halt will automatically halt the merge process on
1456 any merge tool failure. The merge process can be restarted by
1457 using the resolve command. When a merge is halted, the reposi‐
1458 tory is left in a normal unresolved merge state. (default: con‐
1459 tinue)
1460 strict-capability-check
1462 Whether capabilities of internal merge tools are checked
1464 strictly or not, while examining rules to decide merge tool to
1465 be used. (default: False)
1466 merge-patterns
1468 This section specifies merge tools to associate with particular file
1469 patterns. Tools matched here will take precedence over the default
1470 merge tool. Patterns are globs by default, rooted at the repository
1471 root.
1472 Example:
1474 [merge-patterns]
1476 **.c = kdiff3
1477 **.jpg = myimgmerge
1478 merge-tools
1480 This section configures external merge tools to use for file-level
1481 merges. This section has likely been preconfigured at install time.
1482 Use hg config merge-tools to check the existing configuration. Also
1483 see hg help merge-tools for more details.
1484 Example ~/.hgrc:
1486 [merge-tools]
1488 # Override stock tool location
1489 kdiff3.executable = ~/bin/kdiff3
1490 # Specify command line
1491 kdiff3.args = $base $local $other -o $output
1492 # Give higher priority
1493 kdiff3.priority = 1
1494 # Changing the priority of preconfigured tool
1496 meld.priority = 0
1497 # Disable a preconfigured tool
1499 vimdiff.disabled = yes
1500 # Define new tool
1502 myHtmlTool.args = -m $local $other $base $output
1503 myHtmlTool.regkey = Software\FooSoftware\HtmlMerge
1504 myHtmlTool.priority = 1
1505 Supported arguments:
1507 priority
1509 The priority in which to evaluate this tool. (default: 0)
1511 executable
1513 Either just the name of the executable or its pathname.
1515 On Windows, the path can use environment variables with ${Pro‐
1517 gramFiles} syntax.
1518 (default: the tool name)
1520 args
1522 The arguments to pass to the tool executable. You can refer to
1524 the files being merged as well as the output file through these
1525 variables: $base, $local, $other, $output.
1526 The meaning of $local and $other can vary depending on which
1528 action is being performed. During an update or merge, $local
1529 represents the original state of the file, while $other repre‐
1530 sents the commit you are updating to or the commit you are merg‐
1531 ing with. During a rebase, $local represents the destination of
1532 the rebase, and $other represents the commit being rebased.
1533 Some operations define custom labels to assist with identifying
1535 the revisions, accessible via $labellocal, $labelother, and
1536 $labelbase. If custom labels are not available, these will be
1537 local, other, and base, respectively. (default: $local $base
1538 $other)
1539 premerge
1541 Attempt to run internal non-interactive 3-way merge tool before
1543 launching external tool. Options are true, false, keep or
1544 keep-merge3. The keep option will leave markers in the file if
1545 the premerge fails. The keep-merge3 will do the same but include
1546 information about the base of the merge in the marker (see
1547 internal :merge3 in hg help merge-tools). (default: True)
1548 binary
1550 This tool can merge binary files. (default: False, unless tool
1552 was selected by file pattern match)
1553 symlink
1555 This tool can merge symlinks. (default: False)
1557 check
1559 A list of merge success-checking options:
1561 changed
1563 Ask whether merge was successful when the merged file
1565 shows no changes.
1566 conflicts
1568 Check whether there are conflicts even though the tool
1570 reported success.
1571 prompt
1573 Always prompt for merge success, regardless of success
1575 reported by tool.
1576 fixeol
1578 Attempt to fix up EOL changes caused by the merge tool.
1580 (default: False)
1581 gui
1583 This tool requires a graphical interface to run. (default:
1585 False)
1586 mergemarkers
1588 Controls whether the labels passed via $labellocal, $labelother,
1590 and $labelbase are detailed (respecting mergemarkertemplate) or
1591 basic. If premerge is keep or keep-merge3, the conflict markers
1592 generated during premerge will be detailed if either this option
1593 or the corresponding option in the [ui] section is detailed.
1594 (default: basic)
1595 mergemarkertemplate
1597 This setting can be used to override mergemarkertemplate from
1599 the [ui] section on a per-tool basis; this applies to the
1600 $label-prefixed variables and to the conflict markers that are
1601 generated if premerge is keep` or ``keep-merge3. See the corre‐
1602 sponding variable in [ui] for more information.
1603 regkey
1605 Windows registry key which describes install location of this
1607 tool. Mercurial will search for this key first under HKEY_CUR‐
1608 RENT_USER and then under HKEY_LOCAL_MACHINE. (default: None)
1609 regkeyalt
1611 An alternate Windows registry key to try if the first key is not
1613 found. The alternate key uses the same regname and regappend
1614 semantics of the primary key. The most common use for this key
1615 is to search for 32bit applications on 64bit operating systems.
1616 (default: None)
1617 regname
1619 Name of value to read from specified registry key. (default:
1621 the unnamed (default) value)
1622 regappend
1624 String to append to the value read from the registry, typically
1626 the executable name of the tool. (default: None)
1627 pager
1629 Setting used to control when to paginate and with what external tool.
1630 See hg help pager for details.
1631 pager
1633 Define the external tool used as pager.
1635 If no pager is set, Mercurial uses the environment variable
1637 $PAGER. If neither pager.pager, nor $PAGER is set, a default
1638 pager will be used, typically less on Unix and more on Windows.
1639 Example:
1640 [pager]
1642 pager = less -FRX
1643 ignore
1645 List of commands to disable the pager for. Example:
1647 [pager]
1649 ignore = version, help, update
1650 patch
1652 Settings used when applying patches, for instance through the 'import'
1653 command or with Mercurial Queues extension.
1654 eol
1656 When set to 'strict' patch content and patched files end of
1658 lines are preserved. When set to lf or crlf, both files end of
1659 lines are ignored when patching and the result line endings are
1660 normalized to either LF (Unix) or CRLF (Windows). When set to
1661 auto, end of lines are again ignored while patching but line
1662 endings in patched files are normalized to their original set‐
1663 ting on a per-file basis. If target file does not exist or has
1664 no end of line, patch line endings are preserved. (default:
1665 strict)
1666 fuzz
1668 The number of lines of 'fuzz' to allow when applying patches.
1670 This controls how much context the patcher is allowed to ignore
1671 when trying to apply a patch. (default: 2)
1672 paths
1674 Assigns symbolic names and behavior to repositories.
1675 Options are symbolic names defining the URL or directory that is the
1677 location of the repository. Example:
1678 [paths]
1680 my_server = https://example.com/my_repo
1681 local_path = /home/me/repo
1682 These symbolic names can be used from the command line. To pull from
1684 my_server: hg pull my_server. To push to local_path: hg push local_path
1685 .
1686 Options containing colons (:) denote sub-options that can influence
1688 behavior for that specific path. Example:
1689 [paths]
1691 my_server = https://example.com/my_path
1692 my_server:pushurl = ssh://example.com/my_path
1693 The following sub-options can be defined:
1695 pushurl
1697 The URL to use for push operations. If not defined, the location
1699 defined by the path's main entry is used.
1700 pushrev
1702 A revset defining which revisions to push by default.
1704 When hg push is executed without a -r argument, the revset
1706 defined by this sub-option is evaluated to determine what to
1707 push.
1708 For example, a value of . will push the working directory's
1710 revision by default.
1711 Revsets specifying bookmarks will not result in the bookmark
1713 being pushed.
1714 The following special named paths exist:
1716 default
1718 The URL or directory to use when no source or remote is speci‐
1720 fied.
1721 hg clone will automatically define this path to the location the
1723 repository was cloned from.
1724 default-push
1726 (deprecated) The URL or directory for the default hg push loca‐
1728 tion. default:pushurl should be used instead.
1729 phases
1731 Specifies default handling of phases. See hg help phases for more
1732 information about working with phases.
1733 publish
1735 Controls draft phase behavior when working as a server. When
1737 true, pushed changesets are set to public in both client and
1738 server and pulled or cloned changesets are set to public in the
1739 client. (default: True)
1740 new-commit
1742 Phase of newly-created commits. (default: draft)
1744 checksubrepos
1746 Check the phase of the current revision of each subrepository.
1748 Allowed values are "ignore", "follow" and "abort". For settings
1749 other than "ignore", the phase of the current revision of each
1750 subrepository is checked before committing the parent reposi‐
1751 tory. If any of those phases is greater than the phase of the
1752 parent repository (e.g. if a subrepo is in a "secret" phase
1753 while the parent repo is in "draft" phase), the commit is either
1754 aborted (if checksubrepos is set to "abort") or the higher phase
1755 is used for the parent repository commit (if set to "follow").
1756 (default: follow)
1757 profiling
1759 Specifies profiling type, format, and file output. Two profilers are
1760 supported: an instrumenting profiler (named ls), and a sampling pro‐
1761 filer (named stat).
1762 In this section description, 'profiling data' stands for the raw data
1764 collected during profiling, while 'profiling report' stands for a sta‐
1765 tistical text report generated from the profiling data.
1766 enabled
1768 Enable the profiler. (default: false)
1770 This is equivalent to passing --profile on the command line.
1772 type
1774 The type of profiler to use. (default: stat)
1776 ls
1778 Use Python's built-in instrumenting profiler. This pro‐
1780 filer works on all platforms, but each line number it
1781 reports is the first line of a function. This restriction
1782 makes it difficult to identify the expensive parts of a
1783 non-trivial function.
1784 stat
1786 Use a statistical profiler, statprof. This profiler is
1788 most useful for profiling commands that run for longer
1789 than about 0.1 seconds.
1790 format
1792 Profiling format. Specific to the ls instrumenting profiler.
1794 (default: text)
1795 text
1797 Generate a profiling report. When saving to a file, it
1799 should be noted that only the report is saved, and the
1800 profiling data is not kept.
1801 kcachegrind
1803 Format profiling data for kcachegrind use: when saving to
1805 a file, the generated file can directly be loaded into
1806 kcachegrind.
1807 statformat
1809 Profiling format for the stat profiler. (default: hotpath)
1811 hotpath
1813 Show a tree-based display containing the hot path of exe‐
1815 cution (where most time was spent).
1816 bymethod
1818 Show a table of methods ordered by how frequently they
1820 are active.
1821 byline
1823 Show a table of lines in files ordered by how frequently
1825 they are active.
1826 json
1828 Render profiling data as JSON.
1830 frequency
1832 Sampling frequency. Specific to the stat sampling profiler.
1834 (default: 1000)
1835 output
1837 File path where profiling data or report should be saved. If the
1839 file exists, it is replaced. (default: None, data is printed on
1840 stderr)
1841 sort
1843 Sort field. Specific to the ls instrumenting profiler. One of
1845 callcount, reccallcount, totaltime and inlinetime. (default:
1846 inlinetime)
1847 time-track
1849 Control if the stat profiler track cpu or real time. (default:
1851 cpu on Windows, otherwise real)
1852 limit
1854 Number of lines to show. Specific to the ls instrumenting pro‐
1856 filer. (default: 30)
1857 nested
1859 Show at most this number of lines of drill-down info after each
1861 main entry. This can help explain the difference between Total
1862 and Inline. Specific to the ls instrumenting profiler.
1863 (default: 0)
1864 showmin
1866 Minimum fraction of samples an entry must have for it to be dis‐
1868 played. Can be specified as a float between 0.0 and 1.0 or can
1869 have a % afterwards to allow values up to 100. e.g. 5%.
1870 Only used by the stat profiler.
1872 For the hotpath format, default is 0.05. For the chrome format,
1874 default is 0.005.
1875 The option is unused on other formats.
1877 showmax
1879 Maximum fraction of samples an entry can have before it is
1881 ignored in display. Values format is the same as showmin.
1882 Only used by the stat profiler.
1884 For the chrome format, default is 0.999.
1886 The option is unused on other formats.
1888 progress
1890 Mercurial commands can draw progress bars that are as informative as
1891 possible. Some progress bars only offer indeterminate information,
1892 while others have a definite end point.
1893 debug
1895 Whether to print debug info when updating the progress bar.
1897 (default: False)
1898 delay
1900 Number of seconds (float) before showing the progress bar.
1902 (default: 3)
1903 changedelay
1905 Minimum delay before showing a new topic. When set to less than
1907 3 * refresh, that value will be used instead. (default: 1)
1908 estimateinterval
1910 Maximum sampling interval in seconds for speed and estimated
1912 time calculation. (default: 60)
1913 refresh
1915 Time in seconds between refreshes of the progress bar. (default:
1917 0.1)
1918 format
1920 Format of the progress bar.
1922 Valid entries for the format field are topic, bar, number, unit,
1924 estimate, speed, and item. item defaults to the last 20 charac‐
1925 ters of the item, but this can be changed by adding either
1926 -<num> which would take the last num characters, or +<num> for
1927 the first num characters.
1928 (default: topic bar number estimate)
1930 width
1932 If set, the maximum width of the progress information (that is,
1934 min(width, term width) will be used).
1935 clear-complete
1937 Clear the progress bar after it's done. (default: True)
1939 disable
1941 If true, don't show a progress bar.
1943 assume-tty
1945 If true, ALWAYS show a progress bar, unless disable is given.
1947 rebase
1949 evolution.allowdivergence
1950 Default to False, when True allow creating divergence when per‐
1952 forming rebase of obsolete changesets.
1953 revsetalias
1955 Alias definitions for revsets. See hg help revsets for details.
1956 rewrite
1958 backup-bundle
1959 Whether to save stripped changesets to a bundle file. (default:
1961 True)
1962 update-timestamp
1964 If true, updates the date and time of the changeset to current.
1966 It is only applicable for hg amend in current version.
1967 storage
1969 Control the strategy Mercurial uses internally to store history.
1970 Options in this category impact performance and repository size.
1971 revlog.optimize-delta-parent-choice
1973 When storing a merge revision, both parents will be equally con‐
1975 sidered as a possible delta base. This results in better delta
1976 selection and improved revlog compression. This option is
1977 enabled by default.
1978 Turning this option off can result in large increase of reposi‐
1980 tory size for repository with many merges.
1981 server
1983 Controls generic server settings.
1984 bookmarks-pushkey-compat
1986 Trigger pushkey hook when being pushed bookmark updates. This
1988 config exist for compatibility purpose (default to True)
1989 If you use pushkey and pre-pushkey hooks to control bookmark
1991 movement we recommend you migrate them to txnclose-bookmark and
1992 pretxnclose-bookmark.
1993 compressionengines
1995 List of compression engines and their relative priority to
1997 advertise to clients.
1998 The order of compression engines determines their priority, the
2000 first having the highest priority. If a compression engine is
2001 not listed here, it won't be advertised to clients.
2002 If not set (the default), built-in defaults are used. Run hg
2004 debuginstall to list available compression engines and their
2005 default wire protocol priority.
2006 Older Mercurial clients only support zlib compression and this
2008 setting has no effect for legacy clients.
2009 uncompressed
2011 Whether to allow clients to clone a repository using the uncom‐
2013 pressed streaming protocol. This transfers about 40% more data
2014 than a regular clone, but uses less memory and CPU on both
2015 server and client. Over a LAN (100 Mbps or better) or a very
2016 fast WAN, an uncompressed streaming clone is a lot faster (~10x)
2017 than a regular clone. Over most WAN connections (anything slower
2018 than about 6 Mbps), uncompressed streaming is slower, because of
2019 the extra data transfer overhead. This mode will also temporar‐
2020 ily hold the write lock while determining what data to transfer.
2021 (default: True)
2022 uncompressedallowsecret
2024 Whether to allow stream clones when the repository contains
2026 secret changesets. (default: False)
2027 preferuncompressed
2029 When set, clients will try to use the uncompressed streaming
2031 protocol. (default: False)
2032 disablefullbundle
2034 When set, servers will refuse attempts to do pull-based clones.
2036 If this option is set, preferuncompressed and/or clone bundles
2037 are highly recommended. Partial clones will still be allowed.
2038 (default: False)
2039 streamunbundle
2041 When set, servers will apply data sent from the client directly,
2043 otherwise it will be written to a temporary file first. This
2044 option effectively prevents concurrent pushes.
2045 pullbundle
2047 When set, the server will check pullbundle.manifest for bundles
2049 covering the requested heads and common nodes. The first match‐
2050 ing entry will be streamed to the client.
2051 For HTTP transport, the stream will still use zlib compression
2053 for older clients.
2054 concurrent-push-mode
2056 Level of allowed race condition between two pushing clients.
2058 · 'strict': push is abort if another client touched the reposi‐
2060 tory while the push was preparing. (default)
2061 · 'check-related': push is only aborted if it affects head that
2063 got also affected while the push was preparing.
2064 This requires compatible client (version 4.3 and later). Old
2066 client will use 'strict'.
2067 validate
2069 Whether to validate the completeness of pushed changesets by
2071 checking that all new file revisions specified in manifests are
2072 present. (default: False)
2073 maxhttpheaderlen
2075 Instruct HTTP clients not to send request headers longer than
2077 this many bytes. (default: 1024)
2078 bundle1
2080 Whether to allow clients to push and pull using the legacy bun‐
2082 dle1 exchange format. (default: True)
2083 bundle1gd
2085 Like bundle1 but only used if the repository is using the gener‐
2087 aldelta storage format. (default: True)
2088 bundle1.push
2090 Whether to allow clients to push using the legacy bundle1
2092 exchange format. (default: True)
2093 bundle1gd.push
2095 Like bundle1.push but only used if the repository is using the
2097 generaldelta storage format. (default: True)
2098 bundle1.pull
2100 Whether to allow clients to pull using the legacy bundle1
2102 exchange format. (default: True)
2103 bundle1gd.pull
2105 Like bundle1.pull but only used if the repository is using the
2107 generaldelta storage format. (default: True)
2108 Large repositories using the generaldelta storage format should
2110 consider setting this option because converting generaldelta
2111 repositories to the exchange format required by the bundle1 data
2112 format can consume a lot of CPU.
2113 bundle2.stream
2115 Whether to allow clients to pull using the bundle2 streaming
2117 protocol. (default: True)
2118 zliblevel
2120 Integer between -1 and 9 that controls the zlib compression
2122 level for wire protocol commands that send zlib compressed out‐
2123 put (notably the commands that send repository history data).
2124 The default (-1) uses the default zlib compression level, which
2126 is likely equivalent to 6. 0 means no compression. 9 means maxi‐
2127 mum compression.
2128 Setting this option allows server operators to make trade-offs
2130 between bandwidth and CPU used. Lowering the compression lowers
2131 CPU utilization but sends more bytes to clients.
2132 This option only impacts the HTTP server.
2134 zstdlevel
2136 Integer between 1 and 22 that controls the zstd compression
2138 level for wire protocol commands. 1 is the minimal amount of
2139 compression and 22 is the highest amount of compression.
2140 The default (3) should be significantly faster than zlib while
2142 likely delivering better compression ratios.
2143 This option only impacts the HTTP server.
2145 See also server.zliblevel.
2147 smtp
2149 Configuration for extensions that need to send email messages.
2150 host
2152 Host name of mail server, e.g. "mail.example.com".
2154 port
2156 Optional. Port to connect to on mail server. (default: 465 if
2158 tls is smtps; 25 otherwise)
2159 tls
2161 Optional. Method to enable TLS when connecting to mail server:
2163 starttls, smtps or none. (default: none)
2164 username
2166 Optional. User name for authenticating with the SMTP server.
2168 (default: None)
2169 password
2171 Optional. Password for authenticating with the SMTP server. If
2173 not specified, interactive sessions will prompt the user for a
2174 password; non-interactive sessions will fail. (default: None)
2175 local_hostname
2177 Optional. The hostname that the sender can use to identify
2179 itself to the MTA.
2180 subpaths
2182 Subrepository source URLs can go stale if a remote server changes name
2183 or becomes temporarily unavailable. This section lets you define re‐
2184 write rules of the form:
2185 <pattern> = <replacement>
2187 where pattern is a regular expression matching a subrepository source
2189 URL and replacement is the replacement string used to rewrite it.
2190 Groups can be matched in pattern and referenced in replacements. For
2191 instance:
2192 http://server/(.*)-hg/ = http://hg.server/\1/
2194 rewrites http://server/foo-hg/ into http://hg.server/foo/.
2196 Relative subrepository paths are first made absolute, and the rewrite
2198 rules are then applied on the full (absolute) path. If pattern doesn't
2199 match the full path, an attempt is made to apply it on the relative
2200 path alone. The rules are applied in definition order.
2201 subrepos
2203 This section contains options that control the behavior of the sub‐
2204 repositories feature. See also hg help subrepos.
2205 Security note: auditing in Mercurial is known to be insufficient to
2207 prevent clone-time code execution with carefully constructed Git subre‐
2208 pos. It is unknown if a similar detect is present in Subversion subre‐
2209 pos. Both Git and Subversion subrepos are disabled by default out of
2210 security concerns. These subrepo types can be enabled using the respec‐
2211 tive options below.
2212 allowed
2214 Whether subrepositories are allowed in the working directory.
2216 When false, commands involving subrepositories (like hg update)
2218 will fail for all subrepository types. (default: true)
2219 hg:allowed
2221 Whether Mercurial subrepositories are allowed in the working
2223 directory. This option only has an effect if subrepos.allowed is
2224 true. (default: true)
2225 git:allowed
2227 Whether Git subrepositories are allowed in the working direc‐
2229 tory. This option only has an effect if subrepos.allowed is
2230 true.
2231 See the security note above before enabling Git subrepos.
2233 (default: false)
2234 svn:allowed
2236 Whether Subversion subrepositories are allowed in the working
2238 directory. This option only has an effect if subrepos.allowed is
2239 true.
2240 See the security note above before enabling Subversion subrepos.
2242 (default: false)
2243 templatealias
2245 Alias definitions for templates. See hg help templates for details.
2246 templates
2248 Use the [templates] section to define template strings. See hg help
2249 templates for details.
2250 trusted
2252 Mercurial will not use the settings in the .hg/hgrc file from a reposi‐
2253 tory if it doesn't belong to a trusted user or to a trusted group, as
2254 various hgrc features allow arbitrary commands to be run. This issue is
2255 often encountered when configuring hooks or extensions for shared
2256 repositories or servers. However, the web interface will use some safe
2257 settings from the [web] section.
2258 This section specifies what users and groups are trusted. The current
2260 user is always trusted. To trust everybody, list a user or a group with
2261 name *. These settings must be placed in an already-trusted file to
2262 take effect, such as $HOME/.hgrc of the user or service running Mercu‐
2263 rial.
2264 users
2266 Comma-separated list of trusted users.
2268 groups
2270 Comma-separated list of trusted groups.
2272 ui
2274 User interface controls.
2275 archivemeta
2277 Whether to include the .hg_archival.txt file containing meta
2279 data (hashes for the repository base and for tip) in archives
2280 created by the hg archive command or downloaded via hgweb.
2281 (default: True)
2282 askusername
2284 Whether to prompt for a username when committing. If True, and
2286 neither $HGUSER nor $EMAIL has been specified, then the user
2287 will be prompted to enter a username. If no username is entered,
2288 the default USER@HOST is used instead. (default: False)
2289 clonebundles
2291 Whether the "clone bundles" feature is enabled.
2293 When enabled, hg clone may download and apply a server-adver‐
2295 tised bundle file from a URL instead of using the normal
2296 exchange mechanism.
2297 This can likely result in faster and more reliable clones.
2299 (default: True)
2301 clonebundlefallback
2303 Whether failure to apply an advertised "clone bundle" from a
2305 server should result in fallback to a regular clone.
2306 This is disabled by default because servers advertising "clone
2308 bundles" often do so to reduce server load. If advertised bun‐
2309 dles start mass failing and clients automatically fall back to a
2310 regular clone, this would add significant and unexpected load to
2311 the server since the server is expecting clone operations to be
2312 offloaded to pre-generated bundles. Failing fast (the default
2313 behavior) ensures clients don't overwhelm the server when "clone
2314 bundle" application fails.
2315 (default: False)
2317 clonebundleprefers
2319 Defines preferences for which "clone bundles" to use.
2321 Servers advertising "clone bundles" may advertise multiple
2323 available bundles. Each bundle may have different attributes,
2324 such as the bundle type and compression format. This option is
2325 used to prefer a particular bundle over another.
2326 The following keys are defined by Mercurial:
2328 BUNDLESPEC
2330 A bundle type specifier. These are strings passed to hg
2331 bundle -t. e.g. gzip-v2 or bzip2-v1.
2332 COMPRESSION
2334 The compression format of the bundle. e.g. gzip and
2335 bzip2.
2336 Server operators may define custom keys.
2338 Example values: COMPRESSION=bzip2, BUNDLESPEC=gzip-v2, COMPRES‐
2340 SION=gzip.
2341 By default, the first bundle advertised by the server is used.
2343 color
2345 When to colorize output. Possible value are Boolean ("yes" or
2347 "no"), or "debug", or "always". (default: "yes"). "yes" will use
2348 color whenever it seems possible. See hg help color for details.
2349 commitsubrepos
2351 Whether to commit modified subrepositories when committing the
2353 parent repository. If False and one subrepository has uncommit‐
2354 ted changes, abort the commit. (default: False)
2355 debug
2357 Print debugging information. (default: False)
2359 editor
2361 The editor to use during a commit. (default: $EDITOR or vi)
2363 fallbackencoding
2365 Encoding to try if it's not possible to decode the changelog
2367 using UTF-8. (default: ISO-8859-1)
2368 graphnodetemplate
2370 The template used to print changeset nodes in an ASCII revision
2372 graph. (default: {graphnode})
2373 ignore
2375 A file to read per-user ignore patterns from. This file should
2377 be in the same format as a repository-wide .hgignore file. File‐
2378 names are relative to the repository root. This option supports
2379 hook syntax, so if you want to specify multiple ignore files,
2380 you can do so by setting something like ignore.other = ~/.hgig‐
2381 nore2. For details of the ignore file format, see the hgig‐
2382 nore(5) man page.
2383 interactive
2385 Allow to prompt the user. (default: True)
2387 interface
2389 Select the default interface for interactive features (default:
2391 text). Possible values are 'text' and 'curses'.
2392 interface.chunkselector
2394 Select the interface for change recording (e.g. hg commit -i).
2396 Possible values are 'text' and 'curses'. This config overrides
2397 the interface specified by ui.interface.
2398 large-file-limit
2400 Largest file size that gives no memory use warning. Possible
2402 values are integers or 0 to disable the check. (default:
2403 10000000)
2404 logtemplate
2406 Template string for commands that print changesets.
2408 merge
2410 The conflict resolution program to use during a manual merge.
2412 For more information on merge tools see hg help merge-tools.
2413 For configuring merge tools see the [merge-tools] section.
2414 mergemarkers
2416 Sets the merge conflict marker label styling. The detailed style
2418 uses the mergemarkertemplate setting to style the labels. The
2419 basic style just uses 'local' and 'other' as the marker label.
2420 One of basic or detailed. (default: basic)
2421 mergemarkertemplate
2423 The template used to print the commit description next to each
2425 conflict marker during merge conflicts. See hg help templates
2426 for the template format.
2427 Defaults to showing the hash, tags, branches, bookmarks, author,
2429 and the first line of the commit description.
2430 If you use non-ASCII characters in names for tags, branches,
2432 bookmarks, authors, and/or commit descriptions, you must pay
2433 attention to encodings of managed files. At template expansion,
2434 non-ASCII characters use the encoding specified by the --encod‐
2435 ing global option, HGENCODING or other environment variables
2436 that govern your locale. If the encoding of the merge markers is
2437 different from the encoding of the merged files, serious prob‐
2438 lems may occur.
2439 Can be overridden per-merge-tool, see the [merge-tools] section.
2441 message-output
2443 Where to write status and error messages. (default: stdio)
2445 stderr
2447 Everything to stderr.
2449 stdio
2451 Status to stdout, and error to stderr.
2453 origbackuppath
2455 The path to a directory used to store generated .orig files. If
2457 the path is not a directory, one will be created. If set, files
2458 stored in this directory have the same name as the original file
2459 and do not have a .orig suffix.
2460 paginate
2462 Control the pagination of command output (default: True). See hg
2464 help pager for details.
2465 patch
2467 An optional external tool that hg import and some extensions
2469 will use for applying patches. By default Mercurial uses an
2470 internal patch utility. The external tool must work as the com‐
2471 mon Unix patch program. In particular, it must accept a -p argu‐
2472 ment to strip patch headers, a -d argument to specify the cur‐
2473 rent directory, a file name to patch, and a patch file to take
2474 from stdin.
2475 It is possible to specify a patch tool together with extra argu‐
2477 ments. For example, setting this option to patch --merge will
2478 use the patch program with its 2-way merge option.
2479 portablefilenames
2481 Check for portable filenames. Can be warn, ignore or abort.
2483 (default: warn)
2484 warn
2486 Print a warning message on POSIX platforms, if a file
2488 with a non-portable filename is added (e.g. a file with a
2489 name that can't be created on Windows because it contains
2490 reserved parts like AUX, reserved characters like :, or
2491 would cause a case collision with an existing file).
2492 ignore
2494 Don't print a warning.
2496 abort
2498 The command is aborted.
2500 true
2502 Alias for warn.
2504 false
2506 Alias for ignore.
2508 On Windows, this configuration option is ignored and the command
2510 aborted.
2511 pre-merge-tool-output-template
2513 A template that is printed before executing an external merge
2515 tool. This can be used to print out additional context that
2516 might be useful to have during the conflict resolution, such as
2517 the description of the various commits involved or book‐
2518 marks/tags.
2519 Additional information is available in the local`, ``base, and
2521 other dicts. For example: {local.label}, {base.name}, or
2522 {other.islink}.
2523 quiet
2525 Reduce the amount of output printed. (default: False)
2527 remotecmd
2529 Remote command to use for clone/push/pull operations. (default:
2531 hg)
2532 report_untrusted
2534 Warn if a .hg/hgrc file is ignored due to not being owned by a
2536 trusted user or group. (default: True)
2537 slash
2539 (Deprecated. Use slashpath template filter instead.)
2541 Display paths using a slash (/) as the path separator. This only
2543 makes a difference on systems where the default path separator
2544 is not the slash character (e.g. Windows uses the backslash
2545 character (\)). (default: False)
2546 statuscopies
2548 Display copies in the status command.
2550 ssh
2552 Command to use for SSH connections. (default: ssh)
2554 ssherrorhint
2556 A hint shown to the user in the case of SSH error (e.g. Please
2558 see http://company/internalwiki/ssh.html)
2559 strict
2561 Require exact command names, instead of allowing unambiguous
2563 abbreviations. (default: False)
2564 style
2566 Name of style to use for command output.
2568 supportcontact
2570 A URL where users should report a Mercurial traceback. Use this
2572 if you are a large organisation with its own Mercurial deploy‐
2573 ment process and crash reports should be addressed to your
2574 internal support.
2575 textwidth
2577 Maximum width of help text. A longer line generated by hg help
2579 or hg subcommand --help will be broken after white space to get
2580 this width or the terminal width, whichever comes first. A
2581 non-positive value will disable this and the terminal width will
2582 be used. (default: 78)
2583 timeout
2585 The timeout used when a lock is held (in seconds), a negative
2587 value means no timeout. (default: 600)
2588 timeout.warn
2590 Time (in seconds) before a warning is printed about held lock. A
2592 negative value means no warning. (default: 0)
2593 traceback
2595 Mercurial always prints a traceback when an unknown exception
2597 occurs. Setting this to True will make Mercurial print a trace‐
2598 back on all exceptions, even those recognized by Mercurial (such
2599 as IOError or MemoryError). (default: False)
2600 tweakdefaults
2602 By default Mercurial's behavior changes very little from release to
2604 release, but over time the recommended config settings shift. Enable
2605 this config to opt in to get automatic tweaks to Mercurial's behav‐
2606 ior over time. This config setting will have no effect if HGPLAIN is
2607 set or HGPLAINEXCEPT is set and does not include tweakdefaults.
2608 (default: False)
2609 It currently means:
2611 [ui]
2613 # The rollback command is dangerous. As a rule, don't use it.
2614 rollback = False
2615 # Make `hg status` report copy information
2616 statuscopies = yes
2617 # Prefer curses UIs when available. Revert to plain-text with `text`.
2618 interface = curses
2619 [commands]
2621 # Grep working directory by default.
2622 grep.all-files = True
2623 # Make `hg status` emit cwd-relative paths by default.
2624 status.relative = yes
2625 # Refuse to perform an `hg update` that would cause a file content merge
2626 update.check = noconflict
2627 # Show conflicts information in `hg status`
2628 status.verbose = True
2629 [diff]
2631 git = 1
2632 showfunc = 1
2633 word-diff = 1
2634 username
2636 The committer of a changeset created when running "commit".
2638 Typically a person's name and email address, e.g. Fred Widget
2639 <fred@example.com>. Environment variables in the username are
2640 expanded.
2641 (default: $EMAIL or username@hostname. If the username in hgrc
2643 is empty, e.g. if the system admin set username = in the system
2644 hgrc, it has to be specified manually or in a different hgrc
2645 file)
2646 verbose
2648 Increase the amount of output printed. (default: False)
2650 web
2652 Web interface configuration. The settings in this section apply to both
2653 the builtin webserver (started by hg serve) and the script you run
2654 through a webserver (hgweb.cgi and the derivatives for FastCGI and
2655 WSGI).
2656 The Mercurial webserver does no authentication (it does not prompt for
2658 usernames and passwords to validate who users are), but it does do
2659 authorization (it grants or denies access for authenticated users based
2660 on settings in this section). You must either configure your webserver
2661 to do authentication for you, or disable the authorization checks.
2662 For a quick setup in a trusted environment, e.g., a private LAN, where
2664 you want it to accept pushes from anybody, you can use the following
2665 command line:
2666 $ hg --config web.allow-push=* --config web.push_ssl=False serve
2668 Note that this will allow anybody to push anything to the server and
2670 that this should not be used for public servers.
2671 The full set of options is:
2673 accesslog
2675 Where to output the access log. (default: stdout)
2677 address
2679 Interface address to bind to. (default: all)
2681 allow-archive
2683 List of archive format (bz2, gz, zip) allowed for downloading.
2685 (default: empty)
2686 allowbz2
2688 (DEPRECATED) Whether to allow .tar.bz2 downloading of repository
2690 revisions. (default: False)
2691 allowgz
2693 (DEPRECATED) Whether to allow .tar.gz downloading of repository
2695 revisions. (default: False)
2696 allow-pull
2698 Whether to allow pulling from the repository. (default: True)
2700 allow-push
2702 Whether to allow pushing to the repository. If empty or not set,
2704 pushing is not allowed. If the special value *, any remote user
2705 can push, including unauthenticated users. Otherwise, the remote
2706 user must have been authenticated, and the authenticated user
2707 name must be present in this list. The contents of the
2708 allow-push list are examined after the deny_push list.
2709 allow_read
2711 If the user has not already been denied repository access due to
2713 the contents of deny_read, this list determines whether to grant
2714 repository access to the user. If this list is not empty, and
2715 the user is unauthenticated or not present in the list, then
2716 access is denied for the user. If the list is empty or not set,
2717 then access is permitted to all users by default. Setting
2718 allow_read to the special value * is equivalent to it not being
2719 set (i.e. access is permitted to all users). The contents of the
2720 allow_read list are examined after the deny_read list.
2721 allowzip
2723 (DEPRECATED) Whether to allow .zip downloading of repository
2725 revisions. This feature creates temporary files. (default:
2726 False)
2727 archivesubrepos
2729 Whether to recurse into subrepositories when archiving.
2731 (default: False)
2732 baseurl
2734 Base URL to use when publishing URLs in other locations, so
2736 third-party tools like email notification hooks can construct
2737 URLs. Example: http://hgserver/repos/.
2738 cacerts
2740 Path to file containing a list of PEM encoded certificate
2742 authority certificates. Environment variables and ~user con‐
2743 structs are expanded in the filename. If specified on the
2744 client, then it will verify the identity of remote HTTPS servers
2745 with these certificates.
2746 To disable SSL verification temporarily, specify --insecure from
2748 command line.
2749 You can use OpenSSL's CA certificate file if your platform has
2751 one. On most Linux systems this will be /etc/ssl/certs/ca-cer‐
2752 tificates.crt. Otherwise you will have to generate this file
2753 manually. The form must be as follows:
2754 -----BEGIN CERTIFICATE-----
2756 ... (certificate in base64 PEM encoding) ...
2757 -----END CERTIFICATE-----
2758 -----BEGIN CERTIFICATE-----
2759 ... (certificate in base64 PEM encoding) ...
2760 -----END CERTIFICATE-----
2761 cache
2763 Whether to support caching in hgweb. (default: True)
2765 certificate
2767 Certificate to use when running hg serve.
2769 collapse
2771 With descend enabled, repositories in subdirectories are shown
2773 at a single level alongside repositories in the current path.
2774 With collapse also enabled, repositories residing at a deeper
2775 level than the current path are grouped behind navigable direc‐
2776 tory entries that lead to the locations of these repositories.
2777 In effect, this setting collapses each collection of reposito‐
2778 ries found within a subdirectory into a single entry for that
2779 subdirectory. (default: False)
2780 comparisoncontext
2782 Number of lines of context to show in side-by-side file compari‐
2784 son. If negative or the value full, whole files are shown.
2785 (default: 5)
2786 This setting can be overridden by a context request parameter to
2788 the comparison command, taking the same values.
2789 contact
2791 Name or email address of the person in charge of the repository.
2793 (default: ui.username or $EMAIL or "unknown" if unset or empty)
2794 csp
2796 Send a Content-Security-Policy HTTP header with this value.
2798 The value may contain a special string %nonce%, which will be
2800 replaced by a randomly-generated one-time use value. If the
2801 value contains %nonce%, web.cache will be disabled, as caching
2802 undermines the one-time property of the nonce. This nonce will
2803 also be inserted into <script> elements containing inline
2804 JavaScript.
2805 Note: lots of HTML content sent by the server is derived from
2807 repository data. Please consider the potential for malicious
2808 repository data to "inject" itself into generated HTML content
2809 as part of your security threat model.
2810 deny_push
2812 Whether to deny pushing to the repository. If empty or not set,
2814 push is not denied. If the special value *, all remote users are
2815 denied push. Otherwise, unauthenticated users are all denied,
2816 and any authenticated user name present in this list is also
2817 denied. The contents of the deny_push list are examined before
2818 the allow-push list.
2819 deny_read
2821 Whether to deny reading/viewing of the repository. If this list
2823 is not empty, unauthenticated users are all denied, and any
2824 authenticated user name present in this list is also denied
2825 access to the repository. If set to the special value *, all
2826 remote users are denied access (rarely needed ;). If deny_read
2827 is empty or not set, the determination of repository access
2828 depends on the presence and content of the allow_read list (see
2829 description). If both deny_read and allow_read are empty or not
2830 set, then access is permitted to all users by default. If the
2831 repository is being served via hgwebdir, denied users will not
2832 be able to see it in the list of repositories. The contents of
2833 the deny_read list have priority over (are examined before) the
2834 contents of the allow_read list.
2835 descend
2837 hgwebdir indexes will not descend into subdirectories. Only
2839 repositories directly in the current path will be shown (other
2840 repositories are still available from the index corresponding to
2841 their containing path).
2842 description
2844 Textual description of the repository's purpose or contents.
2846 (default: "unknown")
2847 encoding
2849 Character encoding name. (default: the current locale charset)
2851 Example: "UTF-8".
2852 errorlog
2854 Where to output the error log. (default: stderr)
2856 guessmime
2858 Control MIME types for raw download of file content. Set to
2860 True to let hgweb guess the content type from the file exten‐
2861 sion. This will serve HTML files as text/html and might allow
2862 cross-site scripting attacks when serving untrusted reposito‐
2863 ries. (default: False)
2864 hidden
2866 Whether to hide the repository in the hgwebdir index. (default:
2868 False)
2869 ipv6
2871 Whether to use IPv6. (default: False)
2873 labels
2875 List of string labels associated with the repository.
2877 Labels are exposed as a template keyword and can be used to cus‐
2879 tomize output. e.g. the index template can group or filter
2880 repositories by labels and the summary template can display
2881 additional content if a specific label is present.
2882 logoimg
2884 File name of the logo image that some templates display on each
2886 page. The file name is relative to staticurl. That is, the full
2887 path to the logo image is "staticurl/logoimg". If unset, hgl‐
2888 ogo.png will be used.
2889 logourl
2891 Base URL to use for logos. If unset, https://mercurial-scm.org/
2893 will be used.
2894 maxchanges
2896 Maximum number of changes to list on the changelog. (default:
2898 10)
2899 maxfiles
2901 Maximum number of files to list per changeset. (default: 10)
2903 maxshortchanges
2905 Maximum number of changes to list on the shortlog, graph or
2907 filelog pages. (default: 60)
2908 name
2910 Repository name to use in the web interface. (default: current
2912 working directory)
2913 port
2915 Port to listen on. (default: 8000)
2917 prefix
2919 Prefix path to serve from. (default: '' (server root))
2921 push_ssl
2923 Whether to require that inbound pushes be transported over SSL
2925 to prevent password sniffing. (default: True)
2926 refreshinterval
2928 How frequently directory listings re-scan the filesystem for new
2930 repositories, in seconds. This is relevant when wildcards are
2931 used to define paths. Depending on how much filesystem traversal
2932 is required, refreshing may negatively impact performance.
2933 Values less than or equal to 0 always refresh. (default: 20)
2935 server-header
2937 Value for HTTP Server response header.
2939 static
2941 Directory where static files are served from.
2943 staticurl
2945 Base URL to use for static files. If unset, static files (e.g.
2947 the hgicon.png favicon) will be served by the CGI script itself.
2948 Use this setting to serve them directly with the HTTP server.
2949 Example: http://hgserver/static/.
2950 stripes
2952 How many lines a "zebra stripe" should span in multi-line out‐
2954 put. Set to 0 to disable. (default: 1)
2955 style
2957 Which template map style to use. The available options are the
2959 names of subdirectories in the HTML templates path. (default:
2960 paper) Example: monoblue.
2961 templates
2963 Where to find the HTML templates. The default path to the HTML
2965 templates can be obtained from hg debuginstall.
2966 websub
2968 Web substitution filter definition. You can use this section to define
2969 a set of regular expression substitution patterns which let you auto‐
2970 matically modify the hgweb server output.
2971 The default hgweb templates only apply these substitution patterns on
2973 the revision description fields. You can apply them anywhere you want
2974 when you create your own templates by adding calls to the "websub" fil‐
2975 ter (usually after calling the "escape" filter).
2976 This can be used, for example, to convert issue references to links to
2978 your issue tracker, or to convert "markdown-like" syntax into HTML (see
2979 the examples below).
2980 Each entry in this section names a substitution filter. The value of
2982 each entry defines the substitution expression itself. The websub
2983 expressions follow the old interhg extension syntax, which in turn imi‐
2984 tates the Unix sed replacement syntax:
2985 patternname = s/SEARCH_REGEX/REPLACE_EXPRESSION/[i]
2987 You can use any separator other than "/". The final "i" is optional and
2989 indicates that the search must be case insensitive.
2990 Examples:
2992 [websub]
2994 issues = s|issue(\d+)|<a href="http://bts.example.org/issue\1">issue\1</a>|i
2995 italic = s/\b_(\S+)_\b/<i>\1<\/i>/
2996 bold = s/\*\b(\S+)\b\*/<b>\1<\/b>/
2997 worker
2999 Parallel master/worker configuration. We currently perform working
3000 directory updates in parallel on Unix-like systems, which greatly helps
3001 performance.
3002 enabled
3004 Whether to enable workers code to be used. (default: true)
3006 numcpus
3008 Number of CPUs to use for parallel operations. A zero or nega‐
3010 tive value is treated as use the default. (default: 4 or the
3011 number of CPUs on the system, whichever is larger)
3012 backgroundclose
3014 Whether to enable closing file handles on background threads
3016 during certain operations. Some platforms aren't very efficient
3017 at closing file handles that have been written or appended to.
3018 By performing file closing on background threads, file write
3019 rate can increase substantially. (default: true on Windows,
3020 false elsewhere)
3021 backgroundcloseminfilecount
3023 Minimum number of files required to trigger background file
3025 closing. Operations not writing this many files won't start
3026 background close threads. (default: 2048)
3027 backgroundclosemaxqueue
3029 The maximum number of opened file handles waiting to be closed
3031 in the background. This option only has an effect if background‐
3032 close is enabled. (default: 384)
3033 backgroundclosethreadcount
3035 Number of threads to process background file closes. Only rele‐
3037 vant if backgroundclose is enabled. (default: 4)
3038
3040 Bryan O'Sullivan <bos@serpentine.com>.
3041 Mercurial was written by Matt Mackall <mpm@selenic.com>.
3043
3045 hg(1), hgignore(5)
3046
3048 This manual page is copyright 2005 Bryan O'Sullivan. Mercurial is
3049 copyright 2005-2019 Matt Mackall. Free use of this software is granted
3050 under the terms of the GNU General Public License version 2 or any
3051 later version.
3052
3054 Bryan O'Sullivan <bos@serpentine.com>
3055 Organization: Mercurial
3057 HGRC(5)