Configuration Files

The Mercurial system uses a set of configuration files to control aspects of its behavior.

Troubleshooting

If you're having problems with your configuration, 'hg config --debug' can help you understand what is introducing a setting into your environment.

See 'hg help config.syntax' and 'hg help config.files' for information about how and where to override things.

Structure

The configuration files use a simple ini-file format. A configuration file consists of sections, led by a "[section]" header and followed by "name = value" entries:

[ui]
username = Firstname Lastname <firstname.lastname@example.net>
verbose = True

The above entries will be referred to as "ui.username" and "ui.verbose", respectively. See 'hg help config.syntax'.

Files

Mercurial reads configuration data from several files, if they exist. These files do not exist by default and you will have to create the appropriate configuration files yourself:

Local configuration is put into the per-repository "<repo>/.hg/hgrc" file.

Global configuration like the username setting is typically put into:

The names of these files depend on the system on which Mercurial is installed. "*.rc" files from a single directory are read in alphabetical order, later ones overriding earlier ones. Where multiple paths are given below, settings from earlier paths override later ones.

On Unix, the following files are consulted:

• "<repo>/.hg/hgrc" (per-repository)
• "$HOME/.hgrc" (per-user)
• "${XDG_CONFIG_HOME:-$HOME/.config}/hg/hgrc" (per-user)
• "<install-root>/etc/mercurial/hgrc" (per-installation)
• "<install-root>/etc/mercurial/hgrc.d/*.rc" (per-installation)
• "/etc/mercurial/hgrc" (per-system)
• "/etc/mercurial/hgrc.d/*.rc" (per-system)
• "<internal>/default.d/*.rc" (defaults)

On Windows, the following files are consulted:

• "<repo>/.hg/hgrc" (per-repository)
• "%USERPROFILE%\.hgrc" (per-user)
• "%USERPROFILE%\Mercurial.ini" (per-user)
• "%HOME%\.hgrc" (per-user)
• "%HOME%\Mercurial.ini" (per-user)
• "HKEY_LOCAL_MACHINE\SOFTWARE\Mercurial" (per-installation)
• "<install-dir>\hgrc.d\*.rc" (per-installation)
• "<install-dir>\Mercurial.ini" (per-installation)
• "<internal>/default.d/*.rc" (defaults)

Note:

The registry key "HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Mercurial" is used when running 32-bit Python on 64-bit Windows.

On Plan9, the following files are consulted:

• "<repo>/.hg/hgrc" (per-repository)
• "$home/lib/hgrc" (per-user)
• "<install-root>/lib/mercurial/hgrc" (per-installation)
• "<install-root>/lib/mercurial/hgrc.d/*.rc" (per-installation)
• "/lib/mercurial/hgrc" (per-system)
• "/lib/mercurial/hgrc.d/*.rc" (per-system)
• "<internal>/default.d/*.rc" (defaults)

Per-repository configuration options only apply in a particular repository. This file is not version-controlled, and will not get transferred during a "clone" operation. Options in this file override options in all other configuration files.

Per-user configuration file(s) are