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:

.. container:: windows

  - ``%USERPROFILE%\mercurial.ini`` (on Windows)

.. container:: unix.plan9

  - ``$HOME/.hgrc`` (on Unix, Plan9)

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.

.. container:: verbose.unix

  On Unix, the following files are consulted:

  - ``<repo>/.hg/hgrc`` (per-repository)

  - ``$HOME/.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)

.. container:: verbose.windows

  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.

.. container:: windows

  On Windows 9x, ``%HOME%`` is replaced by ``%APPDATA%``.

.. container:: verbose.plan9

  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.

.. container:: unix.plan9

  On Plan 9 and Unix, most of this file will be ignored if it doesn't

  belong to a trusted user or to a trusted group. See

  :hg:`help config.trusted` for more details.

Per-user configuration file(s) are for the user running Mercurial.  Options

in these files apply to all Mercurial commands executed by this user in any

directory. Options in these files override per-system and per-installation

options.

Per-installation configuration files are searched for in the

directory where Mercurial is installed. ``<install-root>`` is the

parent directory of the **hg** executable (or symlink) being run.

.. container:: unix.plan9

  For example, if installed in ``/shared/tools/bin/hg``, Mercurial

  will look in ``/shared/tools/etc/mercurial/hgrc``. Options in these

  files apply to all Mercurial commands executed by any user in any

  directory.

Per-installation configuration files are for the system on

which Mercurial is running. Options in these files apply to all

Mercurial commands executed by any user in any directory. Registry

keys contain PATH-like strings, every part of which must reference

a ``Mercurial.ini`` file or be a directory where ``*.rc`` files will

be read.  Mercurial checks each of these locations in the specified

order until one or more configuration files are detected.

Per-system configuration files are for the system on which Mercurial

is running. Options in these files apply to all Mercurial commands

executed by any user in any directory. Options in these files

override per-installation options.

Mercurial comes with some default configuration. The default configuration

files are installed with Mercurial and will be overwritten on upgrades. Default

configuration files should never be edited by users or administrators but can

be overridden in other configuration files. So far the directory only contains

merge tool configuration but packagers can also put other default configuration

there.

Syntax

======

A configuration file consists of sections, led by a ``[section]`` header

and followed by ``name = value`` entries (sometimes called

``configuration keys``)::

    [spam]

    eggs=ham

    green=

       eggs

Each line contains one entry. If the lines that follow are indented,

they are treated as continuations of that entry. Leading whitespace is

removed from values. Empty lines are skipped. Lines beginning with

``#`` or ``;`` are ignored and may be used to provide comments.

Configuration keys can be set multiple times, in which case Mercurial

will use the value that was configured last. As an example::

    [spam]

    eggs=large

    ham=serrano

    eggs=small

This would set the configuration key named ``eggs`` to ``small``.

It is also possible to define a section multiple times. A section can

be redefined on the same and/or on different configuration files. For

example::

    [foo]

    eggs=large

    ham=serrano

    eggs=small

    [bar]

    eggs=ham

    green=

       eggs

    [foo]

    ham=prosciutto

    eggs=medium

    bread=toasted

This would set the ``eggs``, ``ham``, and ``bread`` configuration keys

of the ``foo`` section to ``medium``, ``prosciutto``, and ``toasted``,

respectively. As you can see there only thing that matters is the last

value that was set for each of the configuration keys.

If a configuration key is set multiple times in different

configuration files the final value will depend on the order in which

the different configuration files are read, with settings from earlier

paths overriding later ones as described on the ``Files`` section

above.

A line of the form ``%include file`` will include ``file`` into the

current configuration file. The inclusion is recursive, which means

that included files can include other files. Filenames are relative to

the configuration file in which the ``%include`` directive is found.

Environment variables and ``~user`` constructs are expanded in

``file``. This lets you do something like::

  %include ~/.hgrc.d/$HOST.rc

to include a different configuration file on each computer you use.

A line with ``%unset name`` will remove ``name`` from the current

section, if it has been set previously.

The values are either free-form text strings, lists of text strings,

or Boolean values. Boolean values can be set to true using any of "1",

"yes", "true", or "on" and to false using "0", "no", "false", or "off"

(all case insensitive).

List values are separated by whitespace or comma, except when values are

