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 as‐
10 pects of its behavior.
11
13 If you're having problems with your configuration, hg config --source
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 ap‐
35 propriate 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 in‐
47 stalled. *.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-not-shared (per-repository)
54 • <repo>/.hg/hgrc (per-repository)
56 • $HOME/.hgrc (per-user)
58 • ${XDG_CONFIG_HOME:-$HOME/.config}/hg/hgrc (per-user)
60 • <install-root>/etc/mercurial/hgrc (per-installation)
62 • <install-root>/etc/mercurial/hgrc.d/*.rc (per-installation)
64 • /etc/mercurial/hgrc (per-system)
66 • /etc/mercurial/hgrc.d/*.rc (per-system)
68 • <internal>/*.rc (defaults)
70 On Windows, the following files are consulted:
72 • <repo>/.hg/hgrc-not-shared (per-repository)
74 • <repo>/.hg/hgrc (per-repository)
76 • %USERPROFILE%\.hgrc (per-user)
78 • %USERPROFILE%\Mercurial.ini (per-user)
80 • %HOME%\.hgrc (per-user)
82 • %HOME%\Mercurial.ini (per-user)
84 • HKEY_LOCAL_MACHINE\SOFTWARE\Mercurial (per-system)
86 • <install-dir>\hgrc.d\*.rc (per-installation)
88 • <install-dir>\Mercurial.ini (per-installation)
90 • %PROGRAMDATA%\Mercurial\hgrc (per-system)
92 • %PROGRAMDATA%\Mercurial\Mercurial.ini (per-system)
94 • %PROGRAMDATA%\Mercurial\hgrc.d\*.rc (per-system)
96 • <internal>/*.rc (defaults)
98 Note The registry key HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Mercu‐
100 rial is used when running 32-bit Python on 64-bit Windows.
101 On Plan9, the following files are consulted:
103 • <repo>/.hg/hgrc-not-shared (per-repository)
105 • <repo>/.hg/hgrc (per-repository)
107 • $home/lib/hgrc (per-user)
109 • <install-root>/lib/mercurial/hgrc (per-installation)
111 • <install-root>/lib/mercurial/hgrc.d/*.rc (per-installation)
113 • /lib/mercurial/hgrc (per-system)
115 • /lib/mercurial/hgrc.d/*.rc (per-system)
117 • <internal>/*.rc (defaults)
119 Per-repository configuration options only apply in a particular reposi‐
121 tory. This file is not version-controlled, and will not get transferred
122 during a "clone" operation. Options in this file override options in
123 all other configuration files.
124 On Plan 9 and Unix, most of this file will be ignored if it doesn't be‐
126 long to a trusted user or to a trusted group. See hg help config.trust‐
127 ed for more details.
128 Per-user configuration file(s) are for the user running Mercurial. Op‐
130 tions in these files apply to all Mercurial commands executed by this
131 user in any directory. Options in these files override per-system and
132 per-installation options.
133 Per-installation configuration files are searched for in the directory
135 where Mercurial is installed. <install-root> is the parent directory of
136 the hg executable (or symlink) being run.
137 For example, if installed in /shared/tools/bin/hg, Mercurial will look
139 in /shared/tools/etc/mercurial/hgrc. Options in these files apply to
140 all Mercurial commands executed by any user in any directory.
141 Per-installation configuration files are for the system on which Mercu‐
143 rial is running. Options in these files apply to all Mercurial commands
144 executed by any user in any directory. Registry keys contain PATH-like
145 strings, every part of which must reference a Mercurial.ini file or be
146 a directory where *.rc files will be read. Mercurial checks each of
147 these locations in the specified order until one or more configuration
148 files are detected.
149 Per-system configuration files are for the system on which Mercurial is
151 running. Options in these files apply to all Mercurial commands exe‐
152 cuted by any user in any directory. Options in these files override
153 per-installation options.
154 Mercurial comes with some default configuration. The default configura‐
156 tion files are installed with Mercurial and will be overwritten on up‐
157 grades. Default configuration files should never be edited by users or
158 administrators but can be overridden in other configuration files. So
159 far the directory only contains merge tool configuration but packagers
160 can also put other default configuration there.
161 On versions 5.7 and later, if share-safe functionality is enabled,
163 shares will read config file of share source too.
164 <share-source/.hg/hgrc> is read before reading <repo/.hg/hgrc>.
165 For configs which should not be shared, <repo/.hg/hgrc-not-shared>
167 should be used.
168
170 A configuration file consists of sections, led by a [section] header
171 and followed by name = value entries (sometimes called configuration
172 keys):
173 [spam]
175 eggs=ham
176 green=
177 eggs
178 Each line contains one entry. If the lines that follow are indented,
180 they are treated as continuations of that entry. Leading whitespace is
181 removed from values. Empty lines are skipped. Lines beginning with # or
182 ; are ignored and may be used to provide comments.
183 Configuration keys can be set multiple times, in which case Mercurial
185 will use the value that was configured last. As an example:
186 [spam]
188 eggs=large
189 ham=serrano
190 eggs=small
191 This would set the configuration key named eggs to small.
193 It is also possible to define a section multiple times. A section can
195 be redefined on the same and/or on different configuration files. For
196 example:
197 [foo]
199 eggs=large
200 ham=serrano
201 eggs=small
202 [bar]
204 eggs=ham
205 green=
206 eggs
207 [foo]
209 ham=prosciutto
210 eggs=medium
211 bread=toasted
212 This would set the eggs, ham, and bread configuration keys of the foo
214 section to medium, prosciutto, and toasted, respectively. As you can
215 see there only thing that matters is the last value that was set for
216 each of the configuration keys.
217 If a configuration key is set multiple times in different configuration
219 files the final value will depend on the order in which the different
220 configuration files are read, with settings from earlier paths overrid‐
221 ing later ones as described on the Files section above.
222 A line of the form %include file will include file into the current
224 configuration file. The inclusion is recursive, which means that in‐
225 cluded files can include other files. Filenames are relative to the
226 configuration file in which the %include directive is found. Environ‐
227 ment variables and ~user constructs are expanded in file. This lets you
228 do something like:
229 %include ~/.hgrc.d/$HOST.rc
231 to include a different configuration file on each computer you use.
233 A line with %unset name will remove name from the current section, if
235 it has been set previously.
236 The values are either free-form text strings, lists of text strings, or
238 Boolean values. Boolean values can be set to true using any of "1",
239 "yes", "true", or "on" and to false using "0", "no", "false", or "off"
240 (all case insensitive).
241 List values are separated by whitespace or comma, except when values
243 are placed in double quotation marks:
244 allow_read = "John Doe, PhD", brian, betty
246 Quotation marks can be escaped by prefixing them with a backslash. Only
248 quotation marks at the beginning of a word is counted as a quotation
249 (e.g., foo"bar baz is the list of foo"bar and baz).
250
252 This section describes the different sections that may appear in a Mer‐
253 curial configuration file, the purpose of each section, its possible
254 keys, and their possible values.
255 alias
257 Defines command aliases.
258 Aliases allow you to define your own commands in terms of other com‐
260 mands (or aliases), optionally including arguments. Positional argu‐
261 ments in the form of $1, $2, etc. in the alias definition are expanded
262 by Mercurial before execution. Positional arguments not already used by
263 $N in the definition are put at the end of the command to be executed.
264 Alias definitions consist of lines of the form:
266 <alias> = <command> [<argument>]...
268 For example, this definition:
270 latest = log --limit 5
272 creates a new command latest that shows only the five most recent
274 changesets. You can define subsequent aliases using earlier ones:
275 stable5 = latest -b stable
277 Note It is possible to create aliases with the same names as existing
279 commands, which will then override the original definitions.
280 This is almost always a bad idea!
281 An alias can start with an exclamation point (!) to make it a shell
283 alias. A shell alias is executed with the shell and will let you run
284 arbitrary commands. As an example,
285 echo = !echo $@
287 will let you do hg echo foo to have foo printed in your terminal. A
289 better example might be:
290 purge = !$HG status --no-status --unknown -0 re: | xargs -0 rm -f
292 which will make hg purge delete all unknown files in the repository in
294 the same manner as the purge extension.
295 Positional arguments like $1, $2, etc. in the alias definition expand
297 to the command arguments. Unmatched arguments are removed. $0 expands
298 to the alias name and $@ expands to all arguments separated by a space.
299 "$@" (with quotes) expands to all arguments quoted individually and
300 separated by a space. These expansions happen before the command is
301 passed to the shell.
302 Shell aliases are executed in an environment where $HG expands to the
304 path of the Mercurial that was used to execute the alias. This is use‐
305 ful when you want to call further Mercurial commands in a shell alias,
306 as was done above for the purge alias. In addition, $HG_ARGS expands to
307 the arguments given to Mercurial. In the hg echo foo call above,
308 $HG_ARGS would expand to echo foo.
309 Note Some global configuration options such as -R are processed be‐
311 fore shell aliases and will thus not be passed to aliases.
312 annotate
314 Settings used when displaying file annotations. All values are Booleans
315 and default to False. See hg help config.diff for related options for
316 the diff command.
317 ignorews
319 Ignore white space when comparing lines.
321 ignorewseol
323 Ignore white space at the end of a line when comparing lines.
325 ignorewsamount
327 Ignore changes in the amount of white space.
329 ignoreblanklines
331 Ignore changes whose lines are all blank.
333 auth
335 Authentication credentials and other authentication-like configuration
336 for HTTP connections. This section allows you to store usernames and
337 passwords for use when logging into HTTP servers. See hg help con‐
338 fig.web if you want to configure who can login to your HTTP server.
339 The following options apply to all hosts.
341 cookiefile
343 Path to a file containing HTTP cookie lines. Cookies matching a
345 host will be sent automatically.
346 The file format uses the Mozilla cookies.txt format, which de‐
348 fines cookies on their own lines. Each line contains 7 fields
349 delimited by the tab character (domain, is_domain_cookie, path,
350 is_secure, expires, name, value). For more info, do an Internet
351 search for "Netscape cookies.txt format."
352 Note: the cookies parser does not handle port numbers on do‐
354 mains. You will need to remove ports from the domain for the
355 cookie to be recognized. This could result in a cookie being
356 disclosed to an unwanted server.
357 The cookies file is read-only.
359 Other options in this section are grouped by name and have the follow‐
361 ing format:
362 <name>.<argument> = <value>
364 where <name> is used to group arguments into authentication entries.
366 Example:
367 foo.prefix = hg.intevation.de/mercurial
369 foo.username = foo
370 foo.password = bar
371 foo.schemes = http https
372 bar.prefix = secure.example.org
374 bar.key = path/to/file.key
375 bar.cert = path/to/file.cert
376 bar.schemes = https
377 Supported arguments:
379 prefix
381 Either * or a URI prefix with or without the scheme part. The
383 authentication entry with the longest matching prefix is used
384 (where * matches everything and counts as a match of length 1).
385 If the prefix doesn't include a scheme, the match is performed
386 against the URI with its scheme stripped as well, and the
387 schemes argument, q.v., is then subsequently consulted.
388 username
390 Optional. Username to authenticate with. If not given, and the
392 remote site requires basic or digest authentication, the user
393 will be prompted for it. Environment variables are expanded in
394 the username letting you do foo.username = $USER. If the URI in‐
395 cludes a username, only [auth] entries with a matching username
396 or without a username will be considered.
397 password
399 Optional. Password to authenticate with. If not given, and the
401 remote site requires basic or digest authentication, the user
402 will be prompted for it.
403 key
405 Optional. PEM encoded client certificate key file. Environment
407 variables are expanded in the filename.
408 cert
410 Optional. PEM encoded client certificate chain file. Environment
412 variables are expanded in the filename.
413 schemes
415 Optional. Space separated list of URI schemes to use this au‐
417 thentication entry with. Only used if the prefix doesn't include
418 a scheme. Supported schemes are http and https. They will match
419 static-http and static-https respectively, as well. (default:
420 https)
421 If no suitable authentication entry is found, the user is prompted for
423 credentials as usual if required by the remote.
424 cmdserver
426 Controls command server settings. (ADVANCED)
427 message-encodings
429 List of encodings for the m (message) channel. The first encod‐
431 ing supported by the server will be selected and advertised in
432 the hello message. This is useful only when ui.message-output is
433 set to channel. Supported encodings are cbor.
434 shutdown-on-interrupt
436 If set to false, the server's main loop will continue running
438 after SIGINT received. runcommand requests can still be inter‐
439 rupted by SIGINT. Close the write end of the pipe to shut down
440 the server process gracefully. (default: True)
441 color
443 Configure the Mercurial color mode. For details about how to define
444 your custom effect and style see hg help color.
445 mode
447 String: control the method used to output color. One of auto,
449 ansi, win32, terminfo or debug. In auto mode, Mercurial will use
450 ANSI mode by default (or win32 mode prior to Windows 10) if it
451 detects a terminal. Any invalid value will disable color.
452 pagermode
454 String: optional override of color.mode used with pager.
456 On some systems, terminfo mode may cause problems when using
458 color with less -R as a pager program. less with the -R option
459 will only display ECMA-48 color codes, and terminfo mode may
460 sometimes emit codes that less doesn't understand. You can work
461 around this by either using ansi mode (or auto mode), or by us‐
462 ing less -r (which will pass through all terminal control codes,
463 not just color control codes).
464 On some systems (such as MSYS in Windows), the terminal may sup‐
466 port a different color mode than the pager program.
467 commands
469 commit.post-status
470 Show status of files in the working directory after successful
472 commit. (default: False)
473 merge.require-rev
475 Require that the revision to merge the current commit with be
477 specified on the command line. If this is enabled and a revision
478 is not specified, the command aborts. (default: False)
479 push.require-revs
481 Require revisions to push be specified using one or more mecha‐
483 nisms such as specifying them positionally on the command line,
484 using -r, -b, and/or -B on the command line, or using
485 paths.<path>:pushrev in the configuration. If this is enabled
486 and revisions are not specified, the command aborts. (default:
487 False)
488 resolve.confirm
490 Confirm before performing action if no filename is passed. (de‐
492 fault: False)
493 resolve.explicit-re-merge
495 Require uses of hg resolve to specify which action it should
497 perform, instead of re-merging files by default. (default:
498 False)
499 resolve.mark-check
501 Determines what level of checking hg resolve --mark will perform
503 before marking files as resolved. Valid values are none`,
504 ``warn, and abort. warn will output a warning listing the
505 file(s) that still have conflict markers in them, but will still
506 mark everything resolved. abort will output the same warning
507 but will not mark things as resolved. If --all is passed and
508 this is set to abort, only a warning will be shown (an error
509 will not be raised). (default: none)
510 status.relative
512 Make paths in hg status output relative to the current direc‐
514 tory. (default: False)
515 status.terse
517 Default value for the --terse flag, which condenses status out‐
519 put. (default: empty)
520 update.check
522 Determines what level of checking hg update will perform before
524 moving to a destination revision. Valid values are abort, none,
525 linear, and noconflict.
526 • abort always fails if the working directory has uncommitted
528 changes.
529 • none performs no checking, and may result in a merge with un‐
531 committed changes.
532 • linear allows any update as long as it follows a straight line
534 in the revision history, and may trigger a merge with uncom‐
535 mitted changes.
536 • noconflict will allow any update which would not trigger a
538 merge with uncommitted changes, if any are present.
539 (default: linear)
541 update.requiredest
543 Require that the user pass a destination when running hg update.
545 For example, hg update .:: will be allowed, but a plain hg up‐
546 date will be disallowed. (default: False)
547 committemplate
549 changeset
550 String: configuration in this section is used as the template to
552 customize the text shown in the editor when committing.
553 In addition to pre-defined template keywords, commit log specific one
555 below can be used for customization:
556 extramsg
558 String: Extra message (typically 'Leave message empty to abort
560 commit.'). This may be changed by some commands or extensions.
561 For example, the template configuration below shows as same text as one
563 shown by default:
564 [committemplate]
566 changeset = {desc}\n\n
567 HG: Enter commit message. Lines beginning with 'HG:' are removed.
568 HG: {extramsg}
569 HG: --
570 HG: user: {author}\n{ifeq(p2rev, "-1", "",
571 "HG: branch merge\n")
572 }HG: branch '{branch}'\n{if(activebookmark,
573 "HG: bookmark '{activebookmark}'\n") }{subrepos %
574 "HG: subrepo {subrepo}\n" }{file_adds %
575 "HG: added {file}\n" }{file_mods %
576 "HG: changed {file}\n" }{file_dels %
577 "HG: removed {file}\n" }{if(files, "",
578 "HG: no files changed\n")}
579 diff()
581 String: show the diff (see hg help templates for detail)
583 Sometimes it is helpful to show the diff of the changeset in the editor
585 without having to prefix 'HG: ' to each line so that highlighting works
586 correctly. For this, Mercurial provides a special string which will ig‐
587 nore everything below it:
588 HG: ------------------------ >8 ------------------------
590 For example, the template configuration below will show the diff below
592 the extra message:
593 [committemplate]
595 changeset = {desc}\n\n
596 HG: Enter commit message. Lines beginning with 'HG:' are removed.
597 HG: {extramsg}
598 HG: ------------------------ >8 ------------------------
599 HG: Do not touch the line above.
600 HG: Everything below will be removed.
601 {diff()}
602 Note For some problematic encodings (see hg help win32mbcs for de‐
604 tail), this customization should be configured carefully, to
605 avoid showing broken characters.
606 For example, if a multibyte character ending with backslash
608 (0x5c) is followed by the ASCII character 'n' in the customized
609 template, the sequence of backslash and 'n' is treated as
610 line-feed unexpectedly (and the multibyte character is broken,
611 too).
612 Customized template is used for commands below (--edit may be re‐
614 quired):
615 • hg backout
617 • hg commit
619 • hg fetch (for merge commit only)
621 • hg graft
623 • hg histedit
625 • hg import
627 • hg qfold, hg qnew and hg qrefresh
629 • hg rebase
631 • hg shelve
633 • hg sign
635 • hg tag
637 • hg transplant
639 Configuring items below instead of changeset allows showing customized
641 message only for specific actions, or showing different messages for
642 each action.
643 • changeset.backout for hg backout
645 • changeset.commit.amend.merge for hg commit --amend on merges
647 • changeset.commit.amend.normal for hg commit --amend on other
649 • changeset.commit.normal.merge for hg commit on merges
651 • changeset.commit.normal.normal for hg commit on other
653 • changeset.fetch for hg fetch (impling merge commit)
655 • changeset.gpg.sign for hg sign
657 • changeset.graft for hg graft
659 • changeset.histedit.edit for edit of hg histedit
661 • changeset.histedit.fold for fold of hg histedit
663 • changeset.histedit.mess for mess of hg histedit
665 • changeset.histedit.pick for pick of hg histedit
667 • changeset.import.bypass for hg import --bypass
669 • changeset.import.normal.merge for hg import on merges
671 • changeset.import.normal.normal for hg import on other
673 • changeset.mq.qnew for hg qnew
675 • changeset.mq.qfold for hg qfold
677 • changeset.mq.qrefresh for hg qrefresh
679 • changeset.rebase.collapse for hg rebase --collapse
681 • changeset.rebase.merge for hg rebase on merges
683 • changeset.rebase.normal for hg rebase on other
685 • changeset.shelve.shelve for hg shelve
687 • changeset.tag.add for hg tag without --remove
689 • changeset.tag.remove for hg tag --remove
691 • changeset.transplant.merge for hg transplant on merges
693 • changeset.transplant.normal for hg transplant on other
695 These dot-separated lists of names are treated as hierarchical ones.
697 For example, changeset.tag.remove customizes the commit message only
698 for hg tag --remove, but changeset.tag customizes the commit message
699 for hg tag regardless of --remove option.
700 When the external editor is invoked for a commit, the corresponding
702 dot-separated list of names without the changeset. prefix (e.g. com‐
703 mit.normal.normal) is in the HGEDITFORM environment variable.
704 In this section, items other than changeset can be referred from oth‐
706 ers. For example, the configuration to list committed files up below
707 can be referred as {listupfiles}:
708 [committemplate]
710 listupfiles = {file_adds %
711 "HG: added {file}\n" }{file_mods %
712 "HG: changed {file}\n" }{file_dels %
713 "HG: removed {file}\n" }{if(files, "",
714 "HG: no files changed\n")}
715 decode/encode
717 Filters for transforming files on checkout/checkin. This would typi‐
718 cally be used for newline processing or other localization/canonical‐
719 ization of files.
720 Filters consist of a filter pattern followed by a filter command. Fil‐
722 ter patterns are globs by default, rooted at the repository root. For
723 example, to match any file ending in .txt in the root directory only,
724 use the pattern *.txt. To match any file ending in .c anywhere in the
725 repository, use the pattern **.c. For each file only the first match‐
726 ing filter applies.
727 The filter command can start with a specifier, either pipe: or temp‐
729 file:. If no specifier is given, pipe: is used by default.
730 A pipe: command must accept data on stdin and return the transformed
732 data on stdout.
733 Pipe example:
735 [encode]
737 # uncompress gzip files on checkin to improve delta compression
738 # note: not necessarily a good idea, just an example
739 *.gz = pipe: gunzip
740 [decode]
742 # recompress gzip files when writing them to the working dir (we
743 # can safely omit "pipe:", because it's the default)
744 *.gz = gzip
745 A tempfile: command is a template. The string INFILE is replaced with
747 the name of a temporary file that contains the data to be filtered by
748 the command. The string OUTFILE is replaced with the name of an empty
749 temporary file, where the filtered data must be written by the command.
750 Note The tempfile mechanism is recommended for Windows systems, where
752 the standard shell I/O redirection operators often have strange
753 effects and may corrupt the contents of your files.
754 This filter mechanism is used internally by the eol extension to trans‐
756 late line ending characters between Windows (CRLF) and Unix (LF) for‐
757 mat. We suggest you use the eol extension for convenience.
758 defaults
760 (defaults are deprecated. Don't use them. Use aliases instead.)
761 Use the [defaults] section to define command defaults, i.e. the default
763 options/arguments to pass to the specified commands.
764 The following example makes hg log run in verbose mode, and hg status
766 show only the modified files, by default:
767 [defaults]
769 log = -v
770 status = -m
771 The actual commands, instead of their aliases, must be used when defin‐
773 ing command defaults. The command defaults will also be applied to the
774 aliases of the commands defined.
775 diff
777 Settings used when displaying diffs. Everything except for unified is a
778 Boolean and defaults to False. See hg help config.annotate for related
779 options for the annotate command.
780 git
782 Use git extended diff format.
784 nobinary
786 Omit git binary patches.
788 nodates
790 Don't include dates in diff headers.
792 noprefix
794 Omit 'a/' and 'b/' prefixes from filenames. Ignored in plain
796 mode.
797 showfunc
799 Show which function each change is in.
801 ignorews
803 Ignore white space when comparing lines.
805 ignorewsamount
807 Ignore changes in the amount of white space.
809 ignoreblanklines
811 Ignore changes whose lines are all blank.
813 unified
815 Number of lines of context to show.
817 word-diff
819 Highlight changed words.
821 email
823 Settings for extensions that send email messages.
824 from
826 Optional. Email address to use in "From" header and SMTP enve‐
828 lope of outgoing messages.
829 to
831 Optional. Comma-separated list of recipients' email addresses.
833 cc
835 Optional. Comma-separated list of carbon copy recipients' email
837 addresses.
838 bcc
840 Optional. Comma-separated list of blind carbon copy recipients'
842 email addresses.
843 method
845 Optional. Method to use to send email messages. If value is smtp
847 (default), use SMTP (see the [smtp] section for configuration).
848 Otherwise, use as name of program to run that acts like sendmail
849 (takes -f option for sender, list of recipients on command line,
850 message on stdin). Normally, setting this to sendmail or
851 /usr/sbin/sendmail is enough to use sendmail to send messages.
852 charsets
854 Optional. Comma-separated list of character sets considered con‐
856 venient for recipients. Addresses, headers, and parts not con‐
857 taining patches of outgoing messages will be encoded in the
858 first character set to which conversion from local encoding
859 ($HGENCODING, ui.fallbackencoding) succeeds. If correct conver‐
860 sion fails, the text in question is sent as is. (default: '')
861 Order of outgoing email character sets:
863 1. us-ascii: always first, regardless of settings
865 2. email.charsets: in order given by user
867 3. ui.fallbackencoding: if not in email.charsets
869 4. $HGENCODING: if not in email.charsets
871 5. utf-8: always last, regardless of settings
873 Email example:
875 [email]
877 from = Joseph User <joe.user@example.com>
878 method = /usr/sbin/sendmail
879 # charsets for western Europeans
880 # us-ascii, utf-8 omitted, as they are tried first and last
881 charsets = iso-8859-1, iso-8859-15, windows-1252
882 extensions
884 Mercurial has an extension mechanism for adding new features. To enable
885 an extension, create an entry for it in this section.
886 If you know that the extension is already in Python's search path, you
888 can give the name of the module, followed by =, with nothing after the
889 =.
890 Otherwise, give a name that you choose, followed by =, followed by the
892 path to the .py file (including the file name extension) that defines
893 the extension.
894 To explicitly disable an extension that is enabled in an hgrc of
896 broader scope, prepend its path with !, as in foo = !/ext/path or foo =
897 ! when path is not supplied.
898 Example for ~/.hgrc:
900 [extensions]
902 # (the churn extension will get loaded from Mercurial's path)
903 churn =
904 # (this extension will get loaded from the file specified)
905 myfeature = ~/.hgext/myfeature.py
906 If an extension fails to load, a warning will be issued, and Mercurial
908 will proceed. To enforce that an extension must be loaded, one can set
909 the required suboption in the config:
910 [extensions]
912 myfeature = ~/.hgext/myfeature.py
913 myfeature:required = yes
914 To debug extension loading issue, one can add --traceback to their mer‐
916 curial invocation.
917 A default setting can we set using the special * extension key:
919 [extensions]
921 *:required = yes
922 myfeature = ~/.hgext/myfeature.py
923 rebase=
924 format
926 Configuration that controls the repository format. Newer format options
927 are more powerful, but incompatible with some older versions of Mercu‐
928 rial. Format options are considered at repository initialization only.
929 You need to make a new clone for config changes to be taken into ac‐
930 count.
931 For more details about repository format and version compatibility, see
933 https://www.mercurial-scm.org/wiki/MissingRequirement
934 usegeneraldelta
936 Enable or disable the "generaldelta" repository format which im‐
938 proves repository compression by allowing "revlog" to store
939 deltas against arbitrary revisions instead of the previously
940 stored one. This provides significant improvement for reposito‐
941 ries with branches.
942 Repositories with this on-disk format require Mercurial version
944 1.9.
945 Enabled by default.
947 dotencode
949 Enable or disable the "dotencode" repository format which en‐
951 hances the "fncache" repository format (which has to be enabled
952 to use dotencode) to avoid issues with filenames starting with
953 "._" on Mac OS X and spaces on Windows.
954 Repositories with this on-disk format require Mercurial version
956 1.7.
957 Enabled by default.
959 usefncache
961 Enable or disable the "fncache" repository format which enhances
963 the "store" repository format (which has to be enabled to use
964 fncache) to allow longer filenames and avoids using Windows re‐
965 served names, e.g. "nul".
966 Repositories with this on-disk format require Mercurial version
968 1.1.
969 Enabled by default.
971 use-dirstate-v2
973 Enable or disable the experimental "dirstate-v2" feature. The
975 dirstate functionality is shared by all commands interacting
976 with the working copy. The new version is more robust, faster
977 and stores more information.
978 The performance-improving version of this feature is currently
980 only implemented in Rust (see hg help rust), so people not using
981 a version of Mercurial compiled with the Rust parts might actu‐
982 ally suffer some slowdown. For this reason, such versions will
983 by default refuse to access repositories with "dirstate-v2" en‐
984 abled.
985 This behavior can be adjusted via configuration: check hg help
987 config.storage.dirstate-v2.slow-path for details.
988 Repositories with this on-disk format require Mercurial 6.0 or
990 above.
991 By default this format variant is disabled if the fast implemen‐
993 tation is not available, and enabled by default if the fast im‐
994 plementation is available.
995 To accomodate installations of Mercurial without the fast imple‐
997 mentation, you can downgrade your repository. To do so run the
998 following command:
999 $ hg debugupgraderepo
1001 --run --config format.use-dirstate-v2=False --config
1002 storage.dirstate-v2.slow-path=allow
1003 For a more comprehensive guide, see hg help inter‐
1005 nals.dirstate-v2.
1006 use-dirstate-v2.automatic-upgrade-of-mismatching-repositories
1008 When enabled, an automatic upgrade will be triggered when a
1010 repository format does not match its use-dirstate-v2 config.
1011 This is an advanced behavior that most users will not need. We
1013 recommend you don't use this unless you are a seasoned adminis‐
1014 trator of a Mercurial install base.
1015 Automatic upgrade means that any process accessing the reposi‐
1017 tory will upgrade the repository format to use dirstate-v2. This
1018 only triggers if a change is needed. This also applies to opera‐
1019 tions that would have been read-only (like hg status).
1020 If the repository cannot be locked, the automatic-upgrade opera‐
1022 tion will be skipped. The next operation will attempt it again.
1023 This configuration will apply for moves in any direction, either
1025 adding the dirstate-v2 format if format.use-dirstate-v2=yes or
1026 removing the dirstate-v2 requirement if for‐
1027 mat.use-dirstate-v2=no. So we recommend setting both this value
1028 and format.use-dirstate-v2 at the same time.
1029 use-dirstate-v2.automatic-upgrade-of-mismatching-repositories:quiet
1031 Hide message when performing such automatic upgrade.
1033 use-dirstate-tracked-hint
1035 Enable or disable the writing of "tracked key" file alongside
1037 the dirstate. (default to disabled)
1038 That "tracked-hint" can help external automations to detect
1040 changes to the set of tracked files. (i.e the result of hg files
1041 or hg status -macd)
1042 The tracked-hint is written in a new .hg/dirstate-tracked-hint.
1044 That file contains two lines: - the first line is the file ver‐
1045 sion (currently: 1), - the second line contains the
1046 "tracked-hint". That file is written right after the dirstate
1047 is written.
1048 The tracked-hint changes whenever the set of file tracked in the
1050 dirstate changes. The general idea is: - if the hint is identi‐
1051 cal, the set of tracked file SHOULD be identical, - if the hint
1052 is different, the set of tracked file MIGHT be different.
1053 The "hint is identical" case uses SHOULD as the dirstate and the
1055 hint file are two distinct files and therefore that cannot be
1056 read or written to in an atomic way. If the key is identical,
1057 nothing garantees that the dirstate is not updated right after
1058 the hint file. This is considered a negligible limitation for
1059 the intended usecase. It is actually possible to prevent this
1060 race by taking the repository lock during read operations.
1061 They are two "ways" to use this feature:
1063 1) monitoring changes to the .hg/dirstate-tracked-hint, if the
1065 file changes, the tracked set might have changed.
1066 2. storing the value and comparing it to a later value.
1068 use-dirstate-tracked-hint.automatic-upgrade-of-mismatching-repositories
1070 When enabled, an automatic upgrade will be triggered when a
1072 repository format does not match its use-dirstate-tracked-hint
1073 config.
1074 This is an advanced behavior that most users will not need. We
1076 recommend you don't use this unless you are a seasoned adminis‐
1077 trator of a Mercurial install base.
1078 Automatic upgrade means that any process accessing the reposi‐
1080 tory will upgrade the repository format to use
1081 dirstate-tracked-hint. This only triggers if a change is needed.
1082 This also applies to operations that would have been read-only
1083 (like hg status).
1084 If the repository cannot be locked, the automatic-upgrade opera‐
1086 tion will be skipped. The next operation will attempt it again.
1087 This configuration will apply for moves in any direction, either
1089 adding the dirstate-tracked-hint format if for‐
1090 mat.use-dirstate-tracked-hint=yes or removing the
1091 dirstate-tracked-hint requirement if for‐
1092 mat.use-dirstate-tracked-hint=no. So we recommend setting both
1093 this value and format.use-dirstate-tracked-hint at the same
1094 time.
1095 use-dirstate-tracked-hint.automatic-upgrade-of-mismatching-reposito‐
1097 ries:quiet
1098 Hide message when performing such automatic upgrade.
1100 use-persistent-nodemap
1102 Enable or disable the "persistent-nodemap" feature which im‐
1104 proves performance if the Rust extensions are available.
1105 The "persistent-nodemap" persist the "node -> rev" on disk re‐
1107 moving the need to dynamically build that mapping for each Mer‐
1108 curial invocation. This significantly reduces the startup cost
1109 of various local and server-side operation for larger reposito‐
1110 ries.
1111 The performance-improving version of this feature is currently
1113 only implemented in Rust (see hg help rust), so people not using
1114 a version of Mercurial compiled with the Rust parts might actu‐
1115 ally suffer some slowdown. For this reason, such versions will
1116 by default refuse to access repositories with "persis‐
1117 tent-nodemap".
1118 This behavior can be adjusted via configuration: check hg help
1120 config.storage.revlog.persistent-nodemap.slow-path for details.
1121 Repositories with this on-disk format require Mercurial 5.4 or
1123 above.
1124 By default this format variant is disabled if the fast implemen‐
1126 tation is not available, and enabled by default if the fast im‐
1127 plementation is available.
1128 To accomodate installations of Mercurial without the fast imple‐
1130 mentation, you can downgrade your repository. To do so run the
1131 following command:
1132 $ hg debugupgraderepo
1134 --run --config format.use-persistent-nodemap=False --con‐
1135 fig storage.revlog.persistent-nodemap.slow-path=allow
1136 use-share-safe
1138 Enforce "safe" behaviors for all "shares" that access this
1140 repository.
1141 With this feature, "shares" using this repository as a source
1143 will:
1144 • read the source repository's configuration
1146 (<source>/.hg/hgrc).
1147 • read and use the source repository's "requirements" (except
1149 the working copy specific one).
1150 Without this feature, "shares" using this repository as a source
1152 will:
1153 • keep tracking the repository "requirements" in the share only,
1155 ignoring the source "requirements", possibly diverging from
1156 them.
1157 • ignore source repository config. This can create problems,
1159 like silently ignoring important hooks.
1160 Beware that existing shares will not be upgraded/downgraded, and
1162 by default, Mercurial will refuse to interact with them until
1163 the mismatch is resolved. See hg help config.share.safe-mis‐
1164 match.source-safe and hg help config.share.safe-mis‐
1165 match.source-not-safe for details.
1166 Introduced in Mercurial 5.7.
1168 Enabled by default in Mercurial 6.1.
1170 use-share-safe.automatic-upgrade-of-mismatching-repositories
1172 When enabled, an automatic upgrade will be triggered when a
1174 repository format does not match its use-share-safe config.
1175 This is an advanced behavior that most users will not need. We
1177 recommend you don't use this unless you are a seasoned adminis‐
1178 trator of a Mercurial install base.
1179 Automatic upgrade means that any process accessing the reposi‐
1181 tory will upgrade the repository format to use share-safe. This
1182 only triggers if a change is needed. This also applies to opera‐
1183 tion that would have been read-only (like hg status).
1184 If the repository cannot be locked, the automatic-upgrade opera‐
1186 tion will be skipped. The next operation will attempt it again.
1187 This configuration will apply for moves in any direction, either
1189 adding the share-safe format if format.use-share-safe=yes or re‐
1190 moving the share-safe requirement if format.use-share-safe=no.
1191 So we recommend setting both this value and for‐
1192 mat.use-share-safe at the same time.
1193 use-share-safe.automatic-upgrade-of-mismatching-repositories:quiet
1195 Hide message when performing such automatic upgrade.
1197 usestore
1199 Enable or disable the "store" repository format which improves
1201 compatibility with systems that fold case or otherwise mangle
1202 filenames. Disabling this option will allow you to store longer
1203 filenames in some situations at the expense of compatibility.
1204 Repositories with this on-disk format require Mercurial version
1206 0.9.4.
1207 Enabled by default.
1209 sparse-revlog
1211 Enable or disable the sparse-revlog delta strategy. This format
1213 improves delta re-use inside revlog. For very branchy reposito‐
1214 ries, it results in a smaller store. For repositories with many
1215 revisions, it also helps performance (by using shortened delta
1216 chains.)
1217 Repositories with this on-disk format require Mercurial version
1219 4.7
1220 Enabled by default.
1222 revlog-compression
1224 Compression algorithm used by revlog. Supported values are zlib
1226 and zstd. The zlib engine is the historical default of Mercu‐
1227 rial. zstd is a newer format that is usually a net win over
1228 zlib, operating faster at better compression rates. Use zstd to
1229 reduce CPU usage. Multiple values can be specified, the first
1230 available one will be used.
1231 On some systems, the Mercurial installation may lack zstd sup‐
1233 port.
1234 Default is zstd if available, zlib otherwise.
1236 bookmarks-in-store
1238 Store bookmarks in .hg/store/. This means that bookmarks are
1240 shared when using hg share regardless of the -B option.
1241 Repositories with this on-disk format require Mercurial version
1243 5.1.
1244 Disabled by default.
1246 graph
1248 Web graph view configuration. This section let you change graph ele‐
1249 ments display properties by branches, for instance to make the default
1250 branch stand out.
1251 Each line has the following format:
1253 <branch>.<argument> = <value>
1255 where <branch> is the name of the branch being customized. Example:
1257 [graph]
1259 # 2px width
1260 default.width = 2
1261 # red color
1262 default.color = FF0000
1263 Supported arguments:
1265 width
1267 Set branch edges width in pixels.
1269 color
1271 Set branch edges color in hexadecimal RGB notation.
1273 hooks
1275 Commands or Python functions that get automatically executed by various
1276 actions such as starting or finishing a commit. Multiple hooks can be
1277 run for the same action by appending a suffix to the action. Overriding
1278 a site-wide hook can be done by changing its value or setting it to an
1279 empty string. Hooks can be prioritized by adding a prefix of priority.
1280 to the hook name on a new line and setting the priority. The default
1281 priority is 0.
1282 Example .hg/hgrc:
1284 [hooks]
1286 # update working directory after adding changesets
1287 changegroup.update = hg update
1288 # do not use the site-wide hook
1289 incoming =
1290 incoming.email = /my/email/hook
1291 incoming.autobuild = /my/build/hook
1292 # force autobuild hook to run before other incoming hooks
1293 priority.incoming.autobuild = 1
1294 ### control HGPLAIN setting when running autobuild hook
1295 # HGPLAIN always set (default from Mercurial 5.7)
1296 incoming.autobuild:run-with-plain = yes
1297 # HGPLAIN never set
1298 incoming.autobuild:run-with-plain = no
1299 # HGPLAIN inherited from environment (default before Mercurial 5.7)
1300 incoming.autobuild:run-with-plain = auto
1301 Most hooks are run with environment variables set that give useful ad‐
1303 ditional information. For each hook below, the environment variables it
1304 is passed are listed with names in the form $HG_foo. The $HG_HOOKTYPE
1305 and $HG_HOOKNAME variables are set for all hooks. They contain the
1306 type of hook which triggered the run and the full name of the hook in
1307 the config, respectively. In the example above, this will be $HG_HOOK‐
1308 TYPE=incoming and $HG_HOOKNAME=incoming.email.
1309 Some basic Unix syntax can be enabled for portability, including $VAR
1311 and ${VAR} style variables. A ~ followed by \ or / will be expanded to
1312 %USERPROFILE% to simulate a subset of tilde expansion on Unix. To use
1313 a literal $ or ~, it must be escaped with a back slash or inside of a
1314 strong quote. Strong quotes will be replaced by double quotes after
1315 processing.
1316 This feature is enabled by adding a prefix of tonative. to the hook
1318 name on a new line, and setting it to True. For example:
1319 [hooks]
1321 incoming.autobuild = /my/build/hook
1322 # enable translation to cmd.exe syntax for autobuild hook
1323 tonative.incoming.autobuild = True
1324 changegroup
1326 Run after a changegroup has been added via push, pull or unbun‐
1328 dle. The ID of the first new changeset is in $HG_NODE and last
1329 is in $HG_NODE_LAST. The URL from which changes came is in
1330 $HG_URL.
1331 commit
1333 Run after a changeset has been created in the local repository.
1335 The ID of the newly created changeset is in $HG_NODE. Parent
1336 changeset IDs are in $HG_PARENT1 and $HG_PARENT2.
1337 incoming
1339 Run after a changeset has been pulled, pushed, or unbundled into
1341 the local repository. The ID of the newly arrived changeset is
1342 in $HG_NODE. The URL that was source of the changes is in
1343 $HG_URL.
1344 outgoing
1346 Run after sending changes from the local repository to another.
1348 The ID of first changeset sent is in $HG_NODE. The source of op‐
1349 eration is in $HG_SOURCE. Also see hg help config.hooks.preout‐
1350 going.
1351 post-<command>
1353 Run after successful invocations of the associated command. The
1355 contents of the command line are passed as $HG_ARGS and the re‐
1356 sult code in $HG_RESULT. Parsed command line arguments are
1357 passed as $HG_PATS and $HG_OPTS. These contain string represen‐
1358 tations of the python data internally passed to <command>.
1359 $HG_OPTS is a dictionary of options (with unspecified options
1360 set to their defaults). $HG_PATS is a list of arguments. Hook
1361 failure is ignored.
1362 fail-<command>
1364 Run after a failed invocation of an associated command. The con‐
1366 tents of the command line are passed as $HG_ARGS. Parsed command
1367 line arguments are passed as $HG_PATS and $HG_OPTS. These con‐
1368 tain string representations of the python data internally passed
1369 to <command>. $HG_OPTS is a dictionary of options (with unspeci‐
1370 fied options set to their defaults). $HG_PATS is a list of argu‐
1371 ments. Hook failure is ignored.
1372 pre-<command>
1374 Run before executing the associated command. The contents of the
1376 command line are passed as $HG_ARGS. Parsed command line argu‐
1377 ments are passed as $HG_PATS and $HG_OPTS. These contain string
1378 representations of the data internally passed to <command>.
1379 $HG_OPTS is a dictionary of options (with unspecified options
1380 set to their defaults). $HG_PATS is a list of arguments. If the
1381 hook returns failure, the command doesn't execute and Mercurial
1382 returns the failure code.
1383 prechangegroup
1385 Run before a changegroup is added via push, pull or unbundle.
1387 Exit status 0 allows the changegroup to proceed. A non-zero sta‐
1388 tus will cause the push, pull or unbundle to fail. The URL from
1389 which changes will come is in $HG_URL.
1390 precommit
1392 Run before starting a local commit. Exit status 0 allows the
1394 commit to proceed. A non-zero status will cause the commit to
1395 fail. Parent changeset IDs are in $HG_PARENT1 and $HG_PARENT2.
1396 prelistkeys
1398 Run before listing pushkeys (like bookmarks) in the repository.
1400 A non-zero status will cause failure. The key namespace is in
1401 $HG_NAMESPACE.
1402 preoutgoing
1404 Run before collecting changes to send from the local repository
1406 to another. A non-zero status will cause failure. This lets you
1407 prevent pull over HTTP or SSH. It can also prevent propagating
1408 commits (via local pull, push (outbound) or bundle commands),
1409 but not completely, since you can just copy files instead. The
1410 source of operation is in $HG_SOURCE. If "serve", the operation
1411 is happening on behalf of a remote SSH or HTTP repository. If
1412 "push", "pull" or "bundle", the operation is happening on behalf
1413 of a repository on same system.
1414 prepushkey
1416 Run before a pushkey (like a bookmark) is added to the reposi‐
1418 tory. A non-zero status will cause the key to be rejected. The
1419 key namespace is in $HG_NAMESPACE, the key is in $HG_KEY, the
1420 old value (if any) is in $HG_OLD, and the new value is in
1421 $HG_NEW.
1422 pretag
1424 Run before creating a tag. Exit status 0 allows the tag to be
1426 created. A non-zero status will cause the tag to fail. The ID of
1427 the changeset to tag is in $HG_NODE. The name of tag is in
1428 $HG_TAG. The tag is local if $HG_LOCAL=1, or in the repository
1429 if $HG_LOCAL=0.
1430 pretransmit-inline-clone-bundle
1432 Run before transferring an inline clonebundle to the peer. If
1434 the exit status is 0, the inline clonebundle will be allowed to
1435 be transferred. A non-zero status will cause the transfer to
1436 fail. The path of the inline clonebundle is in $HG_CLONEB‐
1437 UNDLEPATH.
1438 pretxnopen
1440 Run before any new repository transaction is open. The reason
1442 for the transaction will be in $HG_TXNNAME, and a unique identi‐
1443 fier for the transaction will be in $HG_TXNID. A non-zero status
1444 will prevent the transaction from being opened.
1445 pretxnclose
1447 Run right before the transaction is actually finalized. Any
1449 repository change will be visible to the hook program. This lets
1450 you validate the transaction content or change it. Exit status 0
1451 allows the commit to proceed. A non-zero status will cause the
1452 transaction to be rolled back. The reason for the transaction
1453 opening will be in $HG_TXNNAME, and a unique identifier for the
1454 transaction will be in $HG_TXNID. The rest of the available data
1455 will vary according the transaction type. Changes unbundled to
1456 the repository will add $HG_URL and $HG_SOURCE. New changesets
1457 will add $HG_NODE (the ID of the first added changeset),
1458 $HG_NODE_LAST (the ID of the last added changeset). Bookmark
1459 and phase changes will set $HG_BOOKMARK_MOVED and
1460 $HG_PHASES_MOVED to 1 respectively. The number of new obsmark‐
1461 ers, if any, will be in $HG_NEW_OBSMARKERS, etc.
1462 pretxnclose-bookmark
1464 Run right before a bookmark change is actually finalized. Any
1466 repository change will be visible to the hook program. This lets
1467 you validate the transaction content or change it. Exit status 0
1468 allows the commit to proceed. A non-zero status will cause the
1469 transaction to be rolled back. The name of the bookmark will be
1470 available in $HG_BOOKMARK, the new bookmark location will be
1471 available in $HG_NODE while the previous location will be avail‐
1472 able in $HG_OLDNODE. In case of a bookmark creation $HG_OLDNODE
1473 will be empty. In case of deletion $HG_NODE will be empty. In
1474 addition, the reason for the transaction opening will be in
1475 $HG_TXNNAME, and a unique identifier for the transaction will be
1476 in $HG_TXNID.
1477 pretxnclose-phase
1479 Run right before a phase change is actually finalized. Any
1481 repository change will be visible to the hook program. This lets
1482 you validate the transaction content or change it. Exit status 0
1483 allows the commit to proceed. A non-zero status will cause the
1484 transaction to be rolled back. The hook is called multiple
1485 times, once for each revision affected by a phase change. The
1486 affected node is available in $HG_NODE, the phase in $HG_PHASE
1487 while the previous $HG_OLDPHASE. In case of new node, $HG_OLD‐
1488 PHASE will be empty. In addition, the reason for the transac‐
1489 tion opening will be in $HG_TXNNAME, and a unique identifier for
1490 the transaction will be in $HG_TXNID. The hook is also run for
1491 newly added revisions. In this case the $HG_OLDPHASE entry will
1492 be empty.
1493 txnclose
1495 Run after any repository transaction has been committed. At this
1497 point, the transaction can no longer be rolled back. The hook
1498 will run after the lock is released. See hg help con‐
1499 fig.hooks.pretxnclose for details about available variables.
1500 txnclose-bookmark
1502 Run after any bookmark change has been committed. At this point,
1504 the transaction can no longer be rolled back. The hook will run
1505 after the lock is released. See hg help config.hooks.pretxn‐
1506 close-bookmark for details about available variables.
1507 txnclose-phase
1509 Run after any phase change has been committed. At this point,
1511 the transaction can no longer be rolled back. The hook will run
1512 after the lock is released. See hg help config.hooks.pretxn‐
1513 close-phase for details about available variables.
1514 txnabort
1516 Run when a transaction is aborted. See hg help con‐
1518 fig.hooks.pretxnclose for details about available variables.
1519 pretxnchangegroup
1521 Run after a changegroup has been added via push, pull or unbun‐
1523 dle, but before the transaction has been committed. The change‐
1524 group is visible to the hook program. This allows validation of
1525 incoming changes before accepting them. The ID of the first new
1526 changeset is in $HG_NODE and last is in $HG_NODE_LAST. Exit sta‐
1527 tus 0 allows the transaction to commit. A non-zero status will
1528 cause the transaction to be rolled back, and the push, pull or
1529 unbundle will fail. The URL that was the source of changes is in
1530 $HG_URL.
1531 pretxncommit
1533 Run after a changeset has been created, but before the transac‐
1535 tion is committed. The changeset is visible to the hook program.
1536 This allows validation of the commit message and changes. Exit
1537 status 0 allows the commit to proceed. A non-zero status will
1538 cause the transaction to be rolled back. The ID of the new
1539 changeset is in $HG_NODE. The parent changeset IDs are in
1540 $HG_PARENT1 and $HG_PARENT2.
1541 preupdate
1543 Run before updating the working directory. Exit status 0 allows
1545 the update to proceed. A non-zero status will prevent the up‐
1546 date. The changeset ID of first new parent is in $HG_PARENT1.
1547 If updating to a merge, the ID of second new parent is in
1548 $HG_PARENT2.
1549 listkeys
1551 Run after listing pushkeys (like bookmarks) in the repository.
1553 The key namespace is in $HG_NAMESPACE. $HG_VALUES is a dictio‐
1554 nary containing the keys and values.
1555 pushkey
1557 Run after a pushkey (like a bookmark) is added to the reposi‐
1559 tory. The key namespace is in $HG_NAMESPACE, the key is in
1560 $HG_KEY, the old value (if any) is in $HG_OLD, and the new value
1561 is in $HG_NEW.
1562 tag
1564 Run after a tag is created. The ID of the tagged changeset is in
1566 $HG_NODE. The name of tag is in $HG_TAG. The tag is local if
1567 $HG_LOCAL=1, or in the repository if $HG_LOCAL=0.
1568 update
1570 Run after updating the working directory. The changeset ID of
1572 first new parent is in $HG_PARENT1. If updating to a merge, the
1573 ID of second new parent is in $HG_PARENT2. If the update suc‐
1574 ceeded, $HG_ERROR=0. If the update failed (e.g. because con‐
1575 flicts were not resolved), $HG_ERROR=1.
1576 Note It is generally better to use standard hooks rather than the
1578 generic pre- and post- command hooks, as they are guaranteed to
1579 be called in the appropriate contexts for influencing transac‐
1580 tions. Also, hooks like "commit" will be called in all contexts
1581 that generate a commit (e.g. tag) and not just the commit com‐
1582 mand.
1583 Note Environment variables with empty values may not be passed to
1585 hooks on platforms such as Windows. As an example, $HG_PARENT2
1586 will have an empty value under Unix-like platforms for non-merge
1587 changesets, while it will not be available at all under Windows.
1588 The syntax for Python hooks is as follows:
1590 hookname = python:modulename.submodule.callable
1592 hookname = python:/path/to/python/module.py:callable
1593 Python hooks are run within the Mercurial process. Each hook is called
1595 with at least three keyword arguments: a ui object (keyword ui), a
1596 repository object (keyword repo), and a hooktype keyword that tells
1597 what kind of hook is used. Arguments listed as environment variables
1598 above are passed as keyword arguments, with no HG_ prefix, and names in
1599 lower case.
1600 If a Python hook returns a "true" value or raises an exception, this is
1602 treated as a failure.
1603 hostfingerprints
1605 (Deprecated. Use [hostsecurity]'s fingerprints options instead.)
1606 Fingerprints of the certificates of known HTTPS servers.
1608 A HTTPS connection to a server with a fingerprint configured here will
1610 only succeed if the servers certificate matches the fingerprint. This
1611 is very similar to how ssh known hosts works.
1612 The fingerprint is the SHA-1 hash value of the DER encoded certificate.
1614 Multiple values can be specified (separated by spaces or commas). This
1615 can be used to define both old and new fingerprints while a host tran‐
1616 sitions to a new certificate.
1617 The CA chain and web.cacerts is not used for servers with a finger‐
1619 print.
1620 For example:
1622 [hostfingerprints]
1624 hg.intevation.de = fc:e2:8d:d9:51:cd:cb:c1:4d:18:6b:b7:44:8d:49:72:57:e6:cd:33
1625 hg.intevation.org = fc:e2:8d:d9:51:cd:cb:c1:4d:18:6b:b7:44:8d:49:72:57:e6:cd:33
1626 hostsecurity
1628 Used to specify global and per-host security settings for connecting to
1629 other machines.
1630 The following options control default behavior for all hosts.
1632 ciphers
1634 Defines the cryptographic ciphers to use for connections.
1636 Value must be a valid OpenSSL Cipher List Format as documented
1638 at
1639 https://www.openssl.org/docs/manmaster/apps/ciphers.html#CIPHER-LIST-FORMAT
1640 .
1641 This setting is for advanced users only. Setting to incorrect
1643 values can significantly lower connection security or decrease
1644 performance. You have been warned.
1645 This option requires Python 2.7.
1647 minimumprotocol
1649 Defines the minimum channel encryption protocol to use.
1651 By default, the highest version of TLS supported by both client
1653 and server is used.
1654 Allowed values are: tls1.0, tls1.1, tls1.2.
1656 When running on an old Python version, only tls1.0 is allowed
1658 since old versions of Python only support up to TLS 1.0.
1659 When running a Python that supports modern TLS versions, the de‐
1661 fault is tls1.1. tls1.0 can still be used to allow TLS 1.0. How‐
1662 ever, this weakens security and should only be used as a feature
1663 of last resort if a server does not support TLS 1.1+.
1664 Options in the [hostsecurity] section can have the form hostname:set‐
1666 ting. This allows multiple settings to be defined on a per-host basis.
1667 The following per-host settings can be defined.
1669 ciphers
1671 This behaves like ciphers as described above except it only ap‐
1673 plies to the host on which it is defined.
1674 fingerprints
1676 A list of hashes of the DER encoded peer/remote certificate.
1678 Values have the form algorithm:fingerprint. e.g.
1679 sha256:c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2.
1680 In addition, colons (:) can appear in the fingerprint part.
1681 The following algorithms/prefixes are supported: sha1, sha256,
1683 sha512.
1684 Use of sha256 or sha512 is preferred.
1686 If a fingerprint is specified, the CA chain is not validated for
1688 this host and Mercurial will require the remote certificate to
1689 match one of the fingerprints specified. This means if the
1690 server updates its certificate, Mercurial will abort until a new
1691 fingerprint is defined. This can provide stronger security than
1692 traditional CA-based validation at the expense of convenience.
1693 This option takes precedence over verifycertsfile.
1695 minimumprotocol
1697 This behaves like minimumprotocol as described above except it
1699 only applies to the host on which it is defined.
1700 verifycertsfile
1702 Path to file a containing a list of PEM encoded certificates
1704 used to verify the server certificate. Environment variables and
1705 ~user constructs are expanded in the filename.
1706 The server certificate or the certificate's certificate author‐
1708 ity (CA) must match a certificate from this file or certificate
1709 verification will fail and connections to the server will be re‐
1710 fused.
1711 If defined, only certificates provided by this file will be
1713 used: web.cacerts and any system/default certificates will not
1714 be used.
1715 This option has no effect if the per-host fingerprints option is
1717 set.
1718 The format of the file is as follows:
1720 -----BEGIN CERTIFICATE-----
1722 ... (certificate in base64 PEM encoding) ...
1723 -----END CERTIFICATE-----
1724 -----BEGIN CERTIFICATE-----
1725 ... (certificate in base64 PEM encoding) ...
1726 -----END CERTIFICATE-----
1727 For example:
1729 [hostsecurity]
1731 hg.example.com:fingerprints = sha256:c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2
1732 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
1733 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
1734 foo.example.com:verifycertsfile = /etc/ssl/trusted-ca-certs.pem
1735 To change the default minimum protocol version to TLS 1.2 but to allow
1737 TLS 1.1 when connecting to hg.example.com:
1738 [hostsecurity]
1740 minimumprotocol = tls1.2
1741 hg.example.com:minimumprotocol = tls1.1
1742 http_proxy
1744 Used to access web-based Mercurial repositories through a HTTP proxy.
1745 host
1747 Host name and (optional) port of the proxy server, for example
1749 "myproxy:8000".
1750 no
1752 Optional. Comma-separated list of host names that should bypass
1754 the proxy.
1755 passwd
1757 Optional. Password to authenticate with at the proxy server.
1759 user
1761 Optional. User name to authenticate with at the proxy server.
1763 always
1765 Optional. Always use the proxy, even for localhost and any en‐
1767 tries in http_proxy.no. (default: False)
1768 http
1770 Used to configure access to Mercurial repositories via HTTP.
1771 timeout
1773 If set, blocking operations will timeout after that many sec‐
1775 onds. (default: None)
1776 merge
1778 This section specifies behavior during merges and updates.
1779 checkignored
1781 Controls behavior when an ignored file on disk has the same name
1783 as a tracked file in the changeset being merged or updated to,
1784 and has different contents. Options are abort, warn and ignore.
1785 With abort, abort on such files. With warn, warn on such files
1786 and back them up as .orig. With ignore, don't print a warning
1787 and back them up as .orig. (default: abort)
1788 checkunknown
1790 Controls behavior when an unknown file that isn't ignored has
1792 the same name as a tracked file in the changeset being merged or
1793 updated to, and has different contents. Similar to merge.check‐
1794 ignored, except for files that are not ignored. (default: abort)
1795 on-failure
1797 When set to continue (the default), the merge process attempts
1799 to merge all unresolved files using the merge chosen tool, re‐
1800 gardless of whether previous file merge attempts during the
1801 process succeeded or not. Setting this to prompt will prompt
1802 after any merge failure continue or halt the merge process. Set‐
1803 ting this to halt will automatically halt the merge process on
1804 any merge tool failure. The merge process can be restarted by
1805 using the resolve command. When a merge is halted, the reposi‐
1806 tory is left in a normal unresolved merge state. (default: con‐
1807 tinue)
1808 strict-capability-check
1810 Whether capabilities of internal merge tools are checked
1812 strictly or not, while examining rules to decide merge tool to
1813 be used. (default: False)
1814 merge-patterns
1816 This section specifies merge tools to associate with particular file
1817 patterns. Tools matched here will take precedence over the default
1818 merge tool. Patterns are globs by default, rooted at the repository
1819 root.
1820 Example:
1822 [merge-patterns]
1824 **.c = kdiff3
1825 **.jpg = myimgmerge
1826 merge-tools
1828 This section configures external merge tools to use for file-level
1829 merges. This section has likely been preconfigured at install time.
1830 Use hg config merge-tools to check the existing configuration. Also
1831 see hg help merge-tools for more details.
1832 Example ~/.hgrc:
1834 [merge-tools]
1836 # Override stock tool location
1837 kdiff3.executable = ~/bin/kdiff3
1838 # Specify command line
1839 kdiff3.args = $base $local $other -o $output
1840 # Give higher priority
1841 kdiff3.priority = 1
1842 # Changing the priority of preconfigured tool
1844 meld.priority = 0
1845 # Disable a preconfigured tool
1847 vimdiff.disabled = yes
1848 # Define new tool
1850 myHtmlTool.args = -m $local $other $base $output
1851 myHtmlTool.regkey = Software\FooSoftware\HtmlMerge
1852 myHtmlTool.priority = 1
1853 Supported arguments:
1855 priority
1857 The priority in which to evaluate this tool. (default: 0)
1859 executable
1861 Either just the name of the executable or its pathname.
1863 On Windows, the path can use environment variables with ${Pro‐
1865 gramFiles} syntax.
1866 (default: the tool name)
1868 args
1870 The arguments to pass to the tool executable. You can refer to
1872 the files being merged as well as the output file through these
1873 variables: $base, $local, $other, $output.
1874 The meaning of $local and $other can vary depending on which ac‐
1876 tion is being performed. During an update or merge, $local rep‐
1877 resents the original state of the file, while $other represents
1878 the commit you are updating to or the commit you are merging
1879 with. During a rebase, $local represents the destination of the
1880 rebase, and $other represents the commit being rebased.
1881 Some operations define custom labels to assist with identifying
1883 the revisions, accessible via $labellocal, $labelother, and $la‐
1884 belbase. If custom labels are not available, these will be lo‐
1885 cal, other, and base, respectively. (default: $local $base
1886 $other)
1887 premerge
1889 Attempt to run internal non-interactive 3-way merge tool before
1891 launching external tool. Options are true, false, keep,
1892 keep-merge3, or keep-mergediff (experimental). The keep option
1893 will leave markers in the file if the premerge fails. The
1894 keep-merge3 will do the same but include information about the
1895 base of the merge in the marker (see internal :merge3 in hg help
1896 merge-tools). The keep-mergediff option is similar but uses a
1897 different marker style (see internal :merge3 in hg help
1898 merge-tools). (default: True)
1899 binary
1901 This tool can merge binary files. (default: False, unless tool
1903 was selected by file pattern match)
1904 symlink
1906 This tool can merge symlinks. (default: False)
1908 check
1910 A list of merge success-checking options:
1912 changed
1914 Ask whether merge was successful when the merged file
1916 shows no changes.
1917 conflicts
1919 Check whether there are conflicts even though the tool
1921 reported success.
1922 prompt
1924 Always prompt for merge success, regardless of success
1926 reported by tool.
1927 fixeol
1929 Attempt to fix up EOL changes caused by the merge tool. (de‐
1931 fault: False)
1932 gui
1934 This tool requires a graphical interface to run. (default:
1936 False)
1937 mergemarkers
1939 Controls whether the labels passed via $labellocal, $labelother,
1941 and $labelbase are detailed (respecting mergemarkertemplate) or
1942 basic. If premerge is keep or keep-merge3, the conflict markers
1943 generated during premerge will be detailed if either this option
1944 or the corresponding option in the [ui] section is detailed.
1945 (default: basic)
1946 mergemarkertemplate
1948 This setting can be used to override mergemarker from the [com‐
1950 mand-templates] section on a per-tool basis; this applies to the
1951 $label-prefixed variables and to the conflict markers that are
1952 generated if premerge is keep` or ``keep-merge3. See the corre‐
1953 sponding variable in [ui] for more information.
1954 regkey
1956 Windows registry key which describes install location of this
1958 tool. Mercurial will search for this key first under HKEY_CUR‐
1959 RENT_USER and then under HKEY_LOCAL_MACHINE. (default: None)
1960 regkeyalt
1962 An alternate Windows registry key to try if the first key is not
1964 found. The alternate key uses the same regname and regappend
1965 semantics of the primary key. The most common use for this key
1966 is to search for 32bit applications on 64bit operating systems.
1967 (default: None)
1968 regname
1970 Name of value to read from specified registry key. (default:
1972 the unnamed (default) value)
1973 regappend
1975 String to append to the value read from the registry, typically
1977 the executable name of the tool. (default: None)
1978 pager
1980 Setting used to control when to paginate and with what external tool.
1981 See hg help pager for details.
1982 pager
1984 Define the external tool used as pager.
1986 If no pager is set, Mercurial uses the environment variable
1988 $PAGER. If neither pager.pager, nor $PAGER is set, a default
1989 pager will be used, typically less on Unix and more on Windows.
1990 Example:
1991 [pager]
1993 pager = less -FRX
1994 ignore
1996 List of commands to disable the pager for. Example:
1998 [pager]
2000 ignore = version, help, update
2001 patch
2003 Settings used when applying patches, for instance through the 'import'
2004 command or with Mercurial Queues extension.
2005 eol
2007 When set to 'strict' patch content and patched files end of
2009 lines are preserved. When set to lf or crlf, both files end of
2010 lines are ignored when patching and the result line endings are
2011 normalized to either LF (Unix) or CRLF (Windows). When set to
2012 auto, end of lines are again ignored while patching but line
2013 endings in patched files are normalized to their original set‐
2014 ting on a per-file basis. If target file does not exist or has
2015 no end of line, patch line endings are preserved. (default:
2016 strict)
2017 fuzz
2019 The number of lines of 'fuzz' to allow when applying patches.
2021 This controls how much context the patcher is allowed to ignore
2022 when trying to apply a patch. (default: 2)
2023 paths
2025 Assigns symbolic names and behavior to repositories.
2026 Options are symbolic names defining the URL or directory that is the
2028 location of the repository. Example:
2029 [paths]
2031 my_server = https://example.com/my_repo
2032 local_path = /home/me/repo
2033 These symbolic names can be used from the command line. To pull from
2035 my_server: hg pull my_server. To push to local_path: hg push local_path
2036 . You can check hg help urls for details about valid URLs.
2037 Options containing colons (:) denote sub-options that can influence be‐
2039 havior for that specific path. Example:
2040 [paths]
2042 my_server = https://example.com/my_path
2043 my_server:pushurl = ssh://example.com/my_path
2044 Paths using the path://otherpath scheme will inherit the sub-options
2046 value from the path they point to.
2047 The following sub-options can be defined:
2049 multi-urls
2051 A boolean option. When enabled the value of the [paths] entry
2053 will be parsed as a list and the alias will resolve to multiple
2054 destination. If some of the list entry use the path:// syntax,
2055 the suboption will be inherited individually.
2056 pushurl
2058 The URL to use for push operations. If not defined, the location
2060 defined by the path's main entry is used.
2061 pushrev
2063 A revset defining which revisions to push by default.
2065 When hg push is executed without a -r argument, the revset de‐
2067 fined by this sub-option is evaluated to determine what to push.
2068 For example, a value of . will push the working directory's re‐
2070 vision by default.
2071 Revsets specifying bookmarks will not result in the bookmark be‐
2073 ing pushed.
2074 bookmarks.mode
2076 How bookmark will be dealt during the exchange. It support the
2078 following value
2079 • default: the default behavior, local and remote bookmarks are
2081 "merged" on push/pull.
2082 • mirror: when pulling, replace local bookmarks by remote book‐
2084 marks. This is useful to replicate a repository, or as an op‐
2085 timization.
2086 • ignore: ignore bookmarks during exchange. (This currently
2088 only affect pulling)
2089 pulled-delta-reuse-policy Control the policy regarding deltas sent by
2091 the remote during pulls.
2092 This is an advanced option that non-admin users should not need to un‐
2094 derstand or set. This option can be used to speed up pulls from trusted
2095 central servers, or to fix-up deltas from older servers.
2096 It supports the following values:
2098 • default: use the policy defined by storage.revlog.reuse-exter‐
2100 nal-delta-parent,
2101 • no-reuse: start a new optimal delta search for each new revision we
2103 add to the repository. The deltas from the server will be reused when
2104 the base it applies to is tested (this can be frequent if that base
2105 is the one and unique parent of that revision). This can signifi‐
2106 cantly slowdown pulls but will result in an optimized storage space
2107 if the remote peer is sending poor quality deltas.
2108 • try-base: try to reuse the deltas from the remote peer as long as
2110 they create a valid delta-chain in the local repository. This speeds
2111 up the unbundling process, but can result in sub-optimal storage
2112 space if the remote peer is sending poor quality deltas.
2113 • forced: the deltas from the peer will be reused in all cases, even if
2115 the resulting delta-chain is "invalid". This setting will ensure the
2116 bundle is applied at minimal CPU cost, but it can result in longer
2117 delta chains being created on the client, making revisions poten‐
2118 tially slower to access in the future. If you think you need this op‐
2119 tion, you should make sure you are also talking to the Mercurial de‐
2120 veloper community to get confirmation.
2121 See hg help config.storage.revlog.reuse-external-delta-parent for a
2123 similar global option. That option defines the behavior of default.
2124 The following special named paths exist:
2126 default
2128 The URL or directory to use when no source or remote is speci‐
2130 fied.
2131 hg clone will automatically define this path to the location the
2133 repository was cloned from.
2134 default-push
2136 (deprecated) The URL or directory for the default hg push loca‐
2138 tion. default:pushurl should be used instead.
2139 phases
2141 Specifies default handling of phases. See hg help phases for more in‐
2142 formation about working with phases.
2143 publish
2145 Controls draft phase behavior when working as a server. When
2147 true, pushed changesets are set to public in both client and
2148 server and pulled or cloned changesets are set to public in the
2149 client. (default: True)
2150 new-commit
2152 Phase of newly-created commits. (default: draft)
2154 checksubrepos
2156 Check the phase of the current revision of each subrepository.
2158 Allowed values are "ignore", "follow" and "abort". For settings
2159 other than "ignore", the phase of the current revision of each
2160 subrepository is checked before committing the parent reposi‐
2161 tory. If any of those phases is greater than the phase of the
2162 parent repository (e.g. if a subrepo is in a "secret" phase
2163 while the parent repo is in "draft" phase), the commit is either
2164 aborted (if checksubrepos is set to "abort") or the higher phase
2165 is used for the parent repository commit (if set to "follow").
2166 (default: follow)
2167 profiling
2169 Specifies profiling type, format, and file output. Two profilers are
2170 supported: an instrumenting profiler (named ls), and a sampling pro‐
2171 filer (named stat).
2172 In this section description, 'profiling data' stands for the raw data
2174 collected during profiling, while 'profiling report' stands for a sta‐
2175 tistical text report generated from the profiling data.
2176 enabled
2178 Enable the profiler. (default: false)
2180 This is equivalent to passing --profile on the command line.
2182 type
2184 The type of profiler to use. (default: stat)
2186 ls
2188 Use Python's built-in instrumenting profiler. This pro‐
2190 filer works on all platforms, but each line number it re‐
2191 ports is the first line of a function. This restriction
2192 makes it difficult to identify the expensive parts of a
2193 non-trivial function.
2194 stat
2196 Use a statistical profiler, statprof. This profiler is
2198 most useful for profiling commands that run for longer
2199 than about 0.1 seconds.
2200 format
2202 Profiling format. Specific to the ls instrumenting profiler.
2204 (default: text)
2205 text
2207 Generate a profiling report. When saving to a file, it
2209 should be noted that only the report is saved, and the
2210 profiling data is not kept.
2211 kcachegrind
2213 Format profiling data for kcachegrind use: when saving to
2215 a file, the generated file can directly be loaded into
2216 kcachegrind.
2217 statformat
2219 Profiling format for the stat profiler. (default: hotpath)
2221 hotpath
2223 Show a tree-based display containing the hot path of exe‐
2225 cution (where most time was spent).
2226 bymethod
2228 Show a table of methods ordered by how frequently they
2230 are active.
2231 byline
2233 Show a table of lines in files ordered by how frequently
2235 they are active.
2236 json
2238 Render profiling data as JSON.
2240 freq
2242 Sampling frequency. Specific to the stat sampling profiler.
2244 (default: 1000)
2245 output
2247 File path where profiling data or report should be saved. If the
2249 file exists, it is replaced. (default: None, data is printed on
2250 stderr)
2251 sort
2253 Sort field. Specific to the ls instrumenting profiler. One of
2255 callcount, reccallcount, totaltime and inlinetime. (default:
2256 inlinetime)
2257 time-track
2259 Control if the stat profiler track cpu or real time. (default:
2261 cpu on Windows, otherwise real)
2262 limit
2264 Number of lines to show. Specific to the ls instrumenting pro‐
2266 filer. (default: 30)
2267 nested
2269 Show at most this number of lines of drill-down info after each
2271 main entry. This can help explain the difference between Total
2272 and Inline. Specific to the ls instrumenting profiler. (de‐
2273 fault: 0)
2274 showmin
2276 Minimum fraction of samples an entry must have for it to be dis‐
2278 played. Can be specified as a float between 0.0 and 1.0 or can
2279 have a % afterwards to allow values up to 100. e.g. 5%.
2280 Only used by the stat profiler.
2282 For the hotpath format, default is 0.05. For the chrome format,
2284 default is 0.005.
2285 The option is unused on other formats.
2287 showmax
2289 Maximum fraction of samples an entry can have before it is ig‐
2291 nored in display. Values format is the same as showmin.
2292 Only used by the stat profiler.
2294 For the chrome format, default is 0.999.
2296 The option is unused on other formats.
2298 showtime
2300 Show time taken as absolute durations, in addition to percent‐
2302 ages. Only used by the hotpath format. (default: true)
2303 progress
2305 Mercurial commands can draw progress bars that are as informative as
2306 possible. Some progress bars only offer indeterminate information,
2307 while others have a definite end point.
2308 debug
2310 Whether to print debug info when updating the progress bar. (de‐
2312 fault: False)
2313 delay
2315 Number of seconds (float) before showing the progress bar. (de‐
2317 fault: 3)
2318 changedelay
2320 Minimum delay before showing a new topic. When set to less than
2322 3 * refresh, that value will be used instead. (default: 1)
2323 estimateinterval
2325 Maximum sampling interval in seconds for speed and estimated
2327 time calculation. (default: 60)
2328 refresh
2330 Time in seconds between refreshes of the progress bar. (default:
2332 0.1)
2333 format
2335 Format of the progress bar.
2337 Valid entries for the format field are topic, bar, number, unit,
2339 estimate, speed, and item. item defaults to the last 20 charac‐
2340 ters of the item, but this can be changed by adding either
2341 -<num> which would take the last num characters, or +<num> for
2342 the first num characters.
2343 (default: topic bar number estimate)
2345 width
2347 If set, the maximum width of the progress information (that is,
2349 min(width, term width) will be used).
2350 clear-complete
2352 Clear the progress bar after it's done. (default: True)
2354 disable
2356 If true, don't show a progress bar.
2358 assume-tty
2360 If true, ALWAYS show a progress bar, unless disable is given.
2362 rebase
2364 evolution.allowdivergence
2365 Default to False, when True allow creating divergence when per‐
2367 forming rebase of obsolete changesets.
2368 revsetalias
2370 Alias definitions for revsets. See hg help revsets for details.
2371 rewrite
2373 backup-bundle
2374 Whether to save stripped changesets to a bundle file. (default:
2376 True)
2377 update-timestamp
2379 If true, updates the date and time of the changeset to current.
2381 It is only applicable for hg amend, hg commit --amend and hg un‐
2382 commit in the current version.
2383 empty-successor
2385 Control what happens with empty successors that are the result of
2387 rewrite operations. If set to skip, the successor is not created. If
2388 set to keep, the empty successor is created and kept.
2389 Currently, only the rebase and absorb commands consider this config‐
2391 uration. (EXPERIMENTAL)
2392 rhg
2394 The pure Rust fast-path for Mercurial. See rust/README.rst in the Mer‐
2395 curial repository.
2396 fallback-executable
2398 Path to the executable to run in a sub-process when falling back
2400 to another implementation of Mercurial.
2401 fallback-immediately
2403 Fall back to fallback-executable as soon as possible, regardless
2405 of the rhg.on-unsupported configuration. Useful for debugging,
2406 for example to bypass rhg if the deault hg points to rhg.
2407 Note that because this requires loading the configuration, it is
2409 possible that rhg error out before being able to fall back.
2410 ignored-extensions
2412 Controls which extensions should be ignored by rhg. By default,
2414 rhg triggers the rhg.on-unsupported behavior any unsupported ex‐
2415 tensions. Users can disable that behavior when they know that a
2416 given extension does not need support from rhg.
2417 Expects a list of extension names, or * to ignore all exten‐
2419 sions.
2420 Note: *:<suboption> is also a valid extension name for this con‐
2422 figuration option. As of this writing, the only valid "global"
2423 suboption is required.
2424 on-unsupported
2426 Controls the behavior of rhg when detecting unsupported fea‐
2428 tures.
2429 Possible values are abort (default), abort-silent and fallback.
2431 abort
2433 Print an error message describing what feature is not
2435 supported, and exit with code 252
2436 abort-silent
2438 Silently exit with code 252
2440 fallback
2442 Try running the fallback executable with the same parame‐
2444 ters (and trace the fallback reason, use RUST_LOG=trace
2445 to see).
2446 share
2448 safe-mismatch.source-safe
2449 Controls what happens when the shared repository does not use
2451 the share-safe mechanism but its source repository does.
2452 Possible values are abort (default), allow, upgrade-abort and
2454 upgrade-allow.
2455 abort
2457 Disallows running any command and aborts
2459 allow
2461 Respects the feature presence in the share source
2463 upgrade-abort
2465 Tries to upgrade the share to use share-safe; if it
2467 fails, aborts
2468 upgrade-allow
2470 Tries to upgrade the share; if it fails, continue by re‐
2472 specting the share source setting
2473 Check hg help config.format.use-share-safe for details about the
2475 share-safe feature.
2476 safe-mismatch.source-safe:verbose-upgrade
2478 Display a message when upgrading, (default: True)
2480 safe-mismatch.source-safe.warn
2482 Shows a warning on operations if the shared repository does not
2484 use share-safe, but the source repository does. (default: True)
2485 safe-mismatch.source-not-safe
2487 Controls what happens when the shared repository uses the
2489 share-safe mechanism but its source does not.
2490 Possible values are abort (default), allow, downgrade-abort and
2492 downgrade-allow.
2493 abort
2495 Disallows running any command and aborts
2497 allow
2499 Respects the feature presence in the share source
2501 downgrade-abort
2503 Tries to downgrade the share to not use share-safe; if it
2505 fails, aborts
2506 downgrade-allow
2508 Tries to downgrade the share to not use share-safe; if it
2510 fails, continue by respecting the shared source setting
2511 Check hg help config.format.use-share-safe for details about the
2513 share-safe feature.
2514 safe-mismatch.source-not-safe:verbose-upgrade
2516 Display a message when upgrading, (default: True)
2518 safe-mismatch.source-not-safe.warn
2520 Shows a warning on operations if the shared repository uses
2522 share-safe, but the source repository does not. (default: True)
2523 storage
2525 Control the strategy Mercurial uses internally to store history. Op‐
2526 tions in this category impact performance and repository size.
2527 revlog.issue6528.fix-incoming
2529 Version 5.8 of Mercurial had a bug leading to altering the par‐
2531 ent of file revision with copy information (or any other meta‐
2532 data) on exchange. This leads to the copy metadata to be over‐
2533 looked by various internal logic. The issue was fixed in Mercu‐
2534 rial 5.8.1. (See
2535 https://bz.mercurial-scm.org/show_bug.cgi?id=6528 for details)
2536 As a result Mercurial is now checking and fixing incoming file
2538 revisions to make sure there parents are in the right order.
2539 This behavior can be disabled by setting this option to no. This
2540 apply to revisions added through push, pull, clone and unbundle.
2541 To fix affected revisions that already exist within the reposi‐
2543 tory, one can use hg debug-repair-issue-6528.
2544 revlog.delta-parent-search.candidate-group-chunk-size
2546 Tune the number of delta bases the storage will consider in the
2548 same "round" of search. In some very rare cases, using a smaller
2549 value might result in faster processing at the possible expense
2550 of storage space, while using larger values might result in
2551 slower processing at the possible benefit of storage space. A
2552 value of "0" means no limitation.
2553 default: no limitation
2555 This is unlikely that you'll have to tune this configuration. If
2557 you think you do, consider talking with the mercurial developer
2558 community about your repositories.
2559 revlog.optimize-delta-parent-choice
2561 When storing a merge revision, both parents will be equally con‐
2563 sidered as a possible delta base. This results in better delta
2564 selection and improved revlog compression. This option is en‐
2565 abled by default.
2566 Turning this option off can result in large increase of reposi‐
2568 tory size for repository with many merges.
2569 revlog.persistent-nodemap.mmap
2571 Whether to use the Operating System "memory mapping" feature
2573 (when possible) to access the persistent nodemap data. This im‐
2574 prove performance and reduce memory pressure.
2575 Default to True.
2577 For details on the "persistent-nodemap" feature, see: hg help
2579 config.format.use-persistent-nodemap.
2580 revlog.persistent-nodemap.slow-path
2582 Control the behavior of Merucrial when using a repository with
2584 "persistent" nodemap with an installation of Mercurial without a
2585 fast implementation for the feature:
2586 allow: Silently use the slower implementation to access the
2588 repository. warn: Warn, but use the slower implementation to
2589 access the repository. abort: Prevent access to such reposito‐
2590 ries. (This is the default)
2591 For details on the "persistent-nodemap" feature, see: hg help
2593 config.format.use-persistent-nodemap.
2594 revlog.reuse-external-delta-parent
2596 Control the order in which delta parents are considered when
2598 adding new revisions from an external source. (typically: apply
2599 bundle from hg pull or hg push).
2600 New revisions are usually provided as a delta against other re‐
2602 visions. By default, Mercurial will try to reuse this delta
2603 first, therefore using the same "delta parent" as the source.
2604 Directly using delta's from the source reduces CPU usage and
2605 usually speeds up operation. However, in some case, the source
2606 might have sub-optimal delta bases and forcing their reevalua‐
2607 tion is useful. For example, pushes from an old client could
2608 have sub-optimal delta's parent that the server want to opti‐
2609 mize. (lack of general delta, bad parents, choice, lack of
2610 sparse-revlog, etc).
2611 This option is enabled by default. Turning it off will ensure
2613 bad delta parent choices from older client do not propagate to
2614 this repository, at the cost of a small increase in CPU consump‐
2615 tion.
2616 Note: this option only control the order in which delta parents
2618 are considered. Even when disabled, the existing delta from the
2619 source will be reused if the same delta parent is selected.
2620 revlog.reuse-external-delta
2622 Control the reuse of delta from external source. (typically:
2624 apply bundle from hg pull or hg push).
2625 New revisions are usually provided as a delta against another
2627 revision. By default, Mercurial will not recompute the same
2628 delta again, trusting externally provided deltas. There have
2629 been rare cases of small adjustment to the diffing algorithm in
2630 the past. So in some rare case, recomputing delta provided by
2631 ancient clients can provides better results. Disabling this op‐
2632 tion means going through a full delta recomputation for all in‐
2633 coming revisions. It means a large increase in CPU usage and
2634 will slow operations down.
2635 This option is enabled by default. When disabled, it also dis‐
2637 ables the related storage.revlog.reuse-external-delta-parent op‐
2638 tion.
2639 revlog.zlib.level
2641 Zlib compression level used when storing data into the reposi‐
2643 tory. Accepted Value range from 1 (lowest compression) to 9
2644 (highest compression). Zlib default value is 6.
2645 revlog.zstd.level
2647 zstd compression level used when storing data into the reposi‐
2649 tory. Accepted Value range from 1 (lowest compression) to 22
2650 (highest compression). (default 3)
2651 server
2653 Controls generic server settings.
2654 bookmarks-pushkey-compat
2656 Trigger pushkey hook when being pushed bookmark updates. This
2658 config exist for compatibility purpose (default to True)
2659 If you use pushkey and pre-pushkey hooks to control bookmark
2661 movement we recommend you migrate them to txnclose-bookmark and
2662 pretxnclose-bookmark.
2663 compressionengines
2665 List of compression engines and their relative priority to ad‐
2667 vertise to clients.
2668 The order of compression engines determines their priority, the
2670 first having the highest priority. If a compression engine is
2671 not listed here, it won't be advertised to clients.
2672 If not set (the default), built-in defaults are used. Run hg de‐
2674 buginstall to list available compression engines and their de‐
2675 fault wire protocol priority.
2676 Older Mercurial clients only support zlib compression and this
2678 setting has no effect for legacy clients.
2679 uncompressed
2681 Whether to allow clients to clone a repository using the uncom‐
2683 pressed streaming protocol. This transfers about 40% more data
2684 than a regular clone, but uses less memory and CPU on both
2685 server and client. Over a LAN (100 Mbps or better) or a very
2686 fast WAN, an uncompressed streaming clone is a lot faster (~10x)
2687 than a regular clone. Over most WAN connections (anything slower
2688 than about 6 Mbps), uncompressed streaming is slower, because of
2689 the extra data transfer overhead. This mode will also temporar‐
2690 ily hold the write lock while determining what data to transfer.
2691 (default: True)
2692 uncompressedallowsecret
2694 Whether to allow stream clones when the repository contains se‐
2696 cret changesets. (default: False)
2697 preferuncompressed
2699 When set, clients will try to use the uncompressed streaming
2701 protocol. (default: False)
2702 disablefullbundle
2704 When set, servers will refuse attempts to do pull-based clones.
2706 If this option is set, preferuncompressed and/or clone bundles
2707 are highly recommended. Partial clones will still be allowed.
2708 (default: False)
2709 streamunbundle
2711 When set, servers will apply data sent from the client directly,
2713 otherwise it will be written to a temporary file first. This op‐
2714 tion effectively prevents concurrent pushes.
2715 pullbundle
2717 When set, the server will check pullbundles.manifest for bundles
2719 covering the requested heads and common nodes. The first match‐
2720 ing entry will be streamed to the client.
2721 For HTTP transport, the stream will still use zlib compression
2723 for older clients.
2724 concurrent-push-mode
2726 Level of allowed race condition between two pushing clients.
2728 • 'strict': push is abort if another client touched the reposi‐
2730 tory while the push was preparing.
2731 • 'check-related': push is only aborted if it affects head that
2733 got also affected while the push was preparing. (default since
2734 5.4)
2735 'check-related' only takes effect for compatible clients (ver‐
2737 sion 4.3 and later). Older clients will use 'strict'.
2738 validate
2740 Whether to validate the completeness of pushed changesets by
2742 checking that all new file revisions specified in manifests are
2743 present. (default: False)
2744 maxhttpheaderlen
2746 Instruct HTTP clients not to send request headers longer than
2748 this many bytes. (default: 1024)
2749 bundle1
2751 Whether to allow clients to push and pull using the legacy bun‐
2753 dle1 exchange format. (default: True)
2754 bundle1gd
2756 Like bundle1 but only used if the repository is using the gener‐
2758 aldelta storage format. (default: True)
2759 bundle1.push
2761 Whether to allow clients to push using the legacy bundle1 ex‐
2763 change format. (default: True)
2764 bundle1gd.push
2766 Like bundle1.push but only used if the repository is using the
2768 generaldelta storage format. (default: True)
2769 bundle1.pull
2771 Whether to allow clients to pull using the legacy bundle1 ex‐
2773 change format. (default: True)
2774 bundle1gd.pull
2776 Like bundle1.pull but only used if the repository is using the
2778 generaldelta storage format. (default: True)
2779 Large repositories using the generaldelta storage format should
2781 consider setting this option because converting generaldelta
2782 repositories to the exchange format required by the bundle1 data
2783 format can consume a lot of CPU.
2784 bundle2.stream
2786 Whether to allow clients to pull using the bundle2 streaming
2788 protocol. (default: True)
2789 zliblevel
2791 Integer between -1 and 9 that controls the zlib compression
2793 level for wire protocol commands that send zlib compressed out‐
2794 put (notably the commands that send repository history data).
2795 The default (-1) uses the default zlib compression level, which
2797 is likely equivalent to 6. 0 means no compression. 9 means maxi‐
2798 mum compression.
2799 Setting this option allows server operators to make trade-offs
2801 between bandwidth and CPU used. Lowering the compression lowers
2802 CPU utilization but sends more bytes to clients.
2803 This option only impacts the HTTP server.
2805 zstdlevel
2807 Integer between 1 and 22 that controls the zstd compression
2809 level for wire protocol commands. 1 is the minimal amount of
2810 compression and 22 is the highest amount of compression.
2811 The default (3) should be significantly faster than zlib while
2813 likely delivering better compression ratios.
2814 This option only impacts the HTTP server.
2816 See also server.zliblevel.
2818 view
2820 Repository filter used when exchanging revisions with the peer.
2822 The default view (served) excludes secret and hidden changesets.
2824 Another useful value is immutable (no draft, secret or hidden
2825 changesets). (EXPERIMENTAL)
2826 smtp
2828 Configuration for extensions that need to send email messages.
2829 host
2831 Host name of mail server, e.g. "mail.example.com".
2833 port
2835 Optional. Port to connect to on mail server. (default: 465 if
2837 tls is smtps; 25 otherwise)
2838 tls
2840 Optional. Method to enable TLS when connecting to mail server:
2842 starttls, smtps or none. (default: none)
2843 username
2845 Optional. User name for authenticating with the SMTP server.
2847 (default: None)
2848 password
2850 Optional. Password for authenticating with the SMTP server. If
2852 not specified, interactive sessions will prompt the user for a
2853 password; non-interactive sessions will fail. (default: None)
2854 local_hostname
2856 Optional. The hostname that the sender can use to identify it‐
2858 self to the MTA.
2859 subpaths
2861 Subrepository source URLs can go stale if a remote server changes name
2862 or becomes temporarily unavailable. This section lets you define re‐
2863 write rules of the form:
2864 <pattern> = <replacement>
2866 where pattern is a regular expression matching a subrepository source
2868 URL and replacement is the replacement string used to rewrite it.
2869 Groups can be matched in pattern and referenced in replacements. For
2870 instance:
2871 http://server/(.*)-hg/ = http://hg.server/\1/
2873 rewrites http://server/foo-hg/ into http://hg.server/foo/.
2875 Relative subrepository paths are first made absolute, and the rewrite
2877 rules are then applied on the full (absolute) path. If pattern doesn't
2878 match the full path, an attempt is made to apply it on the relative
2879 path alone. The rules are applied in definition order.
2880 subrepos
2882 This section contains options that control the behavior of the sub‐
2883 repositories feature. See also hg help subrepos.
2884 Security note: auditing in Mercurial is known to be insufficient to
2886 prevent clone-time code execution with carefully constructed Git subre‐
2887 pos. It is unknown if a similar detect is present in Subversion subre‐
2888 pos. Both Git and Subversion subrepos are disabled by default out of
2889 security concerns. These subrepo types can be enabled using the respec‐
2890 tive options below.
2891 allowed
2893 Whether subrepositories are allowed in the working directory.
2895 When false, commands involving subrepositories (like hg update)
2897 will fail for all subrepository types. (default: true)
2898 hg:allowed
2900 Whether Mercurial subrepositories are allowed in the working di‐
2902 rectory. This option only has an effect if subrepos.allowed is
2903 true. (default: true)
2904 git:allowed
2906 Whether Git subrepositories are allowed in the working direc‐
2908 tory. This option only has an effect if subrepos.allowed is
2909 true.
2910 See the security note above before enabling Git subrepos. (de‐
2912 fault: false)
2913 svn:allowed
2915 Whether Subversion subrepositories are allowed in the working
2917 directory. This option only has an effect if subrepos.allowed is
2918 true.
2919 See the security note above before enabling Subversion subrepos.
2921 (default: false)
2922 templatealias
2924 Alias definitions for templates. See hg help templates for details.
2925 templates
2927 Use the [templates] section to define template strings. See hg help
2928 templates for details.
2929 trusted
2931 Mercurial will not use the settings in the .hg/hgrc file from a reposi‐
2932 tory if it doesn't belong to a trusted user or to a trusted group, as
2933 various hgrc features allow arbitrary commands to be run. This issue is
2934 often encountered when configuring hooks or extensions for shared
2935 repositories or servers. However, the web interface will use some safe
2936 settings from the [web] section.
2937 This section specifies what users and groups are trusted. The current
2939 user is always trusted. To trust everybody, list a user or a group with
2940 name *. These settings must be placed in an already-trusted file to
2941 take effect, such as $HOME/.hgrc of the user or service running Mercu‐
2942 rial.
2943 users
2945 Comma-separated list of trusted users.
2947 groups
2949 Comma-separated list of trusted groups.
2951 ui
2953 User interface controls.
2954 archivemeta
2956 Whether to include the .hg_archival.txt file containing meta
2958 data (hashes for the repository base and for tip) in archives
2959 created by the hg archive command or downloaded via hgweb. (de‐
2960 fault: True)
2961 askusername
2963 Whether to prompt for a username when committing. If True, and
2965 neither $HGUSER nor $EMAIL has been specified, then the user
2966 will be prompted to enter a username. If no username is entered,
2967 the default USER@HOST is used instead. (default: False)
2968 clonebundles
2970 Whether the "clone bundles" feature is enabled.
2972 When enabled, hg clone may download and apply a server-adver‐
2974 tised bundle file from a URL instead of using the normal ex‐
2975 change mechanism.
2976 This can likely result in faster and more reliable clones.
2978 (default: True)
2980 clonebundlefallback
2982 Whether failure to apply an advertised "clone bundle" from a
2984 server should result in fallback to a regular clone.
2985 This is disabled by default because servers advertising "clone
2987 bundles" often do so to reduce server load. If advertised bun‐
2988 dles start mass failing and clients automatically fall back to a
2989 regular clone, this would add significant and unexpected load to
2990 the server since the server is expecting clone operations to be
2991 offloaded to pre-generated bundles. Failing fast (the default
2992 behavior) ensures clients don't overwhelm the server when "clone
2993 bundle" application fails.
2994 (default: False)
2996 clonebundleprefers
2998 Defines preferences for which "clone bundles" to use.
3000 Servers advertising "clone bundles" may advertise multiple
3002 available bundles. Each bundle may have different attributes,
3003 such as the bundle type and compression format. This option is
3004 used to prefer a particular bundle over another.
3005 The following keys are defined by Mercurial:
3007 BUNDLESPEC
3009 A bundle type specifier. These are strings passed to hg
3010 bundle -t. e.g. gzip-v2 or bzip2-v1.
3011 COMPRESSION
3013 The compression format of the bundle. e.g. gzip and
3014 bzip2.
3015 Server operators may define custom keys.
3017 Example values: COMPRESSION=bzip2, BUNDLESPEC=gzip-v2, COMPRES‐
3019 SION=gzip.
3020 By default, the first bundle advertised by the server is used.
3022 color
3024 When to colorize output. Possible value are Boolean ("yes" or
3026 "no"), or "debug", or "always". (default: "yes"). "yes" will use
3027 color whenever it seems possible. See hg help color for details.
3028 commitsubrepos
3030 Whether to commit modified subrepositories when committing the
3032 parent repository. If False and one subrepository has uncommit‐
3033 ted changes, abort the commit. (default: False)
3034 debug
3036 Print debugging information. (default: False)
3038 editor
3040 The editor to use during a commit. (default: $EDITOR or vi)
3042 fallbackencoding
3044 Encoding to try if it's not possible to decode the changelog us‐
3046 ing UTF-8. (default: ISO-8859-1)
3047 graphnodetemplate
3049 (DEPRECATED) Use command-templates.graphnode instead.
3051 ignore
3053 A file to read per-user ignore patterns from. This file should
3055 be in the same format as a repository-wide .hgignore file. File‐
3056 names are relative to the repository root. This option supports
3057 hook syntax, so if you want to specify multiple ignore files,
3058 you can do so by setting something like ignore.other = ~/.hgig‐
3059 nore2. For details of the ignore file format, see the hgig‐
3060 nore(5) man page.
3061 interactive
3063 Allow to prompt the user. (default: True)
3065 interface
3067 Select the default interface for interactive features (default:
3069 text). Possible values are 'text' and 'curses'.
3070 interface.chunkselector
3072 Select the interface for change recording (e.g. hg commit -i).
3074 Possible values are 'text' and 'curses'. This config overrides
3075 the interface specified by ui.interface.
3076 large-file-limit
3078 Largest file size that gives no memory use warning. Possible
3080 values are integers or 0 to disable the check. Value is ex‐
3081 pressed in bytes by default, one can use standard units for con‐
3082 venience (e.g. 10MB, 0.1GB, etc) (default: 10MB)
3083 logtemplate
3085 (DEPRECATED) Use command-templates.log instead.
3087 merge
3089 The conflict resolution program to use during a manual merge.
3091 For more information on merge tools see hg help merge-tools.
3092 For configuring merge tools see the [merge-tools] section.
3093 mergemarkers
3095 Sets the merge conflict marker label styling. The detailed style
3097 uses the command-templates.mergemarker setting to style the la‐
3098 bels. The basic style just uses 'local' and 'other' as the
3099 marker label. One of basic or detailed. (default: basic)
3100 mergemarkertemplate
3102 (DEPRECATED) Use command-templates.mergemarker instead.
3104 message-output
3106 Where to write status and error messages. (default: stdio)
3108 channel
3110 Use separate channel for structured output. (Com‐
3112 mand-server only)
3113 stderr
3115 Everything to stderr.
3117 stdio
3119 Status to stdout, and error to stderr.
3121 origbackuppath
3123 The path to a directory used to store generated .orig files. If
3125 the path is not a directory, one will be created. If set, files
3126 stored in this directory have the same name as the original file
3127 and do not have a .orig suffix.
3128 paginate
3130 Control the pagination of command output (default: True). See hg
3132 help pager for details.
3133 patch
3135 An optional external tool that hg import and some extensions
3137 will use for applying patches. By default Mercurial uses an in‐
3138 ternal patch utility. The external tool must work as the common
3139 Unix patch program. In particular, it must accept a -p argument
3140 to strip patch headers, a -d argument to specify the current di‐
3141 rectory, a file name to patch, and a patch file to take from
3142 stdin.
3143 It is possible to specify a patch tool together with extra argu‐
3145 ments. For example, setting this option to patch --merge will
3146 use the patch program with its 2-way merge option.
3147 portablefilenames
3149 Check for portable filenames. Can be warn, ignore or abort.
3151 (default: warn)
3152 warn
3154 Print a warning message on POSIX platforms, if a file
3156 with a non-portable filename is added (e.g. a file with a
3157 name that can't be created on Windows because it contains
3158 reserved parts like AUX, reserved characters like :, or
3159 would cause a case collision with an existing file).
3160 ignore
3162 Don't print a warning.
3164 abort
3166 The command is aborted.
3168 true
3170 Alias for warn.
3172 false
3174 Alias for ignore.
3176 On Windows, this configuration option is ignored and the command
3178 aborted.
3179 pre-merge-tool-output-template
3181 (DEPRECATED) Use command-template.pre-merge-tool-output instead.
3183 quiet
3185 Reduce the amount of output printed. (default: False)
3187 relative-paths
3189 Prefer relative paths in the UI.
3191 remotecmd
3193 Remote command to use for clone/push/pull operations. (default:
3195 hg)
3196 report_untrusted
3198 Warn if a .hg/hgrc file is ignored due to not being owned by a
3200 trusted user or group. (default: True)
3201 slash
3203 (Deprecated. Use slashpath template filter instead.)
3205 Display paths using a slash (/) as the path separator. This only
3207 makes a difference on systems where the default path separator
3208 is not the slash character (e.g. Windows uses the backslash
3209 character (\)). (default: False)
3210 statuscopies
3212 Display copies in the status command.
3214 ssh
3216 Command to use for SSH connections. (default: ssh)
3218 ssherrorhint
3220 A hint shown to the user in the case of SSH error (e.g. Please
3222 see http://company/internalwiki/ssh.html)
3223 strict
3225 Require exact command names, instead of allowing unambiguous ab‐
3227 breviations. (default: False)
3228 style
3230 Name of style to use for command output.
3232 supportcontact
3234 A URL where users should report a Mercurial traceback. Use this
3236 if you are a large organisation with its own Mercurial deploy‐
3237 ment process and crash reports should be addressed to your in‐
3238 ternal support.
3239 textwidth
3241 Maximum width of help text. A longer line generated by hg help
3243 or hg subcommand --help will be broken after white space to get
3244 this width or the terminal width, whichever comes first. A
3245 non-positive value will disable this and the terminal width will
3246 be used. (default: 78)
3247 timeout
3249 The timeout used when a lock is held (in seconds), a negative
3251 value means no timeout. (default: 600)
3252 timeout.warn
3254 Time (in seconds) before a warning is printed about held lock. A
3256 negative value means no warning. (default: 0)
3257 traceback
3259 Mercurial always prints a traceback when an unknown exception
3261 occurs. Setting this to True will make Mercurial print a trace‐
3262 back on all exceptions, even those recognized by Mercurial (such
3263 as IOError or MemoryError). (default: False)
3264 tweakdefaults
3266 By default Mercurial's behavior changes very little from release to
3268 release, but over time the recommended config settings shift. Enable
3269 this config to opt in to get automatic tweaks to Mercurial's behav‐
3270 ior over time. This config setting will have no effect if HGPLAIN is
3271 set or HGPLAINEXCEPT is set and does not include tweakdefaults. (de‐
3272 fault: False)
3273 It currently means:
3275 [ui]
3277 # The rollback command is dangerous. As a rule, don't use it.
3278 rollback = False
3279 # Make `hg status` report copy information
3280 statuscopies = yes
3281 # Prefer curses UIs when available. Revert to plain-text with `text`.
3282 interface = curses
3283 # Make compatible commands emit cwd-relative paths by default.
3284 relative-paths = yes
3285 [commands]
3287 # Grep working directory by default.
3288 grep.all-files = True
3289 # Refuse to perform an `hg update` that would cause a file content merge
3290 update.check = noconflict
3291 # Show conflicts information in `hg status`
3292 status.verbose = True
3293 # Make `hg resolve` with no action (like `-m`) fail instead of re-merging.
3294 resolve.explicit-re-merge = True
3295 [diff]
3297 git = 1
3298 showfunc = 1
3299 word-diff = 1
3300 username
3302 The committer of a changeset created when running "commit".
3304 Typically a person's name and email address, e.g. Fred Widget
3305 <fred@example.com>. Environment variables in the username are
3306 expanded.
3307 (default: $EMAIL or username@hostname. If the username in hgrc
3309 is empty, e.g. if the system admin set username = in the system
3310 hgrc, it has to be specified manually or in a different hgrc
3311 file)
3312 verbose
3314 Increase the amount of output printed. (default: False)
3316 command-templates
3318 Templates used for customizing the output of commands.
3319 graphnode
3321 The template used to print changeset nodes in an ASCII revision
3323 graph. (default: {graphnode})
3324 log
3326 Template string for commands that print changesets.
3328 mergemarker
3330 The template used to print the commit description next to each
3332 conflict marker during merge conflicts. See hg help templates
3333 for the template format.
3334 Defaults to showing the hash, tags, branches, bookmarks, author,
3336 and the first line of the commit description.
3337 If you use non-ASCII characters in names for tags, branches,
3339 bookmarks, authors, and/or commit descriptions, you must pay at‐
3340 tention to encodings of managed files. At template expansion,
3341 non-ASCII characters use the encoding specified by the --encod‐
3342 ing global option, HGENCODING or other environment variables
3343 that govern your locale. If the encoding of the merge markers is
3344 different from the encoding of the merged files, serious prob‐
3345 lems may occur.
3346 Can be overridden per-merge-tool, see the [merge-tools] section.
3348 oneline-summary
3350 A template used by hg rebase and other commands for showing a
3352 one-line summary of a commit. If the template configured here is
3353 longer than one line, then only the first line is used.
3354 The template can be overridden per command by defining a tem‐
3356 plate in oneline-summary.<command>, where <command> can be e.g.
3357 "rebase".
3358 pre-merge-tool-output
3360 A template that is printed before executing an external merge
3362 tool. This can be used to print out additional context that
3363 might be useful to have during the conflict resolution, such as
3364 the description of the various commits involved or book‐
3365 marks/tags.
3366 Additional information is available in the local`, ``base, and
3368 other dicts. For example: {local.label}, {base.name}, or
3369 {other.islink}.
3370 web
3372 Web interface configuration. The settings in this section apply to both
3373 the builtin webserver (started by hg serve) and the script you run
3374 through a webserver (hgweb.cgi and the derivatives for FastCGI and
3375 WSGI).
3376 The Mercurial webserver does no authentication (it does not prompt for
3378 usernames and passwords to validate who users are), but it does do au‐
3379 thorization (it grants or denies access for authenticated users based
3380 on settings in this section). You must either configure your webserver
3381 to do authentication for you, or disable the authorization checks.
3382 For a quick setup in a trusted environment, e.g., a private LAN, where
3384 you want it to accept pushes from anybody, you can use the following
3385 command line:
3386 $ hg --config web.allow-push=* --config web.push_ssl=False serve
3388 Note that this will allow anybody to push anything to the server and
3390 that this should not be used for public servers.
3391 The full set of options is:
3393 accesslog
3395 Where to output the access log. (default: stdout)
3397 address
3399 Interface address to bind to. (default: all)
3401 allow-archive
3403 List of archive format (bz2, gz, zip) allowed for downloading.
3405 (default: empty)
3406 allowbz2
3408 (DEPRECATED) Whether to allow .tar.bz2 downloading of repository
3410 revisions. (default: False)
3411 allowgz
3413 (DEPRECATED) Whether to allow .tar.gz downloading of repository
3415 revisions. (default: False)
3416 allow-pull
3418 Whether to allow pulling from the repository. (default: True)
3420 allow-push
3422 Whether to allow pushing to the repository. If empty or not set,
3424 pushing is not allowed. If the special value *, any remote user
3425 can push, including unauthenticated users. Otherwise, the remote
3426 user must have been authenticated, and the authenticated user
3427 name must be present in this list. The contents of the al‐
3428 low-push list are examined after the deny_push list.
3429 allow_read
3431 If the user has not already been denied repository access due to
3433 the contents of deny_read, this list determines whether to grant
3434 repository access to the user. If this list is not empty, and
3435 the user is unauthenticated or not present in the list, then ac‐
3436 cess is denied for the user. If the list is empty or not set,
3437 then access is permitted to all users by default. Setting al‐
3438 low_read to the special value * is equivalent to it not being
3439 set (i.e. access is permitted to all users). The contents of the
3440 allow_read list are examined after the deny_read list.
3441 allowzip
3443 (DEPRECATED) Whether to allow .zip downloading of repository re‐
3445 visions. This feature creates temporary files. (default: False)
3446 archivesubrepos
3448 Whether to recurse into subrepositories when archiving. (de‐
3450 fault: False)
3451 baseurl
3453 Base URL to use when publishing URLs in other locations, so
3455 third-party tools like email notification hooks can construct
3456 URLs. Example: http://hgserver/repos/.
3457 cacerts
3459 Path to file containing a list of PEM encoded certificate au‐
3461 thority certificates. Environment variables and ~user constructs
3462 are expanded in the filename. If specified on the client, then
3463 it will verify the identity of remote HTTPS servers with these
3464 certificates.
3465 To disable SSL verification temporarily, specify --insecure from
3467 command line.
3468 You can use OpenSSL's CA certificate file if your platform has
3470 one. On most Linux systems this will be /etc/ssl/certs/ca-cer‐
3471 tificates.crt. Otherwise you will have to generate this file
3472 manually. The form must be as follows:
3473 -----BEGIN CERTIFICATE-----
3475 ... (certificate in base64 PEM encoding) ...
3476 -----END CERTIFICATE-----
3477 -----BEGIN CERTIFICATE-----
3478 ... (certificate in base64 PEM encoding) ...
3479 -----END CERTIFICATE-----
3480 cache
3482 Whether to support caching in hgweb. (default: True)
3484 certificate
3486 Certificate to use when running hg serve.
3488 collapse
3490 With descend enabled, repositories in subdirectories are shown
3492 at a single level alongside repositories in the current path.
3493 With collapse also enabled, repositories residing at a deeper
3494 level than the current path are grouped behind navigable direc‐
3495 tory entries that lead to the locations of these repositories.
3496 In effect, this setting collapses each collection of reposito‐
3497 ries found within a subdirectory into a single entry for that
3498 subdirectory. (default: False)
3499 comparisoncontext
3501 Number of lines of context to show in side-by-side file compari‐
3503 son. If negative or the value full, whole files are shown. (de‐
3504 fault: 5)
3505 This setting can be overridden by a context request parameter to
3507 the comparison command, taking the same values.
3508 contact
3510 Name or email address of the person in charge of the repository.
3512 (default: ui.username or $EMAIL or "unknown" if unset or empty)
3513 csp
3515 Send a Content-Security-Policy HTTP header with this value.
3517 The value may contain a special string %nonce%, which will be
3519 replaced by a randomly-generated one-time use value. If the
3520 value contains %nonce%, web.cache will be disabled, as caching
3521 undermines the one-time property of the nonce. This nonce will
3522 also be inserted into <script> elements containing inline Java‐
3523 Script.
3524 Note: lots of HTML content sent by the server is derived from
3526 repository data. Please consider the potential for malicious
3527 repository data to "inject" itself into generated HTML content
3528 as part of your security threat model.
3529 deny_push
3531 Whether to deny pushing to the repository. If empty or not set,
3533 push is not denied. If the special value *, all remote users are
3534 denied push. Otherwise, unauthenticated users are all denied,
3535 and any authenticated user name present in this list is also de‐
3536 nied. The contents of the deny_push list are examined before the
3537 allow-push list.
3538 deny_read
3540 Whether to deny reading/viewing of the repository. If this list
3542 is not empty, unauthenticated users are all denied, and any au‐
3543 thenticated user name present in this list is also denied access
3544 to the repository. If set to the special value *, all remote
3545 users are denied access (rarely needed ;). If deny_read is empty
3546 or not set, the determination of repository access depends on
3547 the presence and content of the allow_read list (see descrip‐
3548 tion). If both deny_read and allow_read are empty or not set,
3549 then access is permitted to all users by default. If the reposi‐
3550 tory is being served via hgwebdir, denied users will not be able
3551 to see it in the list of repositories. The contents of the
3552 deny_read list have priority over (are examined before) the con‐
3553 tents of the allow_read list.
3554 descend
3556 hgwebdir indexes will not descend into subdirectories. Only
3558 repositories directly in the current path will be shown (other
3559 repositories are still available from the index corresponding to
3560 their containing path).
3561 description
3563 Textual description of the repository's purpose or contents.
3565 (default: "unknown")
3566 encoding
3568 Character encoding name. (default: the current locale charset)
3570 Example: "UTF-8".
3571 errorlog
3573 Where to output the error log. (default: stderr)
3575 guessmime
3577 Control MIME types for raw download of file content. Set to
3579 True to let hgweb guess the content type from the file exten‐
3580 sion. This will serve HTML files as text/html and might allow
3581 cross-site scripting attacks when serving untrusted reposito‐
3582 ries. (default: False)
3583 hidden
3585 Whether to hide the repository in the hgwebdir index. (default:
3587 False)
3588 ipv6
3590 Whether to use IPv6. (default: False)
3592 labels
3594 List of string labels associated with the repository.
3596 Labels are exposed as a template keyword and can be used to cus‐
3598 tomize output. e.g. the index template can group or filter
3599 repositories by labels and the summary template can display ad‐
3600 ditional content if a specific label is present.
3601 logoimg
3603 File name of the logo image that some templates display on each
3605 page. The file name is relative to staticurl. That is, the full
3606 path to the logo image is "staticurl/logoimg". If unset, hgl‐
3607 ogo.png will be used.
3608 logourl
3610 Base URL to use for logos. If unset, https://mercurial-scm.org/
3612 will be used.
3613 maxchanges
3615 Maximum number of changes to list on the changelog. (default:
3617 10)
3618 maxfiles
3620 Maximum number of files to list per changeset. (default: 10)
3622 maxshortchanges
3624 Maximum number of changes to list on the shortlog, graph or
3626 filelog pages. (default: 60)
3627 name
3629 Repository name to use in the web interface. (default: current
3631 working directory)
3632 port
3634 Port to listen on. (default: 8000)
3636 prefix
3638 Prefix path to serve from. (default: '' (server root))
3640 push_ssl
3642 Whether to require that inbound pushes be transported over SSL
3644 to prevent password sniffing. (default: True)
3645 refreshinterval
3647 How frequently directory listings re-scan the filesystem for new
3649 repositories, in seconds. This is relevant when wildcards are
3650 used to define paths. Depending on how much filesystem traversal
3651 is required, refreshing may negatively impact performance.
3652 Values less than or equal to 0 always refresh. (default: 20)
3654 server-header
3656 Value for HTTP Server response header.
3658 static
3660 Directory where static files are served from.
3662 staticurl
3664 Base URL to use for static files. If unset, static files (e.g.
3666 the hgicon.png favicon) will be served by the CGI script itself.
3667 Use this setting to serve them directly with the HTTP server.
3668 Example: http://hgserver/static/.
3669 stripes
3671 How many lines a "zebra stripe" should span in multi-line out‐
3673 put. Set to 0 to disable. (default: 1)
3674 style
3676 Which template map style to use. The available options are the
3678 names of subdirectories in the HTML templates path. (default:
3679 paper) Example: monoblue.
3680 templates
3682 Where to find the HTML templates. The default path to the HTML
3684 templates can be obtained from hg debuginstall.
3685 websub
3687 Web substitution filter definition. You can use this section to define
3688 a set of regular expression substitution patterns which let you auto‐
3689 matically modify the hgweb server output.
3690 The default hgweb templates only apply these substitution patterns on
3692 the revision description fields. You can apply them anywhere you want
3693 when you create your own templates by adding calls to the "websub" fil‐
3694 ter (usually after calling the "escape" filter).
3695 This can be used, for example, to convert issue references to links to
3697 your issue tracker, or to convert "markdown-like" syntax into HTML (see
3698 the examples below).
3699 Each entry in this section names a substitution filter. The value of
3701 each entry defines the substitution expression itself. The websub ex‐
3702 pressions follow the old interhg extension syntax, which in turn imi‐
3703 tates the Unix sed replacement syntax:
3704 patternname = s/SEARCH_REGEX/REPLACE_EXPRESSION/[i]
3706 You can use any separator other than "/". The final "i" is optional and
3708 indicates that the search must be case insensitive.
3709 Examples:
3711 [websub]
3713 issues = s|issue(\d+)|<a href="http://bts.example.org/issue\1">issue\1</a>|i
3714 italic = s/\b_(\S+)_\b/<i>\1<\/i>/
3715 bold = s/\*\b(\S+)\b\*/<b>\1<\/b>/
3716 worker
3718 Parallel master/worker configuration. We currently perform working di‐
3719 rectory updates in parallel on Unix-like systems, which greatly helps
3720 performance.
3721 enabled
3723 Whether to enable workers code to be used. (default: true)
3725 numcpus
3727 Number of CPUs to use for parallel operations. A zero or nega‐
3729 tive value is treated as use the default. (default: 4 or the
3730 number of CPUs on the system, whichever is larger)
3731 backgroundclose
3733 Whether to enable closing file handles on background threads
3735 during certain operations. Some platforms aren't very efficient
3736 at closing file handles that have been written or appended to.
3737 By performing file closing on background threads, file write
3738 rate can increase substantially. (default: true on Windows,
3739 false elsewhere)
3740 backgroundcloseminfilecount
3742 Minimum number of files required to trigger background file
3744 closing. Operations not writing this many files won't start
3745 background close threads. (default: 2048)
3746 backgroundclosemaxqueue
3748 The maximum number of opened file handles waiting to be closed
3750 in the background. This option only has an effect if background‐
3751 close is enabled. (default: 384)
3752 backgroundclosethreadcount
3754 Number of threads to process background file closes. Only rele‐
3756 vant if backgroundclose is enabled. (default: 4)
3757
3759 Bryan O'Sullivan <bos@serpentine.com>.
3760 Mercurial was written by Olivia Mackall <olivia@selenic.com>.
3762
3764 hg(1), hgignore(5)
3765
3767 This manual page is copyright 2005 Bryan O'Sullivan. Mercurial is
3768 copyright 2005-2023 Olivia Mackall. Free use of this software is
3769 granted under the terms of the GNU General Public License version 2 or
3770 any later version.
3771
3773 Bryan O'Sullivan <bos@serpentine.com>
3774 Organization: Mercurial
3776 HGRC(5)