mercurial/help/config.txt

17266:4e35dea77e31

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

    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.

Syntax
------

A configuration file consists of sections, led by a ``[section]`` header
and followed by ``name = value`` entries (sometimes called
``configuration keys``)::

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

   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.

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

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.

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.

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.

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

  # 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,

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

    Mac OS X and spaces on Windows. Enabled by default. Disabling this
    option ensures that the on-disk format of newly created
    repositories will be compatible with Mercurial before version 1.7.

``graph``
"""""""""

Web graph view configuration. This section let you change graph
elements display properties by branches, for instance to make the
``default`` branch stand out.

``color``
    Set branch edges color in hexadecimal RGB notation.

``hooks``
"""""""""

Commands or Python functions that get automatically executed by
various actions such as starting or finishing a commit. Multiple
hooks can be run for the same action by appending a suffix to the
action. Overriding a site-wide hook can be done by changing its

If a Python hook returns a "true" value or raises an exception, this
is treated as a failure.


``hostfingerprints``
""""""""""""""""""""

Fingerprints of the certificates of known HTTPS servers.
A HTTPS connection to a server with a fingerprint configured here will
only succeed if the servers certificate matches the fingerprint.
This is very similar to how ssh known hosts works.

This feature is only supported when using Python 2.6 or later.


``http_proxy``
""""""""""""""

Used to access web-based Mercurial repositories through a HTTP
proxy.

``host``

``always``
    Optional. Always use the proxy, even for localhost and any entries
    in ``http_proxy.no``. True or False. Default: False.

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

  [merge-patterns]
  **.c = kdiff3
  **.jpg = myimgmerge

``merge-tools``
"""""""""""""""

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

Example ``~/.hgrc``::

  the executable name of the tool.
  Default: None


``patch``
"""""""""

Settings used when applying patches, for instance through the 'import'
command or with Mercurial Queues extension.

``eol``

    of line, patch line endings are preserved.
    Default: strict.


``paths``
"""""""""

Assigns symbolic names to repositories. The left side is the
symbolic name, and the right gives the directory or URL that is the
location of the repository. Default paths can be declared by setting
the following entries.

``default-push``
    Optional. Directory or URL to use when pushing if no destination
    is specified.

``phases``
""""""""""

Specifies default handling of phases. See :hg:`help phases` for more
information about working with phases.

``publish``

``new-commit``
    Phase of newly-created commits.
    Default: draft

``profiling``
"""""""""""""

Specifies profiling type, format, and file output. Two profilers are
supported: an instrumenting profiler (named ``ls``), and a sampling
profiler (named ``stat``).

    File path where profiling data or report should be saved. If the
    file exists, it is replaced. Default: None, data is printed on
    stderr

``revsetalias``
"""""""""""""""

Alias definitions for revsets. See :hg:`help revsets` for details.

``server``
""""""""""

Controls generic server settings.

``uncompressed``
    Whether to allow clients to clone a repository using the

    Whether to validate the completeness of pushed changesets by
    checking that all new file revisions specified in manifests are
    present. Default is False.

``smtp``
""""""""

Configuration for extensions that need to send email messages.

``host``
    Host name of mail server, e.g. "mail.example.com".

    Optional. It's the hostname that the sender can use to identify
    itself to the MTA.


``subpaths``
""""""""""""

Subrepository source URLs can go stale if a remote server changes name
or becomes temporarily unavailable. This section lets you define
rewrite rules of the form::

Relative subrepository paths are first made absolute, and the
rewrite rules are then applied on the full (absolute) path. The rules
are applied in definition order.

