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 commit.post-status
436 Show status of files in the working directory after successful
438 commit. (default: False)
439 push.require-revs
441 Require revisions to push be specified using one or more mecha‐
443 nisms such as specifying them positionally on the command line,
444 using -r, -b, and/or -B on the command line, or using
445 paths.<path>:pushrev in the configuration. If this is enabled
446 and revisions are not specified, the command aborts. (default:
447 False)
448 resolve.confirm
450 Confirm before performing action if no filename is passed.
452 (default: False)
453 resolve.explicit-re-merge
455 Require uses of hg resolve to specify which action it should
457 perform, instead of re-merging files by default. (default:
458 False)
459 resolve.mark-check
461 Determines what level of checking hg resolve --mark will perform
463 before marking files as resolved. Valid values are none`,
464 ``warn, and abort. warn will output a warning listing the
465 file(s) that still have conflict markers in them, but will still
466 mark everything resolved. abort will output the same warning
467 but will not mark things as resolved. If --all is passed and
468 this is set to abort, only a warning will be shown (an error
469 will not be raised). (default: none)
470 status.relative
472 Make paths in hg status output relative to the current direc‐
474 tory. (default: False)
475 status.terse
477 Default value for the --terse flag, which condenses status out‐
479 put. (default: empty)
480 update.check
482 Determines what level of checking hg update will perform before
484 moving to a destination revision. Valid values are abort, none,
485 linear, and noconflict. abort always fails if the working direc‐
486 tory has uncommitted changes. none performs no checking, and may
487 result in a merge with uncommitted changes. linear allows any
488 update as long as it follows a straight line in the revision
489 history, and may trigger a merge with uncommitted changes.
490 noconflict will allow any update which would not trigger a merge
491 with uncommitted changes, if any are present. (default: linear)
492 update.requiredest
494 Require that the user pass a destination when running hg update.
496 For example, hg update .:: will be allowed, but a plain hg
497 update will be disallowed. (default: False)
498 committemplate
500 changeset
501 String: configuration in this section is used as the template to
503 customize the text shown in the editor when committing.
504 In addition to pre-defined template keywords, commit log specific one
506 below can be used for customization:
507 extramsg
509 String: Extra message (typically 'Leave message empty to abort
511 commit.'). This may be changed by some commands or extensions.
512 For example, the template configuration below shows as same text as one
514 shown by default:
515 [committemplate]
517 changeset = {desc}\n\n
518 HG: Enter commit message. Lines beginning with 'HG:' are removed.
519 HG: {extramsg}
520 HG: --
521 HG: user: {author}\n{ifeq(p2rev, "-1", "",
522 "HG: branch merge\n")
523 }HG: branch '{branch}'\n{if(activebookmark,
524 "HG: bookmark '{activebookmark}'\n") }{subrepos %
525 "HG: subrepo {subrepo}\n" }{file_adds %
526 "HG: added {file}\n" }{file_mods %
527 "HG: changed {file}\n" }{file_dels %
528 "HG: removed {file}\n" }{if(files, "",
529 "HG: no files changed\n")}
530 diff()
532 String: show the diff (see hg help templates for detail)
534 Sometimes it is helpful to show the diff of the changeset in the editor
536 without having to prefix 'HG: ' to each line so that highlighting works
537 correctly. For this, Mercurial provides a special string which will
538 ignore everything below it:
539 HG: ------------------------ >8 ------------------------
541 For example, the template configuration below will show the diff below
543 the extra message:
544 [committemplate]
546 changeset = {desc}\n\n
547 HG: Enter commit message. Lines beginning with 'HG:' are removed.
548 HG: {extramsg}
549 HG: ------------------------ >8 ------------------------
550 HG: Do not touch the line above.
551 HG: Everything below will be removed.
552 {diff()}
553 Note For some problematic encodings (see hg help win32mbcs for
555 detail), this customization should be configured carefully, to
556 avoid showing broken characters.
557 For example, if a multibyte character ending with backslash
559 (0x5c) is followed by the ASCII character 'n' in the customized
560 template, the sequence of backslash and 'n' is treated as
561 line-feed unexpectedly (and the multibyte character is broken,
562 too).
563 Customized template is used for commands below (--edit may be
565 required):
566 · hg backout
568 · hg commit
570 · hg fetch (for merge commit only)
572 · hg graft
574 · hg histedit
576 · hg import
578 · hg qfold, hg qnew and hg qrefresh
580 · hg rebase
582 · hg shelve
584 · hg sign
586 · hg tag
588 · hg transplant
590 Configuring items below instead of changeset allows showing customized
592 message only for specific actions, or showing different messages for
593 each action.
594 · changeset.backout for hg backout
596 · changeset.commit.amend.merge for hg commit --amend on merges
598 · changeset.commit.amend.normal for hg commit --amend on other
600 · changeset.commit.normal.merge for hg commit on merges
602 · changeset.commit.normal.normal for hg commit on other
604 · changeset.fetch for hg fetch (impling merge commit)
606 · changeset.gpg.sign for hg sign
608 · changeset.graft for hg graft
610 · changeset.histedit.edit for edit of hg histedit
612 · changeset.histedit.fold for fold of hg histedit
614 · changeset.histedit.mess for mess of hg histedit
616 · changeset.histedit.pick for pick of hg histedit
618 · changeset.import.bypass for hg import --bypass
620 · changeset.import.normal.merge for hg import on merges
622 · changeset.import.normal.normal for hg import on other
624 · changeset.mq.qnew for hg qnew
626 · changeset.mq.qfold for hg qfold
628 · changeset.mq.qrefresh for hg qrefresh
630 · changeset.rebase.collapse for hg rebase --collapse
632 · changeset.rebase.merge for hg rebase on merges
634 · changeset.rebase.normal for hg rebase on other
636 · changeset.shelve.shelve for hg shelve
638 · changeset.tag.add for hg tag without --remove
640 · changeset.tag.remove for hg tag --remove
642 · changeset.transplant.merge for hg transplant on merges
644 · changeset.transplant.normal for hg transplant on other
646 These dot-separated lists of names are treated as hierarchical ones.
648 For example, changeset.tag.remove customizes the commit message only
649 for hg tag --remove, but changeset.tag customizes the commit message
650 for hg tag regardless of --remove option.
651 When the external editor is invoked for a commit, the corresponding
653 dot-separated list of names without the changeset. prefix (e.g. com‐
654 mit.normal.normal) is in the HGEDITFORM environment variable.
655 In this section, items other than changeset can be referred from oth‐
657 ers. For example, the configuration to list committed files up below
658 can be referred as {listupfiles}:
659 [committemplate]
661 listupfiles = {file_adds %
662 "HG: added {file}\n" }{file_mods %
663 "HG: changed {file}\n" }{file_dels %
664 "HG: removed {file}\n" }{if(files, "",
665 "HG: no files changed\n")}
666 decode/encode
668 Filters for transforming files on checkout/checkin. This would typi‐
669 cally be used for newline processing or other localization/canonical‐
670 ization of files.
671 Filters consist of a filter pattern followed by a filter command. Fil‐
673 ter patterns are globs by default, rooted at the repository root. For
674 example, to match any file ending in .txt in the root directory only,
675 use the pattern *.txt. To match any file ending in .c anywhere in the
676 repository, use the pattern **.c. For each file only the first match‐
677 ing filter applies.
678 The filter command can start with a specifier, either pipe: or temp‐
680 file:. If no specifier is given, pipe: is used by default.
681 A pipe: command must accept data on stdin and return the transformed
683 data on stdout.
684 Pipe example:
686 [encode]
688 # uncompress gzip files on checkin to improve delta compression
689 # note: not necessarily a good idea, just an example
690 *.gz = pipe: gunzip
691 [decode]
693 # recompress gzip files when writing them to the working dir (we
694 # can safely omit "pipe:", because it's the default)
695 *.gz = gzip
696 A tempfile: command is a template. The string INFILE is replaced with
698 the name of a temporary file that contains the data to be filtered by
699 the command. The string OUTFILE is replaced with the name of an empty
700 temporary file, where the filtered data must be written by the command.
701 Note The tempfile mechanism is recommended for Windows systems, where
703 the standard shell I/O redirection operators often have strange
704 effects and may corrupt the contents of your files.
705 This filter mechanism is used internally by the eol extension to trans‐
707 late line ending characters between Windows (CRLF) and Unix (LF) for‐
708 mat. We suggest you use the eol extension for convenience.
709 defaults
711 (defaults are deprecated. Don't use them. Use aliases instead.)
712 Use the [defaults] section to define command defaults, i.e. the default
714 options/arguments to pass to the specified commands.
715 The following example makes hg log run in verbose mode, and hg status
717 show only the modified files, by default:
718 [defaults]
720 log = -v
721 status = -m
722 The actual commands, instead of their aliases, must be used when defin‐
724 ing command defaults. The command defaults will also be applied to the
725 aliases of the commands defined.
726 diff
728 Settings used when displaying diffs. Everything except for unified is a
729 Boolean and defaults to False. See hg help config.annotate for related
730 options for the annotate command.
731 git
733 Use git extended diff format.
735 nobinary
737 Omit git binary patches.
739 nodates
741 Don't include dates in diff headers.
743 noprefix
745 Omit 'a/' and 'b/' prefixes from filenames. Ignored in plain
747 mode.
748 showfunc
750 Show which function each change is in.
752 ignorews
754 Ignore white space when comparing lines.
756 ignorewsamount
758 Ignore changes in the amount of white space.
760 ignoreblanklines
762 Ignore changes whose lines are all blank.
764 unified
766 Number of lines of context to show.
768 word-diff
770 Highlight changed words.
772 email
774 Settings for extensions that send email messages.
775 from
777 Optional. Email address to use in "From" header and SMTP enve‐
779 lope of outgoing messages.
780 to
782 Optional. Comma-separated list of recipients' email addresses.
784 cc
786 Optional. Comma-separated list of carbon copy recipients' email
788 addresses.
789 bcc
791 Optional. Comma-separated list of blind carbon copy recipients'
793 email addresses.
794 method
796 Optional. Method to use to send email messages. If value is smtp
798 (default), use SMTP (see the [smtp] section for configuration).
799 Otherwise, use as name of program to run that acts like sendmail
800 (takes -f option for sender, list of recipients on command line,
801 message on stdin). Normally, setting this to sendmail or
802 /usr/sbin/sendmail is enough to use sendmail to send messages.
803 charsets
805 Optional. Comma-separated list of character sets considered con‐
807 venient for recipients. Addresses, headers, and parts not con‐
808 taining patches of outgoing messages will be encoded in the
809 first character set to which conversion from local encoding
810 ($HGENCODING, ui.fallbackencoding) succeeds. If correct conver‐
811 sion fails, the text in question is sent as is. (default: '')
812 Order of outgoing email character sets:
814 1. us-ascii: always first, regardless of settings
816 2. email.charsets: in order given by user
818 3. ui.fallbackencoding: if not in email.charsets
820 4. $HGENCODING: if not in email.charsets
822 5. utf-8: always last, regardless of settings
824 Email example:
826 [email]
828 from = Joseph User <joe.user@example.com>
829 method = /usr/sbin/sendmail
830 # charsets for western Europeans
831 # us-ascii, utf-8 omitted, as they are tried first and last
832 charsets = iso-8859-1, iso-8859-15, windows-1252
833 extensions
835 Mercurial has an extension mechanism for adding new features. To enable
836 an extension, create an entry for it in this section.
837 If you know that the extension is already in Python's search path, you
839 can give the name of the module, followed by =, with nothing after the
840 =.
841 Otherwise, give a name that you choose, followed by =, followed by the
843 path to the .py file (including the file name extension) that defines
844 the extension.
845 To explicitly disable an extension that is enabled in an hgrc of
847 broader scope, prepend its path with !, as in foo = !/ext/path or foo =
848 ! when path is not supplied.
849 Example for ~/.hgrc:
851 [extensions]
853 # (the churn extension will get loaded from Mercurial's path)
854 churn =
855 # (this extension will get loaded from the file specified)
856 myfeature = ~/.hgext/myfeature.py
857 format
859 Configuration that controls the repository format. Newer format options
860 are more powerful but incompatible with some older versions of Mercu‐
861 rial. Format options are considered at repository initialization only.
862 You need to make a new clone for config change to be taken into
863 account.
864 For more details about repository format and version compatibility, see
866 https://www.mercurial-scm.org/wiki/MissingRequirement
867 usegeneraldelta
869 Enable or disable the "generaldelta" repository format which
871 improves repository compression by allowing "revlog" to store
872 delta against arbitrary revision instead of the previous stored
873 one. This provides significant improvement for repositories with
874 branches.
875 Repositories with this on-disk format require Mercurial version
877 1.9.
878 Enabled by default.
880 dotencode
882 Enable or disable the "dotencode" repository format which
884 enhances the "fncache" repository format (which has to be
885 enabled to use dotencode) to avoid issues with filenames start‐
886 ing with ._ on Mac OS X and spaces on Windows.
887 Repositories with this on-disk format require Mercurial version
889 1.7.
890 Enabled by default.
892 usefncache
894 Enable or disable the "fncache" repository format which enhances
896 the "store" repository format (which has to be enabled to use
897 fncache) to allow longer filenames and avoids using Windows
898 reserved names, e.g. "nul".
899 Repositories with this on-disk format require Mercurial version
901 1.1.
902 Enabled by default.
904 usestore
906 Enable or disable the "store" repository format which improves
908 compatibility with systems that fold case or otherwise mangle
909 filenames. Disabling this option will allow you to store longer
910 filenames in some situations at the expense of compatibility.
911 Repositories with this on-disk format require Mercurial version
913 0.9.4.
914 Enabled by default.
916 sparse-revlog
918 Enable or disable the sparse-revlog delta strategy. This format
920 improves delta re-use inside revlog. For very branchy reposito‐
921 ries, it results in a smaller store. For repositories with many
922 revisions, it also helps performance (by using shortened delta
923 chains.)
924 Repositories with this on-disk format require Mercurial version
926 4.7
927 Enabled by default.
929 revlog-compression
931 Compression algorithm used by revlog. Supported value are zlib
933 and zstd. The zlib engine is the historical default of Mercu‐
934 rial. zstd is a newer format that is usually a net win over zlib
935 operating faster at better compression rate. Use zstd to reduce
936 CPU usage.
937 On some system, Mercurial installation may lack zstd supports.
939 Default is zlib.
940 bookmarks-in-store
942 Store bookmarks in .hg/store/. This means that bookmarks are
944 shared when using hg share regardless of the -B option.
945 Repositories with this on-disk format require Mercurial version
947 5.1.
948 Disabled by default.
950 graph
952 Web graph view configuration. This section let you change graph ele‐
953 ments display properties by branches, for instance to make the default
954 branch stand out.
955 Each line has the following format:
957 <branch>.<argument> = <value>
959 where <branch> is the name of the branch being customized. Example:
961 [graph]
963 # 2px width
964 default.width = 2
965 # red color
966 default.color = FF0000
967 Supported arguments:
969 width
971 Set branch edges width in pixels.
973 color
975 Set branch edges color in hexadecimal RGB notation.
977 hooks
979 Commands or Python functions that get automatically executed by various
980 actions such as starting or finishing a commit. Multiple hooks can be
981 run for the same action by appending a suffix to the action. Overriding
982 a site-wide hook can be done by changing its value or setting it to an
983 empty string. Hooks can be prioritized by adding a prefix of priority.
984 to the hook name on a new line and setting the priority. The default
985 priority is 0.
986 Example .hg/hgrc:
988 [hooks]
990 # update working directory after adding changesets
991 changegroup.update = hg update
992 # do not use the site-wide hook
993 incoming =
994 incoming.email = /my/email/hook
995 incoming.autobuild = /my/build/hook
996 # force autobuild hook to run before other incoming hooks
997 priority.incoming.autobuild = 1
998 Most hooks are run with environment variables set that give useful
1000 additional information. For each hook below, the environment variables
1001 it is passed are listed with names in the form $HG_foo. The $HG_HOOK‐
1002 TYPE and $HG_HOOKNAME variables are set for all hooks. They contain
1003 the type of hook which triggered the run and the full name of the hook
1004 in the config, respectively. In the example above, this will be
1005 $HG_HOOKTYPE=incoming and $HG_HOOKNAME=incoming.email.
1006 Some basic Unix syntax can be enabled for portability, including $VAR
1008 and ${VAR} style variables. A ~ followed by \ or / will be expanded to
1009 %USERPROFILE% to simulate a subset of tilde expansion on Unix. To use
1010 a literal $ or ~, it must be escaped with a back slash or inside of a
1011 strong quote. Strong quotes will be replaced by double quotes after
1012 processing.
1013 This feature is enabled by adding a prefix of tonative. to the hook
1015 name on a new line, and setting it to True. For example:
1016 [hooks]
1018 incoming.autobuild = /my/build/hook
1019 # enable translation to cmd.exe syntax for autobuild hook
1020 tonative.incoming.autobuild = True
1021 changegroup
1023 Run after a changegroup has been added via push, pull or unbun‐
1025 dle. The ID of the first new changeset is in $HG_NODE and last
1026 is in $HG_NODE_LAST. The URL from which changes came is in
1027 $HG_URL.
1028 commit
1030 Run after a changeset has been created in the local repository.
1032 The ID of the newly created changeset is in $HG_NODE. Parent
1033 changeset IDs are in $HG_PARENT1 and $HG_PARENT2.
1034 incoming
1036 Run after a changeset has been pulled, pushed, or unbundled into
1038 the local repository. The ID of the newly arrived changeset is
1039 in $HG_NODE. The URL that was source of the changes is in
1040 $HG_URL.
1041 outgoing
1043 Run after sending changes from the local repository to another.
1045 The ID of first changeset sent is in $HG_NODE. The source of
1046 operation is in $HG_SOURCE. Also see hg help config.hooks.pre‐
1047 outgoing.
1048 post-<command>
1050 Run after successful invocations of the associated command. The
1052 contents of the command line are passed as $HG_ARGS and the
1053 result code in $HG_RESULT. Parsed command line arguments are
1054 passed as $HG_PATS and $HG_OPTS. These contain string represen‐
1055 tations of the python data internally passed to <command>.
1056 $HG_OPTS is a dictionary of options (with unspecified options
1057 set to their defaults). $HG_PATS is a list of arguments. Hook
1058 failure is ignored.
1059 fail-<command>
1061 Run after a failed invocation of an associated command. The con‐
1063 tents of the command line are passed as $HG_ARGS. Parsed command
1064 line arguments are passed as $HG_PATS and $HG_OPTS. These con‐
1065 tain string representations of the python data internally passed
1066 to <command>. $HG_OPTS is a dictionary of options (with unspeci‐
1067 fied options set to their defaults). $HG_PATS is a list of argu‐
1068 ments. Hook failure is ignored.
1069 pre-<command>
1071 Run before executing the associated command. The contents of the
1073 command line are passed as $HG_ARGS. Parsed command line argu‐
1074 ments are passed as $HG_PATS and $HG_OPTS. These contain string
1075 representations of the data internally passed to <command>.
1076 $HG_OPTS is a dictionary of options (with unspecified options
1077 set to their defaults). $HG_PATS is a list of arguments. If the
1078 hook returns failure, the command doesn't execute and Mercurial
1079 returns the failure code.
1080 prechangegroup
1082 Run before a changegroup is added via push, pull or unbundle.
1084 Exit status 0 allows the changegroup to proceed. A non-zero sta‐
1085 tus will cause the push, pull or unbundle to fail. The URL from
1086 which changes will come is in $HG_URL.
1087 precommit
1089 Run before starting a local commit. Exit status 0 allows the
1091 commit to proceed. A non-zero status will cause the commit to
1092 fail. Parent changeset IDs are in $HG_PARENT1 and $HG_PARENT2.
1093 prelistkeys
1095 Run before listing pushkeys (like bookmarks) in the repository.
1097 A non-zero status will cause failure. The key namespace is in
1098 $HG_NAMESPACE.
1099 preoutgoing
1101 Run before collecting changes to send from the local repository
1103 to another. A non-zero status will cause failure. This lets you
1104 prevent pull over HTTP or SSH. It can also prevent propagating
1105 commits (via local pull, push (outbound) or bundle commands),
1106 but not completely, since you can just copy files instead. The
1107 source of operation is in $HG_SOURCE. If "serve", the operation
1108 is happening on behalf of a remote SSH or HTTP repository. If
1109 "push", "pull" or "bundle", the operation is happening on behalf
1110 of a repository on same system.
1111 prepushkey
1113 Run before a pushkey (like a bookmark) is added to the reposi‐
1115 tory. A non-zero status will cause the key to be rejected. The
1116 key namespace is in $HG_NAMESPACE, the key is in $HG_KEY, the
1117 old value (if any) is in $HG_OLD, and the new value is in
1118 $HG_NEW.
1119 pretag
1121 Run before creating a tag. Exit status 0 allows the tag to be
1123 created. A non-zero status will cause the tag to fail. The ID of
1124 the changeset to tag is in $HG_NODE. The name of tag is in
1125 $HG_TAG. The tag is local if $HG_LOCAL=1, or in the repository
1126 if $HG_LOCAL=0.
1127 pretxnopen
1129 Run before any new repository transaction is open. The reason
1131 for the transaction will be in $HG_TXNNAME, and a unique identi‐
1132 fier for the transaction will be in HG_TXNID. A non-zero status
1133 will prevent the transaction from being opened.
1134 pretxnclose
1136 Run right before the transaction is actually finalized. Any
1138 repository change will be visible to the hook program. This lets
1139 you validate the transaction content or change it. Exit status 0
1140 allows the commit to proceed. A non-zero status will cause the
1141 transaction to be rolled back. The reason for the transaction
1142 opening will be in $HG_TXNNAME, and a unique identifier for the
1143 transaction will be in HG_TXNID. The rest of the available data
1144 will vary according the transaction type. New changesets will
1145 add $HG_NODE (the ID of the first added changeset),
1146 $HG_NODE_LAST (the ID of the last added changeset), $HG_URL and
1147 $HG_SOURCE variables. Bookmark and phase changes will set
1148 HG_BOOKMARK_MOVED and HG_PHASES_MOVED to 1 respectively, etc.
1149 pretxnclose-bookmark
1151 Run right before a bookmark change is actually finalized. Any
1153 repository change will be visible to the hook program. This lets
1154 you validate the transaction content or change it. Exit status 0
1155 allows the commit to proceed. A non-zero status will cause the
1156 transaction to be rolled back. The name of the bookmark will be
1157 available in $HG_BOOKMARK, the new bookmark location will be
1158 available in $HG_NODE while the previous location will be avail‐
1159 able in $HG_OLDNODE. In case of a bookmark creation $HG_OLDNODE
1160 will be empty. In case of deletion $HG_NODE will be empty. In
1161 addition, the reason for the transaction opening will be in
1162 $HG_TXNNAME, and a unique identifier for the transaction will be
1163 in HG_TXNID.
1164 pretxnclose-phase
1166 Run right before a phase change is actually finalized. Any
1168 repository change will be visible to the hook program. This lets
1169 you validate the transaction content or change it. Exit status 0
1170 allows the commit to proceed. A non-zero status will cause the
1171 transaction to be rolled back. The hook is called multiple
1172 times, once for each revision affected by a phase change. The
1173 affected node is available in $HG_NODE, the phase in $HG_PHASE
1174 while the previous $HG_OLDPHASE. In case of new node, $HG_OLD‐
1175 PHASE will be empty. In addition, the reason for the transac‐
1176 tion opening will be in $HG_TXNNAME, and a unique identifier for
1177 the transaction will be in HG_TXNID. The hook is also run for
1178 newly added revisions. In this case the $HG_OLDPHASE entry will
1179 be empty.
1180 txnclose
1182 Run after any repository transaction has been committed. At this
1184 point, the transaction can no longer be rolled back. The hook
1185 will run after the lock is released. See hg help con‐
1186 fig.hooks.pretxnclose for details about available variables.
1187 txnclose-bookmark
1189 Run after any bookmark change has been committed. At this point,
1191 the transaction can no longer be rolled back. The hook will run
1192 after the lock is released. See hg help config.hooks.pretxn‐
1193 close-bookmark for details about available variables.
1194 txnclose-phase
1196 Run after any phase change has been committed. At this point,
1198 the transaction can no longer be rolled back. The hook will run
1199 after the lock is released. See hg help config.hooks.pretxn‐
1200 close-phase for details about available variables.
1201 txnabort
1203 Run when a transaction is aborted. See hg help con‐
1205 fig.hooks.pretxnclose for details about available variables.
1206 pretxnchangegroup
1208 Run after a changegroup has been added via push, pull or unbun‐
1210 dle, but before the transaction has been committed. The change‐
1211 group is visible to the hook program. This allows validation of
1212 incoming changes before accepting them. The ID of the first new
1213 changeset is in $HG_NODE and last is in $HG_NODE_LAST. Exit sta‐
1214 tus 0 allows the transaction to commit. A non-zero status will
1215 cause the transaction to be rolled back, and the push, pull or
1216 unbundle will fail. The URL that was the source of changes is in
1217 $HG_URL.
1218 pretxncommit
1220 Run after a changeset has been created, but before the transac‐
1222 tion is committed. The changeset is visible to the hook program.
1223 This allows validation of the commit message and changes. Exit
1224 status 0 allows the commit to proceed. A non-zero status will
1225 cause the transaction to be rolled back. The ID of the new
1226 changeset is in $HG_NODE. The parent changeset IDs are in
1227 $HG_PARENT1 and $HG_PARENT2.
1228 preupdate
1230 Run before updating the working directory. Exit status 0 allows
1232 the update to proceed. A non-zero status will prevent the
1233 update. The changeset ID of first new parent is in $HG_PARENT1.
1234 If updating to a merge, the ID of second new parent is in
1235 $HG_PARENT2.
1236 listkeys
1238 Run after listing pushkeys (like bookmarks) in the repository.
1240 The key namespace is in $HG_NAMESPACE. $HG_VALUES is a dictio‐
1241 nary containing the keys and values.
1242 pushkey
1244 Run after a pushkey (like a bookmark) is added to the reposi‐
1246 tory. The key namespace is in $HG_NAMESPACE, the key is in
1247 $HG_KEY, the old value (if any) is in $HG_OLD, and the new value
1248 is in $HG_NEW.
1249 tag
1251 Run after a tag is created. The ID of the tagged changeset is in
1253 $HG_NODE. The name of tag is in $HG_TAG. The tag is local if
1254 $HG_LOCAL=1, or in the repository if $HG_LOCAL=0.
1255 update
1257 Run after updating the working directory. The changeset ID of
1259 first new parent is in $HG_PARENT1. If updating to a merge, the
1260 ID of second new parent is in $HG_PARENT2. If the update suc‐
1261 ceeded, $HG_ERROR=0. If the update failed (e.g. because con‐
1262 flicts were not resolved), $HG_ERROR=1.
1263 Note It is generally better to use standard hooks rather than the
1265 generic pre- and post- command hooks, as they are guaranteed to
1266 be called in the appropriate contexts for influencing transac‐
1267 tions. Also, hooks like "commit" will be called in all contexts
1268 that generate a commit (e.g. tag) and not just the commit com‐
1269 mand.
1270 Note Environment variables with empty values may not be passed to
1272 hooks on platforms such as Windows. As an example, $HG_PARENT2
1273 will have an empty value under Unix-like platforms for non-merge
1274 changesets, while it will not be available at all under Windows.
1275 The syntax for Python hooks is as follows:
1277 hookname = python:modulename.submodule.callable
1279 hookname = python:/path/to/python/module.py:callable
1280 Python hooks are run within the Mercurial process. Each hook is called
1282 with at least three keyword arguments: a ui object (keyword ui), a
1283 repository object (keyword repo), and a hooktype keyword that tells
1284 what kind of hook is used. Arguments listed as environment variables
1285 above are passed as keyword arguments, with no HG_ prefix, and names in
1286 lower case.
1287 If a Python hook returns a "true" value or raises an exception, this is
1289 treated as a failure.
1290 hostfingerprints
1292 (Deprecated. Use [hostsecurity]'s fingerprints options instead.)
1293 Fingerprints of the certificates of known HTTPS servers.
1295 A HTTPS connection to a server with a fingerprint configured here will
1297 only succeed if the servers certificate matches the fingerprint. This
1298 is very similar to how ssh known hosts works.
1299 The fingerprint is the SHA-1 hash value of the DER encoded certificate.
1301 Multiple values can be specified (separated by spaces or commas). This
1302 can be used to define both old and new fingerprints while a host tran‐
1303 sitions to a new certificate.
1304 The CA chain and web.cacerts is not used for servers with a finger‐
1306 print.
1307 For example:
1309 [hostfingerprints]
1311 hg.intevation.de = fc:e2:8d:d9:51:cd:cb:c1:4d:18:6b:b7:44:8d:49:72:57:e6:cd:33
1312 hg.intevation.org = fc:e2:8d:d9:51:cd:cb:c1:4d:18:6b:b7:44:8d:49:72:57:e6:cd:33
1313 hostsecurity
1315 Used to specify global and per-host security settings for connecting to
1316 other machines.
1317 The following options control default behavior for all hosts.
1319 ciphers
1321 Defines the cryptographic ciphers to use for connections.
1323 Value must be a valid OpenSSL Cipher List Format as documented
1325 at
1326 https://www.openssl.org/docs/manmaster/apps/ciphers.html#CIPHER-LIST-FORMAT
1327 .
1328 This setting is for advanced users only. Setting to incorrect
1330 values can significantly lower connection security or decrease
1331 performance. You have been warned.
1332 This option requires Python 2.7.
1334 minimumprotocol
1336 Defines the minimum channel encryption protocol to use.
1338 By default, the highest version of TLS supported by both client
1340 and server is used.
1341 Allowed values are: tls1.0, tls1.1, tls1.2.
1343 When running on an old Python version, only tls1.0 is allowed
1345 since old versions of Python only support up to TLS 1.0.
1346 When running a Python that supports modern TLS versions, the
1348 default is tls1.1. tls1.0 can still be used to allow TLS 1.0.
1349 However, this weakens security and should only be used as a fea‐
1350 ture of last resort if a server does not support TLS 1.1+.
1351 Options in the [hostsecurity] section can have the form hostname:set‐
1353 ting. This allows multiple settings to be defined on a per-host basis.
1354 The following per-host settings can be defined.
1356 ciphers
1358 This behaves like ciphers as described above except it only
1360 applies to the host on which it is defined.
1361 fingerprints
1363 A list of hashes of the DER encoded peer/remote certificate.
1365 Values have the form algorithm:fingerprint. e.g.
1366 sha256:c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2.
1367 In addition, colons (:) can appear in the fingerprint part.
1368 The following algorithms/prefixes are supported: sha1, sha256,
1370 sha512.
1371 Use of sha256 or sha512 is preferred.
1373 If a fingerprint is specified, the CA chain is not validated for
1375 this host and Mercurial will require the remote certificate to
1376 match one of the fingerprints specified. This means if the
1377 server updates its certificate, Mercurial will abort until a new
1378 fingerprint is defined. This can provide stronger security than
1379 traditional CA-based validation at the expense of convenience.
1380 This option takes precedence over verifycertsfile.
1382 minimumprotocol
1384 This behaves like minimumprotocol as described above except it
1386 only applies to the host on which it is defined.
1387 verifycertsfile
1389 Path to file a containing a list of PEM encoded certificates
1391 used to verify the server certificate. Environment variables and
1392 ~user constructs are expanded in the filename.
1393 The server certificate or the certificate's certificate author‐
1395 ity (CA) must match a certificate from this file or certificate
1396 verification will fail and connections to the server will be
1397 refused.
1398 If defined, only certificates provided by this file will be
1400 used: web.cacerts and any system/default certificates will not
1401 be used.
1402 This option has no effect if the per-host fingerprints option is
1404 set.
1405 The format of the file is as follows:
1407 -----BEGIN CERTIFICATE-----
1409 ... (certificate in base64 PEM encoding) ...
1410 -----END CERTIFICATE-----
1411 -----BEGIN CERTIFICATE-----
1412 ... (certificate in base64 PEM encoding) ...
1413 -----END CERTIFICATE-----
1414 For example:
1416 [hostsecurity]
1418 hg.example.com:fingerprints = sha256:c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2
1419 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
1420 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
1421 foo.example.com:verifycertsfile = /etc/ssl/trusted-ca-certs.pem
1422 To change the default minimum protocol version to TLS 1.2 but to allow
1424 TLS 1.1 when connecting to hg.example.com:
1425 [hostsecurity]
1427 minimumprotocol = tls1.2
1428 hg.example.com:minimumprotocol = tls1.1
1429 http_proxy
1431 Used to access web-based Mercurial repositories through a HTTP proxy.
1432 host
1434 Host name and (optional) port of the proxy server, for example
1436 "myproxy:8000".
1437 no
1439 Optional. Comma-separated list of host names that should bypass
1441 the proxy.
1442 passwd
1444 Optional. Password to authenticate with at the proxy server.
1446 user
1448 Optional. User name to authenticate with at the proxy server.
1450 always
1452 Optional. Always use the proxy, even for localhost and any
1454 entries in http_proxy.no. (default: False)
1455 http
1457 Used to configure access to Mercurial repositories via HTTP.
1458 timeout
1460 If set, blocking operations will timeout after that many sec‐
1462 onds. (default: None)
1463 merge
1465 This section specifies behavior during merges and updates.
1466 checkignored
1468 Controls behavior when an ignored file on disk has the same name
1470 as a tracked file in the changeset being merged or updated to,
1471 and has different contents. Options are abort, warn and ignore.
1472 With abort, abort on such files. With warn, warn on such files
1473 and back them up as .orig. With ignore, don't print a warning
1474 and back them up as .orig. (default: abort)
1475 checkunknown
1477 Controls behavior when an unknown file that isn't ignored has
1479 the same name as a tracked file in the changeset being merged or
1480 updated to, and has different contents. Similar to merge.check‐
1481 ignored, except for files that are not ignored. (default: abort)
1482 on-failure
1484 When set to continue (the default), the merge process attempts
1486 to merge all unresolved files using the merge chosen tool,
1487 regardless of whether previous file merge attempts during the
1488 process succeeded or not. Setting this to prompt will prompt
1489 after any merge failure continue or halt the merge process. Set‐
1490 ting this to halt will automatically halt the merge process on
1491 any merge tool failure. The merge process can be restarted by
1492 using the resolve command. When a merge is halted, the reposi‐
1493 tory is left in a normal unresolved merge state. (default: con‐
1494 tinue)
1495 strict-capability-check
1497 Whether capabilities of internal merge tools are checked
1499 strictly or not, while examining rules to decide merge tool to
1500 be used. (default: False)
1501 merge-patterns
1503 This section specifies merge tools to associate with particular file
1504 patterns. Tools matched here will take precedence over the default
1505 merge tool. Patterns are globs by default, rooted at the repository
1506 root.
1507 Example:
1509 [merge-patterns]
1511 **.c = kdiff3
1512 **.jpg = myimgmerge
1513 merge-tools
1515 This section configures external merge tools to use for file-level
1516 merges. This section has likely been preconfigured at install time.
1517 Use hg config merge-tools to check the existing configuration. Also
1518 see hg help merge-tools for more details.
1519 Example ~/.hgrc:
1521 [merge-tools]
1523 # Override stock tool location
1524 kdiff3.executable = ~/bin/kdiff3
1525 # Specify command line
1526 kdiff3.args = $base $local $other -o $output
1527 # Give higher priority
1528 kdiff3.priority = 1
1529 # Changing the priority of preconfigured tool
1531 meld.priority = 0
1532 # Disable a preconfigured tool
1534 vimdiff.disabled = yes
1535 # Define new tool
1537 myHtmlTool.args = -m $local $other $base $output
1538 myHtmlTool.regkey = Software\FooSoftware\HtmlMerge
1539 myHtmlTool.priority = 1
1540 Supported arguments:
1542 priority
1544 The priority in which to evaluate this tool. (default: 0)
1546 executable
1548 Either just the name of the executable or its pathname.
1550 On Windows, the path can use environment variables with ${Pro‐
1552 gramFiles} syntax.
1553 (default: the tool name)
1555 args
1557 The arguments to pass to the tool executable. You can refer to
1559 the files being merged as well as the output file through these
1560 variables: $base, $local, $other, $output.
1561 The meaning of $local and $other can vary depending on which
1563 action is being performed. During an update or merge, $local
1564 represents the original state of the file, while $other repre‐
1565 sents the commit you are updating to or the commit you are merg‐
1566 ing with. During a rebase, $local represents the destination of
1567 the rebase, and $other represents the commit being rebased.
1568 Some operations define custom labels to assist with identifying
1570 the revisions, accessible via $labellocal, $labelother, and
1571 $labelbase. If custom labels are not available, these will be
1572 local, other, and base, respectively. (default: $local $base
1573 $other)
1574 premerge
1576 Attempt to run internal non-interactive 3-way merge tool before
1578 launching external tool. Options are true, false, keep or
1579 keep-merge3. The keep option will leave markers in the file if
1580 the premerge fails. The keep-merge3 will do the same but include
1581 information about the base of the merge in the marker (see
1582 internal :merge3 in hg help merge-tools). (default: True)
1583 binary
1585 This tool can merge binary files. (default: False, unless tool
1587 was selected by file pattern match)
1588 symlink
1590 This tool can merge symlinks. (default: False)
1592 check
1594 A list of merge success-checking options:
1596 changed
1598 Ask whether merge was successful when the merged file
1600 shows no changes.
1601 conflicts
1603 Check whether there are conflicts even though the tool
1605 reported success.
1606 prompt
1608 Always prompt for merge success, regardless of success
1610 reported by tool.
1611 fixeol
1613 Attempt to fix up EOL changes caused by the merge tool.
1615 (default: False)
1616 gui
1618 This tool requires a graphical interface to run. (default:
1620 False)
1621 mergemarkers
1623 Controls whether the labels passed via $labellocal, $labelother,
1625 and $labelbase are detailed (respecting mergemarkertemplate) or
1626 basic. If premerge is keep or keep-merge3, the conflict markers
1627 generated during premerge will be detailed if either this option
1628 or the corresponding option in the [ui] section is detailed.
1629 (default: basic)
1630 mergemarkertemplate
1632 This setting can be used to override mergemarkertemplate from
1634 the [ui] section on a per-tool basis; this applies to the
1635 $label-prefixed variables and to the conflict markers that are
1636 generated if premerge is keep` or ``keep-merge3. See the corre‐
1637 sponding variable in [ui] for more information.
1638 regkey
1640 Windows registry key which describes install location of this
1642 tool. Mercurial will search for this key first under HKEY_CUR‐
1643 RENT_USER and then under HKEY_LOCAL_MACHINE. (default: None)
1644 regkeyalt
1646 An alternate Windows registry key to try if the first key is not
1648 found. The alternate key uses the same regname and regappend
1649 semantics of the primary key. The most common use for this key
1650 is to search for 32bit applications on 64bit operating systems.
1651 (default: None)
1652 regname
1654 Name of value to read from specified registry key. (default:
1656 the unnamed (default) value)
1657 regappend
1659 String to append to the value read from the registry, typically
1661 the executable name of the tool. (default: None)
1662 pager
1664 Setting used to control when to paginate and with what external tool.
1665 See hg help pager for details.
1666 pager
1668 Define the external tool used as pager.
1670 If no pager is set, Mercurial uses the environment variable
1672 $PAGER. If neither pager.pager, nor $PAGER is set, a default
1673 pager will be used, typically less on Unix and more on Windows.
1674 Example:
1675 [pager]
1677 pager = less -FRX
1678 ignore
1680 List of commands to disable the pager for. Example:
1682 [pager]
1684 ignore = version, help, update
1685 patch
1687 Settings used when applying patches, for instance through the 'import'
1688 command or with Mercurial Queues extension.
1689 eol
1691 When set to 'strict' patch content and patched files end of
1693 lines are preserved. When set to lf or crlf, both files end of
1694 lines are ignored when patching and the result line endings are
1695 normalized to either LF (Unix) or CRLF (Windows). When set to
1696 auto, end of lines are again ignored while patching but line
1697 endings in patched files are normalized to their original set‐
1698 ting on a per-file basis. If target file does not exist or has
1699 no end of line, patch line endings are preserved. (default:
1700 strict)
1701 fuzz
1703 The number of lines of 'fuzz' to allow when applying patches.
1705 This controls how much context the patcher is allowed to ignore
1706 when trying to apply a patch. (default: 2)
1707 paths
1709 Assigns symbolic names and behavior to repositories.
1710 Options are symbolic names defining the URL or directory that is the
1712 location of the repository. Example:
1713 [paths]
1715 my_server = https://example.com/my_repo
1716 local_path = /home/me/repo
1717 These symbolic names can be used from the command line. To pull from
1719 my_server: hg pull my_server. To push to local_path: hg push local_path
1720 .
1721 Options containing colons (:) denote sub-options that can influence
1723 behavior for that specific path. Example:
1724 [paths]
1726 my_server = https://example.com/my_path
1727 my_server:pushurl = ssh://example.com/my_path
1728 The following sub-options can be defined:
1730 pushurl
1732 The URL to use for push operations. If not defined, the location
1734 defined by the path's main entry is used.
1735 pushrev
1737 A revset defining which revisions to push by default.
1739 When hg push is executed without a -r argument, the revset
1741 defined by this sub-option is evaluated to determine what to
1742 push.
1743 For example, a value of . will push the working directory's
1745 revision by default.
1746 Revsets specifying bookmarks will not result in the bookmark
1748 being pushed.
1749 The following special named paths exist:
1751 default
1753 The URL or directory to use when no source or remote is speci‐
1755 fied.
1756 hg clone will automatically define this path to the location the
1758 repository was cloned from.
1759 default-push
1761 (deprecated) The URL or directory for the default hg push loca‐
1763 tion. default:pushurl should be used instead.
1764 phases
1766 Specifies default handling of phases. See hg help phases for more
1767 information about working with phases.
1768 publish
1770 Controls draft phase behavior when working as a server. When
1772 true, pushed changesets are set to public in both client and
1773 server and pulled or cloned changesets are set to public in the
1774 client. (default: True)
1775 new-commit
1777 Phase of newly-created commits. (default: draft)
1779 checksubrepos
1781 Check the phase of the current revision of each subrepository.
1783 Allowed values are "ignore", "follow" and "abort". For settings
1784 other than "ignore", the phase of the current revision of each
1785 subrepository is checked before committing the parent reposi‐
1786 tory. If any of those phases is greater than the phase of the
1787 parent repository (e.g. if a subrepo is in a "secret" phase
1788 while the parent repo is in "draft" phase), the commit is either
1789 aborted (if checksubrepos is set to "abort") or the higher phase
1790 is used for the parent repository commit (if set to "follow").
1791 (default: follow)
1792 profiling
1794 Specifies profiling type, format, and file output. Two profilers are
1795 supported: an instrumenting profiler (named ls), and a sampling pro‐
1796 filer (named stat).
1797 In this section description, 'profiling data' stands for the raw data
1799 collected during profiling, while 'profiling report' stands for a sta‐
1800 tistical text report generated from the profiling data.
1801 enabled
1803 Enable the profiler. (default: false)
1805 This is equivalent to passing --profile on the command line.
1807 type
1809 The type of profiler to use. (default: stat)
1811 ls
1813 Use Python's built-in instrumenting profiler. This pro‐
1815 filer works on all platforms, but each line number it
1816 reports is the first line of a function. This restriction
1817 makes it difficult to identify the expensive parts of a
1818 non-trivial function.
1819 stat
1821 Use a statistical profiler, statprof. This profiler is
1823 most useful for profiling commands that run for longer
1824 than about 0.1 seconds.
1825 format
1827 Profiling format. Specific to the ls instrumenting profiler.
1829 (default: text)
1830 text
1832 Generate a profiling report. When saving to a file, it
1834 should be noted that only the report is saved, and the
1835 profiling data is not kept.
1836 kcachegrind
1838 Format profiling data for kcachegrind use: when saving to
1840 a file, the generated file can directly be loaded into
1841 kcachegrind.
1842 statformat
1844 Profiling format for the stat profiler. (default: hotpath)
1846 hotpath
1848 Show a tree-based display containing the hot path of exe‐
1850 cution (where most time was spent).
1851 bymethod
1853 Show a table of methods ordered by how frequently they
1855 are active.
1856 byline
1858 Show a table of lines in files ordered by how frequently
1860 they are active.
1861 json
1863 Render profiling data as JSON.
1865 frequency
1867 Sampling frequency. Specific to the stat sampling profiler.
1869 (default: 1000)
1870 output
1872 File path where profiling data or report should be saved. If the
1874 file exists, it is replaced. (default: None, data is printed on
1875 stderr)
1876 sort
1878 Sort field. Specific to the ls instrumenting profiler. One of
1880 callcount, reccallcount, totaltime and inlinetime. (default:
1881 inlinetime)
1882 time-track
1884 Control if the stat profiler track cpu or real time. (default:
1886 cpu on Windows, otherwise real)
1887 limit
1889 Number of lines to show. Specific to the ls instrumenting pro‐
1891 filer. (default: 30)
1892 nested
1894 Show at most this number of lines of drill-down info after each
1896 main entry. This can help explain the difference between Total
1897 and Inline. Specific to the ls instrumenting profiler.
1898 (default: 0)
1899 showmin
1901 Minimum fraction of samples an entry must have for it to be dis‐
1903 played. Can be specified as a float between 0.0 and 1.0 or can
1904 have a % afterwards to allow values up to 100. e.g. 5%.
1905 Only used by the stat profiler.
1907 For the hotpath format, default is 0.05. For the chrome format,
1909 default is 0.005.
1910 The option is unused on other formats.
1912 showmax
1914 Maximum fraction of samples an entry can have before it is
1916 ignored in display. Values format is the same as showmin.
1917 Only used by the stat profiler.
1919 For the chrome format, default is 0.999.
1921 The option is unused on other formats.
1923 showtime
1925 Show time taken as absolute durations, in addition to percent‐
1927 ages. Only used by the hotpath format. (default: true)
1928 progress
1930 Mercurial commands can draw progress bars that are as informative as
1931 possible. Some progress bars only offer indeterminate information,
1932 while others have a definite end point.
1933 debug
1935 Whether to print debug info when updating the progress bar.
1937 (default: False)
1938 delay
1940 Number of seconds (float) before showing the progress bar.
1942 (default: 3)
1943 changedelay
1945 Minimum delay before showing a new topic. When set to less than
1947 3 * refresh, that value will be used instead. (default: 1)
1948 estimateinterval
1950 Maximum sampling interval in seconds for speed and estimated
1952 time calculation. (default: 60)
1953 refresh
1955 Time in seconds between refreshes of the progress bar. (default:
1957 0.1)
1958 format
1960 Format of the progress bar.
1962 Valid entries for the format field are topic, bar, number, unit,
1964 estimate, speed, and item. item defaults to the last 20 charac‐
1965 ters of the item, but this can be changed by adding either
1966 -<num> which would take the last num characters, or +<num> for
1967 the first num characters.
1968 (default: topic bar number estimate)
1970 width
1972 If set, the maximum width of the progress information (that is,
1974 min(width, term width) will be used).
1975 clear-complete
1977 Clear the progress bar after it's done. (default: True)
1979 disable
1981 If true, don't show a progress bar.
1983 assume-tty
1985 If true, ALWAYS show a progress bar, unless disable is given.
1987 rebase
1989 evolution.allowdivergence
1990 Default to False, when True allow creating divergence when per‐
1992 forming rebase of obsolete changesets.
1993 revsetalias
1995 Alias definitions for revsets. See hg help revsets for details.
1996 rewrite
1998 backup-bundle
1999 Whether to save stripped changesets to a bundle file. (default:
2001 True)
2002 update-timestamp
2004 If true, updates the date and time of the changeset to current.
2006 It is only applicable for hg amend, hg commit --amend and hg
2007 uncommit in the current version.
2008 storage
2010 Control the strategy Mercurial uses internally to store history.
2011 Options in this category impact performance and repository size.
2012 revlog.optimize-delta-parent-choice
2014 When storing a merge revision, both parents will be equally con‐
2016 sidered as a possible delta base. This results in better delta
2017 selection and improved revlog compression. This option is
2018 enabled by default.
2019 Turning this option off can result in large increase of reposi‐
2021 tory size for repository with many merges.
2022 revlog.reuse-external-delta-parent
2024 Control the order in which delta parents are considered when
2026 adding new revisions from an external source. (typically: apply
2027 bundle from hg pull or hg push).
2028 New revisions are usually provided as a delta against other
2030 revisions. By default, Mercurial will try to reuse this delta
2031 first, therefore using the same "delta parent" as the source.
2032 Directly using delta's from the source reduces CPU usage and
2033 usually speeds up operation. However, in some case, the source
2034 might have sub-optimal delta bases and forcing their reevalua‐
2035 tion is useful. For example, pushes from an old client could
2036 have sub-optimal delta's parent that the server want to opti‐
2037 mize. (lack of general delta, bad parents, choice, lack of
2038 sparse-revlog, etc).
2039 This option is enabled by default. Turning it off will ensure
2041 bad delta parent choices from older client do not propagate to
2042 this repository, at the cost of a small increase in CPU consump‐
2043 tion.
2044 Note: this option only control the order in which delta parents
2046 are considered. Even when disabled, the existing delta from the
2047 source will be reused if the same delta parent is selected.
2048 revlog.reuse-external-delta
2050 Control the reuse of delta from external source. (typically:
2052 apply bundle from hg pull or hg push).
2053 New revisions are usually provided as a delta against another
2055 revision. By default, Mercurial will not recompute the same
2056 delta again, trusting externally provided deltas. There have
2057 been rare cases of small adjustment to the diffing algorithm in
2058 the past. So in some rare case, recomputing delta provided by
2059 ancient clients can provides better results. Disabling this
2060 option means going through a full delta recomputation for all
2061 incoming revisions. It means a large increase in CPU usage and
2062 will slow operations down.
2063 This option is enabled by default. When disabled, it also dis‐
2065 ables the related storage.revlog.reuse-external-delta-parent
2066 option.
2067 revlog.zlib.level
2069 Zlib compression level used when storing data into the reposi‐
2071 tory. Accepted Value range from 1 (lowest compression) to 9
2072 (highest compression). Zlib default value is 6.
2073 revlog.zstd.level
2075 zstd compression level used when storing data into the reposi‐
2077 tory. Accepted Value range from 1 (lowest compression) to 22
2078 (highest compression). (default 3)
2079 server
2081 Controls generic server settings.
2082 bookmarks-pushkey-compat
2084 Trigger pushkey hook when being pushed bookmark updates. This
2086 config exist for compatibility purpose (default to True)
2087 If you use pushkey and pre-pushkey hooks to control bookmark
2089 movement we recommend you migrate them to txnclose-bookmark and
2090 pretxnclose-bookmark.
2091 compressionengines
2093 List of compression engines and their relative priority to
2095 advertise to clients.
2096 The order of compression engines determines their priority, the
2098 first having the highest priority. If a compression engine is
2099 not listed here, it won't be advertised to clients.
2100 If not set (the default), built-in defaults are used. Run hg
2102 debuginstall to list available compression engines and their
2103 default wire protocol priority.
2104 Older Mercurial clients only support zlib compression and this
2106 setting has no effect for legacy clients.
2107 uncompressed
2109 Whether to allow clients to clone a repository using the uncom‐
2111 pressed streaming protocol. This transfers about 40% more data
2112 than a regular clone, but uses less memory and CPU on both
2113 server and client. Over a LAN (100 Mbps or better) or a very
2114 fast WAN, an uncompressed streaming clone is a lot faster (~10x)
2115 than a regular clone. Over most WAN connections (anything slower
2116 than about 6 Mbps), uncompressed streaming is slower, because of
2117 the extra data transfer overhead. This mode will also temporar‐
2118 ily hold the write lock while determining what data to transfer.
2119 (default: True)
2120 uncompressedallowsecret
2122 Whether to allow stream clones when the repository contains
2124 secret changesets. (default: False)
2125 preferuncompressed
2127 When set, clients will try to use the uncompressed streaming
2129 protocol. (default: False)
2130 disablefullbundle
2132 When set, servers will refuse attempts to do pull-based clones.
2134 If this option is set, preferuncompressed and/or clone bundles
2135 are highly recommended. Partial clones will still be allowed.
2136 (default: False)
2137 streamunbundle
2139 When set, servers will apply data sent from the client directly,
2141 otherwise it will be written to a temporary file first. This
2142 option effectively prevents concurrent pushes.
2143 pullbundle
2145 When set, the server will check pullbundle.manifest for bundles
2147 covering the requested heads and common nodes. The first match‐
2148 ing entry will be streamed to the client.
2149 For HTTP transport, the stream will still use zlib compression
2151 for older clients.
2152 concurrent-push-mode
2154 Level of allowed race condition between two pushing clients.
2156 · 'strict': push is abort if another client touched the reposi‐
2158 tory while the push was preparing. (default)
2159 · 'check-related': push is only aborted if it affects head that
2161 got also affected while the push was preparing.
2162 This requires compatible client (version 4.3 and later). Old
2164 client will use 'strict'.
2165 validate
2167 Whether to validate the completeness of pushed changesets by
2169 checking that all new file revisions specified in manifests are
2170 present. (default: False)
2171 maxhttpheaderlen
2173 Instruct HTTP clients not to send request headers longer than
2175 this many bytes. (default: 1024)
2176 bundle1
2178 Whether to allow clients to push and pull using the legacy bun‐
2180 dle1 exchange format. (default: True)
2181 bundle1gd
2183 Like bundle1 but only used if the repository is using the gener‐
2185 aldelta storage format. (default: True)
2186 bundle1.push
2188 Whether to allow clients to push using the legacy bundle1
2190 exchange format. (default: True)
2191 bundle1gd.push
2193 Like bundle1.push but only used if the repository is using the
2195 generaldelta storage format. (default: True)
2196 bundle1.pull
2198 Whether to allow clients to pull using the legacy bundle1
2200 exchange format. (default: True)
2201 bundle1gd.pull
2203 Like bundle1.pull but only used if the repository is using the
2205 generaldelta storage format. (default: True)
2206 Large repositories using the generaldelta storage format should
2208 consider setting this option because converting generaldelta
2209 repositories to the exchange format required by the bundle1 data
2210 format can consume a lot of CPU.
2211 bundle2.stream
2213 Whether to allow clients to pull using the bundle2 streaming
2215 protocol. (default: True)
2216 zliblevel
2218 Integer between -1 and 9 that controls the zlib compression
2220 level for wire protocol commands that send zlib compressed out‐
2221 put (notably the commands that send repository history data).
2222 The default (-1) uses the default zlib compression level, which
2224 is likely equivalent to 6. 0 means no compression. 9 means maxi‐
2225 mum compression.
2226 Setting this option allows server operators to make trade-offs
2228 between bandwidth and CPU used. Lowering the compression lowers
2229 CPU utilization but sends more bytes to clients.
2230 This option only impacts the HTTP server.
2232 zstdlevel
2234 Integer between 1 and 22 that controls the zstd compression
2236 level for wire protocol commands. 1 is the minimal amount of
2237 compression and 22 is the highest amount of compression.
2238 The default (3) should be significantly faster than zlib while
2240 likely delivering better compression ratios.
2241 This option only impacts the HTTP server.
2243 See also server.zliblevel.
2245 view
2247 Repository filter used when exchanging revisions with the peer.
2249 The default view (served) excludes secret and hidden changesets.
2251 Another useful value is immutable (no draft, secret or hidden
2252 changesets). (EXPERIMENTAL)
2253 smtp
2255 Configuration for extensions that need to send email messages.
2256 host
2258 Host name of mail server, e.g. "mail.example.com".
2260 port
2262 Optional. Port to connect to on mail server. (default: 465 if
2264 tls is smtps; 25 otherwise)
2265 tls
2267 Optional. Method to enable TLS when connecting to mail server:
2269 starttls, smtps or none. (default: none)
2270 username
2272 Optional. User name for authenticating with the SMTP server.
2274 (default: None)
2275 password
2277 Optional. Password for authenticating with the SMTP server. If
2279 not specified, interactive sessions will prompt the user for a
2280 password; non-interactive sessions will fail. (default: None)
2281 local_hostname
2283 Optional. The hostname that the sender can use to identify
2285 itself to the MTA.
2286 subpaths
2288 Subrepository source URLs can go stale if a remote server changes name
2289 or becomes temporarily unavailable. This section lets you define re‐
2290 write rules of the form:
2291 <pattern> = <replacement>
2293 where pattern is a regular expression matching a subrepository source
2295 URL and replacement is the replacement string used to rewrite it.
2296 Groups can be matched in pattern and referenced in replacements. For
2297 instance:
2298 http://server/(.*)-hg/ = http://hg.server/\1/
2300 rewrites http://server/foo-hg/ into http://hg.server/foo/.
2302 Relative subrepository paths are first made absolute, and the rewrite
2304 rules are then applied on the full (absolute) path. If pattern doesn't
2305 match the full path, an attempt is made to apply it on the relative
2306 path alone. The rules are applied in definition order.
2307 subrepos
2309 This section contains options that control the behavior of the sub‐
2310 repositories feature. See also hg help subrepos.
2311 Security note: auditing in Mercurial is known to be insufficient to
2313 prevent clone-time code execution with carefully constructed Git subre‐
2314 pos. It is unknown if a similar detect is present in Subversion subre‐
2315 pos. Both Git and Subversion subrepos are disabled by default out of
2316 security concerns. These subrepo types can be enabled using the respec‐
2317 tive options below.
2318 allowed
2320 Whether subrepositories are allowed in the working directory.
2322 When false, commands involving subrepositories (like hg update)
2324 will fail for all subrepository types. (default: true)
2325 hg:allowed
2327 Whether Mercurial subrepositories are allowed in the working
2329 directory. This option only has an effect if subrepos.allowed is
2330 true. (default: true)
2331 git:allowed
2333 Whether Git subrepositories are allowed in the working direc‐
2335 tory. This option only has an effect if subrepos.allowed is
2336 true.
2337 See the security note above before enabling Git subrepos.
2339 (default: false)
2340 svn:allowed
2342 Whether Subversion subrepositories are allowed in the working
2344 directory. This option only has an effect if subrepos.allowed is
2345 true.
2346 See the security note above before enabling Subversion subrepos.
2348 (default: false)
2349 templatealias
2351 Alias definitions for templates. See hg help templates for details.
2352 templates
2354 Use the [templates] section to define template strings. See hg help
2355 templates for details.
2356 trusted
2358 Mercurial will not use the settings in the .hg/hgrc file from a reposi‐
2359 tory if it doesn't belong to a trusted user or to a trusted group, as
2360 various hgrc features allow arbitrary commands to be run. This issue is
2361 often encountered when configuring hooks or extensions for shared
2362 repositories or servers. However, the web interface will use some safe
2363 settings from the [web] section.
2364 This section specifies what users and groups are trusted. The current
2366 user is always trusted. To trust everybody, list a user or a group with
2367 name *. These settings must be placed in an already-trusted file to
2368 take effect, such as $HOME/.hgrc of the user or service running Mercu‐
2369 rial.
2370 users
2372 Comma-separated list of trusted users.
2374 groups
2376 Comma-separated list of trusted groups.
2378 ui
2380 User interface controls.
2381 archivemeta
2383 Whether to include the .hg_archival.txt file containing meta
2385 data (hashes for the repository base and for tip) in archives
2386 created by the hg archive command or downloaded via hgweb.
2387 (default: True)
2388 askusername
2390 Whether to prompt for a username when committing. If True, and
2392 neither $HGUSER nor $EMAIL has been specified, then the user
2393 will be prompted to enter a username. If no username is entered,
2394 the default USER@HOST is used instead. (default: False)
2395 clonebundles
2397 Whether the "clone bundles" feature is enabled.
2399 When enabled, hg clone may download and apply a server-adver‐
2401 tised bundle file from a URL instead of using the normal
2402 exchange mechanism.
2403 This can likely result in faster and more reliable clones.
2405 (default: True)
2407 clonebundlefallback
2409 Whether failure to apply an advertised "clone bundle" from a
2411 server should result in fallback to a regular clone.
2412 This is disabled by default because servers advertising "clone
2414 bundles" often do so to reduce server load. If advertised bun‐
2415 dles start mass failing and clients automatically fall back to a
2416 regular clone, this would add significant and unexpected load to
2417 the server since the server is expecting clone operations to be
2418 offloaded to pre-generated bundles. Failing fast (the default
2419 behavior) ensures clients don't overwhelm the server when "clone
2420 bundle" application fails.
2421 (default: False)
2423 clonebundleprefers
2425 Defines preferences for which "clone bundles" to use.
2427 Servers advertising "clone bundles" may advertise multiple
2429 available bundles. Each bundle may have different attributes,
2430 such as the bundle type and compression format. This option is
2431 used to prefer a particular bundle over another.
2432 The following keys are defined by Mercurial:
2434 BUNDLESPEC
2436 A bundle type specifier. These are strings passed to hg
2437 bundle -t. e.g. gzip-v2 or bzip2-v1.
2438 COMPRESSION
2440 The compression format of the bundle. e.g. gzip and
2441 bzip2.
2442 Server operators may define custom keys.
2444 Example values: COMPRESSION=bzip2, BUNDLESPEC=gzip-v2, COMPRES‐
2446 SION=gzip.
2447 By default, the first bundle advertised by the server is used.
2449 color
2451 When to colorize output. Possible value are Boolean ("yes" or
2453 "no"), or "debug", or "always". (default: "yes"). "yes" will use
2454 color whenever it seems possible. See hg help color for details.
2455 commitsubrepos
2457 Whether to commit modified subrepositories when committing the
2459 parent repository. If False and one subrepository has uncommit‐
2460 ted changes, abort the commit. (default: False)
2461 debug
2463 Print debugging information. (default: False)
2465 editor
2467 The editor to use during a commit. (default: $EDITOR or vi)
2469 fallbackencoding
2471 Encoding to try if it's not possible to decode the changelog
2473 using UTF-8. (default: ISO-8859-1)
2474 graphnodetemplate
2476 The template used to print changeset nodes in an ASCII revision
2478 graph. (default: {graphnode})
2479 ignore
2481 A file to read per-user ignore patterns from. This file should
2483 be in the same format as a repository-wide .hgignore file. File‐
2484 names are relative to the repository root. This option supports
2485 hook syntax, so if you want to specify multiple ignore files,
2486 you can do so by setting something like ignore.other = ~/.hgig‐
2487 nore2. For details of the ignore file format, see the hgig‐
2488 nore(5) man page.
2489 interactive
2491 Allow to prompt the user. (default: True)
2493 interface
2495 Select the default interface for interactive features (default:
2497 text). Possible values are 'text' and 'curses'.
2498 interface.chunkselector
2500 Select the interface for change recording (e.g. hg commit -i).
2502 Possible values are 'text' and 'curses'. This config overrides
2503 the interface specified by ui.interface.
2504 large-file-limit
2506 Largest file size that gives no memory use warning. Possible
2508 values are integers or 0 to disable the check. (default:
2509 10000000)
2510 logtemplate
2512 Template string for commands that print changesets.
2514 merge
2516 The conflict resolution program to use during a manual merge.
2518 For more information on merge tools see hg help merge-tools.
2519 For configuring merge tools see the [merge-tools] section.
2520 mergemarkers
2522 Sets the merge conflict marker label styling. The detailed style
2524 uses the mergemarkertemplate setting to style the labels. The
2525 basic style just uses 'local' and 'other' as the marker label.
2526 One of basic or detailed. (default: basic)
2527 mergemarkertemplate
2529 The template used to print the commit description next to each
2531 conflict marker during merge conflicts. See hg help templates
2532 for the template format.
2533 Defaults to showing the hash, tags, branches, bookmarks, author,
2535 and the first line of the commit description.
2536 If you use non-ASCII characters in names for tags, branches,
2538 bookmarks, authors, and/or commit descriptions, you must pay
2539 attention to encodings of managed files. At template expansion,
2540 non-ASCII characters use the encoding specified by the --encod‐
2541 ing global option, HGENCODING or other environment variables
2542 that govern your locale. If the encoding of the merge markers is
2543 different from the encoding of the merged files, serious prob‐
2544 lems may occur.
2545 Can be overridden per-merge-tool, see the [merge-tools] section.
2547 message-output
2549 Where to write status and error messages. (default: stdio)
2551 stderr
2553 Everything to stderr.
2555 stdio
2557 Status to stdout, and error to stderr.
2559 origbackuppath
2561 The path to a directory used to store generated .orig files. If
2563 the path is not a directory, one will be created. If set, files
2564 stored in this directory have the same name as the original file
2565 and do not have a .orig suffix.
2566 paginate
2568 Control the pagination of command output (default: True). See hg
2570 help pager for details.
2571 patch
2573 An optional external tool that hg import and some extensions
2575 will use for applying patches. By default Mercurial uses an
2576 internal patch utility. The external tool must work as the com‐
2577 mon Unix patch program. In particular, it must accept a -p argu‐
2578 ment to strip patch headers, a -d argument to specify the cur‐
2579 rent directory, a file name to patch, and a patch file to take
2580 from stdin.
2581 It is possible to specify a patch tool together with extra argu‐
2583 ments. For example, setting this option to patch --merge will
2584 use the patch program with its 2-way merge option.
2585 portablefilenames
2587 Check for portable filenames. Can be warn, ignore or abort.
2589 (default: warn)
2590 warn
2592 Print a warning message on POSIX platforms, if a file
2594 with a non-portable filename is added (e.g. a file with a
2595 name that can't be created on Windows because it contains
2596 reserved parts like AUX, reserved characters like :, or
2597 would cause a case collision with an existing file).
2598 ignore
2600 Don't print a warning.
2602 abort
2604 The command is aborted.
2606 true
2608 Alias for warn.
2610 false
2612 Alias for ignore.
2614 On Windows, this configuration option is ignored and the command
2616 aborted.
2617 pre-merge-tool-output-template
2619 A template that is printed before executing an external merge
2621 tool. This can be used to print out additional context that
2622 might be useful to have during the conflict resolution, such as
2623 the description of the various commits involved or book‐
2624 marks/tags.
2625 Additional information is available in the local`, ``base, and
2627 other dicts. For example: {local.label}, {base.name}, or
2628 {other.islink}.
2629 quiet
2631 Reduce the amount of output printed. (default: False)
2633 relative-paths
2635 Prefer relative paths in the UI.
2637 remotecmd
2639 Remote command to use for clone/push/pull operations. (default:
2641 hg)
2642 report_untrusted
2644 Warn if a .hg/hgrc file is ignored due to not being owned by a
2646 trusted user or group. (default: True)
2647 slash
2649 (Deprecated. Use slashpath template filter instead.)
2651 Display paths using a slash (/) as the path separator. This only
2653 makes a difference on systems where the default path separator
2654 is not the slash character (e.g. Windows uses the backslash
2655 character (\)). (default: False)
2656 statuscopies
2658 Display copies in the status command.
2660 ssh
2662 Command to use for SSH connections. (default: ssh)
2664 ssherrorhint
2666 A hint shown to the user in the case of SSH error (e.g. Please
2668 see http://company/internalwiki/ssh.html)
2669 strict
2671 Require exact command names, instead of allowing unambiguous
2673 abbreviations. (default: False)
2674 style
2676 Name of style to use for command output.
2678 supportcontact
2680 A URL where users should report a Mercurial traceback. Use this
2682 if you are a large organisation with its own Mercurial deploy‐
2683 ment process and crash reports should be addressed to your
2684 internal support.
2685 textwidth
2687 Maximum width of help text. A longer line generated by hg help
2689 or hg subcommand --help will be broken after white space to get
2690 this width or the terminal width, whichever comes first. A
2691 non-positive value will disable this and the terminal width will
2692 be used. (default: 78)
2693 timeout
2695 The timeout used when a lock is held (in seconds), a negative
2697 value means no timeout. (default: 600)
2698 timeout.warn
2700 Time (in seconds) before a warning is printed about held lock. A
2702 negative value means no warning. (default: 0)
2703 traceback
2705 Mercurial always prints a traceback when an unknown exception
2707 occurs. Setting this to True will make Mercurial print a trace‐
2708 back on all exceptions, even those recognized by Mercurial (such
2709 as IOError or MemoryError). (default: False)
2710 tweakdefaults
2712 By default Mercurial's behavior changes very little from release to
2714 release, but over time the recommended config settings shift. Enable
2715 this config to opt in to get automatic tweaks to Mercurial's behav‐
2716 ior over time. This config setting will have no effect if HGPLAIN is
2717 set or HGPLAINEXCEPT is set and does not include tweakdefaults.
2718 (default: False)
2719 It currently means:
2721 [ui]
2723 # The rollback command is dangerous. As a rule, don't use it.
2724 rollback = False
2725 # Make `hg status` report copy information
2726 statuscopies = yes
2727 # Prefer curses UIs when available. Revert to plain-text with `text`.
2728 interface = curses
2729 # Make compatible commands emit cwd-relative paths by default.
2730 relative-paths = yes
2731 [commands]
2733 # Grep working directory by default.
2734 grep.all-files = True
2735 # Refuse to perform an `hg update` that would cause a file content merge
2736 update.check = noconflict
2737 # Show conflicts information in `hg status`
2738 status.verbose = True
2739 # Make `hg resolve` with no action (like `-m`) fail instead of re-merging.
2740 resolve.explicit-re-merge = True
2741 [diff]
2743 git = 1
2744 showfunc = 1
2745 word-diff = 1
2746 username
2748 The committer of a changeset created when running "commit".
2750 Typically a person's name and email address, e.g. Fred Widget
2751 <fred@example.com>. Environment variables in the username are
2752 expanded.
2753 (default: $EMAIL or username@hostname. If the username in hgrc
2755 is empty, e.g. if the system admin set username = in the system
2756 hgrc, it has to be specified manually or in a different hgrc
2757 file)
2758 verbose
2760 Increase the amount of output printed. (default: False)
2762 web
2764 Web interface configuration. The settings in this section apply to both
2765 the builtin webserver (started by hg serve) and the script you run
2766 through a webserver (hgweb.cgi and the derivatives for FastCGI and
2767 WSGI).
2768 The Mercurial webserver does no authentication (it does not prompt for
2770 usernames and passwords to validate who users are), but it does do
2771 authorization (it grants or denies access for authenticated users based
2772 on settings in this section). You must either configure your webserver
2773 to do authentication for you, or disable the authorization checks.
2774 For a quick setup in a trusted environment, e.g., a private LAN, where
2776 you want it to accept pushes from anybody, you can use the following
2777 command line:
2778 $ hg --config web.allow-push=* --config web.push_ssl=False serve
2780 Note that this will allow anybody to push anything to the server and
2782 that this should not be used for public servers.
2783 The full set of options is:
2785 accesslog
2787 Where to output the access log. (default: stdout)
2789 address
2791 Interface address to bind to. (default: all)
2793 allow-archive
2795 List of archive format (bz2, gz, zip) allowed for downloading.
2797 (default: empty)
2798 allowbz2
2800 (DEPRECATED) Whether to allow .tar.bz2 downloading of repository
2802 revisions. (default: False)
2803 allowgz
2805 (DEPRECATED) Whether to allow .tar.gz downloading of repository
2807 revisions. (default: False)
2808 allow-pull
2810 Whether to allow pulling from the repository. (default: True)
2812 allow-push
2814 Whether to allow pushing to the repository. If empty or not set,
2816 pushing is not allowed. If the special value *, any remote user
2817 can push, including unauthenticated users. Otherwise, the remote
2818 user must have been authenticated, and the authenticated user
2819 name must be present in this list. The contents of the
2820 allow-push list are examined after the deny_push list.
2821 allow_read
2823 If the user has not already been denied repository access due to
2825 the contents of deny_read, this list determines whether to grant
2826 repository access to the user. If this list is not empty, and
2827 the user is unauthenticated or not present in the list, then
2828 access is denied for the user. If the list is empty or not set,
2829 then access is permitted to all users by default. Setting
2830 allow_read to the special value * is equivalent to it not being
2831 set (i.e. access is permitted to all users). The contents of the
2832 allow_read list are examined after the deny_read list.
2833 allowzip
2835 (DEPRECATED) Whether to allow .zip downloading of repository
2837 revisions. This feature creates temporary files. (default:
2838 False)
2839 archivesubrepos
2841 Whether to recurse into subrepositories when archiving.
2843 (default: False)
2844 baseurl
2846 Base URL to use when publishing URLs in other locations, so
2848 third-party tools like email notification hooks can construct
2849 URLs. Example: http://hgserver/repos/.
2850 cacerts
2852 Path to file containing a list of PEM encoded certificate
2854 authority certificates. Environment variables and ~user con‐
2855 structs are expanded in the filename. If specified on the
2856 client, then it will verify the identity of remote HTTPS servers
2857 with these certificates.
2858 To disable SSL verification temporarily, specify --insecure from
2860 command line.
2861 You can use OpenSSL's CA certificate file if your platform has
2863 one. On most Linux systems this will be /etc/ssl/certs/ca-cer‐
2864 tificates.crt. Otherwise you will have to generate this file
2865 manually. The form must be as follows:
2866 -----BEGIN CERTIFICATE-----
2868 ... (certificate in base64 PEM encoding) ...
2869 -----END CERTIFICATE-----
2870 -----BEGIN CERTIFICATE-----
2871 ... (certificate in base64 PEM encoding) ...
2872 -----END CERTIFICATE-----
2873 cache
2875 Whether to support caching in hgweb. (default: True)
2877 certificate
2879 Certificate to use when running hg serve.
2881 collapse
2883 With descend enabled, repositories in subdirectories are shown
2885 at a single level alongside repositories in the current path.
2886 With collapse also enabled, repositories residing at a deeper
2887 level than the current path are grouped behind navigable direc‐
2888 tory entries that lead to the locations of these repositories.
2889 In effect, this setting collapses each collection of reposito‐
2890 ries found within a subdirectory into a single entry for that
2891 subdirectory. (default: False)
2892 comparisoncontext
2894 Number of lines of context to show in side-by-side file compari‐
2896 son. If negative or the value full, whole files are shown.
2897 (default: 5)
2898 This setting can be overridden by a context request parameter to
2900 the comparison command, taking the same values.
2901 contact
2903 Name or email address of the person in charge of the repository.
2905 (default: ui.username or $EMAIL or "unknown" if unset or empty)
2906 csp
2908 Send a Content-Security-Policy HTTP header with this value.
2910 The value may contain a special string %nonce%, which will be
2912 replaced by a randomly-generated one-time use value. If the
2913 value contains %nonce%, web.cache will be disabled, as caching
2914 undermines the one-time property of the nonce. This nonce will
2915 also be inserted into <script> elements containing inline
2916 JavaScript.
2917 Note: lots of HTML content sent by the server is derived from
2919 repository data. Please consider the potential for malicious
2920 repository data to "inject" itself into generated HTML content
2921 as part of your security threat model.
2922 deny_push
2924 Whether to deny pushing to the repository. If empty or not set,
2926 push is not denied. If the special value *, all remote users are
2927 denied push. Otherwise, unauthenticated users are all denied,
2928 and any authenticated user name present in this list is also
2929 denied. The contents of the deny_push list are examined before
2930 the allow-push list.
2931 deny_read
2933 Whether to deny reading/viewing of the repository. If this list
2935 is not empty, unauthenticated users are all denied, and any
2936 authenticated user name present in this list is also denied
2937 access to the repository. If set to the special value *, all
2938 remote users are denied access (rarely needed ;). If deny_read
2939 is empty or not set, the determination of repository access
2940 depends on the presence and content of the allow_read list (see
2941 description). If both deny_read and allow_read are empty or not
2942 set, then access is permitted to all users by default. If the
2943 repository is being served via hgwebdir, denied users will not
2944 be able to see it in the list of repositories. The contents of
2945 the deny_read list have priority over (are examined before) the
2946 contents of the allow_read list.
2947 descend
2949 hgwebdir indexes will not descend into subdirectories. Only
2951 repositories directly in the current path will be shown (other
2952 repositories are still available from the index corresponding to
2953 their containing path).
2954 description
2956 Textual description of the repository's purpose or contents.
2958 (default: "unknown")
2959 encoding
2961 Character encoding name. (default: the current locale charset)
2963 Example: "UTF-8".
2964 errorlog
2966 Where to output the error log. (default: stderr)
2968 guessmime
2970 Control MIME types for raw download of file content. Set to
2972 True to let hgweb guess the content type from the file exten‐
2973 sion. This will serve HTML files as text/html and might allow
2974 cross-site scripting attacks when serving untrusted reposito‐
2975 ries. (default: False)
2976 hidden
2978 Whether to hide the repository in the hgwebdir index. (default:
2980 False)
2981 ipv6
2983 Whether to use IPv6. (default: False)
2985 labels
2987 List of string labels associated with the repository.
2989 Labels are exposed as a template keyword and can be used to cus‐
2991 tomize output. e.g. the index template can group or filter
2992 repositories by labels and the summary template can display
2993 additional content if a specific label is present.
2994 logoimg
2996 File name of the logo image that some templates display on each
2998 page. The file name is relative to staticurl. That is, the full
2999 path to the logo image is "staticurl/logoimg". If unset, hgl‐
3000 ogo.png will be used.
3001 logourl
3003 Base URL to use for logos. If unset, https://mercurial-scm.org/
3005 will be used.
3006 maxchanges
3008 Maximum number of changes to list on the changelog. (default:
3010 10)
3011 maxfiles
3013 Maximum number of files to list per changeset. (default: 10)
3015 maxshortchanges
3017 Maximum number of changes to list on the shortlog, graph or
3019 filelog pages. (default: 60)
3020 name
3022 Repository name to use in the web interface. (default: current
3024 working directory)
3025 port
3027 Port to listen on. (default: 8000)
3029 prefix
3031 Prefix path to serve from. (default: '' (server root))
3033 push_ssl
3035 Whether to require that inbound pushes be transported over SSL
3037 to prevent password sniffing. (default: True)
3038 refreshinterval
3040 How frequently directory listings re-scan the filesystem for new
3042 repositories, in seconds. This is relevant when wildcards are
3043 used to define paths. Depending on how much filesystem traversal
3044 is required, refreshing may negatively impact performance.
3045 Values less than or equal to 0 always refresh. (default: 20)
3047 server-header
3049 Value for HTTP Server response header.
3051 static
3053 Directory where static files are served from.
3055 staticurl
3057 Base URL to use for static files. If unset, static files (e.g.
3059 the hgicon.png favicon) will be served by the CGI script itself.
3060 Use this setting to serve them directly with the HTTP server.
3061 Example: http://hgserver/static/.
3062 stripes
3064 How many lines a "zebra stripe" should span in multi-line out‐
3066 put. Set to 0 to disable. (default: 1)
3067 style
3069 Which template map style to use. The available options are the
3071 names of subdirectories in the HTML templates path. (default:
3072 paper) Example: monoblue.
3073 templates
3075 Where to find the HTML templates. The default path to the HTML
3077 templates can be obtained from hg debuginstall.
3078 websub
3080 Web substitution filter definition. You can use this section to define
3081 a set of regular expression substitution patterns which let you auto‐
3082 matically modify the hgweb server output.
3083 The default hgweb templates only apply these substitution patterns on
3085 the revision description fields. You can apply them anywhere you want
3086 when you create your own templates by adding calls to the "websub" fil‐
3087 ter (usually after calling the "escape" filter).
3088 This can be used, for example, to convert issue references to links to
3090 your issue tracker, or to convert "markdown-like" syntax into HTML (see
3091 the examples below).
3092 Each entry in this section names a substitution filter. The value of
3094 each entry defines the substitution expression itself. The websub
3095 expressions follow the old interhg extension syntax, which in turn imi‐
3096 tates the Unix sed replacement syntax:
3097 patternname = s/SEARCH_REGEX/REPLACE_EXPRESSION/[i]
3099 You can use any separator other than "/". The final "i" is optional and
3101 indicates that the search must be case insensitive.
3102 Examples:
3104 [websub]
3106 issues = s|issue(\d+)|<a href="http://bts.example.org/issue\1">issue\1</a>|i
3107 italic = s/\b_(\S+)_\b/<i>\1<\/i>/
3108 bold = s/\*\b(\S+)\b\*/<b>\1<\/b>/
3109 worker
3111 Parallel master/worker configuration. We currently perform working
3112 directory updates in parallel on Unix-like systems, which greatly helps
3113 performance.
3114 enabled
3116 Whether to enable workers code to be used. (default: true)
3118 numcpus
3120 Number of CPUs to use for parallel operations. A zero or nega‐
3122 tive value is treated as use the default. (default: 4 or the
3123 number of CPUs on the system, whichever is larger)
3124 backgroundclose
3126 Whether to enable closing file handles on background threads
3128 during certain operations. Some platforms aren't very efficient
3129 at closing file handles that have been written or appended to.
3130 By performing file closing on background threads, file write
3131 rate can increase substantially. (default: true on Windows,
3132 false elsewhere)
3133 backgroundcloseminfilecount
3135 Minimum number of files required to trigger background file
3137 closing. Operations not writing this many files won't start
3138 background close threads. (default: 2048)
3139 backgroundclosemaxqueue
3141 The maximum number of opened file handles waiting to be closed
3143 in the background. This option only has an effect if background‐
3144 close is enabled. (default: 384)
3145 backgroundclosethreadcount
3147 Number of threads to process background file closes. Only rele‐
3149 vant if backgroundclose is enabled. (default: 4)
3150
3152 Bryan O'Sullivan <bos@serpentine.com>.
3153 Mercurial was written by Matt Mackall <mpm@selenic.com>.
3155
3157 hg(1), hgignore(5)
3158
3160 This manual page is copyright 2005 Bryan O'Sullivan. Mercurial is
3161 copyright 2005-2019 Matt Mackall. Free use of this software is granted
3162 under the terms of the GNU General Public License version 2 or any
3163 later version.
3164
3166 Bryan O'Sullivan <bos@serpentine.com>
3167 Organization: Mercurial
3169 HGRC(5)