placed in double quotation marks::

  allow_read = "John Doe, PhD", brian, betty

Quotation marks can be escaped by prefixing them with a backslash. Only

quotation marks at the beginning of a word is counted as a quotation

(e.g., ``foo"bar baz`` is the list of ``foo"bar`` and ``baz``).

Sections

========

This section describes the different sections that may appear in a

Mercurial configuration file, the purpose of each section, its possible

keys, and their possible values.

``alias``

---------

Defines command aliases.

Aliases allow you to define your own commands in terms of other

commands (or aliases), optionally including arguments. Positional

arguments in the form of ``$1``, ``$2``, etc. in the alias definition

are expanded by Mercurial before execution. Positional arguments not

already used by ``$N`` in the definition are put at the end of the

command to be executed.

Alias definitions consist of lines of the form::

    <alias> = <command> [<argument>]...

For example, this definition::

    latest = log --limit 5

creates a new command ``latest`` that shows only the five most recent

changesets. You can define subsequent aliases using earlier ones::

    stable5 = latest -b stable

.. note::

   It is possible to create aliases with the same names as

   existing commands, which will then override the original

   definitions. This is almost always a bad idea!

An alias can start with an exclamation point (``!``) to make it a

shell alias. A shell alias is executed with the shell and will let you

run arbitrary commands. As an example, ::

   echo = !echo $@

will let you do ``hg echo foo`` to have ``foo`` printed in your

terminal. A better example might be::

   purge = !$HG status --no-status --unknown -0 re: | xargs -0 rm

which will make ``hg purge`` delete all unknown files in the

repository in the same manner as the purge extension.

Positional arguments like ``$1``, ``$2``, etc. in the alias definition

expand to the command arguments. Unmatched arguments are

removed. ``$0`` expands to the alias name and ``$@`` expands to all

arguments separated by a space. ``"$@"`` (with quotes) expands to all

arguments quoted individually and separated by a space. These expansions

happen before the command is passed to the shell.

Shell aliases are executed in an environment where ``$HG`` expands to

the path of the Mercurial that was used to execute the alias. This is

useful when you want to call further Mercurial commands in a shell

alias, as was done above for the purge alias. In addition,

``$HG_ARGS`` expands to the arguments given to Mercurial. In the ``hg

echo foo`` call above, ``$HG_ARGS`` would expand to ``echo foo``.

.. note::

   Some global configuration options such as ``-R`` are

   processed before shell aliases and will thus not be passed to

   aliases.

``annotate``

------------

Settings used when displaying file annotations. All values are

Booleans and default to False. See :hg:`help config.diff` for

related options for the diff command.

``ignorews``

    Ignore white space when comparing lines.

``ignorewsamount``

    Ignore changes in the amount of white space.

``ignoreblanklines``

    Ignore changes whose lines are all blank.

``auth``

--------

Authentication credentials for HTTP authentication. This section

allows you to store usernames and passwords for use when logging

*into* HTTP servers. See :hg:`help config.web` if

you want to configure *who* can login to your HTTP server.

Each line has the following format::

    <name>.<argument> = <value>

where ``<name>`` is used to group arguments into authentication

entries. Example::

    foo.prefix = hg.intevation.de/mercurial

    foo.username = foo

    foo.password = bar

    foo.schemes = http https

    bar.prefix = secure.example.org

    bar.key = path/to/file.key

    bar.cert = path/to/file.cert

    bar.schemes = https

Supported arguments:

``prefix``

    Either ``*`` or a URI prefix with or without the scheme part.

    The authentication entry with the longest matching prefix is used

    (where ``*`` matches everything and counts as a match of length

    1). If the prefix doesn't include a scheme, the match is performed

    against the URI with its scheme stripped as well, and the schemes

    argument, q.v., is then subsequently consulted.

``username``

    Optional. Username to authenticate with. If not given, and the

    remote site requires basic or digest authentication, the user will

    be prompted for it. Environment variables are expanded in the

    username letting you do ``foo.username = $USER``. If the URI

    includes a username, only ``[auth]`` entries with a matching

    username or without a username will be considered.

``password``

    Optional. Password to authenticate with. If not given, and the

    remote site requires basic or digest authentication, the user

    will be prompted for it.

