1HGRC(5) Mercurial Manual HGRC(5)
2
6 hgrc - configuration files for Mercurial
7
9 The Mercurial system uses a set of configuration files to control
10 aspects of its behavior.
11
13 If you're having problems with your configuration, hg config --debug
14 can help you understand what is introducing a setting into your envi‐
15 ronment.
16 See hg help config.syntax and hg help config.files for information
18 about how and where to override things.
19
21 The configuration files use a simple ini-file format. A configuration
22 file consists of sections, led by a [section] header and followed by
23 name = value entries:
24 [ui]
26 username = Firstname Lastname <firstname.lastname@example.net>
27 verbose = True
28 The above entries will be referred to as ui.username and ui.verbose,
30 respectively. See hg help config.syntax.
31
33 Mercurial reads configuration data from several files, if they exist.
34 These files do not exist by default and you will have to create the
35 appropriate configuration files yourself:
36 Local configuration is put into the per-repository <repo>/.hg/hgrc
38 file.
39 Global configuration like the username setting is typically put into:
41 · %USERPROFILE%\mercurial.ini (on Windows)
43 · $HOME/.hgrc (on Unix, Plan9)
45 The names of these files depend on the system on which Mercurial is
47 installed. *.rc files from a single directory are read in alphabetical
48 order, later ones overriding earlier ones. Where multiple paths are
49 given below, settings from earlier paths override later ones.
50 On Unix, the following files are consulted:
52 · <repo>/.hg/hgrc (per-repository)
54 · $HOME/.hgrc (per-user)
56 · ${XDG_CONFIG_HOME:-$HOME/.config}/hg/hgrc (per-user)
58 · <install-root>/etc/mercurial/hgrc (per-installation)
60 · <install-root>/etc/mercurial/hgrc.d/*.rc (per-installation)
62 · /etc/mercurial/hgrc (per-system)
64 · /etc/mercurial/hgrc.d/*.rc (per-system)
66 · <internal>/default.d/*.rc (defaults)
68 On Windows, the following files are consulted:
70 · <repo>/.hg/hgrc (per-repository)
72 · %USERPROFILE%\.hgrc (per-user)
74 · %USERPROFILE%\Mercurial.ini (per-user)
76 · %HOME%\.hgrc (per-user)
78 · %HOME%\Mercurial.ini (per-user)
80 · HKEY_LOCAL_MACHINE\SOFTWARE\Mercurial (per-installation)
82 · <install-dir>\hgrc.d\*.rc (per-installation)
84 · <install-dir>\Mercurial.ini (per-installation)
86 · <internal>/default.d/*.rc (defaults)
88 Note The registry key HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Mercu‐
90 rial is used when running 32-bit Python on 64-bit Windows.
91 On Windows 9x, %HOME% is replaced by %APPDATA%.
93 On Plan9, the following files are consulted:
95 · <repo>/.hg/hgrc (per-repository)
97 · $home/lib/hgrc (per-user)
99 · <install-root>/lib/mercurial/hgrc (per-installation)
101 · <install-root>/lib/mercurial/hgrc.d/*.rc (per-installation)
103 · /lib/mercurial/hgrc (per-system)
105 · /lib/mercurial/hgrc.d/*.rc (per-system)
107 · <internal>/default.d/*.rc (defaults)
109 Per-repository configuration options only apply in a particular reposi‐
111 tory. This file is not version-controlled, and will not get transferred
112 during a "clone" operation. Options in this file override options in
113 all other configuration files.
114 On Plan 9 and Unix, most of this file will be ignored if it doesn't
116 belong to a trusted user or to a trusted group. See hg help con‐
117 fig.trusted for more details.
118 Per-user configuration file(s) are for the user running Mercurial.
120 Options in these files apply to all Mercurial commands executed by this
121 user in any directory. Options in these files override per-system and
122 per-installation options.
123 Per-installation configuration files are searched for in the directory
125 where Mercurial is installed. <install-root> is the parent directory of
126 the hg executable (or symlink) being run.
127 For example, if installed in /shared/tools/bin/hg, Mercurial will look
129 in /shared/tools/etc/mercurial/hgrc. Options in these files apply to
130 all Mercurial commands executed by any user in any directory.
131 Per-installation configuration files are for the system on which Mercu‐
133 rial is running. Options in these files apply to all Mercurial commands
134 executed by any user in any directory. Registry keys contain PATH-like
135 strings, every part of which must reference a Mercurial.ini file or be
136 a directory where *.rc files will be read. Mercurial checks each of
137 these locations in the specified order until one or more configuration
138 files are detected.
139 Per-system configuration files are for the system on which Mercurial is
141 running. Options in these files apply to all Mercurial commands exe‐
142 cuted by any user in any directory. Options in these files override
143 per-installation options.
144 Mercurial comes with some default configuration. The default configura‐
146 tion files are installed with Mercurial and will be overwritten on
147 upgrades. Default configuration files should never be edited by users
148 or administrators but can be overridden in other configuration files.
149 So far the directory only contains merge tool configuration but pack‐
150 agers can also put other default configuration there.
151
153 A configuration file consists of sections, led by a [section] header
154 and followed by name = value entries (sometimes called configuration
155 keys):
156 [spam]
158 eggs=ham
159 green=
160 eggs
161 Each line contains one entry. If the lines that follow are indented,
163 they are treated as continuations of that entry. Leading whitespace is
164 removed from values. Empty lines are skipped. Lines beginning with # or
165 ; are ignored and may be used to provide comments.
166 Configuration keys can be set multiple times, in which case Mercurial
168 will use the value that was configured last. As an example:
169 [spam]
171 eggs=large
172 ham=serrano
173 eggs=small
174 This would set the configuration key named eggs to small.
176 It is also possible to define a section multiple times. A section can
178 be redefined on the same and/or on different configuration files. For
179 example:
180 [foo]
182 eggs=large
183 ham=serrano
184 eggs=small
185 [bar]
187 eggs=ham
188 green=
189 eggs
190 [foo]
192 ham=prosciutto
193 eggs=medium
194 bread=toasted
195 This would set the eggs, ham, and bread configuration keys of the foo
197 section to medium, prosciutto, and toasted, respectively. As you can
198 see there only thing that matters is the last value that was set for
199 each of the configuration keys.
200 If a configuration key is set multiple times in different configuration
202 files the final value will depend on the order in which the different
203 configuration files are read, with settings from earlier paths overrid‐
204 ing later ones as described on the Files section above.
205 A line of the form %include file will include file into the current
207 configuration file. The inclusion is recursive, which means that
208 included files can include other files. Filenames are relative to the
209 configuration file in which the %include directive is found. Environ‐
210 ment variables and ~user constructs are expanded in file. This lets you
211 do something like:
212 %include ~/.hgrc.d/$HOST.rc
214 to include a different configuration file on each computer you use.
216 A line with %unset name will remove name from the current section, if
218 it has been set previously.
219 The values are either free-form text strings, lists of text strings, or
221 Boolean values. Boolean values can be set to true using any of "1",
222 "yes", "true", or "on" and to false using "0", "no", "false", or "off"
223 (all case insensitive).
224 List values are separated by whitespace or comma, except when values
226 are placed in double quotation marks:
227 allow_read = "John Doe, PhD", brian, betty
229 Quotation marks can be escaped by prefixing them with a backslash. Only
231 quotation marks at the beginning of a word is counted as a quotation
232 (e.g., foo"bar baz is the list of foo"bar and baz).
233
235 This section describes the different sections that may appear in a Mer‐
236 curial configuration file, the purpose of each section, its possible
237 keys, and their possible values.
238 alias
240 Defines command aliases.
241 Aliases allow you to define your own commands in terms of other com‐
243 mands (or aliases), optionally including arguments. Positional argu‐
244 ments in the form of $1, $2, etc. in the alias definition are expanded
245 by Mercurial before execution. Positional arguments not already used by
246 $N in the definition are put at the end of the command to be executed.
247 Alias definitions consist of lines of the form:
249 <alias> = <command> [<argument>]...
251 For example, this definition:
253 latest = log --limit 5
255 creates a new command latest that shows only the five most recent
257 changesets. You can define subsequent aliases using earlier ones:
258 stable5 = latest -b stable
260 Note It is possible to create aliases with the same names as existing
262 commands, which will then override the original definitions.
263 This is almost always a bad idea!
264 An alias can start with an exclamation point (!) to make it a shell
266 alias. A shell alias is executed with the shell and will let you run
267 arbitrary commands. As an example,
268 echo = !echo $@
270 will let you do hg echo foo to have foo printed in your terminal. A
272 better example might be:
273 purge = !$HG status --no-status --unknown -0 re: | xargs -0 rm -f
275 which will make hg purge delete all unknown files in the repository in
277 the same manner as the purge extension.
278 Positional arguments like $1, $2, etc. in the alias definition expand
280 to the command arguments. Unmatched arguments are removed. $0 expands
281 to the alias name and $@ expands to all arguments separated by a space.
282 "$@" (with quotes) expands to all arguments quoted individually and
283 separated by a space. These expansions happen before the command is
284 passed to the shell.
285 Shell aliases are executed in an environment where $HG expands to the
287 path of the Mercurial that was used to execute the alias. This is use‐
288 ful when you want to call further Mercurial commands in a shell alias,
289 as was done above for the purge alias. In addition, $HG_ARGS expands to
290 the arguments given to Mercurial. In the hg echo foo call above,
291 $HG_ARGS would expand to echo foo.
292 Note Some global configuration options such as -R are processed
294 before shell aliases and will thus not be passed to aliases.
295 annotate
297 Settings used when displaying file annotations. All values are Booleans
298 and default to False. See hg help config.diff for related options for
299 the diff command.
300 ignorews
302 Ignore white space when comparing lines.
304 ignorewseol
306 Ignore white space at the end of a line when comparing lines.
308 ignorewsamount
310 Ignore changes in the amount of white space.
312 ignoreblanklines
314 Ignore changes whose lines are all blank.
316 auth
318 Authentication credentials and other authentication-like configuration
319 for HTTP connections. This section allows you to store usernames and
320 passwords for use when logging into HTTP servers. See hg help con‐
321 fig.web if you want to configure who can login to your HTTP server.
322 The following options apply to all hosts.
324 cookiefile
326 Path to a file containing HTTP cookie lines. Cookies matching a
328 host will be sent automatically.
329 The file format uses the Mozilla cookies.txt format, which
331 defines cookies on their own lines. Each line contains 7 fields
332 delimited by the tab character (domain, is_domain_cookie, path,
333 is_secure, expires, name, value). For more info, do an Internet
334 search for "Netscape cookies.txt format."
335 Note: the cookies parser does not handle port numbers on
337 domains. You will need to remove ports from the domain for the
338 cookie to be recognized. This could result in a cookie being
339 disclosed to an unwanted server.
340 The cookies file is read-only.
342 Other options in this section are grouped by name and have the follow‐
344 ing format:
345 <name>.<argument> = <value>
347 where <name> is used to group arguments into authentication entries.
349 Example:
350 foo.prefix = hg.intevation.de/mercurial
352 foo.username = foo
353 foo.password = bar
354 foo.schemes = http https
355 bar.prefix = secure.example.org
357 bar.key = path/to/file.key
358 bar.cert = path/to/file.cert
359 bar.schemes = https
360 Supported arguments:
362 prefix
364 Either * or a URI prefix with or without the scheme part. The
366 authentication entry with the longest matching prefix is used
367 (where * matches everything and counts as a match of length 1).
368 If the prefix doesn't include a scheme, the match is performed
369 against the URI with its scheme stripped as well, and the
370 schemes argument, q.v., is then subsequently consulted.
371 username
373 Optional. Username to authenticate with. If not given, and the
375 remote site requires basic or digest authentication, the user
376 will be prompted for it. Environment variables are expanded in
377 the username letting you do foo.username = $USER. If the URI
378 includes a username, only [auth] entries with a matching user‐
379 name or without a username will be considered.
380 password
382 Optional. Password to authenticate with. If not given, and the
384 remote site requires basic or digest authentication, the user
385 will be prompted for it.
386 key
388 Optional. PEM encoded client certificate key file. Environment
390 variables are expanded in the filename.
391 cert
393 Optional. PEM encoded client certificate chain file. Environment
395 variables are expanded in the filename.
396 schemes
398 Optional. Space separated list of URI schemes to use this
400 authentication entry with. Only used if the prefix doesn't
401 include a scheme. Supported schemes are http and https. They
402 will match static-http and static-https respectively, as well.
403 (default: https)
404 If no suitable authentication entry is found, the user is prompted for
406 credentials as usual if required by the remote.
407 color
409 Configure the Mercurial color mode. For details about how to define
410 your custom effect and style see hg help color.
411 mode
413 String: control the method used to output color. One of auto,
415 ansi, win32, terminfo or debug. In auto mode, Mercurial will use
416 ANSI mode by default (or win32 mode prior to Windows 10) if it
417 detects a terminal. Any invalid value will disable color.
418 pagermode
420 String: optional override of color.mode used with pager.
422 On some systems, terminfo mode may cause problems when using
424 color with less -R as a pager program. less with the -R option
425 will only display ECMA-48 color codes, and terminfo mode may
426 sometimes emit codes that less doesn't understand. You can work
427 around this by either using ansi mode (or auto mode), or by
428 using less -r (which will pass through all terminal control
429 codes, not just color control codes).
430 On some systems (such as MSYS in Windows), the terminal may sup‐
432 port a different color mode than the pager program.
433 commands
435 status.relative
436 Make paths in hg status output relative to the current direc‐
438 tory. (default: False)
439 update.check
441 Determines what level of checking hg update will perform before
443 moving to a destination revision. Valid values are abort, none,
444 linear, and noconflict. abort always fails if the working direc‐
445 tory has uncommitted changes. none performs no checking, and may
446 result in a merge with uncommitted changes. linear allows any
447 update as long as it follows a straight line in the revision
448 history, and may trigger a merge with uncommitted changes.
449 noconflict will allow any update which would not trigger a merge
450 with uncommitted changes, if any are present. (default: linear)
451 update.requiredest
453 Require that the user pass a destination when running hg update.
455 For example, hg update .:: will be allowed, but a plain hg
456 update will be disallowed. (default: False)
457 committemplate
459 changeset
460 String: configuration in this section is used as the template to
462 customize the text shown in the editor when committing.
463 In addition to pre-defined template keywords, commit log specific one
465 below can be used for customization:
466 extramsg
468 String: Extra message (typically 'Leave message empty to abort
470 commit.'). This may be changed by some commands or extensions.
471 For example, the template configuration below shows as same text as one
473 shown by default:
474 [committemplate]
476 changeset = {desc}\n\n
477 HG: Enter commit message. Lines beginning with 'HG:' are removed.
478 HG: {extramsg}
479 HG: --
480 HG: user: {author}\n{ifeq(p2rev, "-1", "",
481 "HG: branch merge\n")
482 }HG: branch '{branch}'\n{if(activebookmark,
483 "HG: bookmark '{activebookmark}'\n") }{subrepos %
484 "HG: subrepo {subrepo}\n" }{file_adds %
485 "HG: added {file}\n" }{file_mods %
486 "HG: changed {file}\n" }{file_dels %
487 "HG: removed {file}\n" }{if(files, "",
488 "HG: no files changed\n")}
489 diff()
491 String: show the diff (see hg help templates for detail)
493 Sometimes it is helpful to show the diff of the changeset in the editor
495 without having to prefix 'HG: ' to each line so that highlighting works
496 correctly. For this, Mercurial provides a special string which will
497 ignore everything below it:
498 HG: ------------------------ >8 ------------------------
500 For example, the template configuration below will show the diff below
502 the extra message:
503 [committemplate]
505 changeset = {desc}\n\n
506 HG: Enter commit message. Lines beginning with 'HG:' are removed.
507 HG: {extramsg}
508 HG: ------------------------ >8 ------------------------
509 HG: Do not touch the line above.
510 HG: Everything below will be removed.
511 {diff()}
512 Note For some problematic encodings (see hg help win32mbcs for
514 detail), this customization should be configured carefully, to
515 avoid showing broken characters.
516 For example, if a multibyte character ending with backslash
518 (0x5c) is followed by the ASCII character 'n' in the customized
519 template, the sequence of backslash and 'n' is treated as
520 line-feed unexpectedly (and the multibyte character is broken,
521 too).
522 Customized template is used for commands below (--edit may be
524 required):
525 · hg backout
527 · hg commit
529 · hg fetch (for merge commit only)
531 · hg graft
533 · hg histedit
535 · hg import
537 · hg qfold, hg qnew and hg qrefresh
539 · hg rebase
541 · hg shelve
543 · hg sign
545 · hg tag
547 · hg transplant
549 Configuring items below instead of changeset allows showing customized
551 message only for specific actions, or showing different messages for
552 each action.
553 · changeset.backout for hg backout
555 · changeset.commit.amend.merge for hg commit --amend on merges
557 · changeset.commit.amend.normal for hg commit --amend on other
559 · changeset.commit.normal.merge for hg commit on merges
561 · changeset.commit.normal.normal for hg commit on other
563 · changeset.fetch for hg fetch (impling merge commit)
565 · changeset.gpg.sign for hg sign
567 · changeset.graft for hg graft
569 · changeset.histedit.edit for edit of hg histedit
571 · changeset.histedit.fold for fold of hg histedit
573 · changeset.histedit.mess for mess of hg histedit
575 · changeset.histedit.pick for pick of hg histedit
577 · changeset.import.bypass for hg import --bypass
579 · changeset.import.normal.merge for hg import on merges
581 · changeset.import.normal.normal for hg import on other
583 · changeset.mq.qnew for hg qnew
585 · changeset.mq.qfold for hg qfold
587 · changeset.mq.qrefresh for hg qrefresh
589 · changeset.rebase.collapse for hg rebase --collapse
591 · changeset.rebase.merge for hg rebase on merges
593 · changeset.rebase.normal for hg rebase on other
595 · changeset.shelve.shelve for hg shelve
597 · changeset.tag.add for hg tag without --remove
599 · changeset.tag.remove for hg tag --remove
601 · changeset.transplant.merge for hg transplant on merges
603 · changeset.transplant.normal for hg transplant on other
605 These dot-separated lists of names are treated as hierarchical ones.
607 For example, changeset.tag.remove customizes the commit message only
608 for hg tag --remove, but changeset.tag customizes the commit message
609 for hg tag regardless of --remove option.
610 When the external editor is invoked for a commit, the corresponding
612 dot-separated list of names without the changeset. prefix (e.g. com‐
613 mit.normal.normal) is in the HGEDITFORM environment variable.
614 In this section, items other than changeset can be referred from oth‐
616 ers. For example, the configuration to list committed files up below
617 can be referred as {listupfiles}:
618 [committemplate]
620 listupfiles = {file_adds %
621 "HG: added {file}\n" }{file_mods %
622 "HG: changed {file}\n" }{file_dels %
623 "HG: removed {file}\n" }{if(files, "",
624 "HG: no files changed\n")}
625 decode/encode
627 Filters for transforming files on checkout/checkin. This would typi‐
628 cally be used for newline processing or other localization/canonical‐
629 ization of files.
630 Filters consist of a filter pattern followed by a filter command. Fil‐
632 ter patterns are globs by default, rooted at the repository root. For
633 example, to match any file ending in .txt in the root directory only,
634 use the pattern *.txt. To match any file ending in .c anywhere in the
635 repository, use the pattern **.c. For each file only the first match‐
636 ing filter applies.
637 The filter command can start with a specifier, either pipe: or temp‐
639 file:. If no specifier is given, pipe: is used by default.
640 A pipe: command must accept data on stdin and return the transformed
642 data on stdout.
643 Pipe example:
645 [encode]
647 # uncompress gzip files on checkin to improve delta compression
648 # note: not necessarily a good idea, just an example
649 *.gz = pipe: gunzip
650 [decode]
652 # recompress gzip files when writing them to the working dir (we
653 # can safely omit "pipe:", because it's the default)
654 *.gz = gzip
655 A tempfile: command is a template. The string INFILE is replaced with
657 the name of a temporary file that contains the data to be filtered by
658 the command. The string OUTFILE is replaced with the name of an empty
659 temporary file, where the filtered data must be written by the command.
660 Note The tempfile mechanism is recommended for Windows systems, where
662 the standard shell I/O redirection operators often have strange
663 effects and may corrupt the contents of your files.
664 This filter mechanism is used internally by the eol extension to trans‐
666 late line ending characters between Windows (CRLF) and Unix (LF) for‐
667 mat. We suggest you use the eol extension for convenience.
668 defaults
670 (defaults are deprecated. Don't use them. Use aliases instead.)
671 Use the [defaults] section to define command defaults, i.e. the default
673 options/arguments to pass to the specified commands.
674 The following example makes hg log run in verbose mode, and hg status
676 show only the modified files, by default:
677 [defaults]
679 log = -v
680 status = -m
681 The actual commands, instead of their aliases, must be used when defin‐
683 ing command defaults. The command defaults will also be applied to the
684 aliases of the commands defined.
685 diff
687 Settings used when displaying diffs. Everything except for unified is a
688 Boolean and defaults to False. See hg help config.annotate for related
689 options for the annotate command.
690 git
692 Use git extended diff format.
694 nobinary
696 Omit git binary patches.
698 nodates
700 Don't include dates in diff headers.
702 noprefix
704 Omit 'a/' and 'b/' prefixes from filenames. Ignored in plain
706 mode.
707 showfunc
709 Show which function each change is in.
711 ignorews
713 Ignore white space when comparing lines.
715 ignorewsamount
717 Ignore changes in the amount of white space.
719 ignoreblanklines
721 Ignore changes whose lines are all blank.
723 unified
725 Number of lines of context to show.
727 email
729 Settings for extensions that send email messages.
730 from
732 Optional. Email address to use in "From" header and SMTP enve‐
734 lope of outgoing messages.
735 to
737 Optional. Comma-separated list of recipients' email addresses.
739 cc
741 Optional. Comma-separated list of carbon copy recipients' email
743 addresses.
744 bcc
746 Optional. Comma-separated list of blind carbon copy recipients'
748 email addresses.
749 method
751 Optional. Method to use to send email messages. If value is smtp
753 (default), use SMTP (see the [smtp] section for configuration).
754 Otherwise, use as name of program to run that acts like sendmail
755 (takes -f option for sender, list of recipients on command line,
756 message on stdin). Normally, setting this to sendmail or
757 /usr/sbin/sendmail is enough to use sendmail to send messages.
758 charsets
760 Optional. Comma-separated list of character sets considered con‐
762 venient for recipients. Addresses, headers, and parts not con‐
763 taining patches of outgoing messages will be encoded in the
764 first character set to which conversion from local encoding
765 ($HGENCODING, ui.fallbackencoding) succeeds. If correct conver‐
766 sion fails, the text in question is sent as is. (default: '')
767 Order of outgoing email character sets:
769 1. us-ascii: always first, regardless of settings
771 2. email.charsets: in order given by user
773 3. ui.fallbackencoding: if not in email.charsets
775 4. $HGENCODING: if not in email.charsets
777 5. utf-8: always last, regardless of settings
779 Email example:
781 [email]
783 from = Joseph User <joe.user@example.com>
784 method = /usr/sbin/sendmail
785 # charsets for western Europeans
786 # us-ascii, utf-8 omitted, as they are tried first and last
787 charsets = iso-8859-1, iso-8859-15, windows-1252
788 extensions
790 Mercurial has an extension mechanism for adding new features. To enable
791 an extension, create an entry for it in this section.
792 If you know that the extension is already in Python's search path, you
794 can give the name of the module, followed by =, with nothing after the
795 =.
796 Otherwise, give a name that you choose, followed by =, followed by the
798 path to the .py file (including the file name extension) that defines
799 the extension.
800 To explicitly disable an extension that is enabled in an hgrc of
802 broader scope, prepend its path with !, as in foo = !/ext/path or foo =
803 ! when path is not supplied.
804 Example for ~/.hgrc:
806 [extensions]
808 # (the churn extension will get loaded from Mercurial's path)
809 churn =
810 # (this extension will get loaded from the file specified)
811 myfeature = ~/.hgext/myfeature.py
812 format
814 usegeneraldelta
815 Enable or disable the "generaldelta" repository format which
817 improves repository compression by allowing "revlog" to store
818 delta against arbitrary revision instead of the previous stored
819 one. This provides significant improvement for repositories with
820 branches.
821 Repositories with this on-disk format require Mercurial version
823 1.9.
824 Enabled by default.
826 dotencode
828 Enable or disable the "dotencode" repository format which
830 enhances the "fncache" repository format (which has to be
831 enabled to use dotencode) to avoid issues with filenames start‐
832 ing with ._ on Mac OS X and spaces on Windows.
833 Repositories with this on-disk format require Mercurial version
835 1.7.
836 Enabled by default.
838 usefncache
840 Enable or disable the "fncache" repository format which enhances
842 the "store" repository format (which has to be enabled to use
843 fncache) to allow longer filenames and avoids using Windows
844 reserved names, e.g. "nul".
845 Repositories with this on-disk format require Mercurial version
847 1.1.
848 Enabled by default.
850 usestore
852 Enable or disable the "store" repository format which improves
854 compatibility with systems that fold case or otherwise mangle
855 filenames. Disabling this option will allow you to store longer
856 filenames in some situations at the expense of compatibility.
857 Repositories with this on-disk format require Mercurial version
859 0.9.4.
860 Enabled by default.
862 graph
864 Web graph view configuration. This section let you change graph ele‐
865 ments display properties by branches, for instance to make the default
866 branch stand out.
867 Each line has the following format:
869 <branch>.<argument> = <value>
871 where <branch> is the name of the branch being customized. Example:
873 [graph]
875 # 2px width
876 default.width = 2
877 # red color
878 default.color = FF0000
879 Supported arguments:
881 width
883 Set branch edges width in pixels.
885 color
887 Set branch edges color in hexadecimal RGB notation.
889 hooks
891 Commands or Python functions that get automatically executed by various
892 actions such as starting or finishing a commit. Multiple hooks can be
893 run for the same action by appending a suffix to the action. Overriding
894 a site-wide hook can be done by changing its value or setting it to an
895 empty string. Hooks can be prioritized by adding a prefix of priority.
896 to the hook name on a new line and setting the priority. The default
897 priority is 0.
898 Example .hg/hgrc:
900 [hooks]
902 # update working directory after adding changesets
903 changegroup.update = hg update
904 # do not use the site-wide hook
905 incoming =
906 incoming.email = /my/email/hook
907 incoming.autobuild = /my/build/hook
908 # force autobuild hook to run before other incoming hooks
909 priority.incoming.autobuild = 1
910 Most hooks are run with environment variables set that give useful
912 additional information. For each hook below, the environment variables
913 it is passed are listed with names in the form $HG_foo. The $HG_HOOK‐
914 TYPE and $HG_HOOKNAME variables are set for all hooks. They contain
915 the type of hook which triggered the run and the full name of the hook
916 in the config, respectively. In the example above, this will be
917 $HG_HOOKTYPE=incoming and $HG_HOOKNAME=incoming.email.
918 changegroup
920 Run after a changegroup has been added via push, pull or unbun‐
922 dle. The ID of the first new changeset is in $HG_NODE and last
923 is in $HG_NODE_LAST. The URL from which changes came is in
924 $HG_URL.
925 commit
927 Run after a changeset has been created in the local repository.
929 The ID of the newly created changeset is in $HG_NODE. Parent
930 changeset IDs are in $HG_PARENT1 and $HG_PARENT2.
931 incoming
933 Run after a changeset has been pulled, pushed, or unbundled into
935 the local repository. The ID of the newly arrived changeset is
936 in $HG_NODE. The URL that was source of the changes is in
937 $HG_URL.
938 outgoing
940 Run after sending changes from the local repository to another.
942 The ID of first changeset sent is in $HG_NODE. The source of
943 operation is in $HG_SOURCE. Also see hg help config.hooks.pre‐
944 outgoing.
945 post-<command>
947 Run after successful invocations of the associated command. The
949 contents of the command line are passed as $HG_ARGS and the
950 result code in $HG_RESULT. Parsed command line arguments are
951 passed as $HG_PATS and $HG_OPTS. These contain string represen‐
952 tations of the python data internally passed to <command>.
953 $HG_OPTS is a dictionary of options (with unspecified options
954 set to their defaults). $HG_PATS is a list of arguments. Hook
955 failure is ignored.
956 fail-<command>
958 Run after a failed invocation of an associated command. The con‐
960 tents of the command line are passed as $HG_ARGS. Parsed command
961 line arguments are passed as $HG_PATS and $HG_OPTS. These con‐
962 tain string representations of the python data internally passed
963 to <command>. $HG_OPTS is a dictionary of options (with unspeci‐
964 fied options set to their defaults). $HG_PATS is a list of argu‐
965 ments. Hook failure is ignored.
966 pre-<command>
968 Run before executing the associated command. The contents of the
970 command line are passed as $HG_ARGS. Parsed command line argu‐
971 ments are passed as $HG_PATS and $HG_OPTS. These contain string
972 representations of the data internally passed to <command>.
973 $HG_OPTS is a dictionary of options (with unspecified options
974 set to their defaults). $HG_PATS is a list of arguments. If the
975 hook returns failure, the command doesn't execute and Mercurial
976 returns the failure code.
977 prechangegroup
979 Run before a changegroup is added via push, pull or unbundle.
981 Exit status 0 allows the changegroup to proceed. A non-zero sta‐
982 tus will cause the push, pull or unbundle to fail. The URL from
983 which changes will come is in $HG_URL.
984 precommit
986 Run before starting a local commit. Exit status 0 allows the
988 commit to proceed. A non-zero status will cause the commit to
989 fail. Parent changeset IDs are in $HG_PARENT1 and $HG_PARENT2.
990 prelistkeys
992 Run before listing pushkeys (like bookmarks) in the repository.
994 A non-zero status will cause failure. The key namespace is in
995 $HG_NAMESPACE.
996 preoutgoing
998 Run before collecting changes to send from the local repository
1000 to another. A non-zero status will cause failure. This lets you
1001 prevent pull over HTTP or SSH. It can also prevent propagating
1002 commits (via local pull, push (outbound) or bundle commands),
1003 but not completely, since you can just copy files instead. The
1004 source of operation is in $HG_SOURCE. If "serve", the operation
1005 is happening on behalf of a remote SSH or HTTP repository. If
1006 "push", "pull" or "bundle", the operation is happening on behalf
1007 of a repository on same system.
1008 prepushkey
1010 Run before a pushkey (like a bookmark) is added to the reposi‐
1012 tory. A non-zero status will cause the key to be rejected. The
1013 key namespace is in $HG_NAMESPACE, the key is in $HG_KEY, the
1014 old value (if any) is in $HG_OLD, and the new value is in
1015 $HG_NEW.
1016 pretag
1018 Run before creating a tag. Exit status 0 allows the tag to be
1020 created. A non-zero status will cause the tag to fail. The ID of
1021 the changeset to tag is in $HG_NODE. The name of tag is in
1022 $HG_TAG. The tag is local if $HG_LOCAL=1, or in the repository
1023 if $HG_LOCAL=0.
1024 pretxnopen
1026 Run before any new repository transaction is open. The reason
1028 for the transaction will be in $HG_TXNNAME, and a unique identi‐
1029 fier for the transaction will be in HG_TXNID. A non-zero status
1030 will prevent the transaction from being opened.
1031 pretxnclose
1033 Run right before the transaction is actually finalized. Any
1035 repository change will be visible to the hook program. This lets
1036 you validate the transaction content or change it. Exit status 0
1037 allows the commit to proceed. A non-zero status will cause the
1038 transaction to be rolled back. The reason for the transaction
1039 opening will be in $HG_TXNNAME, and a unique identifier for the
1040 transaction will be in HG_TXNID. The rest of the available data
1041 will vary according the transaction type. New changesets will
1042 add $HG_NODE (the ID of the first added changeset),
1043 $HG_NODE_LAST (the ID of the last added changeset), $HG_URL and
1044 $HG_SOURCE variables. Bookmark and phase changes will set
1045 HG_BOOKMARK_MOVED and HG_PHASES_MOVED to 1 respectively, etc.
1046 pretxnclose-bookmark
1048 Run right before a bookmark change is actually finalized. Any
1050 repository change will be visible to the hook program. This lets
1051 you validate the transaction content or change it. Exit status 0
1052 allows the commit to proceed. A non-zero status will cause the
1053 transaction to be rolled back. The name of the bookmark will be
1054 available in $HG_BOOKMARK, the new bookmark location will be
1055 available in $HG_NODE while the previous location will be avail‐
1056 able in $HG_OLDNODE. In case of a bookmark creation $HG_OLDNODE
1057 will be empty. In case of deletion $HG_NODE will be empty. In
1058 addition, the reason for the transaction opening will be in
1059 $HG_TXNNAME, and a unique identifier for the transaction will be
1060 in HG_TXNID.
1061 pretxnclose-phase
1063 Run right before a phase change is actually finalized. Any
1065 repository change will be visible to the hook program. This lets
1066 you validate the transaction content or change it. Exit status 0
1067 allows the commit to proceed. A non-zero status will cause the
1068 transaction to be rolled back. The hook is called multiple
1069 times, once for each revision affected by a phase change. The
1070 affected node is available in $HG_NODE, the phase in $HG_PHASE
1071 while the previous $HG_OLDPHASE. In case of new node, $HG_OLD‐
1072 PHASE will be empty. In addition, the reason for the transac‐
1073 tion opening will be in $HG_TXNNAME, and a unique identifier for
1074 the transaction will be in HG_TXNID. The hook is also run for
1075 newly added revisions. In this case the $HG_OLDPHASE entry will
1076 be empty.
1077 txnclose
1079 Run after any repository transaction has been committed. At this
1081 point, the transaction can no longer be rolled back. The hook
1082 will run after the lock is released. See hg help con‐
1083 fig.hooks.pretxnclose for details about available variables.
1084 txnclose-bookmark
1086 Run after any bookmark change has been committed. At this point,
1088 the transaction can no longer be rolled back. The hook will run
1089 after the lock is released. See hg help config.hooks.pretxn‐
1090 close-bookmark for details about available variables.
1091 txnclose-phase
1093 Run after any phase change has been committed. At this point,
1095 the transaction can no longer be rolled back. The hook will run
1096 after the lock is released. See hg help config.hooks.pretxn‐
1097 close-phase for details about available variables.
1098 txnabort
1100 Run when a transaction is aborted. See hg help con‐
1102 fig.hooks.pretxnclose for details about available variables.
1103 pretxnchangegroup
1105 Run after a changegroup has been added via push, pull or unbun‐
1107 dle, but before the transaction has been committed. The change‐
1108 group is visible to the hook program. This allows validation of
1109 incoming changes before accepting them. The ID of the first new
1110 changeset is in $HG_NODE and last is in $HG_NODE_LAST. Exit sta‐
1111 tus 0 allows the transaction to commit. A non-zero status will
1112 cause the transaction to be rolled back, and the push, pull or
1113 unbundle will fail. The URL that was the source of changes is in
1114 $HG_URL.
1115 pretxncommit
1117 Run after a changeset has been created, but before the transac‐
1119 tion is committed. The changeset is visible to the hook program.
1120 This allows validation of the commit message and changes. Exit
1121 status 0 allows the commit to proceed. A non-zero status will
1122 cause the transaction to be rolled back. The ID of the new
1123 changeset is in $HG_NODE. The parent changeset IDs are in
1124 $HG_PARENT1 and $HG_PARENT2.
1125 preupdate
1127 Run before updating the working directory. Exit status 0 allows
1129 the update to proceed. A non-zero status will prevent the
1130 update. The changeset ID of first new parent is in $HG_PARENT1.
1131 If updating to a merge, the ID of second new parent is in
1132 $HG_PARENT2.
1133 listkeys
1135 Run after listing pushkeys (like bookmarks) in the repository.
1137 The key namespace is in $HG_NAMESPACE. $HG_VALUES is a dictio‐
1138 nary containing the keys and values.
1139 pushkey
1141 Run after a pushkey (like a bookmark) is added to the reposi‐
1143 tory. The key namespace is in $HG_NAMESPACE, the key is in
1144 $HG_KEY, the old value (if any) is in $HG_OLD, and the new value
1145 is in $HG_NEW.
1146 tag
1148 Run after a tag is created. The ID of the tagged changeset is in
1150 $HG_NODE. The name of tag is in $HG_TAG. The tag is local if
1151 $HG_LOCAL=1, or in the repository if $HG_LOCAL=0.
1152 update
1154 Run after updating the working directory. The changeset ID of
1156 first new parent is in $HG_PARENT1. If updating to a merge, the
1157 ID of second new parent is in $HG_PARENT2. If the update suc‐
1158 ceeded, $HG_ERROR=0. If the update failed (e.g. because con‐
1159 flicts were not resolved), $HG_ERROR=1.
1160 Note It is generally better to use standard hooks rather than the
1162 generic pre- and post- command hooks, as they are guaranteed to
1163 be called in the appropriate contexts for influencing transac‐
1164 tions. Also, hooks like "commit" will be called in all contexts
1165 that generate a commit (e.g. tag) and not just the commit com‐
1166 mand.
1167 Note Environment variables with empty values may not be passed to
1169 hooks on platforms such as Windows. As an example, $HG_PARENT2
1170 will have an empty value under Unix-like platforms for non-merge
1171 changesets, while it will not be available at all under Windows.
1172 The syntax for Python hooks is as follows:
1174 hookname = python:modulename.submodule.callable
1176 hookname = python:/path/to/python/module.py:callable
1177 Python hooks are run within the Mercurial process. Each hook is called
1179 with at least three keyword arguments: a ui object (keyword ui), a
1180 repository object (keyword repo), and a hooktype keyword that tells
1181 what kind of hook is used. Arguments listed as environment variables
1182 above are passed as keyword arguments, with no HG_ prefix, and names in
1183 lower case.
1184 If a Python hook returns a "true" value or raises an exception, this is
1186 treated as a failure.
1187 hostfingerprints
1189 (Deprecated. Use [hostsecurity]'s fingerprints options instead.)
1190 Fingerprints of the certificates of known HTTPS servers.
1192 A HTTPS connection to a server with a fingerprint configured here will
1194 only succeed if the servers certificate matches the fingerprint. This
1195 is very similar to how ssh known hosts works.
1196 The fingerprint is the SHA-1 hash value of the DER encoded certificate.
1198 Multiple values can be specified (separated by spaces or commas). This
1199 can be used to define both old and new fingerprints while a host tran‐
1200 sitions to a new certificate.
1201 The CA chain and web.cacerts is not used for servers with a finger‐
1203 print.
1204 For example:
1206 [hostfingerprints]
1208 hg.intevation.de = fc:e2:8d:d9:51:cd:cb:c1:4d:18:6b:b7:44:8d:49:72:57:e6:cd:33
1209 hg.intevation.org = fc:e2:8d:d9:51:cd:cb:c1:4d:18:6b:b7:44:8d:49:72:57:e6:cd:33
1210 hostsecurity
1212 Used to specify global and per-host security settings for connecting to
1213 other machines.
1214 The following options control default behavior for all hosts.
1216 ciphers
1218 Defines the cryptographic ciphers to use for connections.
1220 Value must be a valid OpenSSL Cipher List Format as documented
1222 at
1223 https://www.openssl.org/docs/manmaster/apps/ciphers.html#CIPHER-LIST-FORMAT
1224 .
1225 This setting is for advanced users only. Setting to incorrect
1227 values can significantly lower connection security or decrease
1228 performance. You have been warned.
1229 This option requires Python 2.7.
1231 minimumprotocol
1233 Defines the minimum channel encryption protocol to use.
1235 By default, the highest version of TLS supported by both client
1237 and server is used.
1238 Allowed values are: tls1.0, tls1.1, tls1.2.
1240 When running on an old Python version, only tls1.0 is allowed
1242 since old versions of Python only support up to TLS 1.0.
1243 When running a Python that supports modern TLS versions, the
1245 default is tls1.1. tls1.0 can still be used to allow TLS 1.0.
1246 However, this weakens security and should only be used as a fea‐
1247 ture of last resort if a server does not support TLS 1.1+.
1248 Options in the [hostsecurity] section can have the form hostname:set‐
1250 ting. This allows multiple settings to be defined on a per-host basis.
1251 The following per-host settings can be defined.
1253 ciphers
1255 This behaves like ciphers as described above except it only
1257 applies to the host on which it is defined.
1258 fingerprints
1260 A list of hashes of the DER encoded peer/remote certificate.
1262 Values have the form algorithm:fingerprint. e.g.
1263 sha256:c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2.
1264 In addition, colons (:) can appear in the fingerprint part.
1265 The following algorithms/prefixes are supported: sha1, sha256,
1267 sha512.
1268 Use of sha256 or sha512 is preferred.
1270 If a fingerprint is specified, the CA chain is not validated for
1272 this host and Mercurial will require the remote certificate to
1273 match one of the fingerprints specified. This means if the
1274 server updates its certificate, Mercurial will abort until a new
1275 fingerprint is defined. This can provide stronger security than
1276 traditional CA-based validation at the expense of convenience.
1277 This option takes precedence over verifycertsfile.
1279 minimumprotocol
1281 This behaves like minimumprotocol as described above except it
1283 only applies to the host on which it is defined.
1284 verifycertsfile
1286 Path to file a containing a list of PEM encoded certificates
1288 used to verify the server certificate. Environment variables and
1289 ~user constructs are expanded in the filename.
1290 The server certificate or the certificate's certificate author‐
1292 ity (CA) must match a certificate from this file or certificate
1293 verification will fail and connections to the server will be
1294 refused.
1295 If defined, only certificates provided by this file will be
1297 used: web.cacerts and any system/default certificates will not
1298 be used.
1299 This option has no effect if the per-host fingerprints option is
1301 set.
1302 The format of the file is as follows:
1304 -----BEGIN CERTIFICATE-----
1306 ... (certificate in base64 PEM encoding) ...
1307 -----END CERTIFICATE-----
1308 -----BEGIN CERTIFICATE-----
1309 ... (certificate in base64 PEM encoding) ...
1310 -----END CERTIFICATE-----
1311 For example:
1313 [hostsecurity]
1315 hg.example.com:fingerprints = sha256:c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2
1316 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
1317 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
1318 foo.example.com:verifycertsfile = /etc/ssl/trusted-ca-certs.pem
1319 To change the default minimum protocol version to TLS 1.2 but to allow
1321 TLS 1.1 when connecting to hg.example.com:
1322 [hostsecurity]
1324 minimumprotocol = tls1.2
1325 hg.example.com:minimumprotocol = tls1.1
1326 http_proxy
1328 Used to access web-based Mercurial repositories through a HTTP proxy.
1329 host
1331 Host name and (optional) port of the proxy server, for example
1333 "myproxy:8000".
1334 no
1336 Optional. Comma-separated list of host names that should bypass
1338 the proxy.
1339 passwd
1341 Optional. Password to authenticate with at the proxy server.
1343 user
1345 Optional. User name to authenticate with at the proxy server.
1347 always
1349 Optional. Always use the proxy, even for localhost and any
1351 entries in http_proxy.no. (default: False)
1352 merge
1354 This section specifies behavior during merges and updates.
1355 checkignored
1357 Controls behavior when an ignored file on disk has the same name
1359 as a tracked file in the changeset being merged or updated to,
1360 and has different contents. Options are abort, warn and ignore.
1361 With abort, abort on such files. With warn, warn on such files
1362 and back them up as .orig. With ignore, don't print a warning
1363 and back them up as .orig. (default: abort)
1364 checkunknown
1366 Controls behavior when an unknown file that isn't ignored has
1368 the same name as a tracked file in the changeset being merged or
1369 updated to, and has different contents. Similar to merge.check‐
1370 ignored, except for files that are not ignored. (default: abort)
1371 on-failure
1373 When set to continue (the default), the merge process attempts
1375 to merge all unresolved files using the merge chosen tool,
1376 regardless of whether previous file merge attempts during the
1377 process succeeded or not. Setting this to prompt will prompt
1378 after any merge failure continue or halt the merge process. Set‐
1379 ting this to halt will automatically halt the merge process on
1380 any merge tool failure. The merge process can be restarted by
1381 using the resolve command. When a merge is halted, the reposi‐
1382 tory is left in a normal unresolved merge state. (default: con‐
1383 tinue)
1384 merge-patterns
1386 This section specifies merge tools to associate with particular file
1387 patterns. Tools matched here will take precedence over the default
1388 merge tool. Patterns are globs by default, rooted at the repository
1389 root.
1390 Example:
1392 [merge-patterns]
1394 **.c = kdiff3
1395 **.jpg = myimgmerge
1396 merge-tools
1398 This section configures external merge tools to use for file-level
1399 merges. This section has likely been preconfigured at install time.
1400 Use hg config merge-tools to check the existing configuration. Also
1401 see hg help merge-tools for more details.
1402 Example ~/.hgrc:
1404 [merge-tools]
1406 # Override stock tool location
1407 kdiff3.executable = ~/bin/kdiff3
1408 # Specify command line
1409 kdiff3.args = $base $local $other -o $output
1410 # Give higher priority
1411 kdiff3.priority = 1
1412 # Changing the priority of preconfigured tool
1414 meld.priority = 0
1415 # Disable a preconfigured tool
1417 vimdiff.disabled = yes
1418 # Define new tool
1420 myHtmlTool.args = -m $local $other $base $output
1421 myHtmlTool.regkey = Software\FooSoftware\HtmlMerge
1422 myHtmlTool.priority = 1
1423 Supported arguments:
1425 priority
1427 The priority in which to evaluate this tool. (default: 0)
1429 executable
1431 Either just the name of the executable or its pathname.
1433 On Windows, the path can use environment variables with ${Pro‐
1435 gramFiles} syntax.
1436 (default: the tool name)
1438 args
1440 The arguments to pass to the tool executable. You can refer to
1442 the files being merged as well as the output file through these
1443 variables: $base, $local, $other, $output. The meaning of $local
1444 and $other can vary depending on which action is being per‐
1445 formed. During and update or merge, $local represents the origi‐
1446 nal state of the file, while $other represents the commit you
1447 are updating to or the commit you are merging with. During a
1448 rebase $local represents the destination of the rebase, and
1449 $other represents the commit being rebased. (default: $local
1450 $base $other)
1451 premerge
1453 Attempt to run internal non-interactive 3-way merge tool before
1455 launching external tool. Options are true, false, keep or
1456 keep-merge3. The keep option will leave markers in the file if
1457 the premerge fails. The keep-merge3 will do the same but include
1458 information about the base of the merge in the marker (see
1459 internal :merge3 in hg help merge-tools). (default: True)
1460 binary
1462 This tool can merge binary files. (default: False, unless tool
1464 was selected by file pattern match)
1465 symlink
1467 This tool can merge symlinks. (default: False)
1469 check
1471 A list of merge success-checking options:
1473 changed
1475 Ask whether merge was successful when the merged file
1477 shows no changes.
1478 conflicts
1480 Check whether there are conflicts even though the tool
1482 reported success.
1483 prompt
1485 Always prompt for merge success, regardless of success
1487 reported by tool.
1488 fixeol
1490 Attempt to fix up EOL changes caused by the merge tool.
1492 (default: False)
1493 gui
1495 This tool requires a graphical interface to run. (default:
1497 False)
1498 regkey
1500 Windows registry key which describes install location of this
1502 tool. Mercurial will search for this key first under HKEY_CUR‐
1503 RENT_USER and then under HKEY_LOCAL_MACHINE. (default: None)
1504 regkeyalt
1506 An alternate Windows registry key to try if the first key is not
1508 found. The alternate key uses the same regname and regappend
1509 semantics of the primary key. The most common use for this key
1510 is to search for 32bit applications on 64bit operating systems.
1511 (default: None)
1512 regname
1514 Name of value to read from specified registry key. (default:
1516 the unnamed (default) value)
1517 regappend
1519 String to append to the value read from the registry, typically
1521 the executable name of the tool. (default: None)
1522 pager
1524 Setting used to control when to paginate and with what external tool.
1525 See hg help pager for details.
1526 pager
1528 Define the external tool used as pager.
1530 If no pager is set, Mercurial uses the environment variable
1532 $PAGER. If neither pager.pager, nor $PAGER is set, a default
1533 pager will be used, typically less on Unix and more on Windows.
1534 Example:
1535 [pager]
1537 pager = less -FRX
1538 ignore
1540 List of commands to disable the pager for. Example:
1542 [pager]
1544 ignore = version, help, update
1545 patch
1547 Settings used when applying patches, for instance through the 'import'
1548 command or with Mercurial Queues extension.
1549 eol
1551 When set to 'strict' patch content and patched files end of
1553 lines are preserved. When set to lf or crlf, both files end of
1554 lines are ignored when patching and the result line endings are
1555 normalized to either LF (Unix) or CRLF (Windows). When set to
1556 auto, end of lines are again ignored while patching but line
1557 endings in patched files are normalized to their original set‐
1558 ting on a per-file basis. If target file does not exist or has
1559 no end of line, patch line endings are preserved. (default:
1560 strict)
1561 fuzz
1563 The number of lines of 'fuzz' to allow when applying patches.
1565 This controls how much context the patcher is allowed to ignore
1566 when trying to apply a patch. (default: 2)
1567 paths
1569 Assigns symbolic names and behavior to repositories.
1570 Options are symbolic names defining the URL or directory that is the
1572 location of the repository. Example:
1573 [paths]
1575 my_server = https://example.com/my_repo
1576 local_path = /home/me/repo
1577 These symbolic names can be used from the command line. To pull from
1579 my_server: hg pull my_server. To push to local_path: hg push local_path
1580 .
1581 Options containing colons (:) denote sub-options that can influence
1583 behavior for that specific path. Example:
1584 [paths]
1586 my_server = https://example.com/my_path
1587 my_server:pushurl = ssh://example.com/my_path
1588 The following sub-options can be defined:
1590 pushurl
1592 The URL to use for push operations. If not defined, the location
1594 defined by the path's main entry is used.
1595 pushrev
1597 A revset defining which revisions to push by default.
1599 When hg push is executed without a -r argument, the revset
1601 defined by this sub-option is evaluated to determine what to
1602 push.
1603 For example, a value of . will push the working directory's
1605 revision by default.
1606 Revsets specifying bookmarks will not result in the bookmark
1608 being pushed.
1609 The following special named paths exist:
1611 default
1613 The URL or directory to use when no source or remote is speci‐
1615 fied.
1616 hg clone will automatically define this path to the location the
1618 repository was cloned from.
1619 default-push
1621 (deprecated) The URL or directory for the default hg push loca‐
1623 tion. default:pushurl should be used instead.
1624 phases
1626 Specifies default handling of phases. See hg help phases for more
1627 information about working with phases.
1628 publish
1630 Controls draft phase behavior when working as a server. When
1632 true, pushed changesets are set to public in both client and
1633 server and pulled or cloned changesets are set to public in the
1634 client. (default: True)
1635 new-commit
1637 Phase of newly-created commits. (default: draft)
1639 checksubrepos
1641 Check the phase of the current revision of each subrepository.
1643 Allowed values are "ignore", "follow" and "abort". For settings
1644 other than "ignore", the phase of the current revision of each
1645 subrepository is checked before committing the parent reposi‐
1646 tory. If any of those phases is greater than the phase of the
1647 parent repository (e.g. if a subrepo is in a "secret" phase
1648 while the parent repo is in "draft" phase), the commit is either
1649 aborted (if checksubrepos is set to "abort") or the higher phase
1650 is used for the parent repository commit (if set to "follow").
1651 (default: follow)
1652 profiling
1654 Specifies profiling type, format, and file output. Two profilers are
1655 supported: an instrumenting profiler (named ls), and a sampling pro‐
1656 filer (named stat).
1657 In this section description, 'profiling data' stands for the raw data
1659 collected during profiling, while 'profiling report' stands for a sta‐
1660 tistical text report generated from the profiling data. The profiling
1661 is done using lsprof.
1662 enabled
1664 Enable the profiler. (default: false)
1666 This is equivalent to passing --profile on the command line.
1668 type
1670 The type of profiler to use. (default: stat)
1672 ls
1674 Use Python's built-in instrumenting profiler. This pro‐
1676 filer works on all platforms, but each line number it
1677 reports is the first line of a function. This restriction
1678 makes it difficult to identify the expensive parts of a
1679 non-trivial function.
1680 stat
1682 Use a statistical profiler, statprof. This profiler is
1684 most useful for profiling commands that run for longer
1685 than about 0.1 seconds.
1686 format
1688 Profiling format. Specific to the ls instrumenting profiler.
1690 (default: text)
1691 text
1693 Generate a profiling report. When saving to a file, it
1695 should be noted that only the report is saved, and the
1696 profiling data is not kept.
1697 kcachegrind
1699 Format profiling data for kcachegrind use: when saving to
1701 a file, the generated file can directly be loaded into
1702 kcachegrind.
1703 statformat
1705 Profiling format for the stat profiler. (default: hotpath)
1707 hotpath
1709 Show a tree-based display containing the hot path of exe‐
1711 cution (where most time was spent).
1712 bymethod
1714 Show a table of methods ordered by how frequently they
1716 are active.
1717 byline
1719 Show a table of lines in files ordered by how frequently
1721 they are active.
1722 json
1724 Render profiling data as JSON.
1726 frequency
1728 Sampling frequency. Specific to the stat sampling profiler.
1730 (default: 1000)
1731 output
1733 File path where profiling data or report should be saved. If the
1735 file exists, it is replaced. (default: None, data is printed on
1736 stderr)
1737 sort
1739 Sort field. Specific to the ls instrumenting profiler. One of
1741 callcount, reccallcount, totaltime and inlinetime. (default:
1742 inlinetime)
1743 limit
1745 Number of lines to show. Specific to the ls instrumenting pro‐
1747 filer. (default: 30)
1748 nested
1750 Show at most this number of lines of drill-down info after each
1752 main entry. This can help explain the difference between Total
1753 and Inline. Specific to the ls instrumenting profiler.
1754 (default: 5)
1755 showmin
1757 Minimum fraction of samples an entry must have for it to be dis‐
1759 played. Can be specified as a float between 0.0 and 1.0 or can
1760 have a % afterwards to allow values up to 100. e.g. 5%.
1761 Only used by the stat profiler.
1763 For the hotpath format, default is 0.05. For the chrome format,
1765 default is 0.005.
1766 The option is unused on other formats.
1768 showmax
1770 Maximum fraction of samples an entry can have before it is
1772 ignored in display. Values format is the same as showmin.
1773 Only used by the stat profiler.
1775 For the chrome format, default is 0.999.
1777 The option is unused on other formats.
1779 progress
1781 Mercurial commands can draw progress bars that are as informative as
1782 possible. Some progress bars only offer indeterminate information,
1783 while others have a definite end point.
1784 delay
1786 Number of seconds (float) before showing the progress bar.
1788 (default: 3)
1789 changedelay
1791 Minimum delay before showing a new topic. When set to less than
1793 3 * refresh, that value will be used instead. (default: 1)
1794 estimateinterval
1796 Maximum sampling interval in seconds for speed and estimated
1798 time calculation. (default: 60)
1799 refresh
1801 Time in seconds between refreshes of the progress bar. (default:
1803 0.1)
1804 format
1806 Format of the progress bar.
1808 Valid entries for the format field are topic, bar, number, unit,
1810 estimate, speed, and item. item defaults to the last 20 charac‐
1811 ters of the item, but this can be changed by adding either
1812 -<num> which would take the last num characters, or +<num> for
1813 the first num characters.
1814 (default: topic bar number estimate)
1816 width
1818 If set, the maximum width of the progress information (that is,
1820 min(width, term width) will be used).
1821 clear-complete
1823 Clear the progress bar after it's done. (default: True)
1825 disable
1827 If true, don't show a progress bar.
1829 assume-tty
1831 If true, ALWAYS show a progress bar, unless disable is given.
1833 rebase
1835 evolution.allowdivergence
1836 Default to False, when True allow creating divergence when per‐
1838 forming rebase of obsolete changesets.
1839 revsetalias
1841 Alias definitions for revsets. See hg help revsets for details.
1842 server
1844 Controls generic server settings.
1845 bookmarks-pushkey-compat
1847 Trigger pushkey hook when being pushed bookmark updates. This
1849 config exist for compatibility purpose (default to True)
1850 If you use pushkey and pre-pushkey hooks to control bookmark
1852 movement we recommend you migrate them to txnclose-bookmark and
1853 pretxnclose-bookmark.
1854 compressionengines
1856 List of compression engines and their relative priority to
1858 advertise to clients.
1859 The order of compression engines determines their priority, the
1861 first having the highest priority. If a compression engine is
1862 not listed here, it won't be advertised to clients.
1863 If not set (the default), built-in defaults are used. Run hg
1865 debuginstall to list available compression engines and their
1866 default wire protocol priority.
1867 Older Mercurial clients only support zlib compression and this
1869 setting has no effect for legacy clients.
1870 uncompressed
1872 Whether to allow clients to clone a repository using the uncom‐
1874 pressed streaming protocol. This transfers about 40% more data
1875 than a regular clone, but uses less memory and CPU on both
1876 server and client. Over a LAN (100 Mbps or better) or a very
1877 fast WAN, an uncompressed streaming clone is a lot faster (~10x)
1878 than a regular clone. Over most WAN connections (anything slower
1879 than about 6 Mbps), uncompressed streaming is slower, because of
1880 the extra data transfer overhead. This mode will also temporar‐
1881 ily hold the write lock while determining what data to transfer.
1882 (default: True)
1883 uncompressedallowsecret
1885 Whether to allow stream clones when the repository contains
1887 secret changesets. (default: False)
1888 preferuncompressed
1890 When set, clients will try to use the uncompressed streaming
1892 protocol. (default: False)
1893 disablefullbundle
1895 When set, servers will refuse attempts to do pull-based clones.
1897 If this option is set, preferuncompressed and/or clone bundles
1898 are highly recommended. Partial clones will still be allowed.
1899 (default: False)
1900 concurrent-push-mode
1902 Level of allowed race condition between two pushing clients.
1904 · 'strict': push is abort if another client touched the reposi‐
1906 tory while the push was preparing. (default)
1907 · 'check-related': push is only aborted if it affects head that
1909 got also affected while the push was preparing.
1910 This requires compatible client (version 4.3 and later). Old
1912 client will use 'strict'.
1913 validate
1915 Whether to validate the completeness of pushed changesets by
1917 checking that all new file revisions specified in manifests are
1918 present. (default: False)
1919 maxhttpheaderlen
1921 Instruct HTTP clients not to send request headers longer than
1923 this many bytes. (default: 1024)
1924 bundle1
1926 Whether to allow clients to push and pull using the legacy bun‐
1928 dle1 exchange format. (default: True)
1929 bundle1gd
1931 Like bundle1 but only used if the repository is using the gener‐
1933 aldelta storage format. (default: True)
1934 bundle1.push
1936 Whether to allow clients to push using the legacy bundle1
1938 exchange format. (default: True)
1939 bundle1gd.push
1941 Like bundle1.push but only used if the repository is using the
1943 generaldelta storage format. (default: True)
1944 bundle1.pull
1946 Whether to allow clients to pull using the legacy bundle1
1948 exchange format. (default: True)
1949 bundle1gd.pull
1951 Like bundle1.pull but only used if the repository is using the
1953 generaldelta storage format. (default: True)
1954 Large repositories using the generaldelta storage format should
1956 consider setting this option because converting generaldelta
1957 repositories to the exchange format required by the bundle1 data
1958 format can consume a lot of CPU.
1959 zliblevel
1961 Integer between -1 and 9 that controls the zlib compression
1963 level for wire protocol commands that send zlib compressed out‐
1964 put (notably the commands that send repository history data).
1965 The default (-1) uses the default zlib compression level, which
1967 is likely equivalent to 6. 0 means no compression. 9 means maxi‐
1968 mum compression.
1969 Setting this option allows server operators to make trade-offs
1971 between bandwidth and CPU used. Lowering the compression lowers
1972 CPU utilization but sends more bytes to clients.
1973 This option only impacts the HTTP server.
1975 zstdlevel
1977 Integer between 1 and 22 that controls the zstd compression
1979 level for wire protocol commands. 1 is the minimal amount of
1980 compression and 22 is the highest amount of compression.
1981 The default (3) should be significantly faster than zlib while
1983 likely delivering better compression ratios.
1984 This option only impacts the HTTP server.
1986 See also server.zliblevel.
1988 smtp
1990 Configuration for extensions that need to send email messages.
1991 host
1993 Host name of mail server, e.g. "mail.example.com".
1995 port
1997 Optional. Port to connect to on mail server. (default: 465 if
1999 tls is smtps; 25 otherwise)
2000 tls
2002 Optional. Method to enable TLS when connecting to mail server:
2004 starttls, smtps or none. (default: none)
2005 username
2007 Optional. User name for authenticating with the SMTP server.
2009 (default: None)
2010 password
2012 Optional. Password for authenticating with the SMTP server. If
2014 not specified, interactive sessions will prompt the user for a
2015 password; non-interactive sessions will fail. (default: None)
2016 local_hostname
2018 Optional. The hostname that the sender can use to identify
2020 itself to the MTA.
2021 subpaths
2023 Subrepository source URLs can go stale if a remote server changes name
2024 or becomes temporarily unavailable. This section lets you define re‐
2025 write rules of the form:
2026 <pattern> = <replacement>
2028 where pattern is a regular expression matching a subrepository source
2030 URL and replacement is the replacement string used to rewrite it.
2031 Groups can be matched in pattern and referenced in replacements. For
2032 instance:
2033 http://server/(.*)-hg/ = http://hg.server/\1/
2035 rewrites http://server/foo-hg/ into http://hg.server/foo/.
2037 Relative subrepository paths are first made absolute, and the rewrite
2039 rules are then applied on the full (absolute) path. If pattern doesn't
2040 match the full path, an attempt is made to apply it on the relative
2041 path alone. The rules are applied in definition order.
2042 subrepos
2044 This section contains options that control the behavior of the sub‐
2045 repositories feature. See also hg help subrepos.
2046 Security note: auditing in Mercurial is known to be insufficient to
2048 prevent clone-time code execution with carefully constructed Git subre‐
2049 pos. It is unknown if a similar detect is present in Subversion subre‐
2050 pos. Both Git and Subversion subrepos are disabled by default out of
2051 security concerns. These subrepo types can be enabled using the respec‐
2052 tive options below.
2053 allowed
2055 Whether subrepositories are allowed in the working directory.
2057 When false, commands involving subrepositories (like hg update)
2059 will fail for all subrepository types. (default: true)
2060 hg:allowed
2062 Whether Mercurial subrepositories are allowed in the working
2064 directory. This option only has an effect if subrepos.allowed is
2065 true. (default: true)
2066 git:allowed
2068 Whether Git subrepositories are allowed in the working direc‐
2070 tory. This option only has an effect if subrepos.allowed is
2071 true.
2072 See the security note above before enabling Git subrepos.
2074 (default: false)
2075 svn:allowed
2077 Whether Subversion subrepositories are allowed in the working
2079 directory. This option only has an effect if subrepos.allowed is
2080 true.
2081 See the security note above before enabling Subversion subrepos.
2083 (default: false)
2084 templatealias
2086 Alias definitions for templates. See hg help templates for details.
2087 templates
2089 Use the [templates] section to define template strings. See hg help
2090 templates for details.
2091 trusted
2093 Mercurial will not use the settings in the .hg/hgrc file from a reposi‐
2094 tory if it doesn't belong to a trusted user or to a trusted group, as
2095 various hgrc features allow arbitrary commands to be run. This issue is
2096 often encountered when configuring hooks or extensions for shared
2097 repositories or servers. However, the web interface will use some safe
2098 settings from the [web] section.
2099 This section specifies what users and groups are trusted. The current
2101 user is always trusted. To trust everybody, list a user or a group with
2102 name *. These settings must be placed in an already-trusted file to
2103 take effect, such as $HOME/.hgrc of the user or service running Mercu‐
2104 rial.
2105 users
2107 Comma-separated list of trusted users.
2109 groups
2111 Comma-separated list of trusted groups.
2113 ui
2115 User interface controls.
2116 archivemeta
2118 Whether to include the .hg_archival.txt file containing meta
2120 data (hashes for the repository base and for tip) in archives
2121 created by the hg archive command or downloaded via hgweb.
2122 (default: True)
2123 askusername
2125 Whether to prompt for a username when committing. If True, and
2127 neither $HGUSER nor $EMAIL has been specified, then the user
2128 will be prompted to enter a username. If no username is entered,
2129 the default USER@HOST is used instead. (default: False)
2130 clonebundles
2132 Whether the "clone bundles" feature is enabled.
2134 When enabled, hg clone may download and apply a server-adver‐
2136 tised bundle file from a URL instead of using the normal
2137 exchange mechanism.
2138 This can likely result in faster and more reliable clones.
2140 (default: True)
2142 clonebundlefallback
2144 Whether failure to apply an advertised "clone bundle" from a
2146 server should result in fallback to a regular clone.
2147 This is disabled by default because servers advertising "clone
2149 bundles" often do so to reduce server load. If advertised bun‐
2150 dles start mass failing and clients automatically fall back to a
2151 regular clone, this would add significant and unexpected load to
2152 the server since the server is expecting clone operations to be
2153 offloaded to pre-generated bundles. Failing fast (the default
2154 behavior) ensures clients don't overwhelm the server when "clone
2155 bundle" application fails.
2156 (default: False)
2158 clonebundleprefers
2160 Defines preferences for which "clone bundles" to use.
2162 Servers advertising "clone bundles" may advertise multiple
2164 available bundles. Each bundle may have different attributes,
2165 such as the bundle type and compression format. This option is
2166 used to prefer a particular bundle over another.
2167 The following keys are defined by Mercurial:
2169 BUNDLESPEC
2171 A bundle type specifier. These are strings passed to hg
2172 bundle -t. e.g. gzip-v2 or bzip2-v1.
2173 COMPRESSION
2175 The compression format of the bundle. e.g. gzip and
2176 bzip2.
2177 Server operators may define custom keys.
2179 Example values: COMPRESSION=bzip2, BUNDLESPEC=gzip-v2, COMPRES‐
2181 SION=gzip.
2182 By default, the first bundle advertised by the server is used.
2184 color
2186 When to colorize output. Possible value are Boolean ("yes" or
2188 "no"), or "debug", or "always". (default: "yes"). "yes" will use
2189 color whenever it seems possible. See hg help color for details.
2190 commitsubrepos
2192 Whether to commit modified subrepositories when committing the
2194 parent repository. If False and one subrepository has uncommit‐
2195 ted changes, abort the commit. (default: False)
2196 debug
2198 Print debugging information. (default: False)
2200 editor
2202 The editor to use during a commit. (default: $EDITOR or vi)
2204 fallbackencoding
2206 Encoding to try if it's not possible to decode the changelog
2208 using UTF-8. (default: ISO-8859-1)
2209 graphnodetemplate
2211 The template used to print changeset nodes in an ASCII revision
2213 graph. (default: {graphnode})
2214 ignore
2216 A file to read per-user ignore patterns from. This file should
2218 be in the same format as a repository-wide .hgignore file. File‐
2219 names are relative to the repository root. This option supports
2220 hook syntax, so if you want to specify multiple ignore files,
2221 you can do so by setting something like ignore.other = ~/.hgig‐
2222 nore2. For details of the ignore file format, see the hgig‐
2223 nore(5) man page.
2224 interactive
2226 Allow to prompt the user. (default: True)
2228 interface
2230 Select the default interface for interactive features (default:
2232 text). Possible values are 'text' and 'curses'.
2233 interface.chunkselector
2235 Select the interface for change recording (e.g. hg commit -i).
2237 Possible values are 'text' and 'curses'. This config overrides
2238 the interface specified by ui.interface.
2239 logtemplate
2241 Template string for commands that print changesets.
2243 merge
2245 The conflict resolution program to use during a manual merge.
2247 For more information on merge tools see hg help merge-tools.
2248 For configuring merge tools see the [merge-tools] section.
2249 mergemarkers
2251 Sets the merge conflict marker label styling. The detailed style
2253 uses the mergemarkertemplate setting to style the labels. The
2254 basic style just uses 'local' and 'other' as the marker label.
2255 One of basic or detailed. (default: basic)
2256 mergemarkertemplate
2258 The template used to print the commit description next to each
2260 conflict marker during merge conflicts. See hg help templates
2261 for the template format.
2262 Defaults to showing the hash, tags, branches, bookmarks, author,
2264 and the first line of the commit description.
2265 If you use non-ASCII characters in names for tags, branches,
2267 bookmarks, authors, and/or commit descriptions, you must pay
2268 attention to encodings of managed files. At template expansion,
2269 non-ASCII characters use the encoding specified by the --encod‐
2270 ing global option, HGENCODING or other environment variables
2271 that govern your locale. If the encoding of the merge markers is
2272 different from the encoding of the merged files, serious prob‐
2273 lems may occur.
2274 origbackuppath
2276 The path to a directory used to store generated .orig files. If
2278 the path is not a directory, one will be created. If set, files
2279 stored in this directory have the same name as the original file
2280 and do not have a .orig suffix.
2281 paginate
2283 Control the pagination of command output (default: True). See hg
2285 help pager for details.
2286 patch
2288 An optional external tool that hg import and some extensions
2290 will use for applying patches. By default Mercurial uses an
2291 internal patch utility. The external tool must work as the com‐
2292 mon Unix patch program. In particular, it must accept a -p argu‐
2293 ment to strip patch headers, a -d argument to specify the cur‐
2294 rent directory, a file name to patch, and a patch file to take
2295 from stdin.
2296 It is possible to specify a patch tool together with extra argu‐
2298 ments. For example, setting this option to patch --merge will
2299 use the patch program with its 2-way merge option.
2300 portablefilenames
2302 Check for portable filenames. Can be warn, ignore or abort.
2304 (default: warn)
2305 warn
2307 Print a warning message on POSIX platforms, if a file
2309 with a non-portable filename is added (e.g. a file with a
2310 name that can't be created on Windows because it contains
2311 reserved parts like AUX, reserved characters like :, or
2312 would cause a case collision with an existing file).
2313 ignore
2315 Don't print a warning.
2317 abort
2319 The command is aborted.
2321 true
2323 Alias for warn.
2325 false
2327 Alias for ignore.
2329 On Windows, this configuration option is ignored and the command
2331 aborted.
2332 quiet
2334 Reduce the amount of output printed. (default: False)
2336 remotecmd
2338 Remote command to use for clone/push/pull operations. (default:
2340 hg)
2341 report_untrusted
2343 Warn if a .hg/hgrc file is ignored due to not being owned by a
2345 trusted user or group. (default: True)
2346 slash
2348 (Deprecated. Use slashpath template filter instead.)
2350 Display paths using a slash (/) as the path separator. This only
2352 makes a difference on systems where the default path separator
2353 is not the slash character (e.g. Windows uses the backslash
2354 character (\)). (default: False)
2355 statuscopies
2357 Display copies in the status command.
2359 ssh
2361 Command to use for SSH connections. (default: ssh)
2363 ssherrorhint
2365 A hint shown to the user in the case of SSH error (e.g. Please
2367 see http://company/internalwiki/ssh.html)
2368 strict
2370 Require exact command names, instead of allowing unambiguous
2372 abbreviations. (default: False)
2373 style
2375 Name of style to use for command output.
2377 supportcontact
2379 A URL where users should report a Mercurial traceback. Use this
2381 if you are a large organisation with its own Mercurial deploy‐
2382 ment process and crash reports should be addressed to your
2383 internal support.
2384 textwidth
2386 Maximum width of help text. A longer line generated by hg help
2388 or hg subcommand --help will be broken after white space to get
2389 this width or the terminal width, whichever comes first. A
2390 non-positive value will disable this and the terminal width will
2391 be used. (default: 78)
2392 timeout
2394 The timeout used when a lock is held (in seconds), a negative
2396 value means no timeout. (default: 600)
2397 timeout.warn
2399 Time (in seconds) before a warning is printed about held lock. A
2401 negative value means no warning. (default: 0)
2402 traceback
2404 Mercurial always prints a traceback when an unknown exception
2406 occurs. Setting this to True will make Mercurial print a trace‐
2407 back on all exceptions, even those recognized by Mercurial (such
2408 as IOError or MemoryError). (default: False)
2409 tweakdefaults
2411 By default Mercurial's behavior changes very little from release to
2413 release, but over time the recommended config settings shift. Enable
2414 this config to opt in to get automatic tweaks to Mercurial's behav‐
2415 ior over time. This config setting will have no effet if HGPLAIN` is
2416 set or ``HGPLAINEXCEPT is set and does not include tweakdefaults.
2417 (default: False)
2418 username
2420 The committer of a changeset created when running "commit".
2422 Typically a person's name and email address, e.g. Fred Widget
2423 <fred@example.com>. Environment variables in the username are
2424 expanded.
2425 (default: $EMAIL or username@hostname. If the username in hgrc
2427 is empty, e.g. if the system admin set username = in the system
2428 hgrc, it has to be specified manually or in a different hgrc
2429 file)
2430 verbose
2432 Increase the amount of output printed. (default: False)
2434 web
2436 Web interface configuration. The settings in this section apply to both
2437 the builtin webserver (started by hg serve) and the script you run
2438 through a webserver (hgweb.cgi and the derivatives for FastCGI and
2439 WSGI).
2440 The Mercurial webserver does no authentication (it does not prompt for
2442 usernames and passwords to validate who users are), but it does do
2443 authorization (it grants or denies access for authenticated users based
2444 on settings in this section). You must either configure your webserver
2445 to do authentication for you, or disable the authorization checks.
2446 For a quick setup in a trusted environment, e.g., a private LAN, where
2448 you want it to accept pushes from anybody, you can use the following
2449 command line:
2450 $ hg --config web.allow-push=* --config web.push_ssl=False serve
2452 Note that this will allow anybody to push anything to the server and
2454 that this should not be used for public servers.
2455 The full set of options is:
2457 accesslog
2459 Where to output the access log. (default: stdout)
2461 address
2463 Interface address to bind to. (default: all)
2465 allow_archive
2467 List of archive format (bz2, gz, zip) allowed for downloading.
2469 (default: empty)
2470 allowbz2
2472 (DEPRECATED) Whether to allow .tar.bz2 downloading of repository
2474 revisions. (default: False)
2475 allowgz
2477 (DEPRECATED) Whether to allow .tar.gz downloading of repository
2479 revisions. (default: False)
2480 allow-pull
2482 Whether to allow pulling from the repository. (default: True)
2484 allow-push
2486 Whether to allow pushing to the repository. If empty or not set,
2488 pushing is not allowed. If the special value *, any remote user
2489 can push, including unauthenticated users. Otherwise, the remote
2490 user must have been authenticated, and the authenticated user
2491 name must be present in this list. The contents of the
2492 allow-push list are examined after the deny_push list.
2493 allow_read
2495 If the user has not already been denied repository access due to
2497 the contents of deny_read, this list determines whether to grant
2498 repository access to the user. If this list is not empty, and
2499 the user is unauthenticated or not present in the list, then
2500 access is denied for the user. If the list is empty or not set,
2501 then access is permitted to all users by default. Setting
2502 allow_read to the special value * is equivalent to it not being
2503 set (i.e. access is permitted to all users). The contents of the
2504 allow_read list are examined after the deny_read list.
2505 allowzip
2507 (DEPRECATED) Whether to allow .zip downloading of repository
2509 revisions. This feature creates temporary files. (default:
2510 False)
2511 archivesubrepos
2513 Whether to recurse into subrepositories when archiving.
2515 (default: False)
2516 baseurl
2518 Base URL to use when publishing URLs in other locations, so
2520 third-party tools like email notification hooks can construct
2521 URLs. Example: http://hgserver/repos/.
2522 cacerts
2524 Path to file containing a list of PEM encoded certificate
2526 authority certificates. Environment variables and ~user con‐
2527 structs are expanded in the filename. If specified on the
2528 client, then it will verify the identity of remote HTTPS servers
2529 with these certificates.
2530 To disable SSL verification temporarily, specify --insecure from
2532 command line.
2533 You can use OpenSSL's CA certificate file if your platform has
2535 one. On most Linux systems this will be /etc/ssl/certs/ca-cer‐
2536 tificates.crt. Otherwise you will have to generate this file
2537 manually. The form must be as follows:
2538 -----BEGIN CERTIFICATE-----
2540 ... (certificate in base64 PEM encoding) ...
2541 -----END CERTIFICATE-----
2542 -----BEGIN CERTIFICATE-----
2543 ... (certificate in base64 PEM encoding) ...
2544 -----END CERTIFICATE-----
2545 cache
2547 Whether to support caching in hgweb. (default: True)
2549 certificate
2551 Certificate to use when running hg serve.
2553 collapse
2555 With descend enabled, repositories in subdirectories are shown
2557 at a single level alongside repositories in the current path.
2558 With collapse also enabled, repositories residing at a deeper
2559 level than the current path are grouped behind navigable direc‐
2560 tory entries that lead to the locations of these repositories.
2561 In effect, this setting collapses each collection of reposito‐
2562 ries found within a subdirectory into a single entry for that
2563 subdirectory. (default: False)
2564 comparisoncontext
2566 Number of lines of context to show in side-by-side file compari‐
2568 son. If negative or the value full, whole files are shown.
2569 (default: 5)
2570 This setting can be overridden by a context request parameter to
2572 the comparison command, taking the same values.
2573 contact
2575 Name or email address of the person in charge of the repository.
2577 (default: ui.username or $EMAIL or "unknown" if unset or empty)
2578 csp
2580 Send a Content-Security-Policy HTTP header with this value.
2582 The value may contain a special string %nonce%, which will be
2584 replaced by a randomly-generated one-time use value. If the
2585 value contains %nonce%, web.cache will be disabled, as caching
2586 undermines the one-time property of the nonce. This nonce will
2587 also be inserted into <script> elements containing inline
2588 JavaScript.
2589 Note: lots of HTML content sent by the server is derived from
2591 repository data. Please consider the potential for malicious
2592 repository data to "inject" itself into generated HTML content
2593 as part of your security threat model.
2594 deny_push
2596 Whether to deny pushing to the repository. If empty or not set,
2598 push is not denied. If the special value *, all remote users are
2599 denied push. Otherwise, unauthenticated users are all denied,
2600 and any authenticated user name present in this list is also
2601 denied. The contents of the deny_push list are examined before
2602 the allow-push list.
2603 deny_read
2605 Whether to deny reading/viewing of the repository. If this list
2607 is not empty, unauthenticated users are all denied, and any
2608 authenticated user name present in this list is also denied
2609 access to the repository. If set to the special value *, all
2610 remote users are denied access (rarely needed ;). If deny_read
2611 is empty or not set, the determination of repository access
2612 depends on the presence and content of the allow_read list (see
2613 description). If both deny_read and allow_read are empty or not
2614 set, then access is permitted to all users by default. If the
2615 repository is being served via hgwebdir, denied users will not
2616 be able to see it in the list of repositories. The contents of
2617 the deny_read list have priority over (are examined before) the
2618 contents of the allow_read list.
2619 descend
2621 hgwebdir indexes will not descend into subdirectories. Only
2623 repositories directly in the current path will be shown (other
2624 repositories are still available from the index corresponding to
2625 their containing path).
2626 description
2628 Textual description of the repository's purpose or contents.
2630 (default: "unknown")
2631 encoding
2633 Character encoding name. (default: the current locale charset)
2635 Example: "UTF-8".
2636 errorlog
2638 Where to output the error log. (default: stderr)
2640 guessmime
2642 Control MIME types for raw download of file content. Set to
2644 True to let hgweb guess the content type from the file exten‐
2645 sion. This will serve HTML files as text/html and might allow
2646 cross-site scripting attacks when serving untrusted reposito‐
2647 ries. (default: False)
2648 hidden
2650 Whether to hide the repository in the hgwebdir index. (default:
2652 False)
2653 ipv6
2655 Whether to use IPv6. (default: False)
2657 labels
2659 List of string labels associated with the repository.
2661 Labels are exposed as a template keyword and can be used to cus‐
2663 tomize output. e.g. the index template can group or filter
2664 repositories by labels and the summary template can display
2665 additional content if a specific label is present.
2666 logoimg
2668 File name of the logo image that some templates display on each
2670 page. The file name is relative to staticurl. That is, the full
2671 path to the logo image is "staticurl/logoimg". If unset, hgl‐
2672 ogo.png will be used.
2673 logourl
2675 Base URL to use for logos. If unset, https://mercurial-scm.org/
2677 will be used.
2678 maxchanges
2680 Maximum number of changes to list on the changelog. (default:
2682 10)
2683 maxfiles
2685 Maximum number of files to list per changeset. (default: 10)
2687 maxshortchanges
2689 Maximum number of changes to list on the shortlog, graph or
2691 filelog pages. (default: 60)
2692 name
2694 Repository name to use in the web interface. (default: current
2696 working directory)
2697 port
2699 Port to listen on. (default: 8000)
2701 prefix
2703 Prefix path to serve from. (default: '' (server root))
2705 push_ssl
2707 Whether to require that inbound pushes be transported over SSL
2709 to prevent password sniffing. (default: True)
2710 refreshinterval
2712 How frequently directory listings re-scan the filesystem for new
2714 repositories, in seconds. This is relevant when wildcards are
2715 used to define paths. Depending on how much filesystem traversal
2716 is required, refreshing may negatively impact performance.
2717 Values less than or equal to 0 always refresh. (default: 20)
2719 staticurl
2721 Base URL to use for static files. If unset, static files (e.g.
2723 the hgicon.png favicon) will be served by the CGI script itself.
2724 Use this setting to serve them directly with the HTTP server.
2725 Example: http://hgserver/static/.
2726 stripes
2728 How many lines a "zebra stripe" should span in multi-line out‐
2730 put. Set to 0 to disable. (default: 1)
2731 style
2733 Which template map style to use. The available options are the
2735 names of subdirectories in the HTML templates path. (default:
2736 paper) Example: monoblue.
2737 templates
2739 Where to find the HTML templates. The default path to the HTML
2741 templates can be obtained from hg debuginstall.
2742 websub
2744 Web substitution filter definition. You can use this section to define
2745 a set of regular expression substitution patterns which let you auto‐
2746 matically modify the hgweb server output.
2747 The default hgweb templates only apply these substitution patterns on
2749 the revision description fields. You can apply them anywhere you want
2750 when you create your own templates by adding calls to the "websub" fil‐
2751 ter (usually after calling the "escape" filter).
2752 This can be used, for example, to convert issue references to links to
2754 your issue tracker, or to convert "markdown-like" syntax into HTML (see
2755 the examples below).
2756 Each entry in this section names a substitution filter. The value of
2758 each entry defines the substitution expression itself. The websub
2759 expressions follow the old interhg extension syntax, which in turn imi‐
2760 tates the Unix sed replacement syntax:
2761 patternname = s/SEARCH_REGEX/REPLACE_EXPRESSION/[i]
2763 You can use any separator other than "/". The final "i" is optional and
2765 indicates that the search must be case insensitive.
2766 Examples:
2768 [websub]
2770 issues = s|issue(\d+)|<a href="http://bts.example.org/issue\1">issue\1</a>|i
2771 italic = s/\b_(\S+)_\b/<i>\1<\/i>/
2772 bold = s/\*\b(\S+)\b\*/<b>\1<\/b>/
2773 worker
2775 Parallel master/worker configuration. We currently perform working
2776 directory updates in parallel on Unix-like systems, which greatly helps
2777 performance.
2778 enabled
2780 Whether to enable workers code to be used. (default: true)
2782 numcpus
2784 Number of CPUs to use for parallel operations. A zero or nega‐
2786 tive value is treated as use the default. (default: 4 or the
2787 number of CPUs on the system, whichever is larger)
2788 backgroundclose
2790 Whether to enable closing file handles on background threads
2792 during certain operations. Some platforms aren't very efficient
2793 at closing file handles that have been written or appended to.
2794 By performing file closing on background threads, file write
2795 rate can increase substantially. (default: true on Windows,
2796 false elsewhere)
2797 backgroundcloseminfilecount
2799 Minimum number of files required to trigger background file
2801 closing. Operations not writing this many files won't start
2802 background close threads. (default: 2048)
2803 backgroundclosemaxqueue
2805 The maximum number of opened file handles waiting to be closed
2807 in the background. This option only has an effect if background‐
2808 close is enabled. (default: 384)
2809 backgroundclosethreadcount
2811 Number of threads to process background file closes. Only rele‐
2813 vant if backgroundclose is enabled. (default: 4)
2814
2816 Bryan O'Sullivan <bos@serpentine.com>.
2817 Mercurial was written by Matt Mackall <mpm@selenic.com>.
2819
2821 hg(1), hgignore(5)
2822
2824 This manual page is copyright 2005 Bryan O'Sullivan. Mercurial is
2825 copyright 2005-2018 Matt Mackall. Free use of this software is granted
2826 under the terms of the GNU General Public License version 2 or any
2827 later version.
2828
2830 Bryan O'Sullivan <bos@serpentine.com>
2831 Organization: Mercurial
2833 HGRC(5)