``trusted``
"""""""""""

Mercurial will not use the settings in the
``.hg/hgrc`` file from a repository if it doesn't belong to a trusted
user or to a trusted group, as various hgrc features allow arbitrary
commands to be run. This issue is often encountered when configuring

``groups``
  Comma-separated list of trusted groups.


``ui``
""""""

User interface controls.

``archivemeta``
    Whether to include the .hg_archival.txt file containing meta data

``verbose``
    Increase the amount of output printed. True or False. Default is False.


``web``
"""""""

Web interface configuration. The settings in this section apply to
both the builtin webserver (started by :hg:`serve`) and the script you
run through a webserver (``hgweb.cgi`` and the derivatives for FastCGI
and WSGI).

17267:979b107eaea2

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

    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.

Syntax
======

A configuration file consists of sections, led by a ``[section]`` header
and followed by ``name = value`` entries (sometimes called
``configuration keys``)::

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

   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.

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

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.

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.

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.

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

  # 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,

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

    Mac OS X and spaces on Windows. Enabled by default. Disabling this
    option ensures that the on-disk format of newly created
    repositories will be compatible with Mercurial before version 1.7.

``graph``
---------

Web graph view configuration. This section let you change graph
elements display properties by branches, for instance to make the
``default`` branch stand out.

``color``
    Set branch edges color in hexadecimal RGB notation.

``hooks``
---------

Commands or Python functions that get automatically executed by
various actions such as starting or finishing a commit. Multiple
hooks can be run for the same action by appending a suffix to the
action. Overriding a site-wide hook can be done by changing its

If a Python hook returns a "true" value or raises an exception, this
is treated as a failure.


``hostfingerprints``
--------------------

Fingerprints of the certificates of known HTTPS servers.
A HTTPS connection to a server with a fingerprint configured here will
only succeed if the servers certificate matches the fingerprint.
This is very similar to how ssh known hosts works.

This feature is only supported when using Python 2.6 or later.


``http_proxy``
--------------

Used to access web-based Mercurial repositories through a HTTP
proxy.

``host``

``always``
    Optional. Always use the proxy, even for localhost and any entries
    in ``http_proxy.no``. True or False. Default: False.

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

  [merge-patterns]
  **.c = kdiff3
  **.jpg = myimgmerge

``merge-tools``
---------------

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

Example ``~/.hgrc``::

  the executable name of the tool.
  Default: None


``patch``
---------

Settings used when applying patches, for instance through the 'import'
command or with Mercurial Queues extension.

``eol``

    of line, patch line endings are preserved.
    Default: strict.


``paths``
---------

Assigns symbolic names to repositories. The left side is the
symbolic name, and the right gives the directory or URL that is the
location of the repository. Default paths can be declared by setting
the following entries.

``default-push``
    Optional. Directory or URL to use when pushing if no destination
    is specified.

``phases``
----------

Specifies default handling of phases. See :hg:`help phases` for more
information about working with phases.

``publish``

``new-commit``
    Phase of newly-created commits.
    Default: draft

``profiling``
-------------

Specifies profiling type, format, and file output. Two profilers are
supported: an instrumenting profiler (named ``ls``), and a sampling
profiler (named ``stat``).

    File path where profiling data or report should be saved. If the
    file exists, it is replaced. Default: None, data is printed on
    stderr

``revsetalias``
---------------

Alias definitions for revsets. See :hg:`help revsets` for details.

``server``
----------

Controls generic server settings.

``uncompressed``
    Whether to allow clients to clone a repository using the

    Whether to validate the completeness of pushed changesets by
    checking that all new file revisions specified in manifests are
    present. Default is False.

``smtp``
--------

Configuration for extensions that need to send email messages.

``host``
    Host name of mail server, e.g. "mail.example.com".

    Optional. It's the hostname that the sender can use to identify
    itself to the MTA.


``subpaths``
------------

Subrepository source URLs can go stale if a remote server changes name
or becomes temporarily unavailable. This section lets you define
rewrite rules of the form::

Relative subrepository paths are first made absolute, and the
rewrite rules are then applied on the full (absolute) path. The rules
are applied in definition order.

``trusted``
-----------

Mercurial will not use the settings in the
``.hg/hgrc`` file from a repository if it doesn't belong to a trusted
user or to a trusted group, as various hgrc features allow arbitrary
commands to be run. This issue is often encountered when configuring

``groups``
  Comma-separated list of trusted groups.


``ui``
------

User interface controls.

``archivemeta``
    Whether to include the .hg_archival.txt file containing meta data

``verbose``
    Increase the amount of output printed. True or False. Default is False.


``web``
-------

Web interface configuration. The settings in this section apply to
both the builtin webserver (started by :hg:`serve`) and the script you
run through a webserver (``hgweb.cgi`` and the derivatives for FastCGI
and WSGI).