``key``

    Optional. PEM encoded client certificate key file. Environment

    variables are expanded in the filename.

``cert``

    Optional. PEM encoded client certificate chain file. Environment

    variables are expanded in the filename.

``schemes``

    Optional. Space separated list of URI schemes to use this

    authentication entry with. Only used if the prefix doesn't include

    a scheme. Supported schemes are http and https. They will match

    static-http and static-https respectively, as well.

    (default: https)

If no suitable authentication entry is found, the user is prompted

for credentials as usual if required by the remote.

``committemplate``

------------------

``changeset``

    String: configuration in this section is used as the template to

    customize the text shown in the editor when committing.

In addition to pre-defined template keywords, commit log specific one

below can be used for customization:

``extramsg``

    String: Extra message (typically 'Leave message empty to abort

    commit.'). This may be changed by some commands or extensions.

For example, the template configuration below shows as same text as

one shown by default::

    [committemplate]

    changeset = {desc}\n\n

        HG: Enter commit message.  Lines beginning with 'HG:' are removed.

        HG: {extramsg}

        HG: --

        HG: user: {author}\n{ifeq(p2rev, "-1", "",

       "HG: branch merge\n")

       }HG: branch '{branch}'\n{if(activebookmark,

       "HG: bookmark '{activebookmark}'\n")   }{subrepos %

       "HG: subrepo {subrepo}\n"              }{file_adds %

       "HG: added {file}\n"                   }{file_mods %

       "HG: changed {file}\n"                 }{file_dels %

       "HG: removed {file}\n"                 }{if(files, "",

       "HG: no files changed\n")}

``diff()``

    String: show the diff (see :hg:`help templates` for detail)

Sometimes it is helpful to show the diff of the changeset in the editor without

having to prefix 'HG: ' to each line so that highlighting works correctly. For

this, Mercurial provides a special string which will ignore everything below

it::

     HG: ------------------------ >8 ------------------------

For example, the template configuration below will show the diff below the

extra message::

    [committemplate]

    changeset = {desc}\n\n

        HG: Enter commit message.  Lines beginning with 'HG:' are removed.

        HG: {extramsg}

        HG: ------------------------ >8 ------------------------

        HG: Do not touch the line above.

        HG: Everything below will be removed.

        {diff()}

.. note::

   For some problematic encodings (see :hg:`help win32mbcs` for

   detail), this customization should be configured carefully, to

   avoid showing broken characters.

   For example, if a multibyte character ending with backslash (0x5c) is

   followed by the ASCII character 'n' in the customized template,

   the sequence of backslash and 'n' is treated as line-feed unexpectedly

   (and the multibyte character is broken, too).

Customized template is used for commands below (``--edit`` may be

required):

- :hg:`backout`

- :hg:`commit`

- :hg:`fetch` (for merge commit only)

- :hg:`graft`

- :hg:`histedit`

- :hg:`import`

- :hg:`qfold`, :hg:`qnew` and :hg:`qrefresh`

- :hg:`rebase`

- :hg:`shelve`

- :hg:`sign`

- :hg:`tag`

- :hg:`transplant`

Configuring items below instead of ``changeset`` allows showing

customized message only for specific actions, or showing different

messages for each action.

- ``changeset.backout`` for :hg:`backout`

- ``changeset.commit.amend.merge`` for :hg:`commit --amend` on merges

- ``changeset.commit.amend.normal`` for :hg:`commit --amend` on other

- ``changeset.commit.normal.merge`` for :hg:`commit` on merges

- ``changeset.commit.normal.normal`` for :hg:`commit` on other

- ``changeset.fetch`` for :hg:`fetch` (impling merge commit)

- ``changeset.gpg.sign`` for :hg:`sign`

- ``changeset.graft`` for :hg:`graft`

- ``changeset.histedit.edit`` for ``edit`` of :hg:`histedit`

- ``changeset.histedit.fold`` for ``fold`` of :hg:`histedit`

- ``changeset.histedit.mess`` for ``mess`` of :hg:`histedit`

- ``changeset.histedit.pick`` for ``pick`` of :hg:`histedit`

- ``changeset.import.bypass`` for :hg:`import --bypass`

- ``changeset.import.normal.merge`` for :hg:`import` on merges

- ``changeset.import.normal.normal`` for :hg:`import` on other