1HGRC(5) Mercurial Manual HGRC(5)
2
6 hgrc - configuration files for Mercurial
7
9 The Mercurial system uses a set of configuration files to control
10 aspects of its behavior.
11
13 If you're having problems with your configuration, hg config --debug
14 can help you understand what is introducing a setting into your envi‐
15 ronment.
16 See hg help config.syntax and hg help config.files for information
18 about how and where to override things.
19
21 The configuration files use a simple ini-file format. A configuration
22 file consists of sections, led by a [section] header and followed by
23 name = value entries:
24 [ui]
26 username = Firstname Lastname <firstname.lastname@example.net>
27 verbose = True
28 The above entries will be referred to as ui.username and ui.verbose,
30 respectively. See hg help config.syntax.
31
33 Mercurial reads configuration data from several files, if they exist.
34 These files do not exist by default and you will have to create the
35 appropriate configuration files yourself:
36 Local configuration is put into the per-repository <repo>/.hg/hgrc
38 file.
39 Global configuration like the username setting is typically put into:
41 · %USERPROFILE%\mercurial.ini (on Windows)
43 · $HOME/.hgrc (on Unix, Plan9)
45 The names of these files depend on the system on which Mercurial is
47 installed. *.rc files from a single directory are read in alphabetical
48 order, later ones overriding earlier ones. Where multiple paths are
49 given below, settings from earlier paths override later ones.
50 On Unix, the following files are consulted:
52 · <repo>/.hg/hgrc (per-repository)
54 · $HOME/.hgrc (per-user)
56 · ${XDG_CONFIG_HOME:-$HOME/.config}/hg/hgrc (per-user)
58 · <install-root>/etc/mercurial/hgrc (per-installation)
60 · <install-root>/etc/mercurial/hgrc.d/*.rc (per-installation)
62 · /etc/mercurial/hgrc (per-system)
64 · /etc/mercurial/hgrc.d/*.rc (per-system)
66 · <internal>/*.rc (defaults)
68 On Windows, the following files are consulted:
70 · <repo>/.hg/hgrc (per-repository)
72 · %USERPROFILE%\.hgrc (per-user)
74 · %USERPROFILE%\Mercurial.ini (per-user)
76 · %HOME%\.hgrc (per-user)
78 · %HOME%\Mercurial.ini (per-user)
80 · HKEY_LOCAL_MACHINE\SOFTWARE\Mercurial (per-system)
82 · <install-dir>\hgrc.d\*.rc (per-installation)
84 · <install-dir>\Mercurial.ini (per-installation)
86 · %PROGRAMDATA%\Mercurial\hgrc (per-system)
88 · %PROGRAMDATA%\Mercurial\Mercurial.ini (per-system)
90 · %PROGRAMDATA%\Mercurial\hgrc.d\*.rc (per-system)
92 · <internal>/*.rc (defaults)
94 Note The registry key HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Mercu‐
96 rial is used when running 32-bit Python on 64-bit Windows.
97 On Plan9, the following files are consulted:
99 · <repo>/.hg/hgrc (per-repository)
101 · $home/lib/hgrc (per-user)
103 · <install-root>/lib/mercurial/hgrc (per-installation)
105 · <install-root>/lib/mercurial/hgrc.d/*.rc (per-installation)
107 · /lib/mercurial/hgrc (per-system)
109 · /lib/mercurial/hgrc.d/*.rc (per-system)
111 · <internal>/*.rc (defaults)
113 Per-repository configuration options only apply in a particular reposi‐
115 tory. This file is not version-controlled, and will not get transferred
116 during a "clone" operation. Options in this file override options in
117 all other configuration files.
118 On Plan 9 and Unix, most of this file will be ignored if it doesn't
120 belong to a trusted user or to a trusted group. See hg help con‐
121 fig.trusted for more details.
122 Per-user configuration file(s) are for the user running Mercurial.
124 Options in these files apply to all Mercurial commands executed by this
125 user in any directory. Options in these files override per-system and
126 per-installation options.
127 Per-installation configuration files are searched for in the directory
129 where Mercurial is installed. <install-root> is the parent directory of
130 the hg executable (or symlink) being run.
131 For example, if installed in /shared/tools/bin/hg, Mercurial will look
133 in /shared/tools/etc/mercurial/hgrc. Options in these files apply to
134 all Mercurial commands executed by any user in any directory.
135 Per-installation configuration files are for the system on which Mercu‐
137 rial is running. Options in these files apply to all Mercurial commands
138 executed by any user in any directory. Registry keys contain PATH-like
139 strings, every part of which must reference a Mercurial.ini file or be
140 a directory where *.rc files will be read. Mercurial checks each of
141 these locations in the specified order until one or more configuration
142 files are detected.
143 Per-system configuration files are for the system on which Mercurial is
145 running. Options in these files apply to all Mercurial commands exe‐
146 cuted by any user in any directory. Options in these files override
147 per-installation options.
148 Mercurial comes with some default configuration. The default configura‐
150 tion files are installed with Mercurial and will be overwritten on
151 upgrades. Default configuration files should never be edited by users
152 or administrators but can be overridden in other configuration files.
153 So far the directory only contains merge tool configuration but pack‐
154 agers can also put other default configuration there.
155
157 A configuration file consists of sections, led by a [section] header
158 and followed by name = value entries (sometimes called configuration
159 keys):
160 [spam]
162 eggs=ham
163 green=
164 eggs
165 Each line contains one entry. If the lines that follow are indented,
167 they are treated as continuations of that entry. Leading whitespace is
168 removed from values. Empty lines are skipped. Lines beginning with # or
169 ; are ignored and may be used to provide comments.
170 Configuration keys can be set multiple times, in which case Mercurial
172 will use the value that was configured last. As an example:
173 [spam]
175 eggs=large
176 ham=serrano
177 eggs=small
178 This would set the configuration key named eggs to small.
180 It is also possible to define a section multiple times. A section can
182 be redefined on the same and/or on different configuration files. For
183 example:
184 [foo]
186 eggs=large
187 ham=serrano
188 eggs=small
189 [bar]
191 eggs=ham
192 green=
193 eggs
194 [foo]
196 ham=prosciutto
197 eggs=medium
198 bread=toasted
199 This would set the eggs, ham, and bread configuration keys of the foo
201 section to medium, prosciutto, and toasted, respectively. As you can
202 see there only thing that matters is the last value that was set for
203 each of the configuration keys.
204 If a configuration key is set multiple times in different configuration
206 files the final value will depend on the order in which the different
207 configuration files are read, with settings from earlier paths overrid‐
208 ing later ones as described on the Files section above.
209 A line of the form %include file will include file into the current
211 configuration file. The inclusion is recursive, which means that
212 included files can include other files. Filenames are relative to the
213 configuration file in which the %include directive is found. Environ‐
214 ment variables and ~user constructs are expanded in file. This lets you
215 do something like:
216 %include ~/.hgrc.d/$HOST.rc
218 to include a different configuration file on each computer you use.
220 A line with %unset name will remove name from the current section, if
222 it has been set previously.
223 The values are either free-form text strings, lists of text strings, or
225 Boolean values. Boolean values can be set to true using any of "1",
226 "yes", "true", or "on" and to false using "0", "no", "false", or "off"
227 (all case insensitive).
228 List values are separated by whitespace or comma, except when values
230 are placed in double quotation marks:
231 allow_read = "John Doe, PhD", brian, betty
233 Quotation marks can be escaped by prefixing them with a backslash. Only
235 quotation marks at the beginning of a word is counted as a quotation
236 (e.g., foo"bar baz is the list of foo"bar and baz).
237
239 This section describes the different sections that may appear in a Mer‐
240 curial configuration file, the purpose of each section, its possible
241 keys, and their possible values.
242 alias
244 Defines command aliases.
245 Aliases allow you to define your own commands in terms of other com‐
247 mands (or aliases), optionally including arguments. Positional argu‐
248 ments in the form of $1, $2, etc. in the alias definition are expanded
249 by Mercurial before execution. Positional arguments not already used by
250 $N in the definition are put at the end of the command to be executed.
251 Alias definitions consist of lines of the form:
253 <alias> = <command> [<argument>]...
255 For example, this definition:
257 latest = log --limit 5
259 creates a new command latest that shows only the five most recent
261 changesets. You can define subsequent aliases using earlier ones:
262 stable5 = latest -b stable
264 Note It is possible to create aliases with the same names as existing
266 commands, which will then override the original definitions.
267 This is almost always a bad idea!
268 An alias can start with an exclamation point (!) to make it a shell
270 alias. A shell alias is executed with the shell and will let you run
271 arbitrary commands. As an example,
272 echo = !echo $@
274 will let you do hg echo foo to have foo printed in your terminal. A
276 better example might be:
277 purge = !$HG status --no-status --unknown -0 re: | xargs -0 rm -f
279 which will make hg purge delete all unknown files in the repository in
281 the same manner as the purge extension.
282 Positional arguments like $1, $2, etc. in the alias definition expand
284 to the command arguments. Unmatched arguments are removed. $0 expands
285 to the alias name and $@ expands to all arguments separated by a space.
286 "$@" (with quotes) expands to all arguments quoted individually and
287 separated by a space. These expansions happen before the command is
288 passed to the shell.
289 Shell aliases are executed in an environment where $HG expands to the
291 path of the Mercurial that was used to execute the alias. This is use‐
292 ful when you want to call further Mercurial commands in a shell alias,
293 as was done above for the purge alias. In addition, $HG_ARGS expands to
294 the arguments given to Mercurial. In the hg echo foo call above,
295 $HG_ARGS would expand to echo foo.
296 Note Some global configuration options such as -R are processed
298 before shell aliases and will thus not be passed to aliases.
299 annotate
301 Settings used when displaying file annotations. All values are Booleans
302 and default to False. See hg help config.diff for related options for
303 the diff command.
304 ignorews
306 Ignore white space when comparing lines.
308 ignorewseol
310 Ignore white space at the end of a line when comparing lines.
312 ignorewsamount
314 Ignore changes in the amount of white space.
316 ignoreblanklines
318 Ignore changes whose lines are all blank.
320 auth
322 Authentication credentials and other authentication-like configuration
323 for HTTP connections. This section allows you to store usernames and
324 passwords for use when logging into HTTP servers. See hg help con‐
325 fig.web if you want to configure who can login to your HTTP server.
326 The following options apply to all hosts.
328 cookiefile
330 Path to a file containing HTTP cookie lines. Cookies matching a
332 host will be sent automatically.
333 The file format uses the Mozilla cookies.txt format, which
335 defines cookies on their own lines. Each line contains 7 fields
336 delimited by the tab character (domain, is_domain_cookie, path,
337 is_secure, expires, name, value). For more info, do an Internet
338 search for "Netscape cookies.txt format."
339 Note: the cookies parser does not handle port numbers on
341 domains. You will need to remove ports from the domain for the
342 cookie to be recognized. This could result in a cookie being
343 disclosed to an unwanted server.
344 The cookies file is read-only.
346 Other options in this section are grouped by name and have the follow‐
348 ing format:
349 <name>.<argument> = <value>
351 where <name> is used to group arguments into authentication entries.
353 Example:
354 foo.prefix = hg.intevation.de/mercurial
356 foo.username = foo
357 foo.password = bar
358 foo.schemes = http https
359 bar.prefix = secure.example.org
361 bar.key = path/to/file.key
362 bar.cert = path/to/file.cert
363 bar.schemes = https
364 Supported arguments:
366 prefix
368 Either * or a URI prefix with or without the scheme part. The
370 authentication entry with the longest matching prefix is used
371 (where * matches everything and counts as a match of length 1).
372 If the prefix doesn't include a scheme, the match is performed
373 against the URI with its scheme stripped as well, and the
374 schemes argument, q.v., is then subsequently consulted.
375 username
377 Optional. Username to authenticate with. If not given, and the
379 remote site requires basic or digest authentication, the user
380 will be prompted for it. Environment variables are expanded in
381 the username letting you do foo.username = $USER. If the URI
382 includes a username, only [auth] entries with a matching user‐
383 name or without a username will be considered.
384 password
386 Optional. Password to authenticate with. If not given, and the
388 remote site requires basic or digest authentication, the user
389 will be prompted for it.
390 key
392 Optional. PEM encoded client certificate key file. Environment
394 variables are expanded in the filename.
395 cert
397 Optional. PEM encoded client certificate chain file. Environment
399 variables are expanded in the filename.
400 schemes
402 Optional. Space separated list of URI schemes to use this
404 authentication entry with. Only used if the prefix doesn't
405 include a scheme. Supported schemes are http and https. They
406 will match static-http and static-https respectively, as well.
407 (default: https)
408 If no suitable authentication entry is found, the user is prompted for
410 credentials as usual if required by the remote.
411 color
413 Configure the Mercurial color mode. For details about how to define
414 your custom effect and style see hg help color.
415 mode
417 String: control the method used to output color. One of auto,
419 ansi, win32, terminfo or debug. In auto mode, Mercurial will use
420 ANSI mode by default (or win32 mode prior to Windows 10) if it
421 detects a terminal. Any invalid value will disable color.
422 pagermode
424 String: optional override of color.mode used with pager.
426 On some systems, terminfo mode may cause problems when using
428 color with less -R as a pager program. less with the -R option
429 will only display ECMA-48 color codes, and terminfo mode may
430 sometimes emit codes that less doesn't understand. You can work
431 around this by either using ansi mode (or auto mode), or by
432 using less -r (which will pass through all terminal control
433 codes, not just color control codes).
434 On some systems (such as MSYS in Windows), the terminal may sup‐
436 port a different color mode than the pager program.
437 commands
439 commit.post-status
440 Show status of files in the working directory after successful
442 commit. (default: False)
443 merge.require-rev
445 Require that the revision to merge the current commit with be
447 specified on the command line. If this is enabled and a revision
448 is not specified, the command aborts. (default: False)
449 push.require-revs
451 Require revisions to push be specified using one or more mecha‐
453 nisms such as specifying them positionally on the command line,
454 using -r, -b, and/or -B on the command line, or using
455 paths.<path>:pushrev in the configuration. If this is enabled
456 and revisions are not specified, the command aborts. (default:
457 False)
458 resolve.confirm
460 Confirm before performing action if no filename is passed.
462 (default: False)
463 resolve.explicit-re-merge
465 Require uses of hg resolve to specify which action it should
467 perform, instead of re-merging files by default. (default:
468 False)
469 resolve.mark-check
471 Determines what level of checking hg resolve --mark will perform
473 before marking files as resolved. Valid values are none`,
474 ``warn, and abort. warn will output a warning listing the
475 file(s) that still have conflict markers in them, but will still
476 mark everything resolved. abort will output the same warning
477 but will not mark things as resolved. If --all is passed and
478 this is set to abort, only a warning will be shown (an error
479 will not be raised). (default: none)
480 status.relative
482 Make paths in hg status output relative to the current direc‐
484 tory. (default: False)
485 status.terse
487 Default value for the --terse flag, which condenses status out‐
489 put. (default: empty)
490 update.check
492 Determines what level of checking hg update will perform before
494 moving to a destination revision. Valid values are abort, none,
495 linear, and noconflict. abort always fails if the working direc‐
496 tory has uncommitted changes. none performs no checking, and may
497 result in a merge with uncommitted changes. linear allows any
498 update as long as it follows a straight line in the revision
499 history, and may trigger a merge with uncommitted changes.
500 noconflict will allow any update which would not trigger a merge
501 with uncommitted changes, if any are present. (default: linear)
502 update.requiredest
504 Require that the user pass a destination when running hg update.
506 For example, hg update .:: will be allowed, but a plain hg
507 update will be disallowed. (default: False)
508 committemplate
510 changeset
511 String: configuration in this section is used as the template to
513 customize the text shown in the editor when committing.
514 In addition to pre-defined template keywords, commit log specific one
516 below can be used for customization:
517 extramsg
519 String: Extra message (typically 'Leave message empty to abort
521 commit.'). This may be changed by some commands or extensions.
522 For example, the template configuration below shows as same text as one
524 shown by default:
525 [committemplate]
527 changeset = {desc}\n\n
528 HG: Enter commit message. Lines beginning with 'HG:' are removed.
529 HG: {extramsg}
530 HG: --
531 HG: user: {author}\n{ifeq(p2rev, "-1", "",
532 "HG: branch merge\n")
533 }HG: branch '{branch}'\n{if(activebookmark,
534 "HG: bookmark '{activebookmark}'\n") }{subrepos %
535 "HG: subrepo {subrepo}\n" }{file_adds %
536 "HG: added {file}\n" }{file_mods %
537 "HG: changed {file}\n" }{file_dels %
538 "HG: removed {file}\n" }{if(files, "",
539 "HG: no files changed\n")}
540 diff()
542 String: show the diff (see hg help templates for detail)
544 Sometimes it is helpful to show the diff of the changeset in the editor
546 without having to prefix 'HG: ' to each line so that highlighting works
547 correctly. For this, Mercurial provides a special string which will
548 ignore everything below it:
549 HG: ------------------------ >8 ------------------------
551 For example, the template configuration below will show the diff below
553 the extra message:
554 [committemplate]
556 changeset = {desc}\n\n
557 HG: Enter commit message. Lines beginning with 'HG:' are removed.
558 HG: {extramsg}
559 HG: ------------------------ >8 ------------------------
560 HG: Do not touch the line above.
561 HG: Everything below will be removed.
562 {diff()}
563 Note For some problematic encodings (see hg help win32mbcs for
565 detail), this customization should be configured carefully, to
566 avoid showing broken characters.
567 For example, if a multibyte character ending with backslash
569 (0x5c) is followed by the ASCII character 'n' in the customized
570 template, the sequence of backslash and 'n' is treated as
571 line-feed unexpectedly (and the multibyte character is broken,
572 too).
573 Customized template is used for commands below (--edit may be
575 required):
576 · hg backout
578 · hg commit
580 · hg fetch (for merge commit only)
582 · hg graft
584 · hg histedit
586 · hg import
588 · hg qfold, hg qnew and hg qrefresh
590 · hg rebase
592 · hg shelve
594 · hg sign
596 · hg tag
598 · hg transplant
600 Configuring items below instead of changeset allows showing customized
602 message only for specific actions, or showing different messages for
603 each action.
604 · changeset.backout for hg backout
606 · changeset.commit.amend.merge for hg commit --amend on merges
608 · changeset.commit.amend.normal for hg commit --amend on other
610 · changeset.commit.normal.merge for hg commit on merges
612 · changeset.commit.normal.normal for hg commit on other
614 · changeset.fetch for hg fetch (impling merge commit)
616 · changeset.gpg.sign for hg sign
618 · changeset.graft for hg graft
620 · changeset.histedit.edit for edit of hg histedit
622 · changeset.histedit.fold for fold of hg histedit
624 · changeset.histedit.mess for mess of hg histedit
626 · changeset.histedit.pick for pick of hg histedit
628 · changeset.import.bypass for hg import --bypass
630 · changeset.import.normal.merge for hg import on merges
632 · changeset.import.normal.normal for hg import on other
634 · changeset.mq.qnew for hg qnew
636 · changeset.mq.qfold for hg qfold
638 · changeset.mq.qrefresh for hg qrefresh
640 · changeset.rebase.collapse for hg rebase --collapse
642 · changeset.rebase.merge for hg rebase on merges
644 · changeset.rebase.normal for hg rebase on other
646 · changeset.shelve.shelve for hg shelve
648 · changeset.tag.add for hg tag without --remove
650 · changeset.tag.remove for hg tag --remove
652 · changeset.transplant.merge for hg transplant on merges
654 · changeset.transplant.normal for hg transplant on other
656 These dot-separated lists of names are treated as hierarchical ones.
658 For example, changeset.tag.remove customizes the commit message only
659 for hg tag --remove, but changeset.tag customizes the commit message
660 for hg tag regardless of --remove option.
661 When the external editor is invoked for a commit, the corresponding
663 dot-separated list of names without the changeset. prefix (e.g. com‐
664 mit.normal.normal) is in the HGEDITFORM environment variable.
665 In this section, items other than changeset can be referred from oth‐
667 ers. For example, the configuration to list committed files up below
668 can be referred as {listupfiles}:
669 [committemplate]
671 listupfiles = {file_adds %
672 "HG: added {file}\n" }{file_mods %
673 "HG: changed {file}\n" }{file_dels %
674 "HG: removed {file}\n" }{if(files, "",
675 "HG: no files changed\n")}
676 decode/encode
678 Filters for transforming files on checkout/checkin. This would typi‐
679 cally be used for newline processing or other localization/canonical‐
680 ization of files.
681 Filters consist of a filter pattern followed by a filter command. Fil‐
683 ter patterns are globs by default, rooted at the repository root. For
684 example, to match any file ending in .txt in the root directory only,
685 use the pattern *.txt. To match any file ending in .c anywhere in the
686 repository, use the pattern **.c. For each file only the first match‐
687 ing filter applies.
688 The filter command can start with a specifier, either pipe: or temp‐
690 file:. If no specifier is given, pipe: is used by default.
691 A pipe: command must accept data on stdin and return the transformed
693 data on stdout.
694 Pipe example:
696 [encode]
698 # uncompress gzip files on checkin to improve delta compression
699 # note: not necessarily a good idea, just an example
700 *.gz = pipe: gunzip
701 [decode]
703 # recompress gzip files when writing them to the working dir (we
704 # can safely omit "pipe:", because it's the default)
705 *.gz = gzip
706 A tempfile: command is a template. The string INFILE is replaced with
708 the name of a temporary file that contains the data to be filtered by
709 the command. The string OUTFILE is replaced with the name of an empty
710 temporary file, where the filtered data must be written by the command.
711 Note The tempfile mechanism is recommended for Windows systems, where
713 the standard shell I/O redirection operators often have strange
714 effects and may corrupt the contents of your files.
715 This filter mechanism is used internally by the eol extension to trans‐
717 late line ending characters between Windows (CRLF) and Unix (LF) for‐
718 mat. We suggest you use the eol extension for convenience.
719 defaults
721 (defaults are deprecated. Don't use them. Use aliases instead.)
722 Use the [defaults] section to define command defaults, i.e. the default
724 options/arguments to pass to the specified commands.
725 The following example makes hg log run in verbose mode, and hg status
727 show only the modified files, by default:
728 [defaults]
730 log = -v
731 status = -m
732 The actual commands, instead of their aliases, must be used when defin‐
734 ing command defaults. The command defaults will also be applied to the
735 aliases of the commands defined.
736 diff
738 Settings used when displaying diffs. Everything except for unified is a
739 Boolean and defaults to False. See hg help config.annotate for related
740 options for the annotate command.
741 git
743 Use git extended diff format.
745 nobinary
747 Omit git binary patches.
749 nodates
751 Don't include dates in diff headers.
753 noprefix
755 Omit 'a/' and 'b/' prefixes from filenames. Ignored in plain
757 mode.
758 showfunc
760 Show which function each change is in.
762 ignorews
764 Ignore white space when comparing lines.
766 ignorewsamount
768 Ignore changes in the amount of white space.
770 ignoreblanklines
772 Ignore changes whose lines are all blank.
774 unified
776 Number of lines of context to show.
778 word-diff
780 Highlight changed words.
782 email
784 Settings for extensions that send email messages.
785 from
787 Optional. Email address to use in "From" header and SMTP enve‐
789 lope of outgoing messages.
790 to
792 Optional. Comma-separated list of recipients' email addresses.
794 cc
796 Optional. Comma-separated list of carbon copy recipients' email
798 addresses.
799 bcc
801 Optional. Comma-separated list of blind carbon copy recipients'
803 email addresses.
804 method
806 Optional. Method to use to send email messages. If value is smtp
808 (default), use SMTP (see the [smtp] section for configuration).
809 Otherwise, use as name of program to run that acts like sendmail
810 (takes -f option for sender, list of recipients on command line,
811 message on stdin). Normally, setting this to sendmail or
812 /usr/sbin/sendmail is enough to use sendmail to send messages.
813 charsets
815 Optional. Comma-separated list of character sets considered con‐
817 venient for recipients. Addresses, headers, and parts not con‐
818 taining patches of outgoing messages will be encoded in the
819 first character set to which conversion from local encoding
820 ($HGENCODING, ui.fallbackencoding) succeeds. If correct conver‐
821 sion fails, the text in question is sent as is. (default: '')
822 Order of outgoing email character sets:
824 1. us-ascii: always first, regardless of settings
826 2. email.charsets: in order given by user
828 3. ui.fallbackencoding: if not in email.charsets
830 4. $HGENCODING: if not in email.charsets
832 5. utf-8: always last, regardless of settings
834 Email example:
836 [email]
838 from = Joseph User <joe.user@example.com>
839 method = /usr/sbin/sendmail
840 # charsets for western Europeans
841 # us-ascii, utf-8 omitted, as they are tried first and last
842 charsets = iso-8859-1, iso-8859-15, windows-1252
843 extensions
845 Mercurial has an extension mechanism for adding new features. To enable
846 an extension, create an entry for it in this section.
847 If you know that the extension is already in Python's search path, you
849 can give the name of the module, followed by =, with nothing after the
850 =.
851 Otherwise, give a name that you choose, followed by =, followed by the
853 path to the .py file (including the file name extension) that defines
854 the extension.
855 To explicitly disable an extension that is enabled in an hgrc of
857 broader scope, prepend its path with !, as in foo = !/ext/path or foo =
858 ! when path is not supplied.
859 Example for ~/.hgrc:
861 [extensions]
863 # (the churn extension will get loaded from Mercurial's path)
864 churn =
865 # (this extension will get loaded from the file specified)
866 myfeature = ~/.hgext/myfeature.py
867 format
869 Configuration that controls the repository format. Newer format options
870 are more powerful, but incompatible with some older versions of Mercu‐
871 rial. Format options are considered at repository initialization only.
872 You need to make a new clone for config changes to be taken into
873 account.
874 For more details about repository format and version compatibility, see
876 https://www.mercurial-scm.org/wiki/MissingRequirement
877 usegeneraldelta
879 Enable or disable the "generaldelta" repository format which
881 improves repository compression by allowing "revlog" to store
882 deltas against arbitrary revisions instead of the previously
883 stored one. This provides significant improvement for reposito‐
884 ries with branches.
885 Repositories with this on-disk format require Mercurial version
887 1.9.
888 Enabled by default.
890 dotencode
892 Enable or disable the "dotencode" repository format which
894 enhances the "fncache" repository format (which has to be
895 enabled to use dotencode) to avoid issues with filenames start‐
896 ing with "._" on Mac OS X and spaces on Windows.
897 Repositories with this on-disk format require Mercurial version
899 1.7.
900 Enabled by default.
902 usefncache
904 Enable or disable the "fncache" repository format which enhances
906 the "store" repository format (which has to be enabled to use
907 fncache) to allow longer filenames and avoids using Windows
908 reserved names, e.g. "nul".
909 Repositories with this on-disk format require Mercurial version
911 1.1.
912 Enabled by default.
914 usestore
916 Enable or disable the "store" repository format which improves
918 compatibility with systems that fold case or otherwise mangle
919 filenames. Disabling this option will allow you to store longer
920 filenames in some situations at the expense of compatibility.
921 Repositories with this on-disk format require Mercurial version
923 0.9.4.
924 Enabled by default.
926 sparse-revlog
928 Enable or disable the sparse-revlog delta strategy. This format
930 improves delta re-use inside revlog. For very branchy reposito‐
931 ries, it results in a smaller store. For repositories with many
932 revisions, it also helps performance (by using shortened delta
933 chains.)
934 Repositories with this on-disk format require Mercurial version
936 4.7
937 Enabled by default.
939 revlog-compression
941 Compression algorithm used by revlog. Supported values are zlib
943 and zstd. The zlib engine is the historical default of Mercu‐
944 rial. zstd is a newer format that is usually a net win over
945 zlib, operating faster at better compression rates. Use zstd to
946 reduce CPU usage. Multiple values can be specified, the first
947 available one will be used.
948 On some systems, the Mercurial installation may lack zstd sup‐
950 port.
951 Default is zlib.
953 bookmarks-in-store
955 Store bookmarks in .hg/store/. This means that bookmarks are
957 shared when using hg share regardless of the -B option.
958 Repositories with this on-disk format require Mercurial version
960 5.1.
961 Disabled by default.
963 graph
965 Web graph view configuration. This section let you change graph ele‐
966 ments display properties by branches, for instance to make the default
967 branch stand out.
968 Each line has the following format:
970 <branch>.<argument> = <value>
972 where <branch> is the name of the branch being customized. Example:
974 [graph]
976 # 2px width
977 default.width = 2
978 # red color
979 default.color = FF0000
980 Supported arguments:
982 width
984 Set branch edges width in pixels.
986 color
988 Set branch edges color in hexadecimal RGB notation.
990 hooks
992 Commands or Python functions that get automatically executed by various
993 actions such as starting or finishing a commit. Multiple hooks can be
994 run for the same action by appending a suffix to the action. Overriding
995 a site-wide hook can be done by changing its value or setting it to an
996 empty string. Hooks can be prioritized by adding a prefix of priority.
997 to the hook name on a new line and setting the priority. The default
998 priority is 0.
999 Example .hg/hgrc:
1001 [hooks]
1003 # update working directory after adding changesets
1004 changegroup.update = hg update
1005 # do not use the site-wide hook
1006 incoming =
1007 incoming.email = /my/email/hook
1008 incoming.autobuild = /my/build/hook
1009 # force autobuild hook to run before other incoming hooks
1010 priority.incoming.autobuild = 1
1011 Most hooks are run with environment variables set that give useful
1013 additional information. For each hook below, the environment variables
1014 it is passed are listed with names in the form $HG_foo. The $HG_HOOK‐
1015 TYPE and $HG_HOOKNAME variables are set for all hooks. They contain
1016 the type of hook which triggered the run and the full name of the hook
1017 in the config, respectively. In the example above, this will be
1018 $HG_HOOKTYPE=incoming and $HG_HOOKNAME=incoming.email.
1019 Some basic Unix syntax can be enabled for portability, including $VAR
1021 and ${VAR} style variables. A ~ followed by \ or / will be expanded to
1022 %USERPROFILE% to simulate a subset of tilde expansion on Unix. To use
1023 a literal $ or ~, it must be escaped with a back slash or inside of a
1024 strong quote. Strong quotes will be replaced by double quotes after
1025 processing.
1026 This feature is enabled by adding a prefix of tonative. to the hook
1028 name on a new line, and setting it to True. For example:
1029 [hooks]
1031 incoming.autobuild = /my/build/hook
1032 # enable translation to cmd.exe syntax for autobuild hook
1033 tonative.incoming.autobuild = True
1034 changegroup
1036 Run after a changegroup has been added via push, pull or unbun‐
1038 dle. The ID of the first new changeset is in $HG_NODE and last
1039 is in $HG_NODE_LAST. The URL from which changes came is in
1040 $HG_URL.
1041 commit
1043 Run after a changeset has been created in the local repository.
1045 The ID of the newly created changeset is in $HG_NODE. Parent
1046 changeset IDs are in $HG_PARENT1 and $HG_PARENT2.
1047 incoming
1049 Run after a changeset has been pulled, pushed, or unbundled into
1051 the local repository. The ID of the newly arrived changeset is
1052 in $HG_NODE. The URL that was source of the changes is in
1053 $HG_URL.
1054 outgoing
1056 Run after sending changes from the local repository to another.
1058 The ID of first changeset sent is in $HG_NODE. The source of
1059 operation is in $HG_SOURCE. Also see hg help config.hooks.pre‐
1060 outgoing.
1061 post-<command>
1063 Run after successful invocations of the associated command. The
1065 contents of the command line are passed as $HG_ARGS and the
1066 result code in $HG_RESULT. Parsed command line arguments are
1067 passed as $HG_PATS and $HG_OPTS. These contain string represen‐
1068 tations of the python data internally passed to <command>.
1069 $HG_OPTS is a dictionary of options (with unspecified options
1070 set to their defaults). $HG_PATS is a list of arguments. Hook
1071 failure is ignored.
1072 fail-<command>
1074 Run after a failed invocation of an associated command. The con‐
1076 tents of the command line are passed as $HG_ARGS. Parsed command
1077 line arguments are passed as $HG_PATS and $HG_OPTS. These con‐
1078 tain string representations of the python data internally passed
1079 to <command>. $HG_OPTS is a dictionary of options (with unspeci‐
1080 fied options set to their defaults). $HG_PATS is a list of argu‐
1081 ments. Hook failure is ignored.
1082 pre-<command>
1084 Run before executing the associated command. The contents of the
1086 command line are passed as $HG_ARGS. Parsed command line argu‐
1087 ments are passed as $HG_PATS and $HG_OPTS. These contain string
1088 representations of the data internally passed to <command>.
1089 $HG_OPTS is a dictionary of options (with unspecified options
1090 set to their defaults). $HG_PATS is a list of arguments. If the
1091 hook returns failure, the command doesn't execute and Mercurial
1092 returns the failure code.
1093 prechangegroup
1095 Run before a changegroup is added via push, pull or unbundle.
1097 Exit status 0 allows the changegroup to proceed. A non-zero sta‐
1098 tus will cause the push, pull or unbundle to fail. The URL from
1099 which changes will come is in $HG_URL.
1100 precommit
1102 Run before starting a local commit. Exit status 0 allows the
1104 commit to proceed. A non-zero status will cause the commit to
1105 fail. Parent changeset IDs are in $HG_PARENT1 and $HG_PARENT2.
1106 prelistkeys
1108 Run before listing pushkeys (like bookmarks) in the repository.
1110 A non-zero status will cause failure. The key namespace is in
1111 $HG_NAMESPACE.
1112 preoutgoing
1114 Run before collecting changes to send from the local repository
1116 to another. A non-zero status will cause failure. This lets you
1117 prevent pull over HTTP or SSH. It can also prevent propagating
1118 commits (via local pull, push (outbound) or bundle commands),
1119 but not completely, since you can just copy files instead. The
1120 source of operation is in $HG_SOURCE. If "serve", the operation
1121 is happening on behalf of a remote SSH or HTTP repository. If
1122 "push", "pull" or "bundle", the operation is happening on behalf
1123 of a repository on same system.
1124 prepushkey
1126 Run before a pushkey (like a bookmark) is added to the reposi‐
1128 tory. A non-zero status will cause the key to be rejected. The
1129 key namespace is in $HG_NAMESPACE, the key is in $HG_KEY, the
1130 old value (if any) is in $HG_OLD, and the new value is in
1131 $HG_NEW.
1132 pretag
1134 Run before creating a tag. Exit status 0 allows the tag to be
1136 created. A non-zero status will cause the tag to fail. The ID of
1137 the changeset to tag is in $HG_NODE. The name of tag is in
1138 $HG_TAG. The tag is local if $HG_LOCAL=1, or in the repository
1139 if $HG_LOCAL=0.
1140 pretxnopen
1142 Run before any new repository transaction is open. The reason
1144 for the transaction will be in $HG_TXNNAME, and a unique identi‐
1145 fier for the transaction will be in HG_TXNID. A non-zero status
1146 will prevent the transaction from being opened.
1147 pretxnclose
1149 Run right before the transaction is actually finalized. Any
1151 repository change will be visible to the hook program. This lets
1152 you validate the transaction content or change it. Exit status 0
1153 allows the commit to proceed. A non-zero status will cause the
1154 transaction to be rolled back. The reason for the transaction
1155 opening will be in $HG_TXNNAME, and a unique identifier for the
1156 transaction will be in HG_TXNID. The rest of the available data
1157 will vary according the transaction type. New changesets will
1158 add $HG_NODE (the ID of the first added changeset),
1159 $HG_NODE_LAST (the ID of the last added changeset), $HG_URL and
1160 $HG_SOURCE variables. Bookmark and phase changes will set
1161 HG_BOOKMARK_MOVED and HG_PHASES_MOVED to 1 respectively, etc.
1162 pretxnclose-bookmark
1164 Run right before a bookmark change is actually finalized. Any
1166 repository change will be visible to the hook program. This lets
1167 you validate the transaction content or change it. Exit status 0
1168 allows the commit to proceed. A non-zero status will cause the
1169 transaction to be rolled back. The name of the bookmark will be
1170 available in $HG_BOOKMARK, the new bookmark location will be
1171 available in $HG_NODE while the previous location will be avail‐
1172 able in $HG_OLDNODE. In case of a bookmark creation $HG_OLDNODE
1173 will be empty. In case of deletion $HG_NODE will be empty. In
1174 addition, the reason for the transaction opening will be in
1175 $HG_TXNNAME, and a unique identifier for the transaction will be
1176 in HG_TXNID.
1177 pretxnclose-phase
1179 Run right before a phase change is actually finalized. Any
1181 repository change will be visible to the hook program. This lets
1182 you validate the transaction content or change it. Exit status 0
1183 allows the commit to proceed. A non-zero status will cause the
1184 transaction to be rolled back. The hook is called multiple
1185 times, once for each revision affected by a phase change. The
1186 affected node is available in $HG_NODE, the phase in $HG_PHASE
1187 while the previous $HG_OLDPHASE. In case of new node, $HG_OLD‐
1188 PHASE will be empty. In addition, the reason for the transac‐
1189 tion opening will be in $HG_TXNNAME, and a unique identifier for
1190 the transaction will be in HG_TXNID. The hook is also run for
1191 newly added revisions. In this case the $HG_OLDPHASE entry will
1192 be empty.
1193 txnclose
1195 Run after any repository transaction has been committed. At this
1197 point, the transaction can no longer be rolled back. The hook
1198 will run after the lock is released. See hg help con‐
1199 fig.hooks.pretxnclose for details about available variables.
1200 txnclose-bookmark
1202 Run after any bookmark change has been committed. At this point,
1204 the transaction can no longer be rolled back. The hook will run
1205 after the lock is released. See hg help config.hooks.pretxn‐
1206 close-bookmark for details about available variables.
1207 txnclose-phase
1209 Run after any phase change has been committed. At this point,
1211 the transaction can no longer be rolled back. The hook will run
1212 after the lock is released. See hg help config.hooks.pretxn‐
1213 close-phase for details about available variables.
1214 txnabort
1216 Run when a transaction is aborted. See hg help con‐
1218 fig.hooks.pretxnclose for details about available variables.
1219 pretxnchangegroup
1221 Run after a changegroup has been added via push, pull or unbun‐
1223 dle, but before the transaction has been committed. The change‐
1224 group is visible to the hook program. This allows validation of
1225 incoming changes before accepting them. The ID of the first new
1226 changeset is in $HG_NODE and last is in $HG_NODE_LAST. Exit sta‐
1227 tus 0 allows the transaction to commit. A non-zero status will
1228 cause the transaction to be rolled back, and the push, pull or
1229 unbundle will fail. The URL that was the source of changes is in
1230 $HG_URL.
1231 pretxncommit
1233 Run after a changeset has been created, but before the transac‐
1235 tion is committed. The changeset is visible to the hook program.
1236 This allows validation of the commit message and changes. Exit
1237 status 0 allows the commit to proceed. A non-zero status will
1238 cause the transaction to be rolled back. The ID of the new
1239 changeset is in $HG_NODE. The parent changeset IDs are in
1240 $HG_PARENT1 and $HG_PARENT2.
1241 preupdate
1243 Run before updating the working directory. Exit status 0 allows
1245 the update to proceed. A non-zero status will prevent the
1246 update. The changeset ID of first new parent is in $HG_PARENT1.
1247 If updating to a merge, the ID of second new parent is in
1248 $HG_PARENT2.
1249 listkeys
1251 Run after listing pushkeys (like bookmarks) in the repository.
1253 The key namespace is in $HG_NAMESPACE. $HG_VALUES is a dictio‐
1254 nary containing the keys and values.
1255 pushkey
1257 Run after a pushkey (like a bookmark) is added to the reposi‐
1259 tory. The key namespace is in $HG_NAMESPACE, the key is in
1260 $HG_KEY, the old value (if any) is in $HG_OLD, and the new value
1261 is in $HG_NEW.
1262 tag
1264 Run after a tag is created. The ID of the tagged changeset is in
1266 $HG_NODE. The name of tag is in $HG_TAG. The tag is local if
1267 $HG_LOCAL=1, or in the repository if $HG_LOCAL=0.
1268 update
1270 Run after updating the working directory. The changeset ID of
1272 first new parent is in $HG_PARENT1. If updating to a merge, the
1273 ID of second new parent is in $HG_PARENT2. If the update suc‐
1274 ceeded, $HG_ERROR=0. If the update failed (e.g. because con‐
1275 flicts were not resolved), $HG_ERROR=1.
1276 Note It is generally better to use standard hooks rather than the
1278 generic pre- and post- command hooks, as they are guaranteed to
1279 be called in the appropriate contexts for influencing transac‐
1280 tions. Also, hooks like "commit" will be called in all contexts
1281 that generate a commit (e.g. tag) and not just the commit com‐
1282 mand.
1283 Note Environment variables with empty values may not be passed to
1285 hooks on platforms such as Windows. As an example, $HG_PARENT2
1286 will have an empty value under Unix-like platforms for non-merge
1287 changesets, while it will not be available at all under Windows.
1288 The syntax for Python hooks is as follows:
1290 hookname = python:modulename.submodule.callable
1292 hookname = python:/path/to/python/module.py:callable
1293 Python hooks are run within the Mercurial process. Each hook is called
1295 with at least three keyword arguments: a ui object (keyword ui), a
1296 repository object (keyword repo), and a hooktype keyword that tells
1297 what kind of hook is used. Arguments listed as environment variables
1298 above are passed as keyword arguments, with no HG_ prefix, and names in
1299 lower case.
1300 If a Python hook returns a "true" value or raises an exception, this is
1302 treated as a failure.
1303 hostfingerprints
1305 (Deprecated. Use [hostsecurity]'s fingerprints options instead.)
1306 Fingerprints of the certificates of known HTTPS servers.
1308 A HTTPS connection to a server with a fingerprint configured here will
1310 only succeed if the servers certificate matches the fingerprint. This
1311 is very similar to how ssh known hosts works.
1312 The fingerprint is the SHA-1 hash value of the DER encoded certificate.
1314 Multiple values can be specified (separated by spaces or commas). This
1315 can be used to define both old and new fingerprints while a host tran‐
1316 sitions to a new certificate.
1317 The CA chain and web.cacerts is not used for servers with a finger‐
1319 print.
1320 For example:
1322 [hostfingerprints]
1324 hg.intevation.de = fc:e2:8d:d9:51:cd:cb:c1:4d:18:6b:b7:44:8d:49:72:57:e6:cd:33
1325 hg.intevation.org = fc:e2:8d:d9:51:cd:cb:c1:4d:18:6b:b7:44:8d:49:72:57:e6:cd:33
1326 hostsecurity
1328 Used to specify global and per-host security settings for connecting to
1329 other machines.
1330 The following options control default behavior for all hosts.
1332 ciphers
1334 Defines the cryptographic ciphers to use for connections.
1336 Value must be a valid OpenSSL Cipher List Format as documented
1338 at
1339 https://www.openssl.org/docs/manmaster/apps/ciphers.html#CIPHER-LIST-FORMAT
1340 .
1341 This setting is for advanced users only. Setting to incorrect
1343 values can significantly lower connection security or decrease
1344 performance. You have been warned.
1345 This option requires Python 2.7.
1347 minimumprotocol
1349 Defines the minimum channel encryption protocol to use.
1351 By default, the highest version of TLS supported by both client
1353 and server is used.
1354 Allowed values are: tls1.0, tls1.1, tls1.2.
1356 When running on an old Python version, only tls1.0 is allowed
1358 since old versions of Python only support up to TLS 1.0.
1359 When running a Python that supports modern TLS versions, the
1361 default is tls1.1. tls1.0 can still be used to allow TLS 1.0.
1362 However, this weakens security and should only be used as a fea‐
1363 ture of last resort if a server does not support TLS 1.1+.
1364 Options in the [hostsecurity] section can have the form hostname:set‐
1366 ting. This allows multiple settings to be defined on a per-host basis.
1367 The following per-host settings can be defined.
1369 ciphers
1371 This behaves like ciphers as described above except it only
1373 applies to the host on which it is defined.
1374 fingerprints
1376 A list of hashes of the DER encoded peer/remote certificate.
1378 Values have the form algorithm:fingerprint. e.g.
1379 sha256:c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2.
1380 In addition, colons (:) can appear in the fingerprint part.
1381 The following algorithms/prefixes are supported: sha1, sha256,
1383 sha512.
1384 Use of sha256 or sha512 is preferred.
1386 If a fingerprint is specified, the CA chain is not validated for
1388 this host and Mercurial will require the remote certificate to
1389 match one of the fingerprints specified. This means if the
1390 server updates its certificate, Mercurial will abort until a new
1391 fingerprint is defined. This can provide stronger security than
1392 traditional CA-based validation at the expense of convenience.
1393 This option takes precedence over verifycertsfile.
1395 minimumprotocol
1397 This behaves like minimumprotocol as described above except it
1399 only applies to the host on which it is defined.
1400 verifycertsfile
1402 Path to file a containing a list of PEM encoded certificates
1404 used to verify the server certificate. Environment variables and
1405 ~user constructs are expanded in the filename.
1406 The server certificate or the certificate's certificate author‐
1408 ity (CA) must match a certificate from this file or certificate
1409 verification will fail and connections to the server will be
1410 refused.
1411 If defined, only certificates provided by this file will be
1413 used: web.cacerts and any system/default certificates will not
1414 be used.
1415 This option has no effect if the per-host fingerprints option is
1417 set.
1418 The format of the file is as follows:
1420 -----BEGIN CERTIFICATE-----
1422 ... (certificate in base64 PEM encoding) ...
1423 -----END CERTIFICATE-----
1424 -----BEGIN CERTIFICATE-----
1425 ... (certificate in base64 PEM encoding) ...
1426 -----END CERTIFICATE-----
1427 For example:
1429 [hostsecurity]
1431 hg.example.com:fingerprints = sha256:c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2
1432 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
1433 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
1434 foo.example.com:verifycertsfile = /etc/ssl/trusted-ca-certs.pem
1435 To change the default minimum protocol version to TLS 1.2 but to allow
1437 TLS 1.1 when connecting to hg.example.com:
1438 [hostsecurity]
1440 minimumprotocol = tls1.2
1441 hg.example.com:minimumprotocol = tls1.1
1442 http_proxy
1444 Used to access web-based Mercurial repositories through a HTTP proxy.
1445 host
1447 Host name and (optional) port of the proxy server, for example
1449 "myproxy:8000".
1450 no
1452 Optional. Comma-separated list of host names that should bypass
1454 the proxy.
1455 passwd
1457 Optional. Password to authenticate with at the proxy server.
1459 user
1461 Optional. User name to authenticate with at the proxy server.
1463 always
1465 Optional. Always use the proxy, even for localhost and any
1467 entries in http_proxy.no. (default: False)
1468 http
1470 Used to configure access to Mercurial repositories via HTTP.
1471 timeout
1473 If set, blocking operations will timeout after that many sec‐
1475 onds. (default: None)
1476 merge
1478 This section specifies behavior during merges and updates.
1479 checkignored
1481 Controls behavior when an ignored file on disk has the same name
1483 as a tracked file in the changeset being merged or updated to,
1484 and has different contents. Options are abort, warn and ignore.
1485 With abort, abort on such files. With warn, warn on such files
1486 and back them up as .orig. With ignore, don't print a warning
1487 and back them up as .orig. (default: abort)
1488 checkunknown
1490 Controls behavior when an unknown file that isn't ignored has
1492 the same name as a tracked file in the changeset being merged or
1493 updated to, and has different contents. Similar to merge.check‐
1494 ignored, except for files that are not ignored. (default: abort)
1495 on-failure
1497 When set to continue (the default), the merge process attempts
1499 to merge all unresolved files using the merge chosen tool,
1500 regardless of whether previous file merge attempts during the
1501 process succeeded or not. Setting this to prompt will prompt
1502 after any merge failure continue or halt the merge process. Set‐
1503 ting this to halt will automatically halt the merge process on
1504 any merge tool failure. The merge process can be restarted by
1505 using the resolve command. When a merge is halted, the reposi‐
1506 tory is left in a normal unresolved merge state. (default: con‐
1507 tinue)
1508 strict-capability-check
1510 Whether capabilities of internal merge tools are checked
1512 strictly or not, while examining rules to decide merge tool to
1513 be used. (default: False)
1514 merge-patterns
1516 This section specifies merge tools to associate with particular file
1517 patterns. Tools matched here will take precedence over the default
1518 merge tool. Patterns are globs by default, rooted at the repository
1519 root.
1520 Example:
1522 [merge-patterns]
1524 **.c = kdiff3
1525 **.jpg = myimgmerge
1526 merge-tools
1528 This section configures external merge tools to use for file-level
1529 merges. This section has likely been preconfigured at install time.
1530 Use hg config merge-tools to check the existing configuration. Also
1531 see hg help merge-tools for more details.
1532 Example ~/.hgrc:
1534 [merge-tools]
1536 # Override stock tool location
1537 kdiff3.executable = ~/bin/kdiff3
1538 # Specify command line
1539 kdiff3.args = $base $local $other -o $output
1540 # Give higher priority
1541 kdiff3.priority = 1
1542 # Changing the priority of preconfigured tool
1544 meld.priority = 0
1545 # Disable a preconfigured tool
1547 vimdiff.disabled = yes
1548 # Define new tool
1550 myHtmlTool.args = -m $local $other $base $output
1551 myHtmlTool.regkey = Software\FooSoftware\HtmlMerge
1552 myHtmlTool.priority = 1
1553 Supported arguments:
1555 priority
1557 The priority in which to evaluate this tool. (default: 0)
1559 executable
1561 Either just the name of the executable or its pathname.
1563 On Windows, the path can use environment variables with ${Pro‐
1565 gramFiles} syntax.
1566 (default: the tool name)
1568 args
1570 The arguments to pass to the tool executable. You can refer to
1572 the files being merged as well as the output file through these
1573 variables: $base, $local, $other, $output.
1574 The meaning of $local and $other can vary depending on which
1576 action is being performed. During an update or merge, $local
1577 represents the original state of the file, while $other repre‐
1578 sents the commit you are updating to or the commit you are merg‐
1579 ing with. During a rebase, $local represents the destination of
1580 the rebase, and $other represents the commit being rebased.
1581 Some operations define custom labels to assist with identifying
1583 the revisions, accessible via $labellocal, $labelother, and
1584 $labelbase. If custom labels are not available, these will be
1585 local, other, and base, respectively. (default: $local $base
1586 $other)
1587 premerge
1589 Attempt to run internal non-interactive 3-way merge tool before
1591 launching external tool. Options are true, false, keep or
1592 keep-merge3. The keep option will leave markers in the file if
1593 the premerge fails. The keep-merge3 will do the same but include
1594 information about the base of the merge in the marker (see
1595 internal :merge3 in hg help merge-tools). (default: True)
1596 binary
1598 This tool can merge binary files. (default: False, unless tool
1600 was selected by file pattern match)
1601 symlink
1603 This tool can merge symlinks. (default: False)
1605 check
1607 A list of merge success-checking options:
1609 changed
1611 Ask whether merge was successful when the merged file
1613 shows no changes.
1614 conflicts
1616 Check whether there are conflicts even though the tool
1618 reported success.
1619 prompt
1621 Always prompt for merge success, regardless of success
1623 reported by tool.
1624 fixeol
1626 Attempt to fix up EOL changes caused by the merge tool.
1628 (default: False)
1629 gui
1631 This tool requires a graphical interface to run. (default:
1633 False)
1634 mergemarkers
1636 Controls whether the labels passed via $labellocal, $labelother,
1638 and $labelbase are detailed (respecting mergemarkertemplate) or
1639 basic. If premerge is keep or keep-merge3, the conflict markers
1640 generated during premerge will be detailed if either this option
1641 or the corresponding option in the [ui] section is detailed.
1642 (default: basic)
1643 mergemarkertemplate
1645 This setting can be used to override mergemarkertemplate from
1647 the [ui] section on a per-tool basis; this applies to the
1648 $label-prefixed variables and to the conflict markers that are
1649 generated if premerge is keep` or ``keep-merge3. See the corre‐
1650 sponding variable in [ui] for more information.
1651 regkey
1653 Windows registry key which describes install location of this
1655 tool. Mercurial will search for this key first under HKEY_CUR‐
1656 RENT_USER and then under HKEY_LOCAL_MACHINE. (default: None)
1657 regkeyalt
1659 An alternate Windows registry key to try if the first key is not
1661 found. The alternate key uses the same regname and regappend
1662 semantics of the primary key. The most common use for this key
1663 is to search for 32bit applications on 64bit operating systems.
1664 (default: None)
1665 regname
1667 Name of value to read from specified registry key. (default:
1669 the unnamed (default) value)
1670 regappend
1672 String to append to the value read from the registry, typically
1674 the executable name of the tool. (default: None)
1675 pager
1677 Setting used to control when to paginate and with what external tool.
1678 See hg help pager for details.
1679 pager
1681 Define the external tool used as pager.
1683 If no pager is set, Mercurial uses the environment variable
1685 $PAGER. If neither pager.pager, nor $PAGER is set, a default
1686 pager will be used, typically less on Unix and more on Windows.
1687 Example:
1688 [pager]
1690 pager = less -FRX
1691 ignore
1693 List of commands to disable the pager for. Example:
1695 [pager]
1697 ignore = version, help, update
1698 patch
1700 Settings used when applying patches, for instance through the 'import'
1701 command or with Mercurial Queues extension.
1702 eol
1704 When set to 'strict' patch content and patched files end of
1706 lines are preserved. When set to lf or crlf, both files end of
1707 lines are ignored when patching and the result line endings are
1708 normalized to either LF (Unix) or CRLF (Windows). When set to
1709 auto, end of lines are again ignored while patching but line
1710 endings in patched files are normalized to their original set‐
1711 ting on a per-file basis. If target file does not exist or has
1712 no end of line, patch line endings are preserved. (default:
1713 strict)
1714 fuzz
1716 The number of lines of 'fuzz' to allow when applying patches.
1718 This controls how much context the patcher is allowed to ignore
1719 when trying to apply a patch. (default: 2)
1720 paths
1722 Assigns symbolic names and behavior to repositories.
1723 Options are symbolic names defining the URL or directory that is the
1725 location of the repository. Example:
1726 [paths]
1728 my_server = https://example.com/my_repo
1729 local_path = /home/me/repo
1730 These symbolic names can be used from the command line. To pull from
1732 my_server: hg pull my_server. To push to local_path: hg push local_path
1733 .
1734 Options containing colons (:) denote sub-options that can influence
1736 behavior for that specific path. Example:
1737 [paths]
1739 my_server = https://example.com/my_path
1740 my_server:pushurl = ssh://example.com/my_path
1741 The following sub-options can be defined:
1743 pushurl
1745 The URL to use for push operations. If not defined, the location
1747 defined by the path's main entry is used.
1748 pushrev
1750 A revset defining which revisions to push by default.
1752 When hg push is executed without a -r argument, the revset
1754 defined by this sub-option is evaluated to determine what to
1755 push.
1756 For example, a value of . will push the working directory's
1758 revision by default.
1759 Revsets specifying bookmarks will not result in the bookmark
1761 being pushed.
1762 The following special named paths exist:
1764 default
1766 The URL or directory to use when no source or remote is speci‐
1768 fied.
1769 hg clone will automatically define this path to the location the
1771 repository was cloned from.
1772 default-push
1774 (deprecated) The URL or directory for the default hg push loca‐
1776 tion. default:pushurl should be used instead.
1777 phases
1779 Specifies default handling of phases. See hg help phases for more
1780 information about working with phases.
1781 publish
1783 Controls draft phase behavior when working as a server. When
1785 true, pushed changesets are set to public in both client and
1786 server and pulled or cloned changesets are set to public in the
1787 client. (default: True)
1788 new-commit
1790 Phase of newly-created commits. (default: draft)
1792 checksubrepos
1794 Check the phase of the current revision of each subrepository.
1796 Allowed values are "ignore", "follow" and "abort". For settings
1797 other than "ignore", the phase of the current revision of each
1798 subrepository is checked before committing the parent reposi‐
1799 tory. If any of those phases is greater than the phase of the
1800 parent repository (e.g. if a subrepo is in a "secret" phase
1801 while the parent repo is in "draft" phase), the commit is either
1802 aborted (if checksubrepos is set to "abort") or the higher phase
1803 is used for the parent repository commit (if set to "follow").
1804 (default: follow)
1805 profiling
1807 Specifies profiling type, format, and file output. Two profilers are
1808 supported: an instrumenting profiler (named ls), and a sampling pro‐
1809 filer (named stat).
1810 In this section description, 'profiling data' stands for the raw data
1812 collected during profiling, while 'profiling report' stands for a sta‐
1813 tistical text report generated from the profiling data.
1814 enabled
1816 Enable the profiler. (default: false)
1818 This is equivalent to passing --profile on the command line.
1820 type
1822 The type of profiler to use. (default: stat)
1824 ls
1826 Use Python's built-in instrumenting profiler. This pro‐
1828 filer works on all platforms, but each line number it
1829 reports is the first line of a function. This restriction
1830 makes it difficult to identify the expensive parts of a
1831 non-trivial function.
1832 stat
1834 Use a statistical profiler, statprof. This profiler is
1836 most useful for profiling commands that run for longer
1837 than about 0.1 seconds.
1838 format
1840 Profiling format. Specific to the ls instrumenting profiler.
1842 (default: text)
1843 text
1845 Generate a profiling report. When saving to a file, it
1847 should be noted that only the report is saved, and the
1848 profiling data is not kept.
1849 kcachegrind
1851 Format profiling data for kcachegrind use: when saving to
1853 a file, the generated file can directly be loaded into
1854 kcachegrind.
1855 statformat
1857 Profiling format for the stat profiler. (default: hotpath)
1859 hotpath
1861 Show a tree-based display containing the hot path of exe‐
1863 cution (where most time was spent).
1864 bymethod
1866 Show a table of methods ordered by how frequently they
1868 are active.
1869 byline
1871 Show a table of lines in files ordered by how frequently
1873 they are active.
1874 json
1876 Render profiling data as JSON.
1878 frequency
1880 Sampling frequency. Specific to the stat sampling profiler.
1882 (default: 1000)
1883 output
1885 File path where profiling data or report should be saved. If the
1887 file exists, it is replaced. (default: None, data is printed on
1888 stderr)
1889 sort
1891 Sort field. Specific to the ls instrumenting profiler. One of
1893 callcount, reccallcount, totaltime and inlinetime. (default:
1894 inlinetime)
1895 time-track
1897 Control if the stat profiler track cpu or real time. (default:
1899 cpu on Windows, otherwise real)
1900 limit
1902 Number of lines to show. Specific to the ls instrumenting pro‐
1904 filer. (default: 30)
1905 nested
1907 Show at most this number of lines of drill-down info after each
1909 main entry. This can help explain the difference between Total
1910 and Inline. Specific to the ls instrumenting profiler.
1911 (default: 0)
1912 showmin
1914 Minimum fraction of samples an entry must have for it to be dis‐
1916 played. Can be specified as a float between 0.0 and 1.0 or can
1917 have a % afterwards to allow values up to 100. e.g. 5%.
1918 Only used by the stat profiler.
1920 For the hotpath format, default is 0.05. For the chrome format,
1922 default is 0.005.
1923 The option is unused on other formats.
1925 showmax
1927 Maximum fraction of samples an entry can have before it is
1929 ignored in display. Values format is the same as showmin.
1930 Only used by the stat profiler.
1932 For the chrome format, default is 0.999.
1934 The option is unused on other formats.
1936 showtime
1938 Show time taken as absolute durations, in addition to percent‐
1940 ages. Only used by the hotpath format. (default: true)
1941 progress
1943 Mercurial commands can draw progress bars that are as informative as
1944 possible. Some progress bars only offer indeterminate information,
1945 while others have a definite end point.
1946 debug
1948 Whether to print debug info when updating the progress bar.
1950 (default: False)
1951 delay
1953 Number of seconds (float) before showing the progress bar.
1955 (default: 3)
1956 changedelay
1958 Minimum delay before showing a new topic. When set to less than
1960 3 * refresh, that value will be used instead. (default: 1)
1961 estimateinterval
1963 Maximum sampling interval in seconds for speed and estimated
1965 time calculation. (default: 60)
1966 refresh
1968 Time in seconds between refreshes of the progress bar. (default:
1970 0.1)
1971 format
1973 Format of the progress bar.
1975 Valid entries for the format field are topic, bar, number, unit,
1977 estimate, speed, and item. item defaults to the last 20 charac‐
1978 ters of the item, but this can be changed by adding either
1979 -<num> which would take the last num characters, or +<num> for
1980 the first num characters.
1981 (default: topic bar number estimate)
1983 width
1985 If set, the maximum width of the progress information (that is,
1987 min(width, term width) will be used).
1988 clear-complete
1990 Clear the progress bar after it's done. (default: True)
1992 disable
1994 If true, don't show a progress bar.
1996 assume-tty
1998 If true, ALWAYS show a progress bar, unless disable is given.
2000 rebase
2002 evolution.allowdivergence
2003 Default to False, when True allow creating divergence when per‐
2005 forming rebase of obsolete changesets.
2006 revsetalias
2008 Alias definitions for revsets. See hg help revsets for details.
2009 rewrite
2011 backup-bundle
2012 Whether to save stripped changesets to a bundle file. (default:
2014 True)
2015 update-timestamp
2017 If true, updates the date and time of the changeset to current.
2019 It is only applicable for hg amend, hg commit --amend and hg
2020 uncommit in the current version.
2021 storage
2023 Control the strategy Mercurial uses internally to store history.
2024 Options in this category impact performance and repository size.
2025 revlog.optimize-delta-parent-choice
2027 When storing a merge revision, both parents will be equally con‐
2029 sidered as a possible delta base. This results in better delta
2030 selection and improved revlog compression. This option is
2031 enabled by default.
2032 Turning this option off can result in large increase of reposi‐
2034 tory size for repository with many merges.
2035 revlog.reuse-external-delta-parent
2037 Control the order in which delta parents are considered when
2039 adding new revisions from an external source. (typically: apply
2040 bundle from hg pull or hg push).
2041 New revisions are usually provided as a delta against other
2043 revisions. By default, Mercurial will try to reuse this delta
2044 first, therefore using the same "delta parent" as the source.
2045 Directly using delta's from the source reduces CPU usage and
2046 usually speeds up operation. However, in some case, the source
2047 might have sub-optimal delta bases and forcing their reevalua‐
2048 tion is useful. For example, pushes from an old client could
2049 have sub-optimal delta's parent that the server want to opti‐
2050 mize. (lack of general delta, bad parents, choice, lack of
2051 sparse-revlog, etc).
2052 This option is enabled by default. Turning it off will ensure
2054 bad delta parent choices from older client do not propagate to
2055 this repository, at the cost of a small increase in CPU consump‐
2056 tion.
2057 Note: this option only control the order in which delta parents
2059 are considered. Even when disabled, the existing delta from the
2060 source will be reused if the same delta parent is selected.
2061 revlog.reuse-external-delta
2063 Control the reuse of delta from external source. (typically:
2065 apply bundle from hg pull or hg push).
2066 New revisions are usually provided as a delta against another
2068 revision. By default, Mercurial will not recompute the same
2069 delta again, trusting externally provided deltas. There have
2070 been rare cases of small adjustment to the diffing algorithm in
2071 the past. So in some rare case, recomputing delta provided by
2072 ancient clients can provides better results. Disabling this
2073 option means going through a full delta recomputation for all
2074 incoming revisions. It means a large increase in CPU usage and
2075 will slow operations down.
2076 This option is enabled by default. When disabled, it also dis‐
2078 ables the related storage.revlog.reuse-external-delta-parent
2079 option.
2080 revlog.zlib.level
2082 Zlib compression level used when storing data into the reposi‐
2084 tory. Accepted Value range from 1 (lowest compression) to 9
2085 (highest compression). Zlib default value is 6.
2086 revlog.zstd.level
2088 zstd compression level used when storing data into the reposi‐
2090 tory. Accepted Value range from 1 (lowest compression) to 22
2091 (highest compression). (default 3)
2092 server
2094 Controls generic server settings.
2095 bookmarks-pushkey-compat
2097 Trigger pushkey hook when being pushed bookmark updates. This
2099 config exist for compatibility purpose (default to True)
2100 If you use pushkey and pre-pushkey hooks to control bookmark
2102 movement we recommend you migrate them to txnclose-bookmark and
2103 pretxnclose-bookmark.
2104 compressionengines
2106 List of compression engines and their relative priority to
2108 advertise to clients.
2109 The order of compression engines determines their priority, the
2111 first having the highest priority. If a compression engine is
2112 not listed here, it won't be advertised to clients.
2113 If not set (the default), built-in defaults are used. Run hg
2115 debuginstall to list available compression engines and their
2116 default wire protocol priority.
2117 Older Mercurial clients only support zlib compression and this
2119 setting has no effect for legacy clients.
2120 uncompressed
2122 Whether to allow clients to clone a repository using the uncom‐
2124 pressed streaming protocol. This transfers about 40% more data
2125 than a regular clone, but uses less memory and CPU on both
2126 server and client. Over a LAN (100 Mbps or better) or a very
2127 fast WAN, an uncompressed streaming clone is a lot faster (~10x)
2128 than a regular clone. Over most WAN connections (anything slower
2129 than about 6 Mbps), uncompressed streaming is slower, because of
2130 the extra data transfer overhead. This mode will also temporar‐
2131 ily hold the write lock while determining what data to transfer.
2132 (default: True)
2133 uncompressedallowsecret
2135 Whether to allow stream clones when the repository contains
2137 secret changesets. (default: False)
2138 preferuncompressed
2140 When set, clients will try to use the uncompressed streaming
2142 protocol. (default: False)
2143 disablefullbundle
2145 When set, servers will refuse attempts to do pull-based clones.
2147 If this option is set, preferuncompressed and/or clone bundles
2148 are highly recommended. Partial clones will still be allowed.
2149 (default: False)
2150 streamunbundle
2152 When set, servers will apply data sent from the client directly,
2154 otherwise it will be written to a temporary file first. This
2155 option effectively prevents concurrent pushes.
2156 pullbundle
2158 When set, the server will check pullbundle.manifest for bundles
2160 covering the requested heads and common nodes. The first match‐
2161 ing entry will be streamed to the client.
2162 For HTTP transport, the stream will still use zlib compression
2164 for older clients.
2165 concurrent-push-mode
2167 Level of allowed race condition between two pushing clients.
2169 · 'strict': push is abort if another client touched the reposi‐
2171 tory while the push was preparing.
2172 · 'check-related': push is only aborted if it affects head that
2174 got also affected while the push was preparing. (default since
2175 5.4)
2176 'check-related' only takes effect for compatible clients (ver‐
2178 sion 4.3 and later). Older clients will use 'strict'.
2179 validate
2181 Whether to validate the completeness of pushed changesets by
2183 checking that all new file revisions specified in manifests are
2184 present. (default: False)
2185 maxhttpheaderlen
2187 Instruct HTTP clients not to send request headers longer than
2189 this many bytes. (default: 1024)
2190 bundle1
2192 Whether to allow clients to push and pull using the legacy bun‐
2194 dle1 exchange format. (default: True)
2195 bundle1gd
2197 Like bundle1 but only used if the repository is using the gener‐
2199 aldelta storage format. (default: True)
2200 bundle1.push
2202 Whether to allow clients to push using the legacy bundle1
2204 exchange format. (default: True)
2205 bundle1gd.push
2207 Like bundle1.push but only used if the repository is using the
2209 generaldelta storage format. (default: True)
2210 bundle1.pull
2212 Whether to allow clients to pull using the legacy bundle1
2214 exchange format. (default: True)
2215 bundle1gd.pull
2217 Like bundle1.pull but only used if the repository is using the
2219 generaldelta storage format. (default: True)
2220 Large repositories using the generaldelta storage format should
2222 consider setting this option because converting generaldelta
2223 repositories to the exchange format required by the bundle1 data
2224 format can consume a lot of CPU.
2225 bundle2.stream
2227 Whether to allow clients to pull using the bundle2 streaming
2229 protocol. (default: True)
2230 zliblevel
2232 Integer between -1 and 9 that controls the zlib compression
2234 level for wire protocol commands that send zlib compressed out‐
2235 put (notably the commands that send repository history data).
2236 The default (-1) uses the default zlib compression level, which
2238 is likely equivalent to 6. 0 means no compression. 9 means maxi‐
2239 mum compression.
2240 Setting this option allows server operators to make trade-offs
2242 between bandwidth and CPU used. Lowering the compression lowers
2243 CPU utilization but sends more bytes to clients.
2244 This option only impacts the HTTP server.
2246 zstdlevel
2248 Integer between 1 and 22 that controls the zstd compression
2250 level for wire protocol commands. 1 is the minimal amount of
2251 compression and 22 is the highest amount of compression.
2252 The default (3) should be significantly faster than zlib while
2254 likely delivering better compression ratios.
2255 This option only impacts the HTTP server.
2257 See also server.zliblevel.
2259 view
2261 Repository filter used when exchanging revisions with the peer.
2263 The default view (served) excludes secret and hidden changesets.
2265 Another useful value is immutable (no draft, secret or hidden
2266 changesets). (EXPERIMENTAL)
2267 smtp
2269 Configuration for extensions that need to send email messages.
2270 host
2272 Host name of mail server, e.g. "mail.example.com".
2274 port
2276 Optional. Port to connect to on mail server. (default: 465 if
2278 tls is smtps; 25 otherwise)
2279 tls
2281 Optional. Method to enable TLS when connecting to mail server:
2283 starttls, smtps or none. (default: none)
2284 username
2286 Optional. User name for authenticating with the SMTP server.
2288 (default: None)
2289 password
2291 Optional. Password for authenticating with the SMTP server. If
2293 not specified, interactive sessions will prompt the user for a
2294 password; non-interactive sessions will fail. (default: None)
2295 local_hostname
2297 Optional. The hostname that the sender can use to identify
2299 itself to the MTA.
2300 subpaths
2302 Subrepository source URLs can go stale if a remote server changes name
2303 or becomes temporarily unavailable. This section lets you define re‐
2304 write rules of the form:
2305 <pattern> = <replacement>
2307 where pattern is a regular expression matching a subrepository source
2309 URL and replacement is the replacement string used to rewrite it.
2310 Groups can be matched in pattern and referenced in replacements. For
2311 instance:
2312 http://server/(.*)-hg/ = http://hg.server/\1/
2314 rewrites http://server/foo-hg/ into http://hg.server/foo/.
2316 Relative subrepository paths are first made absolute, and the rewrite
2318 rules are then applied on the full (absolute) path. If pattern doesn't
2319 match the full path, an attempt is made to apply it on the relative
2320 path alone. The rules are applied in definition order.
2321 subrepos
2323 This section contains options that control the behavior of the sub‐
2324 repositories feature. See also hg help subrepos.
2325 Security note: auditing in Mercurial is known to be insufficient to
2327 prevent clone-time code execution with carefully constructed Git subre‐
2328 pos. It is unknown if a similar detect is present in Subversion subre‐
2329 pos. Both Git and Subversion subrepos are disabled by default out of
2330 security concerns. These subrepo types can be enabled using the respec‐
2331 tive options below.
2332 allowed
2334 Whether subrepositories are allowed in the working directory.
2336 When false, commands involving subrepositories (like hg update)
2338 will fail for all subrepository types. (default: true)
2339 hg:allowed
2341 Whether Mercurial subrepositories are allowed in the working
2343 directory. This option only has an effect if subrepos.allowed is
2344 true. (default: true)
2345 git:allowed
2347 Whether Git subrepositories are allowed in the working direc‐
2349 tory. This option only has an effect if subrepos.allowed is
2350 true.
2351 See the security note above before enabling Git subrepos.
2353 (default: false)
2354 svn:allowed
2356 Whether Subversion subrepositories are allowed in the working
2358 directory. This option only has an effect if subrepos.allowed is
2359 true.
2360 See the security note above before enabling Subversion subrepos.
2362 (default: false)
2363 templatealias
2365 Alias definitions for templates. See hg help templates for details.
2366 templates
2368 Use the [templates] section to define template strings. See hg help
2369 templates for details.
2370 trusted
2372 Mercurial will not use the settings in the .hg/hgrc file from a reposi‐
2373 tory if it doesn't belong to a trusted user or to a trusted group, as
2374 various hgrc features allow arbitrary commands to be run. This issue is
2375 often encountered when configuring hooks or extensions for shared
2376 repositories or servers. However, the web interface will use some safe
2377 settings from the [web] section.
2378 This section specifies what users and groups are trusted. The current
2380 user is always trusted. To trust everybody, list a user or a group with
2381 name *. These settings must be placed in an already-trusted file to
2382 take effect, such as $HOME/.hgrc of the user or service running Mercu‐
2383 rial.
2384 users
2386 Comma-separated list of trusted users.
2388 groups
2390 Comma-separated list of trusted groups.
2392 ui
2394 User interface controls.
2395 archivemeta
2397 Whether to include the .hg_archival.txt file containing meta
2399 data (hashes for the repository base and for tip) in archives
2400 created by the hg archive command or downloaded via hgweb.
2401 (default: True)
2402 askusername
2404 Whether to prompt for a username when committing. If True, and
2406 neither $HGUSER nor $EMAIL has been specified, then the user
2407 will be prompted to enter a username. If no username is entered,
2408 the default USER@HOST is used instead. (default: False)
2409 clonebundles
2411 Whether the "clone bundles" feature is enabled.
2413 When enabled, hg clone may download and apply a server-adver‐
2415 tised bundle file from a URL instead of using the normal
2416 exchange mechanism.
2417 This can likely result in faster and more reliable clones.
2419 (default: True)
2421 clonebundlefallback
2423 Whether failure to apply an advertised "clone bundle" from a
2425 server should result in fallback to a regular clone.
2426 This is disabled by default because servers advertising "clone
2428 bundles" often do so to reduce server load. If advertised bun‐
2429 dles start mass failing and clients automatically fall back to a
2430 regular clone, this would add significant and unexpected load to
2431 the server since the server is expecting clone operations to be
2432 offloaded to pre-generated bundles. Failing fast (the default
2433 behavior) ensures clients don't overwhelm the server when "clone
2434 bundle" application fails.
2435 (default: False)
2437 clonebundleprefers
2439 Defines preferences for which "clone bundles" to use.
2441 Servers advertising "clone bundles" may advertise multiple
2443 available bundles. Each bundle may have different attributes,
2444 such as the bundle type and compression format. This option is
2445 used to prefer a particular bundle over another.
2446 The following keys are defined by Mercurial:
2448 BUNDLESPEC
2450 A bundle type specifier. These are strings passed to hg
2451 bundle -t. e.g. gzip-v2 or bzip2-v1.
2452 COMPRESSION
2454 The compression format of the bundle. e.g. gzip and
2455 bzip2.
2456 Server operators may define custom keys.
2458 Example values: COMPRESSION=bzip2, BUNDLESPEC=gzip-v2, COMPRES‐
2460 SION=gzip.
2461 By default, the first bundle advertised by the server is used.
2463 color
2465 When to colorize output. Possible value are Boolean ("yes" or
2467 "no"), or "debug", or "always". (default: "yes"). "yes" will use
2468 color whenever it seems possible. See hg help color for details.
2469 commitsubrepos
2471 Whether to commit modified subrepositories when committing the
2473 parent repository. If False and one subrepository has uncommit‐
2474 ted changes, abort the commit. (default: False)
2475 debug
2477 Print debugging information. (default: False)
2479 editor
2481 The editor to use during a commit. (default: $EDITOR or vi)
2483 fallbackencoding
2485 Encoding to try if it's not possible to decode the changelog
2487 using UTF-8. (default: ISO-8859-1)
2488 graphnodetemplate
2490 The template used to print changeset nodes in an ASCII revision
2492 graph. (default: {graphnode})
2493 ignore
2495 A file to read per-user ignore patterns from. This file should
2497 be in the same format as a repository-wide .hgignore file. File‐
2498 names are relative to the repository root. This option supports
2499 hook syntax, so if you want to specify multiple ignore files,
2500 you can do so by setting something like ignore.other = ~/.hgig‐
2501 nore2. For details of the ignore file format, see the hgig‐
2502 nore(5) man page.
2503 interactive
2505 Allow to prompt the user. (default: True)
2507 interface
2509 Select the default interface for interactive features (default:
2511 text). Possible values are 'text' and 'curses'.
2512 interface.chunkselector
2514 Select the interface for change recording (e.g. hg commit -i).
2516 Possible values are 'text' and 'curses'. This config overrides
2517 the interface specified by ui.interface.
2518 large-file-limit
2520 Largest file size that gives no memory use warning. Possible
2522 values are integers or 0 to disable the check. (default:
2523 10000000)
2524 logtemplate
2526 Template string for commands that print changesets.
2528 merge
2530 The conflict resolution program to use during a manual merge.
2532 For more information on merge tools see hg help merge-tools.
2533 For configuring merge tools see the [merge-tools] section.
2534 mergemarkers
2536 Sets the merge conflict marker label styling. The detailed style
2538 uses the mergemarkertemplate setting to style the labels. The
2539 basic style just uses 'local' and 'other' as the marker label.
2540 One of basic or detailed. (default: basic)
2541 mergemarkertemplate
2543 The template used to print the commit description next to each
2545 conflict marker during merge conflicts. See hg help templates
2546 for the template format.
2547 Defaults to showing the hash, tags, branches, bookmarks, author,
2549 and the first line of the commit description.
2550 If you use non-ASCII characters in names for tags, branches,
2552 bookmarks, authors, and/or commit descriptions, you must pay
2553 attention to encodings of managed files. At template expansion,
2554 non-ASCII characters use the encoding specified by the --encod‐
2555 ing global option, HGENCODING or other environment variables
2556 that govern your locale. If the encoding of the merge markers is
2557 different from the encoding of the merged files, serious prob‐
2558 lems may occur.
2559 Can be overridden per-merge-tool, see the [merge-tools] section.
2561 message-output
2563 Where to write status and error messages. (default: stdio)
2565 stderr
2567 Everything to stderr.
2569 stdio
2571 Status to stdout, and error to stderr.
2573 origbackuppath
2575 The path to a directory used to store generated .orig files. If
2577 the path is not a directory, one will be created. If set, files
2578 stored in this directory have the same name as the original file
2579 and do not have a .orig suffix.
2580 paginate
2582 Control the pagination of command output (default: True). See hg
2584 help pager for details.
2585 patch
2587 An optional external tool that hg import and some extensions
2589 will use for applying patches. By default Mercurial uses an
2590 internal patch utility. The external tool must work as the com‐
2591 mon Unix patch program. In particular, it must accept a -p argu‐
2592 ment to strip patch headers, a -d argument to specify the cur‐
2593 rent directory, a file name to patch, and a patch file to take
2594 from stdin.
2595 It is possible to specify a patch tool together with extra argu‐
2597 ments. For example, setting this option to patch --merge will
2598 use the patch program with its 2-way merge option.
2599 portablefilenames
2601 Check for portable filenames. Can be warn, ignore or abort.
2603 (default: warn)
2604 warn
2606 Print a warning message on POSIX platforms, if a file
2608 with a non-portable filename is added (e.g. a file with a
2609 name that can't be created on Windows because it contains
2610 reserved parts like AUX, reserved characters like :, or
2611 would cause a case collision with an existing file).
2612 ignore
2614 Don't print a warning.
2616 abort
2618 The command is aborted.
2620 true
2622 Alias for warn.
2624 false
2626 Alias for ignore.
2628 On Windows, this configuration option is ignored and the command
2630 aborted.
2631 pre-merge-tool-output-template
2633 A template that is printed before executing an external merge
2635 tool. This can be used to print out additional context that
2636 might be useful to have during the conflict resolution, such as
2637 the description of the various commits involved or book‐
2638 marks/tags.
2639 Additional information is available in the local`, ``base, and
2641 other dicts. For example: {local.label}, {base.name}, or
2642 {other.islink}.
2643 quiet
2645 Reduce the amount of output printed. (default: False)
2647 relative-paths
2649 Prefer relative paths in the UI.
2651 remotecmd
2653 Remote command to use for clone/push/pull operations. (default:
2655 hg)
2656 report_untrusted
2658 Warn if a .hg/hgrc file is ignored due to not being owned by a
2660 trusted user or group. (default: True)
2661 slash
2663 (Deprecated. Use slashpath template filter instead.)
2665 Display paths using a slash (/) as the path separator. This only
2667 makes a difference on systems where the default path separator
2668 is not the slash character (e.g. Windows uses the backslash
2669 character (\)). (default: False)
2670 statuscopies
2672 Display copies in the status command.
2674 ssh
2676 Command to use for SSH connections. (default: ssh)
2678 ssherrorhint
2680 A hint shown to the user in the case of SSH error (e.g. Please
2682 see http://company/internalwiki/ssh.html)
2683 strict
2685 Require exact command names, instead of allowing unambiguous
2687 abbreviations. (default: False)
2688 style
2690 Name of style to use for command output.
2692 supportcontact
2694 A URL where users should report a Mercurial traceback. Use this
2696 if you are a large organisation with its own Mercurial deploy‐
2697 ment process and crash reports should be addressed to your
2698 internal support.
2699 textwidth
2701 Maximum width of help text. A longer line generated by hg help
2703 or hg subcommand --help will be broken after white space to get
2704 this width or the terminal width, whichever comes first. A
2705 non-positive value will disable this and the terminal width will
2706 be used. (default: 78)
2707 timeout
2709 The timeout used when a lock is held (in seconds), a negative
2711 value means no timeout. (default: 600)
2712 timeout.warn
2714 Time (in seconds) before a warning is printed about held lock. A
2716 negative value means no warning. (default: 0)
2717 traceback
2719 Mercurial always prints a traceback when an unknown exception
2721 occurs. Setting this to True will make Mercurial print a trace‐
2722 back on all exceptions, even those recognized by Mercurial (such
2723 as IOError or MemoryError). (default: False)
2724 tweakdefaults
2726 By default Mercurial's behavior changes very little from release to
2728 release, but over time the recommended config settings shift. Enable
2729 this config to opt in to get automatic tweaks to Mercurial's behav‐
2730 ior over time. This config setting will have no effect if HGPLAIN is
2731 set or HGPLAINEXCEPT is set and does not include tweakdefaults.
2732 (default: False)
2733 It currently means:
2735 [ui]
2737 # The rollback command is dangerous. As a rule, don't use it.
2738 rollback = False
2739 # Make `hg status` report copy information
2740 statuscopies = yes
2741 # Prefer curses UIs when available. Revert to plain-text with `text`.
2742 interface = curses
2743 # Make compatible commands emit cwd-relative paths by default.
2744 relative-paths = yes
2745 [commands]
2747 # Grep working directory by default.
2748 grep.all-files = True
2749 # Refuse to perform an `hg update` that would cause a file content merge
2750 update.check = noconflict
2751 # Show conflicts information in `hg status`
2752 status.verbose = True
2753 # Make `hg resolve` with no action (like `-m`) fail instead of re-merging.
2754 resolve.explicit-re-merge = True
2755 [diff]
2757 git = 1
2758 showfunc = 1
2759 word-diff = 1
2760 username
2762 The committer of a changeset created when running "commit".
2764 Typically a person's name and email address, e.g. Fred Widget
2765 <fred@example.com>. Environment variables in the username are
2766 expanded.
2767 (default: $EMAIL or username@hostname. If the username in hgrc
2769 is empty, e.g. if the system admin set username = in the system
2770 hgrc, it has to be specified manually or in a different hgrc
2771 file)
2772 verbose
2774 Increase the amount of output printed. (default: False)
2776 web
2778 Web interface configuration. The settings in this section apply to both
2779 the builtin webserver (started by hg serve) and the script you run
2780 through a webserver (hgweb.cgi and the derivatives for FastCGI and
2781 WSGI).
2782 The Mercurial webserver does no authentication (it does not prompt for
2784 usernames and passwords to validate who users are), but it does do
2785 authorization (it grants or denies access for authenticated users based
2786 on settings in this section). You must either configure your webserver
2787 to do authentication for you, or disable the authorization checks.
2788 For a quick setup in a trusted environment, e.g., a private LAN, where
2790 you want it to accept pushes from anybody, you can use the following
2791 command line:
2792 $ hg --config web.allow-push=* --config web.push_ssl=False serve
2794 Note that this will allow anybody to push anything to the server and
2796 that this should not be used for public servers.
2797 The full set of options is:
2799 accesslog
2801 Where to output the access log. (default: stdout)
2803 address
2805 Interface address to bind to. (default: all)
2807 allow-archive
2809 List of archive format (bz2, gz, zip) allowed for downloading.
2811 (default: empty)
2812 allowbz2
2814 (DEPRECATED) Whether to allow .tar.bz2 downloading of repository
2816 revisions. (default: False)
2817 allowgz
2819 (DEPRECATED) Whether to allow .tar.gz downloading of repository
2821 revisions. (default: False)
2822 allow-pull
2824 Whether to allow pulling from the repository. (default: True)
2826 allow-push
2828 Whether to allow pushing to the repository. If empty or not set,
2830 pushing is not allowed. If the special value *, any remote user
2831 can push, including unauthenticated users. Otherwise, the remote
2832 user must have been authenticated, and the authenticated user
2833 name must be present in this list. The contents of the
2834 allow-push list are examined after the deny_push list.
2835 allow_read
2837 If the user has not already been denied repository access due to
2839 the contents of deny_read, this list determines whether to grant
2840 repository access to the user. If this list is not empty, and
2841 the user is unauthenticated or not present in the list, then
2842 access is denied for the user. If the list is empty or not set,
2843 then access is permitted to all users by default. Setting
2844 allow_read to the special value * is equivalent to it not being
2845 set (i.e. access is permitted to all users). The contents of the
2846 allow_read list are examined after the deny_read list.
2847 allowzip
2849 (DEPRECATED) Whether to allow .zip downloading of repository
2851 revisions. This feature creates temporary files. (default:
2852 False)
2853 archivesubrepos
2855 Whether to recurse into subrepositories when archiving.
2857 (default: False)
2858 baseurl
2860 Base URL to use when publishing URLs in other locations, so
2862 third-party tools like email notification hooks can construct
2863 URLs. Example: http://hgserver/repos/.
2864 cacerts
2866 Path to file containing a list of PEM encoded certificate
2868 authority certificates. Environment variables and ~user con‐
2869 structs are expanded in the filename. If specified on the
2870 client, then it will verify the identity of remote HTTPS servers
2871 with these certificates.
2872 To disable SSL verification temporarily, specify --insecure from
2874 command line.
2875 You can use OpenSSL's CA certificate file if your platform has
2877 one. On most Linux systems this will be /etc/ssl/certs/ca-cer‐
2878 tificates.crt. Otherwise you will have to generate this file
2879 manually. The form must be as follows:
2880 -----BEGIN CERTIFICATE-----
2882 ... (certificate in base64 PEM encoding) ...
2883 -----END CERTIFICATE-----
2884 -----BEGIN CERTIFICATE-----
2885 ... (certificate in base64 PEM encoding) ...
2886 -----END CERTIFICATE-----
2887 cache
2889 Whether to support caching in hgweb. (default: True)
2891 certificate
2893 Certificate to use when running hg serve.
2895 collapse
2897 With descend enabled, repositories in subdirectories are shown
2899 at a single level alongside repositories in the current path.
2900 With collapse also enabled, repositories residing at a deeper
2901 level than the current path are grouped behind navigable direc‐
2902 tory entries that lead to the locations of these repositories.
2903 In effect, this setting collapses each collection of reposito‐
2904 ries found within a subdirectory into a single entry for that
2905 subdirectory. (default: False)
2906 comparisoncontext
2908 Number of lines of context to show in side-by-side file compari‐
2910 son. If negative or the value full, whole files are shown.
2911 (default: 5)
2912 This setting can be overridden by a context request parameter to
2914 the comparison command, taking the same values.
2915 contact
2917 Name or email address of the person in charge of the repository.
2919 (default: ui.username or $EMAIL or "unknown" if unset or empty)
2920 csp
2922 Send a Content-Security-Policy HTTP header with this value.
2924 The value may contain a special string %nonce%, which will be
2926 replaced by a randomly-generated one-time use value. If the
2927 value contains %nonce%, web.cache will be disabled, as caching
2928 undermines the one-time property of the nonce. This nonce will
2929 also be inserted into <script> elements containing inline
2930 JavaScript.
2931 Note: lots of HTML content sent by the server is derived from
2933 repository data. Please consider the potential for malicious
2934 repository data to "inject" itself into generated HTML content
2935 as part of your security threat model.
2936 deny_push
2938 Whether to deny pushing to the repository. If empty or not set,
2940 push is not denied. If the special value *, all remote users are
2941 denied push. Otherwise, unauthenticated users are all denied,
2942 and any authenticated user name present in this list is also
2943 denied. The contents of the deny_push list are examined before
2944 the allow-push list.
2945 deny_read
2947 Whether to deny reading/viewing of the repository. If this list
2949 is not empty, unauthenticated users are all denied, and any
2950 authenticated user name present in this list is also denied
2951 access to the repository. If set to the special value *, all
2952 remote users are denied access (rarely needed ;). If deny_read
2953 is empty or not set, the determination of repository access
2954 depends on the presence and content of the allow_read list (see
2955 description). If both deny_read and allow_read are empty or not
2956 set, then access is permitted to all users by default. If the
2957 repository is being served via hgwebdir, denied users will not
2958 be able to see it in the list of repositories. The contents of
2959 the deny_read list have priority over (are examined before) the
2960 contents of the allow_read list.
2961 descend
2963 hgwebdir indexes will not descend into subdirectories. Only
2965 repositories directly in the current path will be shown (other
2966 repositories are still available from the index corresponding to
2967 their containing path).
2968 description
2970 Textual description of the repository's purpose or contents.
2972 (default: "unknown")
2973 encoding
2975 Character encoding name. (default: the current locale charset)
2977 Example: "UTF-8".
2978 errorlog
2980 Where to output the error log. (default: stderr)
2982 guessmime
2984 Control MIME types for raw download of file content. Set to
2986 True to let hgweb guess the content type from the file exten‐
2987 sion. This will serve HTML files as text/html and might allow
2988 cross-site scripting attacks when serving untrusted reposito‐
2989 ries. (default: False)
2990 hidden
2992 Whether to hide the repository in the hgwebdir index. (default:
2994 False)
2995 ipv6
2997 Whether to use IPv6. (default: False)
2999 labels
3001 List of string labels associated with the repository.
3003 Labels are exposed as a template keyword and can be used to cus‐
3005 tomize output. e.g. the index template can group or filter
3006 repositories by labels and the summary template can display
3007 additional content if a specific label is present.
3008 logoimg
3010 File name of the logo image that some templates display on each
3012 page. The file name is relative to staticurl. That is, the full
3013 path to the logo image is "staticurl/logoimg". If unset, hgl‐
3014 ogo.png will be used.
3015 logourl
3017 Base URL to use for logos. If unset, https://mercurial-scm.org/
3019 will be used.
3020 maxchanges
3022 Maximum number of changes to list on the changelog. (default:
3024 10)
3025 maxfiles
3027 Maximum number of files to list per changeset. (default: 10)
3029 maxshortchanges
3031 Maximum number of changes to list on the shortlog, graph or
3033 filelog pages. (default: 60)
3034 name
3036 Repository name to use in the web interface. (default: current
3038 working directory)
3039 port
3041 Port to listen on. (default: 8000)
3043 prefix
3045 Prefix path to serve from. (default: '' (server root))
3047 push_ssl
3049 Whether to require that inbound pushes be transported over SSL
3051 to prevent password sniffing. (default: True)
3052 refreshinterval
3054 How frequently directory listings re-scan the filesystem for new
3056 repositories, in seconds. This is relevant when wildcards are
3057 used to define paths. Depending on how much filesystem traversal
3058 is required, refreshing may negatively impact performance.
3059 Values less than or equal to 0 always refresh. (default: 20)
3061 server-header
3063 Value for HTTP Server response header.
3065 static
3067 Directory where static files are served from.
3069 staticurl
3071 Base URL to use for static files. If unset, static files (e.g.
3073 the hgicon.png favicon) will be served by the CGI script itself.
3074 Use this setting to serve them directly with the HTTP server.
3075 Example: http://hgserver/static/.
3076 stripes
3078 How many lines a "zebra stripe" should span in multi-line out‐
3080 put. Set to 0 to disable. (default: 1)
3081 style
3083 Which template map style to use. The available options are the
3085 names of subdirectories in the HTML templates path. (default:
3086 paper) Example: monoblue.
3087 templates
3089 Where to find the HTML templates. The default path to the HTML
3091 templates can be obtained from hg debuginstall.
3092 websub
3094 Web substitution filter definition. You can use this section to define
3095 a set of regular expression substitution patterns which let you auto‐
3096 matically modify the hgweb server output.
3097 The default hgweb templates only apply these substitution patterns on
3099 the revision description fields. You can apply them anywhere you want
3100 when you create your own templates by adding calls to the "websub" fil‐
3101 ter (usually after calling the "escape" filter).
3102 This can be used, for example, to convert issue references to links to
3104 your issue tracker, or to convert "markdown-like" syntax into HTML (see
3105 the examples below).
3106 Each entry in this section names a substitution filter. The value of
3108 each entry defines the substitution expression itself. The websub
3109 expressions follow the old interhg extension syntax, which in turn imi‐
3110 tates the Unix sed replacement syntax:
3111 patternname = s/SEARCH_REGEX/REPLACE_EXPRESSION/[i]
3113 You can use any separator other than "/". The final "i" is optional and
3115 indicates that the search must be case insensitive.
3116 Examples:
3118 [websub]
3120 issues = s|issue(\d+)|<a href="http://bts.example.org/issue\1">issue\1</a>|i
3121 italic = s/\b_(\S+)_\b/<i>\1<\/i>/
3122 bold = s/\*\b(\S+)\b\*/<b>\1<\/b>/
3123 worker
3125 Parallel master/worker configuration. We currently perform working
3126 directory updates in parallel on Unix-like systems, which greatly helps
3127 performance.
3128 enabled
3130 Whether to enable workers code to be used. (default: true)
3132 numcpus
3134 Number of CPUs to use for parallel operations. A zero or nega‐
3136 tive value is treated as use the default. (default: 4 or the
3137 number of CPUs on the system, whichever is larger)
3138 backgroundclose
3140 Whether to enable closing file handles on background threads
3142 during certain operations. Some platforms aren't very efficient
3143 at closing file handles that have been written or appended to.
3144 By performing file closing on background threads, file write
3145 rate can increase substantially. (default: true on Windows,
3146 false elsewhere)
3147 backgroundcloseminfilecount
3149 Minimum number of files required to trigger background file
3151 closing. Operations not writing this many files won't start
3152 background close threads. (default: 2048)
3153 backgroundclosemaxqueue
3155 The maximum number of opened file handles waiting to be closed
3157 in the background. This option only has an effect if background‐
3158 close is enabled. (default: 384)
3159 backgroundclosethreadcount
3161 Number of threads to process background file closes. Only rele‐
3163 vant if backgroundclose is enabled. (default: 4)
3164
3166 Bryan O'Sullivan <bos@serpentine.com>.
3167 Mercurial was written by Matt Mackall <mpm@selenic.com>.
3169
3171 hg(1), hgignore(5)
3172
3174 This manual page is copyright 2005 Bryan O'Sullivan. Mercurial is
3175 copyright 2005-2020 Matt Mackall. Free use of this software is granted
3176 under the terms of the GNU General Public License version 2 or any
3177 later version.
3178
3180 Bryan O'Sullivan <bos@serpentine.com>
3181 Organization: Mercurial
3183 HGRC(5)