======

 hgrc

======

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

configuration files for Mercurial

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

:Author:         Bryan O'Sullivan <bos@serpentine.com>

:Organization:   Mercurial

:Manual section: 5

:Manual group:   Mercurial Manual

.. contents::

   :backlinks: top

   :class: htmlonly

Synopsis

--------

The Mercurial system uses a set of configuration files to control

aspects of its behavior.

Files

-----

Mercurial reads configuration data from several files, if they exist.

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.

| (Unix, Windows) ``<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

    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.

| (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.

| (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.

| (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``

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

| (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.  If the

    pywin32 extensions are not installed, Mercurial will only look for

    site-wide configuration in ``C:\Mercurial\Mercurial.ini``.

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 hgrc 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 "hgrc" 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.

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!

``auth``

""""""""

Authentication credentials for HTTP authentication. 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.

``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.

``cert``

    Optional. PEM encoded client certificate chain file.

``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:`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. They are all Boolean and

defaults to False.

``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.

``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.

To explicitly disable an extension that is enabled in an hgrc of

broader scope, prepend its path with ``!``, as in

``hgext.foo = !/ext/path`` or ``hgext.foo = !``  when path is not

supplied.

Example for ``~/.hgrc``::

  [extensions]

  # (the mq extension will get loaded from Mercurial's path)

  hgext.mq =

  # (this extension will get loaded from the file specified)

  myfeature = ~/.hgext/myfeature.py

``format``

""""""""""

``usestore``

    Enable or disable the "store" repository format which improves

    compatibility with systems that fold case or otherwise mangle

    filenames. Enabled by default. Disabling this option will allow

    you to store longer filenames in some situations at the expense of

    compatibility and ensures that the on-disk format of newly created

    repositories will be compatible with Mercurial before version 0.9.4.

``usefncache``

    Enable or disable the "fncache" repository format which enhances

    the "store" repository format (which has to be enabled to use

    fncache) to allow longer filenames and avoids using Windows

    reserved names, e.g. "nul". Enabled by default. Disabling this

    option ensures that the on-disk format of newly created

    repositories will be compatible with Mercurial before version 1.1.

``merge-patterns``

""""""""""""""""""

This section specifies merge tools to associate with particular file

patterns. Tools matched here will take precedence over the default

merge tool. Patterns are globs by default, rooted at the repository

root.

Example::

  [merge-patterns]

  **.c = kdiff3

  **.jpg = myimgmerge

``merge-tools``

"""""""""""""""

This section configures external merge tools to use for file-level

merges.

Example ``~/.hgrc``::

  [merge-tools]

  # Override stock tool location

  kdiff3.executable = ~/bin/kdiff3

  # Specify command line

  kdiff3.args = $base $local $other -o $output

  # Give higher priority

  kdiff3.priority = 1

  # Define new tool

  myHtmlTool.args = -m $local $other $base $output

  myHtmlTool.regkey = Software\FooSoftware\HtmlMerge

  myHtmlTool.priority = 1

Supported arguments:

``priority``

  The priority in which to evaluate this tool.

  Default: 0.

``executable``

  Either just the name of the executable or its pathname.  On Windows,

  the path can use environment variables with ${ProgramFiles} syntax.

  Default: the tool name.

``args``

  The arguments to pass to the tool executable. You can refer to the