The Mercurial system uses a set of configuration files to control

aspects of its behavior.

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 the Syntax section below.

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: global configuration like

the username setting is typically put into

``%USERPROFILE%\mercurial.ini`` or ``$HOME/.hgrc`` and local

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

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.

| (All) ``<repo>/.hg/hgrc``

    Per-repository configuration options that 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. 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 the documentation

    for the ``[trusted]`` section below for more details.

| (Plan 9) ``$home/lib/hgrc``

| (Unix) ``$HOME/.hgrc``

| (Windows) ``%USERPROFILE%\.hgrc``

| (Windows) ``%USERPROFILE%\Mercurial.ini``

| (Windows) ``%HOME%\.hgrc``

| (Windows) ``%HOME%\Mercurial.ini``

    Per-user configuration file(s), for the user running Mercurial. On

    Windows 9x, ``%HOME%`` is replaced by ``%APPDATA%``. 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.

| (Plan 9) ``/lib/mercurial/hgrc``

| (Plan 9) ``/lib/mercurial/hgrc.d/*.rc``

| (Unix) ``/etc/mercurial/hgrc``

| (Unix) ``/etc/mercurial/hgrc.d/*.rc``

    Per-system configuration files, 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.

| (Plan 9) ``<install-root>/lib/mercurial/hgrc``

| (Plan 9) ``<install-root>/lib/mercurial/hgrc.d/*.rc``

| (Unix) ``<install-root>/etc/mercurial/hgrc``

| (Unix) ``<install-root>/etc/mercurial/hgrc.d/*.rc``

    Per-installation configuration files, searched for in the

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

    parent directory of the **hg** executable (or symlink) being run. 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.

| (Windows) ``<install-dir>\Mercurial.ini`` **or**

| (Windows) ``<install-dir>\hgrc.d\*.rc`` **or**

| (Windows) ``HKEY_LOCAL_MACHINE\SOFTWARE\Mercurial``

    Per-installation/system configuration files, 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.

.. note:: The registry key ``HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Mercurial``

   is used when running 32-bit Python on 64-bit Windows.

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 | 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. 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 ``diff`` section 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 the ``[web]`` configuration section 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.org/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.

``decode/encode``

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

Filters for transforming files on checkout/checkin. This would

typically be used for newline processing or other

localization/canonicalization of files.

Filters consist of a filter pattern followed by a filter command.

Filter patterns are globs by default, rooted at the repository root.

For example, to match any file ending in ``.txt`` in the root

directory only, use the pattern ``*.txt``. To match any file ending

in ``.c`` anywhere in the repository, use the pattern ``**.c``.

For each file only the first matching filter applies.

The filter command can start with a specifier, either ``pipe:`` or

``tempfile:``. If no specifier is given, ``pipe:`` is used by default.

A ``pipe:`` command must accept data on stdin and return the transformed

data on stdout.

Pipe example::

  [encode]

  # uncompress gzip files on checkin to improve delta compression

  # note: not necessarily a good idea, just an example

  *.gz = pipe: gunzip

  [decode]

  # recompress gzip files when writing them to the working dir (we

  # can safely omit "pipe:", because it's the default)

  *.gz = gzip

A ``tempfile:`` command is a template. The string ``INFILE`` is replaced

with the name of a temporary file that contains the data to be

filtered by the command. The string ``OUTFILE`` is replaced with the name

of an empty temporary file, where the filtered data must be written by

the command.

.. note:: The tempfile mechanism is recommended for Windows systems,

   where the standard shell I/O redirection operators often have

   strange effects and may corrupt the contents of your files.

This filter mechanism is used internally by the ``eol`` extension to

translate line ending characters between Windows (CRLF) and Unix (LF)

format. We suggest you use the ``eol`` extension for convenience.

``defaults``

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

(defaults are deprecated. Don't use them. Use aliases instead)

Use the ``[defaults]`` section to define command defaults, i.e. the

default options/arguments to pass to the specified commands.

The following example makes :hg:`log` run in verbose mode, and

:hg:`status` show only the modified files, by default::

  [defaults]

  log = -v

  status = -m

The actual commands, instead of their aliases, must be used when

defining command defaults. The command defaults will also be applied

to the aliases of the commands defined.

``diff``

--------

Settings used when displaying diffs. Everything except for ``unified``

is a Boolean and defaults to False. See ``annotate`` section for

related options for the annotate command.

``git``

    Use git extended diff format.

``nodates``

    Don't include dates in diff headers.

``showfunc``

    Show which function each change is in.

``ignorews``

    Ignore white space when comparing lines.

``ignorewsamount``

    Ignore changes in the amount of white space.

``ignoreblanklines``

    Ignore changes whose lines are all blank.

``unified``

    Number of lines of context to show.

``email``

---------

Settings for extensions that send email messages.

``from``

    Optional. Email address to use in "From" header and SMTP envelope

    of outgoing messages.

``to``

    Optional. Comma-separated list of recipients' email addresses.

``cc``

    Optional. Comma-separated list of carbon copy recipients'

    email addresses.

``bcc``

    Optional. Comma-separated list of blind carbon copy recipients'

    email addresses.

``method``

    Optional. Method to use to send email messages. If value is ``smtp``

    (default), use SMTP (see the ``[smtp]`` section for configuration).

    Otherwise, use as name of program to run that acts like sendmail

    (takes ``-f`` option for sender, list of recipients on command line,

    message on stdin). Normally, setting this to ``sendmail`` or

    ``/usr/sbin/sendmail`` is enough to use sendmail to send messages.

``charsets``

    Optional. Comma-separated list of character sets considered

    convenient for recipients. Addresses, headers, and parts not

    containing patches of outgoing messages will be encoded in the

    first character set to which conversion from local encoding

    (``$HGENCODING``, ``ui.fallbackencoding``) succeeds. If correct

    conversion fails, the text in question is sent as is. Defaults to

    empty (explicit) list.

    Order of outgoing email character sets:

    1. ``us-ascii``: always first, regardless of settings

    2. ``email.charsets``: in order given by user

    3. ``ui.fallbackencoding``: if not in email.charsets

    4. ``$HGENCODING``: if not in email.charsets

    5. ``utf-8``: always last, regardless of settings

Email example::

  [email]

  from = Joseph User <joe.user@example.com>

  method = /usr/sbin/sendmail

  # charsets for western Europeans

  # us-ascii, utf-8 omitted, as they are tried first and last

  charsets = iso-8859-1, iso-8859-15, windows-1252

``extensions``

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

Mercurial has an extension mechanism for adding new features. To

enable an extension, create an entry for it in this section.

If you know that the extension is already in Python's search path,

you can give the name of the module, followed by ``=``, with nothing

after the ``=``.

Otherwise, give a name that you choose, followed by ``=``, followed by

the path to the ``.py`` file (including the file name extension) that

defines the extension.