hgrc.5.txt
983 lines
| 35.7 KiB
| text/plain
|
TextLexer
/ doc / hgrc.5.txt
|
r9158 | ====== | ||
hgrc | ||||
====== | ||||
|
r671 | |||
|
r9158 | --------------------------------- | ||
configuration files for Mercurial | ||||
--------------------------------- | ||||
:Author: Bryan O'Sullivan <bos@serpentine.com> | ||||
:Organization: Mercurial | ||||
:Manual section: 5 | ||||
:Manual group: Mercurial Manual | ||||
|
r9422 | .. contents:: | ||
:backlinks: top | ||||
:class: htmlonly | ||||
|
r671 | |||
|
r9792 | Synopsis | ||
|
r671 | -------- | ||
The Mercurial system uses a set of configuration files to control | ||||
|
r8773 | aspects of its behavior. | ||
|
r671 | |||
|
r9792 | Files | ||
|
r671 | ----- | ||
|
r1583 | Mercurial reads configuration data from several files, if they exist. | ||
The names of these files depend on the system on which Mercurial is | ||||
|
r9161 | installed. ``*.rc`` files from a single directory are read in | ||
|
r8782 | alphabetical order, later ones overriding earlier ones. Where multiple | ||
|
r9659 | paths are given below, settings from earlier paths override later | ||
|
r8782 | ones. | ||
|
r951 | |||
|
r9158 | | (Unix, Windows) ``<repo>/.hg/hgrc`` | ||
|
r671 | Per-repository configuration options that only apply in a | ||
|
r6446 | particular repository. This file is not version-controlled, and | ||
will not get transferred during a "clone" operation. Options in | ||||
|
r8730 | 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 | ||||
|
r9702 | trusted_ section below for more details. | ||
|
r671 | |||
|
r9659 | | (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. | ||||
|
r10388 | | (Windows) ``<install-dir>\Mercurial.ini`` | ||
| (Windows) ``<install-dir>\hgrc.d\*.rc`` | ||||
|
r9659 | | (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 | ||||
|
r10388 | be read. Mercurial checks each of these locations in the specified | ||
order until one or more configuration files are detected. If the | ||||
|
r10391 | pywin32 extensions are not installed, Mercurial will only look for | ||
|
r10388 | site-wide configuration in ``C:\Mercurial\Mercurial.ini``. | ||
|
r9659 | |||
|
r9792 | Syntax | ||
|
r671 | ------ | ||
|
r9624 | A configuration file consists of sections, led by a ``[section]`` header | ||
|
r9784 | and followed by ``name = value`` entries:: | ||
|
r671 | |||
[spam] | ||||
eggs=ham | ||||
green= | ||||
eggs | ||||
|
r6446 | Each line contains one entry. If the lines that follow are indented, | ||
|
r9701 | 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. | ||||
|
r671 | |||
|
r9624 | A line of the form ``%include file`` will include ``file`` into the | ||
|
r9376 | current configuration file. The inclusion is recursive, which means | ||
that included files can include other files. Filenames are relative to | ||||
|
r9377 | the configuration file in which the ``%include`` directive is found. | ||
|
r9376 | |||
|
r9624 | A line with ``%unset name`` will remove ``name`` from the current | ||
|
r9380 | section, if it has been set previously. | ||
|
r9376 | |||
|
r9792 | Sections | ||
|
r671 | -------- | ||
This section describes the different sections that may appear in a | ||||
|
r8730 | Mercurial "hgrc" file, the purpose of each section, its possible keys, | ||
and their possible values. | ||||
|
r671 | |||
|
r9158 | ``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:: | ||||
|
r8769 | |||
|
r8655 | <alias> = <command> [<argument]... | ||
|
r8769 | |||
|
r9158 | For example, this definition:: | ||
|
r8769 | |||
|
r8655 | latest = log --limit 5 | ||
|
r8769 | |||
|
r9161 | creates a new command ``latest`` that shows only the five most recent | ||
|
r9158 | changesets. You can define subsequent aliases using earlier ones:: | ||
|
r8769 | |||
|
r8655 | stable5 = latest -b stable | ||
|
r8769 | |||
|
r9700 | .. 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! | ||||
|
r9158 | |||
|
r8655 | |||
|
r9158 | ``auth`` | ||
"""""""" | ||||
|
r8769 | Authentication credentials for HTTP authentication. Each line has | ||
|
r9158 | the following format:: | ||
|
r8333 | |||
<name>.<argument> = <value> | ||||
|
r9158 | |||
|
r9835 | where ``<name>`` is used to group arguments into authentication | ||
entries. Example:: | ||||
|
r8333 | |||
foo.prefix = hg.intevation.org/mercurial | ||||
foo.username = foo | ||||
foo.password = bar | ||||
foo.schemes = http https | ||||
|
r8847 | bar.prefix = secure.example.org | ||
bar.key = path/to/file.key | ||||
bar.cert = path/to/file.cert | ||||
bar.schemes = https | ||||
|
r8769 | Supported arguments: | ||
|
r8333 | |||
|
r9158 | ``prefix`` | ||
|
r9624 | Either ``*`` or a URI prefix with or without the scheme part. | ||
|
r8782 | The authentication entry with the longest matching prefix is used | ||
|
r9624 | (where ``*`` matches everything and counts as a match of length | ||
|
r8782 | 1). If the prefix doesn't include a scheme, the match is performed | ||
|
r8730 | against the URI with its scheme stripped as well, and the schemes | ||
argument, q.v., is then subsequently consulted. | ||||
|
r9158 | ``username`` | ||
|
r8847 | Optional. Username to authenticate with. If not given, and the | ||
remote site requires basic or digest authentication, the user | ||||
will be prompted for it. | ||||
|
r9158 | ``password`` | ||
|
r8847 | Optional. Password to authenticate with. If not given, and the | ||
remote site requires basic or digest authentication, the user | ||||
|
r8730 | will be prompted for it. | ||
|
r9158 | ``key`` | ||
|
r8847 | Optional. PEM encoded client certificate key file. | ||
|
r9158 | ``cert`` | ||
|
r8847 | Optional. PEM encoded client certificate chain file. | ||
|
r9158 | ``schemes`` | ||
|
r8730 | 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. | ||||
|
r8333 | Default: https. | ||
|
r8769 | If no suitable authentication entry is found, the user is prompted | ||
for credentials as usual if required by the remote. | ||||
|
r9158 | |||
|
r8333 | |||
|
r9158 | ``decode/encode`` | ||
""""""""""""""""" | ||||
Filters for transforming files on checkout/checkin. This would | ||||
typically be used for newline processing or other | ||||
localization/canonicalization of files. | ||||
|
r8769 | Filters consist of a filter pattern followed by a filter command. | ||
Filter patterns are globs by default, rooted at the repository root. | ||||
|
r9624 | 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``. | ||||
|
r10211 | For each file only the first matching filter applies. | ||
|
r1258 | |||
|
r9835 | The filter command can start with a specifier, either ``pipe:`` or | ||
``tempfile:``. If no specifier is given, ``pipe:`` is used by default. | ||||
|
r1293 | |||
|
r9835 | A ``pipe:`` command must accept data on stdin and return the transformed | ||
|
r8782 | data on stdout. | ||
|
r1293 | |||
|
r9158 | Pipe example:: | ||
|
r1258 | |||
|
r8769 | [encode] | ||
# uncompress gzip files on checkin to improve delta compression | ||||
# note: not necessarily a good idea, just an example | ||||
*.gz = pipe: gunzip | ||||
|
r1258 | |||
|
r8769 | [decode] | ||
# recompress gzip files when writing them to the working dir (we | ||||
# can safely omit "pipe:", because it's the default) | ||||
*.gz = gzip | ||||
|
r1258 | |||
|
r9835 | A ``tempfile:`` command is a template. The string ``INFILE`` is replaced | ||
|
r8769 | with the name of a temporary file that contains the data to be | ||
|
r9835 | filtered by the command. The string ``OUTFILE`` is replaced with the name | ||
|
r8782 | of an empty temporary file, where the filtered data must be written by | ||
the command. | ||||
|
r1293 | |||
|
r9700 | .. 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. | ||||
|
r1293 | |||
|
r8769 | The most common usage is for LF <-> CRLF translation on Windows. For | ||
|
r9158 | this, use the "smart" converters which check for binary files:: | ||
|
r1293 | |||
|
r8769 | [extensions] | ||
hgext.win32text = | ||||
[encode] | ||||
** = cleverencode: | ||||
[decode] | ||||
** = cleverdecode: | ||||
|
r5678 | |||
|
r9158 | or if you only want to translate certain files:: | ||
|
r5678 | |||
|
r8769 | [extensions] | ||
hgext.win32text = | ||||
[encode] | ||||
**.txt = dumbencode: | ||||
[decode] | ||||
**.txt = dumbdecode: | ||||
|
r9158 | |||
``defaults`` | ||||
"""""""""""" | ||||
|
r1293 | |||
|
r9630 | (defaults are deprecated. Don't use them. Use aliases instead) | ||
|
r9835 | Use the ``[defaults]`` section to define command defaults, i.e. the | ||
|
r9158 | default options/arguments to pass to the specified commands. | ||
|
r9746 | The following example makes ``hg log`` run in verbose mode, and ``hg | ||
status`` show only the modified files, by default:: | ||||
|
r5081 | |||
|
r8769 | [defaults] | ||
log = -v | ||||
status = -m | ||||
|
r5081 | |||
|
r8769 | 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. | ||||
|
r9158 | |||
``diff`` | ||||
"""""""" | ||||
|
r3039 | |||
|
r9158 | Settings used when displaying diffs. They are all Boolean and | ||
defaults to False. | ||||
``git`` | ||||
|
r4011 | Use git extended diff format. | ||
|
r9158 | ``nodates`` | ||
|
r4011 | Don't include dates in diff headers. | ||
|
r9158 | ``showfunc`` | ||
|
r4011 | Show which function each change is in. | ||
|
r9158 | ``ignorews`` | ||
|
r4011 | Ignore white space when comparing lines. | ||
|
r9158 | ``ignorewsamount`` | ||
|
r4011 | Ignore changes in the amount of white space. | ||
|
r9158 | ``ignoreblanklines`` | ||
|
r4011 | Ignore changes whose lines are all blank. | ||
|
r9158 | ``email`` | ||
""""""""" | ||||
Settings for extensions that send email messages. | ||||
``from`` | ||||
|
r6446 | Optional. Email address to use in "From" header and SMTP envelope | ||
|
r2200 | of outgoing messages. | ||
|
r9158 | ``to`` | ||
|
r6446 | Optional. Comma-separated list of recipients' email addresses. | ||
|
r9158 | ``cc`` | ||
|
r6446 | Optional. Comma-separated list of carbon copy recipients' | ||
|
r2691 | email addresses. | ||
|
r9158 | ``bcc`` | ||
|
r8730 | Optional. Comma-separated list of blind carbon copy recipients' | ||
|
r10283 | email addresses. | ||
|
r9158 | ``method`` | ||
|
r9835 | Optional. Method to use to send email messages. If value is ``smtp`` | ||
|
r9702 | (default), use SMTP (see the SMTP_ section for configuration). | ||
|
r8730 | Otherwise, use as name of program to run that acts like sendmail | ||
|
r9835 | (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. | ||||
|
r9158 | ``charsets`` | ||
|
r8773 | 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 | ||||
|
r9161 | (``$HGENCODING``, ``ui.fallbackencoding``) succeeds. If correct | ||
|
r8773 | conversion fails, the text in question is sent as is. Defaults to | ||
empty (explicit) list. | ||||
|
r9158 | |||
|
r9744 | Order of outgoing email character sets: | ||
|
r7241 | |||
|
r9744 | 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 | ||||
|
r2292 | |||
|
r9158 | Email example:: | ||
|
r2292 | |||
|
r8769 | [email] | ||
from = Joseph User <joe.user@example.com> | ||||
method = /usr/sbin/sendmail | ||||
|
r8773 | # charsets for western Europeans | ||
|
r8769 | # us-ascii, utf-8 omitted, as they are tried first and last | ||
charsets = iso-8859-1, iso-8859-15, windows-1252 | ||||
|
r9158 | |||
|
r2200 | |||
|
r9158 | ``extensions`` | ||
"""""""""""""" | ||||
|
r2200 | |||
|
r9158 | Mercurial has an extension mechanism for adding new features. To | ||
enable an extension, create an entry for it in this section. | ||||
|
r8769 | If you know that the extension is already in Python's search path, | ||
|
r9624 | you can give the name of the module, followed by ``=``, with nothing | ||
after the ``=``. | ||||
|
r2211 | |||
|
r9624 | Otherwise, give a name that you choose, followed by ``=``, followed by | ||
the path to the ``.py`` file (including the file name extension) that | ||||
|
r8769 | defines the extension. | ||
|
r2211 | |||
|
r8769 | To explicitly disable an extension that is enabled in an hgrc of | ||
|
r9624 | broader scope, prepend its path with ``!``, as in | ||
``hgext.foo = !/ext/path`` or ``hgext.foo = !`` when path is not | ||||
|
r8769 | supplied. | ||
|
r9161 | Example for ``~/.hgrc``:: | ||
|
r6175 | |||
|
r8769 | [extensions] | ||
|
r8773 | # (the mq extension will get loaded from Mercurial's path) | ||
|
r8769 | hgext.mq = | ||
# (this extension will get loaded from the file specified) | ||||
myfeature = ~/.hgext/myfeature.py | ||||
|
r9158 | |||
|
r2387 | |||
|
r9158 | ``format`` | ||
"""""""""" | ||||
|
r4163 | |||
|
r9158 | ``usestore`` | ||
|
r4163 | 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 | ||||
|
r7235 | compatibility and ensures that the on-disk format of newly created | ||
repositories will be compatible with Mercurial before version 0.9.4. | ||||
|
r9158 | ``usefncache`` | ||
|
r7235 | Enable or disable the "fncache" repository format which enhances | ||
the "store" repository format (which has to be enabled to use | ||||
|
r8730 | 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. | ||||
|
r4163 | |||
|
r9158 | ``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:: | ||||
|
r8769 | [merge-patterns] | ||
**.c = kdiff3 | ||||
**.jpg = myimgmerge | ||||
|
r6010 | |||
|
r9158 | ``merge-tools`` | ||
""""""""""""""" | ||||
This section configures external merge tools to use for file-level | ||||
merges. | ||||
|
r9161 | Example ``~/.hgrc``:: | ||
|
r6010 | |||
|
r8769 | [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 | ||||
|
r6010 | |||
|
r8769 | # Define new tool | ||
myHtmlTool.args = -m $local $other $base $output | ||||
myHtmlTool.regkey = Software\FooSoftware\HtmlMerge | ||||
myHtmlTool.priority = 1 | ||||
|
r6010 | |||
|
r8769 | Supported arguments: | ||
|
r6445 | |||
|
r9158 | ``priority`` | ||
|
r8769 | The priority in which to evaluate this tool. | ||
Default: 0. | ||||
|
r9158 | ``executable`` | ||
|
r8769 | Either just the name of the executable or its pathname. | ||
Default: the tool name. | ||||
|
r9158 | ``args`` | ||
|
r8769 | The arguments to pass to the tool executable. You can refer to the | ||
files being merged as well as the output file through these | ||||
|
r9161 | variables: ``$base``, ``$local``, ``$other``, ``$output``. | ||
Default: ``$local $base $other`` | ||||
|
r9158 | ``premerge`` | ||
|
r8769 | Attempt to run internal non-interactive 3-way merge tool before | ||
launching external tool. | ||||
Default: True | ||||
|
r9158 | ``binary`` | ||
|
r8769 | This tool can merge binary files. Defaults to False, unless tool | ||
was selected by file pattern match. | ||||
|
r9158 | ``symlink`` | ||
|
r8769 | This tool can merge symlinks. Defaults to False, even if tool was | ||
selected by file pattern match. | ||||
|
r9158 | ``checkconflicts`` | ||
|
r8769 | Check whether there are conflicts even though the tool reported | ||
success. | ||||
Default: False | ||||
|
r9158 | ``checkchanged`` | ||
|
r8769 | Check whether outputs were written even though the tool reported | ||
success. | ||||
Default: False | ||||
|
r9158 | ``fixeol`` | ||
|
r8769 | Attempt to fix up EOL changes caused by the merge tool. | ||
Default: False | ||||
|
r9158 | ``gui`` | ||
|
r8769 | This tool requires a graphical interface to run. Default: False | ||
|
r9158 | ``regkey`` | ||
|
r8769 | Windows registry key which describes install location of this | ||
tool. Mercurial will search for this key first under | ||||
|
r9161 | ``HKEY_CURRENT_USER`` and then under ``HKEY_LOCAL_MACHINE``. | ||
|
r8769 | Default: None | ||
|
r9158 | ``regname`` | ||
|
r8769 | Name of value to read from specified registry key. Defaults to the | ||
unnamed (default) value. | ||||
|
r9158 | ``regappend`` | ||
|
r8769 | String to append to the value read from the registry, typically | ||
the executable name of the tool. | ||||
Default: None | ||||
|
r9158 | |||
|
r6010 | |||
|
r9158 | ``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 | ||||
value or setting it to an empty string. | ||||
|
r9161 | Example ``.hg/hgrc``:: | ||
|
r1485 | |||
|
r8769 | [hooks] | ||
|
r9830 | # update working directory after adding changesets | ||
changegroup.update = hg update | ||||
|
r8769 | # do not use the site-wide hook | ||
incoming = | ||||
incoming.email = /my/email/hook | ||||
incoming.autobuild = /my/build/hook | ||||
|
r1485 | |||
|
r8769 | Most hooks are run with environment variables set that give useful | ||
additional information. For each hook below, the environment | ||||
|
r9746 | variables it is passed are listed with names of the form ``$HG_foo``. | ||
|
r1727 | |||
|
r9158 | ``changegroup`` | ||
|
r8769 | Run after a changegroup has been added via push, pull or unbundle. | ||
|
r9161 | ID of the first new changeset is in ``$HG_NODE``. URL from which | ||
changes came is in ``$HG_URL``. | ||||
|
r9158 | ``commit`` | ||
|
r8769 | Run after a changeset has been created in the local repository. ID | ||
|
r9161 | of the newly created changeset is in ``$HG_NODE``. Parent changeset | ||
IDs are in ``$HG_PARENT1`` and ``$HG_PARENT2``. | ||||
|
r9158 | ``incoming`` | ||
|
r8769 | Run after a changeset has been pulled, pushed, or unbundled into | ||
the local repository. The ID of the newly arrived changeset is in | ||||
|
r9161 | ``$HG_NODE``. URL that was source of changes came is in ``$HG_URL``. | ||
|
r9158 | ``outgoing`` | ||
|
r8769 | Run after sending changes from local repository to another. ID of | ||
|
r9161 | first changeset sent is in ``$HG_NODE``. Source of operation is in | ||
``$HG_SOURCE``; see "preoutgoing" hook for description. | ||||
|
r9158 | ``post-<command>`` | ||
|
r8769 | Run after successful invocations of the associated command. The | ||
|
r9161 | contents of the command line are passed as ``$HG_ARGS`` and the result | ||
code in ``$HG_RESULT``. Hook failure is ignored. | ||||
|
r9158 | ``pre-<command>`` | ||
|
r8769 | Run before executing the associated command. The contents of the | ||
|
r9161 | command line are passed as ``$HG_ARGS``. If the hook returns failure, | ||
|
r8769 | the command doesn't execute and Mercurial returns the failure | ||
code. | ||||
|
r9158 | ``prechangegroup`` | ||
|
r8769 | Run before a changegroup is added via push, pull or unbundle. Exit | ||
status 0 allows the changegroup to proceed. Non-zero status will | ||||
cause the push, pull or unbundle to fail. URL from which changes | ||||
|
r9161 | will come is in ``$HG_URL``. | ||
|
r9158 | ``precommit`` | ||
|
r8769 | Run before starting a local commit. Exit status 0 allows the | ||
commit to proceed. Non-zero status will cause the commit to fail. | ||||
|
r9161 | Parent changeset IDs are in ``$HG_PARENT1`` and ``$HG_PARENT2``. | ||
|
r9158 | ``preoutgoing`` | ||
|
r8769 | Run before collecting changes to send from the local repository to | ||
another. Non-zero status will cause failure. This lets you prevent | ||||
|
r8773 | pull over HTTP or SSH. Also prevents against local pull, push | ||
|
r8769 | (outbound) or bundle commands, but not effective, since you can | ||
just copy files instead then. Source of operation is in | ||||
|
r9161 | ``$HG_SOURCE``. If "serve", operation is happening on behalf of remote | ||
|
r8773 | SSH or HTTP repository. If "push", "pull" or "bundle", operation | ||
|
r8769 | is happening on behalf of repository on same system. | ||
|
r9158 | ``pretag`` | ||
|
r8769 | Run before creating a tag. Exit status 0 allows the tag to be | ||
created. Non-zero status will cause the tag to fail. ID of | ||||
|
r9161 | changeset to tag is in ``$HG_NODE``. Name of tag is in ``$HG_TAG``. Tag is | ||
local if ``$HG_LOCAL=1``, in repository if ``$HG_LOCAL=0``. | ||||
|
r9158 | ``pretxnchangegroup`` | ||
|
r8769 | Run after a changegroup has been added via push, pull or unbundle, | ||
but before the transaction has been committed. Changegroup is | ||||
visible to hook program. This lets you validate incoming changes | ||||
before accepting them. Passed the ID of the first new changeset in | ||||
|
r9161 | ``$HG_NODE``. Exit status 0 allows the transaction to commit. Non-zero | ||
|
r8769 | status will cause the transaction to be rolled back and the push, | ||
pull or unbundle will fail. URL that was source of changes is in | ||||
|
r9161 | ``$HG_URL``. | ||
|
r9158 | ``pretxncommit`` | ||
|
r8769 | Run after a changeset has been created but the transaction not yet | ||
committed. Changeset is visible to hook program. This lets you | ||||
validate commit message and changes. Exit status 0 allows the | ||||
commit to proceed. Non-zero status will cause the transaction to | ||||
|
r9161 | be rolled back. ID of changeset is in ``$HG_NODE``. Parent changeset | ||
IDs are in ``$HG_PARENT1`` and ``$HG_PARENT2``. | ||||
|
r9158 | ``preupdate`` | ||
|
r8769 | Run before updating the working directory. Exit status 0 allows | ||
the update to proceed. Non-zero status will prevent the update. | ||||
|
r9161 | Changeset ID of first new parent is in ``$HG_PARENT1``. If merge, ID | ||
of second new parent is in ``$HG_PARENT2``. | ||||
|
r9158 | ``tag`` | ||
|
r9161 | Run after a tag is created. ID of tagged changeset is in ``$HG_NODE``. | ||
Name of tag is in ``$HG_TAG``. Tag is local if ``$HG_LOCAL=1``, in | ||||
repository if ``$HG_LOCAL=0``. | ||||
|
r9158 | ``update`` | ||
|
r8769 | Run after updating the working directory. Changeset ID of first | ||
|
r9161 | new parent is in ``$HG_PARENT1``. If merge, ID of second new parent is | ||
in ``$HG_PARENT2``. If the update succeeded, ``$HG_ERROR=0``. If the | ||||
update failed (e.g. because conflicts not resolved), ``$HG_ERROR=1``. | ||||
|
r1726 | |||
|
r9700 | .. note:: It is generally better to use standard hooks rather than the | ||
generic pre- and post- command hooks as they are guaranteed to be | ||||
called in the appropriate contexts for influencing transactions. | ||||
Also, hooks like "commit" will be called in all contexts that | ||||
generate a commit (e.g. tag) and not just the commit command. | ||||
|
r671 | |||
|
r9700 | .. note:: Environment variables with empty values may not be passed to | ||
hooks on platforms such as Windows. As an example, ``$HG_PARENT2`` | ||||
will have an empty value under Unix-like platforms for non-merge | ||||
changesets, while it will not be available at all under Windows. | ||||
|
r4641 | |||
|
r9158 | The syntax for Python hooks is as follows:: | ||
|
r2155 | |||
|
r8769 | hookname = python:modulename.submodule.callable | ||
hookname = python:/path/to/python/module.py:callable | ||||
|
r2155 | |||
|
r8769 | Python hooks are run within the Mercurial process. Each hook is | ||
called with at least three keyword arguments: a ui object (keyword | ||||
|
r9835 | ``ui``), a repository object (keyword ``repo``), and a ``hooktype`` | ||
|
r8769 | keyword that tells what kind of hook is used. Arguments listed as | ||
environment variables above are passed as keyword arguments, with no | ||||
|
r9624 | ``HG_`` prefix, and names in lower case. | ||
|
r2155 | |||
|
r8769 | If a Python hook returns a "true" value or raises an exception, this | ||
is treated as a failure. | ||||
|
r9158 | |||
|
r2155 | |||
|
r9158 | ``http_proxy`` | ||
"""""""""""""" | ||||
Used to access web-based Mercurial repositories through a HTTP | ||||
proxy. | ||||
``host`` | ||||
|
r671 | Host name and (optional) port of the proxy server, for example | ||
"myproxy:8000". | ||||
|
r9158 | ``no`` | ||
|
r6446 | Optional. Comma-separated list of host names that should bypass | ||
|
r671 | the proxy. | ||
|
r9158 | ``passwd`` | ||
|
r6446 | Optional. Password to authenticate with at the proxy server. | ||
|
r9158 | ``user`` | ||
|
r6446 | Optional. User name to authenticate with at the proxy server. | ||
|
r671 | |||
|
r9158 | ``smtp`` | ||
"""""""" | ||||
Configuration for extensions that need to send email messages. | ||||
``host`` | ||||
|
r2853 | Host name of mail server, e.g. "mail.example.com". | ||
|
r9158 | ``port`` | ||
|
r6446 | Optional. Port to connect to on mail server. Default: 25. | ||
|
r9158 | ``tls`` | ||
|
r6446 | Optional. Whether to connect to mail server using TLS. True or | ||
False. Default: False. | ||||
|
r9158 | ``username`` | ||
|
r8730 | Optional. User name to authenticate to SMTP server with. If | ||
username is specified, password must also be specified. | ||||
|
r2200 | Default: none. | ||
|
r9158 | ``password`` | ||
|
r8730 | Optional. Password to authenticate to SMTP server with. If | ||
username is specified, password must also be specified. | ||||
|
r2200 | Default: none. | ||
|
r9158 | ``local_hostname`` | ||
|
r8730 | Optional. It's the hostname that the sender can use to identify | ||
itself to the MTA. | ||||
|
r2200 | |||
|
r9158 | |||
``patch`` | ||||
""""""""" | ||||
Settings used when applying patches, for instance through the 'import' | ||||
command or with Mercurial Queues extension. | ||||
``eol`` | ||||
|
r8810 | When set to 'strict' patch content and patched files end of lines | ||
|
r10127 | are preserved. When set to ``lf`` or ``crlf``, both files end of | ||
lines are ignored when patching and the result line endings are | ||||
|
r10102 | normalized to either LF (Unix) or CRLF (Windows). When set to | ||
``auto``, end of lines are again ignored while patching but line | ||||
endings in patched files are normalized to their original setting | ||||
|
r10127 | on a per-file basis. If target file does not exist or has no end | ||
of line, patch line endings are preserved. | ||||
|
r8810 | Default: strict. | ||
|
r9158 | |||
``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`` | ||||
|
r2277 | Directory or URL to use when pulling if no source is specified. | ||
|
r8730 | Default is set to repository from which the current repository was | ||
cloned. | ||||
|
r9158 | ``default-push`` | ||
|
r6446 | Optional. Directory or URL to use when pushing if no destination | ||
|
r2277 | is specified. | ||
|
r671 | |||
|
r9158 | |||
``profiling`` | ||||
""""""""""""" | ||||
Specifies profiling format and file output. In this section | ||||
description, 'profiling data' stands for the raw data collected | ||||
during profiling, while 'profiling report' stands for a statistical | ||||
text report generated from the profiling data. The profiling is done | ||||
using lsprof. | ||||
``format`` | ||||
|
r8023 | Profiling format. | ||
Default: text. | ||||
|
r9158 | |||
``text`` | ||||
|
r8730 | Generate a profiling report. When saving to a file, it should be | ||
noted that only the report is saved, and the profiling data is | ||||
not kept. | ||||
|
r9158 | ``kcachegrind`` | ||
|
r8730 | Format profiling data for kcachegrind use: when saving to a | ||
file, the generated file can directly be loaded into | ||||
kcachegrind. | ||||
|
r9158 | ``output`` | ||
|
r8730 | File path where profiling data or report should be saved. If the | ||
file exists, it is replaced. Default: None, data is printed on | ||||
stderr | ||||
|
r8022 | |||
|
r9158 | ``server`` | ||
"""""""""" | ||||
Controls generic server settings. | ||||
``uncompressed`` | ||||
|
r8773 | Whether to allow clients to clone a repository using the | ||
uncompressed streaming protocol. This transfers about 40% more | ||||
data than a regular clone, but uses less memory and CPU on both | ||||
server and client. Over a LAN (100 Mbps or better) or a very fast | ||||
WAN, an uncompressed streaming clone is a lot faster (~10x) than a | ||||
regular clone. Over most WAN connections (anything slower than | ||||
about 6 Mbps), uncompressed streaming is slower, because of the | ||||
extra data transfer overhead. Default is False. | ||||
|
r2621 | |||
|
r9158 | |||
``trusted`` | ||||
""""""""""" | ||||
For security reasons, Mercurial will not use the settings in the | ||||
|
r9161 | ``.hg/hgrc`` file from a repository if it doesn't belong to a trusted | ||
|
r9158 | user or to a trusted group. The main exception is the web interface, | ||
which automatically uses some safe settings, since it's common to | ||||
serve repositories from different users. | ||||
|
r8769 | This section specifies what users and groups are trusted. The | ||
current user is always trusted. To trust everybody, list a user or a | ||||
|
r9624 | group with name ``*``. | ||
|
r3552 | |||
|
r9158 | ``users`` | ||
|
r8769 | Comma-separated list of trusted users. | ||
|
r9158 | ``groups`` | ||
|
r8769 | Comma-separated list of trusted groups. | ||
|
r9158 | |||
|
r3551 | |||
|
r9158 | ``ui`` | ||
"""""" | ||||
User interface controls. | ||||
``archivemeta`` | ||||
|
r8773 | Whether to include the .hg_archival.txt file containing meta data | ||
|
r8730 | (hashes for the repository base and for tip) in archives created | ||
by the hg archive command or downloaded via hgweb. | ||||
|
r9699 | Default is True. | ||
|
r9158 | ``askusername`` | ||
|
r6862 | Whether to prompt for a username when committing. If True, and | ||
|
r9161 | neither ``$HGUSER`` nor ``$EMAIL`` has been specified, then the user will | ||
|
r8730 | be prompted to enter a username. If no username is entered, the | ||
|
r9745 | default ``USER@HOST`` is used instead. | ||
|
r6862 | Default is False. | ||
|
r9158 | ``debug`` | ||
|
r6446 | Print debugging information. True or False. Default is False. | ||
|
r9158 | ``editor`` | ||
|
r9746 | The editor to use during a commit. Default is ``$EDITOR`` or ``vi``. | ||
|
r9158 | ``fallbackencoding`` | ||
|
r3835 | Encoding to try if it's not possible to decode the changelog using | ||
|
r6446 | UTF-8. Default is ISO-8859-1. | ||
|
r9158 | ``ignore`` | ||
|
r8730 | A file to read per-user ignore patterns from. This file should be | ||
in the same format as a repository-wide .hgignore file. This | ||||
option supports hook syntax, so if you want to specify multiple | ||||
ignore files, you can do so by setting something like | ||||
|
r9624 | ``ignore.other = ~/.hgignore2``. For details of the ignore file | ||
|
r9162 | format, see the |hgignore(5)|_ man page. | ||
|
r9158 | ``interactive`` | ||
|
r6446 | Allow to prompt the user. True or False. Default is True. | ||
|
r9158 | ``logtemplate`` | ||
|
r1907 | Template string for commands that print changesets. | ||
|
r9158 | ``merge`` | ||
|
r671 | The conflict resolution program to use during a manual merge. | ||
|
r6010 | There are some internal tools available: | ||
|
r9158 | |||
``internal:local`` | ||||
|
r6010 | keep the local version | ||
|
r9158 | ``internal:other`` | ||
|
r6010 | use the other version | ||
|
r9158 | ``internal:merge`` | ||
|
r6010 | use the internal non-interactive merge tool | ||
|
r9158 | ``internal:fail`` | ||
|
r6010 | fail to merge | ||
|
r9158 | |||
|
r8769 | For more information on configuring merge tools see the | ||
|
r9702 | merge-tools_ section. | ||
|
r6445 | |||
|
r9158 | ``patch`` | ||
|
r9746 | command to use to apply patches. Look for ``gpatch`` or ``patch`` in | ||
|
r8730 | PATH if unset. | ||
|
r9158 | ``quiet`` | ||
|
r6446 | Reduce the amount of output printed. True or False. Default is False. | ||
|
r9158 | ``remotecmd`` | ||
|
r9746 | remote command to use for clone/push/pull operations. Default is ``hg``. | ||
|
r9158 | ``report_untrusted`` | ||
|
r9161 | Warn if a ``.hg/hgrc`` file is ignored due to not being owned by a | ||
|
r6446 | trusted user or group. True or False. Default is True. | ||
|
r9158 | ``slash`` | ||
|
r9624 | Display paths using a slash (``/``) as the path separator. This | ||
|
r8782 | only makes a difference on systems where the default path | ||
separator is not the slash character (e.g. Windows uses the | ||||
|
r9624 | backslash character (``\``)). | ||
|
r4527 | Default is False. | ||
|
r9158 | ``ssh`` | ||
|
r9746 | command to use for SSH connections. Default is ``ssh``. | ||
|
r9158 | ``strict`` | ||
|
r2988 | Require exact command names, instead of allowing unambiguous | ||
|
r6446 | abbreviations. True or False. Default is False. | ||
|
r9158 | ``style`` | ||
|
r4715 | Name of style to use for command output. | ||
|
r9158 | ``timeout`` | ||
|
r1787 | The timeout used when a lock is held (in seconds), a negative value | ||
|
r1788 | means no timeout. Default is 600. | ||
|
r9697 | ``traceback`` | ||
Mercurial always prints a traceback when an unknown exception | ||||
occurs. Setting this to True will make Mercurial print a traceback | ||||
on all exceptions, even those recognized by Mercurial (such as | ||||
IOError or MemoryError). Default is False. | ||||
|
r9158 | ``username`` | ||
|
r671 | The committer of a changeset created when running "commit". | ||
|
r9745 | Typically a person's name and email address, e.g. ``Fred Widget | ||
<fred@example.com>``. Default is ``$EMAIL`` or ``username@hostname``. If | ||||
|
r8730 | the username in hgrc is empty, it has to be specified manually or | ||
|
r9161 | in a different hgrc file (e.g. ``$HOME/.hgrc``, if the admin set | ||
|
r9746 | ``username =`` in the system hgrc). | ||
|
r9158 | ``verbose`` | ||
|
r6446 | Increase the amount of output printed. True or False. Default is False. | ||
|
r9158 | |||
|
r671 | |||
|
r9158 | ``web`` | ||
""""""" | ||||
Web interface configuration. | ||||
``accesslog`` | ||||
|
r938 | Where to output the access log. Default is stdout. | ||
|
r9158 | ``address`` | ||
|
r1171 | Interface address to bind to. Default is all. | ||
|
r9158 | ``allow_archive`` | ||
|
r2358 | List of archive format (bz2, gz, zip) allowed for downloading. | ||
Default is empty. | ||||
|
r9158 | ``allowbz2`` | ||
|
r8773 | (DEPRECATED) Whether to allow .tar.bz2 downloading of repository | ||
revisions. | ||||
|
r9699 | Default is False. | ||
|
r9158 | ``allowgz`` | ||
|
r8773 | (DEPRECATED) Whether to allow .tar.gz downloading of repository | ||
revisions. | ||||
|
r9699 | Default is False. | ||
|
r9158 | ``allowpull`` | ||
|
r9699 | Whether to allow pulling from the repository. Default is True. | ||
|
r9158 | ``allow_push`` | ||
|
r6446 | Whether to allow pushing to the repository. If empty or not set, | ||
|
r9624 | push is not allowed. If the special value ``*``, any remote user can | ||
|
r8730 | push, including unauthenticated users. Otherwise, the remote user | ||
must have been authenticated, and the authenticated user name must | ||||
|
r9746 | be present in this list (separated by whitespace or ``,``). The | ||
|
r8730 | contents of the allow_push list are examined after the deny_push | ||
list. | ||||
|
r9158 | ``allow_read`` | ||
|
r8730 | If the user has not already been denied repository access due to | ||
the contents of deny_read, this list determines whether to grant | ||||
repository access to the user. If this list is not empty, and the | ||||
user is unauthenticated or not present in the list (separated by | ||||
|
r9746 | whitespace or ``,``), then access is denied for the user. If the | ||
|
r8730 | list is empty or not set, then access is permitted to all users by | ||
|
r9624 | default. Setting allow_read to the special value ``*`` is equivalent | ||
|
r8730 | to it not being set (i.e. access is permitted to all users). The | ||
contents of the allow_read list are examined after the deny_read | ||||
list. | ||||
|
r9158 | ``allowzip`` | ||
|
r8773 | (DEPRECATED) Whether to allow .zip downloading of repository | ||
|
r9699 | revisions. Default is False. This feature creates temporary files. | ||
|
r9158 | ``baseurl`` | ||
|
r2197 | Base URL to use when publishing URLs in other locations, so | ||
|
r8730 | third-party tools like email notification hooks can construct | ||
|
r9745 | URLs. Example: ``http://hgserver/repos/``. | ||
|
r10409 | ``cacerts`` | ||
Path to file containing a list of PEM encoded certificate authorities | ||||
that may be used to verify an SSL server's identity. The form must be | ||||
as follows:: | ||||
-----BEGIN CERTIFICATE----- | ||||
... (certificate in base64 PEM encoding) ... | ||||
-----END CERTIFICATE----- | ||||
-----BEGIN CERTIFICATE----- | ||||
... (certificate in base64 PEM encoding) ... | ||||
-----END CERTIFICATE----- | ||||
This feature is only supported when using Python 2.6. If you wish to | ||||
use it with earlier versions of Python, install the backported | ||||
version of the ssl library that is available from | ||||
``http://pypi.python.org``. | ||||
You can use OpenSSL's CA certificate file if your platform has one. | ||||
On most Linux systems this will be ``/etc/ssl/certs/ca-certificates.crt``. | ||||
Otherwise you will have to generate this file manually. | ||||
|
r9158 | ``contact`` | ||
|
r2430 | Name or email address of the person in charge of the repository. | ||
|
r9161 | Defaults to ui.username or ``$EMAIL`` or "unknown" if unset or empty. | ||
|
r9158 | ``deny_push`` | ||
|
r6446 | Whether to deny pushing to the repository. If empty or not set, | ||
|
r9624 | push is not denied. If the special value ``*``, all remote users are | ||
|
r8730 | denied push. Otherwise, unauthenticated users are all denied, and | ||
any authenticated user name present in this list (separated by | ||||
|
r9746 | whitespace or ``,``) is also denied. The contents of the deny_push | ||
|
r2466 | list are examined before the allow_push list. | ||
|
r9158 | ``deny_read`` | ||
|
r8730 | Whether to deny reading/viewing of the repository. If this list is | ||
not empty, unauthenticated users are all denied, and any | ||||
authenticated user name present in this list (separated by | ||||
|
r9746 | whitespace or ``,``) is also denied access to the repository. If set | ||
|
r9624 | to the special value ``*``, all remote users are denied access | ||
|
r8730 | (rarely needed ;). If deny_read is empty or not set, the | ||
determination of repository access depends on the presence and | ||||
content of the allow_read list (see description). If both | ||||
deny_read and allow_read are empty or not set, then access is | ||||
permitted to all users by default. If the repository is being | ||||
served via hgwebdir, denied users will not be able to see it in | ||||
the list of repositories. The contents of the deny_read list have | ||||
priority over (are examined before) the contents of the allow_read | ||||
list. | ||||
|
r9363 | ``descend`` | ||
hgwebdir indexes will not descend into subdirectories. Only repositories | ||||
directly in the current path will be shown (other repositories are still | ||||
available from the index corresponding to their containing path). | ||||
|
r9158 | ``description`` | ||
|
r1171 | Textual description of the repository's purpose or contents. | ||
Default is "unknown". | ||||
|
r9158 | ``encoding`` | ||
|
r4715 | Character encoding name. | ||
Example: "UTF-8" | ||||
|
r9158 | ``errorlog`` | ||
|
r1171 | Where to output the error log. Default is stderr. | ||
|
r9158 | ``hidden`` | ||
|
r8730 | Whether to hide the repository in the hgwebdir index. | ||
|
r9699 | Default is False. | ||
|
r9158 | ``ipv6`` | ||
|
r9699 | Whether to use IPv6. Default is False. | ||
|
r9158 | ``name`` | ||
|
r1171 | Repository name to use in the web interface. Default is current | ||
working directory. | ||||
|
r9158 | ``maxchanges`` | ||
|
r1171 | Maximum number of changes to list on the changelog. Default is 10. | ||
|
r9158 | ``maxfiles`` | ||
|
r1171 | Maximum number of files to list per changeset. Default is 10. | ||
|
r9158 | ``port`` | ||
|
r1171 | Port to listen on. Default is 8000. | ||
|
r9158 | ``prefix`` | ||
|
r5972 | Prefix path to serve from. Default is '' (server root). | ||
|
r9158 | ``push_ssl`` | ||
|
r2466 | Whether to require that inbound pushes be transported over SSL to | ||
|
r9699 | prevent password sniffing. Default is True. | ||
|
r9158 | ``staticurl`` | ||
|
r8730 | Base URL to use for static files. If unset, static files (e.g. the | ||
hgicon.png favicon) will be served by the CGI script itself. Use | ||||
this setting to serve them directly with the HTTP server. | ||||
|
r9745 | Example: ``http://hgserver/static/``. | ||
|
r9158 | ``stripes`` | ||
|
r2666 | How many lines a "zebra stripe" should span in multiline output. | ||
Default is 1; set to 0 to disable. | ||||
|
r9158 | ``style`` | ||
|
r1171 | Which template map style to use. | ||
|
r9158 | ``templates`` | ||
|
r1171 | Where to find the HTML templates. Default is install path. | ||
|
r1079 | |||
|
r938 | |||
|
r9792 | Author | ||
|
r671 | ------ | ||
Bryan O'Sullivan <bos@serpentine.com>. | ||||
Mercurial was written by Matt Mackall <mpm@selenic.com>. | ||||
|
r9792 | See Also | ||
|
r671 | -------- | ||
|
r9162 | |hg(1)|_, |hgignore(5)|_ | ||
|
r671 | |||
|
r9792 | Copying | ||
|
r671 | ------- | ||
This manual page is copyright 2005 Bryan O'Sullivan. | ||||
|
r10209 | Mercurial is copyright 2005-2010 Matt Mackall. | ||
|
r671 | Free use of this software is granted under the terms of the GNU General | ||
|
r10263 | Public License version 2 or any later version. | ||
|
r9162 | |||
.. include:: common.txt | ||||