======

 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::

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

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.

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. Lists are split on whitespace and commas. 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).

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.

The most common usage is for LF <-> CRLF translation on Windows. For

this, use the "smart" converters which check for binary files::

  [extensions]

  hgext.win32text =

  [encode]

  ** = cleverencode:

  [decode]

  ** = cleverdecode:

or if you only want to translate certain files::

  [extensions]

  hgext.win32text =

  [encode]

  **.txt = dumbencode:

  [decode]

  **.txt = dumbdecode:

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

  files being merged as well as the output file through these

  variables: ``$base``, ``$local``, ``$other``, ``$output``.

  Default: ``$local $base $other``

``premerge``

  Attempt to run internal non-interactive 3-way merge tool before

  launching external tool.

  Default: True

``binary``

  This tool can merge binary files. Defaults to False, unless tool

  was selected by file pattern match.

``symlink``

  This tool can merge symlinks. Defaults to False, even if tool was

  selected by file pattern match.

``checkconflicts``

  Check whether there are conflicts even though the tool reported

  success.

  Default: False

``checkchanged``

  Check whether outputs were written even though the tool reported

  success.

  Default: False

``fixeol``

  Attempt to fix up EOL changes caused by the merge tool.

  Default: False

``gui``

  This tool requires a graphical interface to run. Default: False

``regkey``

  Windows registry key which describes install location of this

  tool. Mercurial will search for this key first under

  ``HKEY_CURRENT_USER`` and then under ``HKEY_LOCAL_MACHINE``.

  Default: None

``regname``

  Name of value to read from specified registry key. Defaults to the

  unnamed (default) value.

``regappend``

  String to append to the value read from the registry, typically

  the executable name of the tool.