|
|
HGRC(5)
|
|
|
=======
|
|
|
Bryan O'Sullivan <bos@serpentine.com>
|
|
|
|
|
|
NAME
|
|
|
----
|
|
|
hgrc - configuration files for Mercurial
|
|
|
|
|
|
SYNOPSIS
|
|
|
--------
|
|
|
|
|
|
The Mercurial system uses a set of configuration files to control
|
|
|
aspects of its behaviour.
|
|
|
|
|
|
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.
|
|
|
|
|
|
(Unix) <install-root>/etc/mercurial/hgrc.d/*.rc::
|
|
|
(Unix) <install-root>/etc/mercurial/hgrc::
|
|
|
Per-installation configuration files, searched for in the
|
|
|
directory where Mercurial is installed. For example, if installed
|
|
|
in /shared/tools, 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.
|
|
|
|
|
|
(Unix) /etc/mercurial/hgrc.d/*.rc::
|
|
|
(Unix) /etc/mercurial/hgrc::
|
|
|
(Windows) C:\Mercurial\Mercurial.ini::
|
|
|
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) $HOME/.hgrc::
|
|
|
(Windows) C:\Documents and Settings\USERNAME\Mercurial.ini::
|
|
|
(Windows) $HOME\Mercurial.ini::
|
|
|
Per-user configuration file, for the user running Mercurial.
|
|
|
Options in this file apply to all Mercurial commands executed by
|
|
|
any user in any directory. Options in this file override
|
|
|
per-installation and per-system options.
|
|
|
On Windows system, one of these is chosen exclusively according
|
|
|
to definition of HOME environment variable.
|
|
|
|
|
|
(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.
|
|
|
|
|
|
SYNTAX
|
|
|
------
|
|
|
|
|
|
A configuration file consists of sections, led by a "[section]" header
|
|
|
and followed by "name: value" entries; "name=value" is also accepted.
|
|
|
|
|
|
[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.
|
|
|
|
|
|
The optional values can contain format strings which refer to other
|
|
|
values in the same section, or values in a special DEFAULT section.
|
|
|
|
|
|
Lines beginning with "#" or ";" are ignored and may be used to provide
|
|
|
comments.
|
|
|
|
|
|
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.
|
|
|
|
|
|
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".
|
|
|
|
|
|
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. In particular, if you are doing line ending
|
|
|
conversion on Windows using the popular dos2unix and unix2dos
|
|
|
programs, you *must* use the tempfile mechanism, as using pipes will
|
|
|
corrupt the contents of your files.
|
|
|
|
|
|
Tempfile example:
|
|
|
|
|
|
[encode]
|
|
|
# convert files to unix line ending conventions on checkin
|
|
|
**.txt = tempfile: dos2unix -n INFILE OUTFILE
|
|
|
|
|
|
[decode]
|
|
|
# convert files to windows line ending conventions when writing
|
|
|
# them to the working dir
|
|
|
**.txt = tempfile: unix2dos -n INFILE OUTFILE
|
|
|
|
|
|
defaults::
|
|
|
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. Cannot be set interactively.
|
|
|
method;;
|
|
|
Optional. Method to use to send email messages. If value is
|
|
|
"smtp" (default), use SMTP (see section "[smtp]" 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.
|
|
|
|
|
|
Email example:
|
|
|
|
|
|
[email]
|
|
|
from = Joseph User <joe.user@example.com>
|
|
|
method = /usr/sbin/sendmail
|
|
|
|
|
|
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.
|
|
|
|
|
|
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
|
|
|
|
|
|
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.
|
|
|
|
|
|
Example .hg/hgrc:
|
|
|
|
|
|
[hooks]
|
|
|
# do not use the site-wide hook
|
|
|
incoming =
|
|
|
incoming.email = /my/email/hook
|
|
|
incoming.autobuild = /my/build/hook
|
|
|
|
|
|
Most hooks are run with environment variables set that give added
|
|
|
useful information. For each hook below, the environment variables
|
|
|
it is passed are listed with names of the form "$HG_foo".
|
|
|
|
|
|
changegroup;;
|
|
|
Run after a changegroup has been added via push, pull or
|
|
|
unbundle. ID of the first new changeset is in $HG_NODE. URL from
|
|
|
which changes came is in $HG_URL.
|
|
|
commit;;
|
|
|
Run after a changeset has been created in the local repository.
|
|
|
ID of the newly created changeset is in $HG_NODE. Parent
|
|
|
changeset IDs are in $HG_PARENT1 and $HG_PARENT2.
|
|
|
incoming;;
|
|
|
Run after a changeset has been pulled, pushed, or unbundled into
|
|
|
the local repository. The ID of the newly arrived changeset is in
|
|
|
$HG_NODE. URL that was source of changes came is in $HG_URL.
|
|
|
outgoing;;
|
|
|
Run after sending changes from local repository to another. ID of
|
|
|
first changeset sent is in $HG_NODE. Source of operation is in
|
|
|
$HG_SOURCE; see "preoutgoing" hook for description.
|
|
|
prechangegroup;;
|
|
|
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 will come is in $HG_URL.
|
|
|
precommit;;
|
|
|
Run before starting a local commit. Exit status 0 allows the
|
|
|
commit to proceed. Non-zero status will cause the commit to fail.
|
|
|
Parent changeset IDs are in $HG_PARENT1 and $HG_PARENT2.
|
|
|
preoutgoing;;
|
|
|
Run before computing changes to send from the local repository to
|
|
|
another. Non-zero status will cause failure. This lets you
|
|
|
prevent pull over http or ssh. Also prevents against local pull,
|
|
|
push (outbound) or bundle commands, but not effective, since you
|
|
|
can just copy files instead then. Source of operation is in
|
|
|
$HG_SOURCE. If "serve", operation is happening on behalf of
|
|
|
remote ssh or http repository. If "push", "pull" or "bundle",
|
|
|
operation is happening on behalf of repository on same system.
|
|
|
pretag;;
|
|
|
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
|
|
|
changeset to tag is in $HG_NODE. Name of tag is in $HG_TAG. Tag
|
|
|
is local if $HG_LOCAL=1, in repo if $HG_LOCAL=0.
|
|
|
pretxnchangegroup;;
|
|
|
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 $HG_NODE. Exit status 0 allows the transaction to commit.
|
|
|
Non-zero 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 $HG_URL.
|
|
|
pretxncommit;;
|
|
|
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
|
|
|
be rolled back. ID of changeset is in $HG_NODE. Parent changeset
|
|
|
IDs are in $HG_PARENT1 and $HG_PARENT2.
|
|
|
preupdate;;
|
|
|
Run before updating the working directory. Exit status 0 allows
|
|
|
the update to proceed. Non-zero status will prevent the update.
|
|
|
Changeset ID of first new parent is in $HG_PARENT1. If merge, ID
|
|
|
of second new parent is in $HG_PARENT2.
|
|
|
tag;;
|
|
|
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 repo if $HG_LOCAL=0.
|
|
|
update;;
|
|
|
Run after updating the working directory. Changeset ID of first
|
|
|
new parent is in $HG_PARENT1. If merge, ID of second new parent
|
|
|
is in $HG_PARENT2. If update succeeded, $HG_ERROR=0. If update
|
|
|
failed (e.g. because conflicts not resolved), $HG_ERROR=1.
|
|
|
|
|
|
Note: In earlier releases, the names of hook environment variables
|
|
|
did not have a "HG_" prefix. The old unprefixed names are no longer
|
|
|
provided in the environment.
|
|
|
|
|
|
The syntax for Python hooks is as follows:
|
|
|
|
|
|
hookname = python:modulename.submodule.callable
|
|
|
|
|
|
Python hooks are run within the Mercurial process. Each hook is
|
|
|
called with at least three keyword arguments: a ui object (keyword
|
|
|
"ui"), a repository object (keyword "repo"), and a "hooktype"
|
|
|
keyword that tells what kind of hook is used. Arguments listed as
|
|
|
environment variables above are passed as keyword arguments, with no
|
|
|
"HG_" prefix, and names in lower case.
|
|
|
|
|
|
If a Python hook returns a "true" value or raises an exception, this
|
|
|
is treated as failure of the hook.
|
|
|
|
|
|
http_proxy::
|
|
|
Used to access web-based Mercurial repositories through a HTTP
|
|
|
proxy.
|
|
|
host;;
|
|
|
Host name and (optional) port of the proxy server, for example
|
|
|
"myproxy:8000".
|
|
|
no;;
|
|
|
Optional. Comma-separated list of host names that should bypass
|
|
|
the proxy.
|
|
|
passwd;;
|
|
|
Optional. Password to authenticate with at the proxy server.
|
|
|
user;;
|
|
|
Optional. User name to authenticate with at the proxy server.
|
|
|
|
|
|
smtp::
|
|
|
Configuration for extensions that need to send email messages.
|
|
|
host;;
|
|
|
Host name of mail server, e.g. "mail.example.com".
|
|
|
port;;
|
|
|
Optional. Port to connect to on mail server. Default: 25.
|
|
|
tls;;
|
|
|
Optional. Whether to connect to mail server using TLS. True or
|
|
|
False. Default: False.
|
|
|
username;;
|
|
|
Optional. User name to authenticate to SMTP server with.
|
|
|
If username is specified, password must also be specified.
|
|
|
Default: none.
|
|
|
password;;
|
|
|
Optional. Password to authenticate to SMTP server with.
|
|
|
If username is specified, password must also be specified.
|
|
|
Default: none.
|
|
|
local_hostname;;
|
|
|
Optional. It's the hostname that the sender can use to identify itself
|
|
|
to the MTA.
|
|
|
|
|
|
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;;
|
|
|
Directory or URL to use when pulling if no source is specified.
|
|
|
Default is set to repository from which the current repository
|
|
|
was cloned.
|
|
|
default-push;;
|
|
|
Optional. Directory or URL to use when pushing if no destination
|
|
|
is specified.
|
|
|
|
|
|
server::
|
|
|
Controls generic server settings.
|
|
|
uncompressed;;
|
|
|
Whether to allow clients to clone a repo 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 (100Mbps 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
|
|
|
6Mbps), uncompressed streaming is slower, because of the extra
|
|
|
data transfer overhead. Default is False.
|
|
|
|
|
|
trusted::
|
|
|
For security reasons, 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. The main exception is the
|
|
|
web interface, which automatically uses some safe settings, since
|
|
|
it's common to serve repositories from different users.
|
|
|
|
|
|
This section specifies what users and groups are trusted. The
|
|
|
current user is always trusted. To trust everybody, list a user
|
|
|
or a group with name "*".
|
|
|
|
|
|
users;;
|
|
|
Comma-separated list of trusted users.
|
|
|
groups;;
|
|
|
Comma-separated list of trusted groups.
|
|
|
|
|
|
ui::
|
|
|
User interface controls.
|
|
|
debug;;
|
|
|
Print debugging information. True or False. Default is False.
|
|
|
editor;;
|
|
|
The editor to use during a commit. Default is $EDITOR or "vi".
|
|
|
fallbackencoding;;
|
|
|
Encoding to try if it's not possible to decode the changelog using
|
|
|
UTF-8. Default is ISO-8859-1.
|
|
|
ignore;;
|
|
|
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
|
|
|
"ignore.other = ~/.hgignore2". For details of the ignore file
|
|
|
format, see the hgignore(5) man page.
|
|
|
interactive;;
|
|
|
Allow to prompt the user. True or False. Default is True.
|
|
|
logtemplate;;
|
|
|
Template string for commands that print changesets.
|
|
|
style;;
|
|
|
Name of style to use for command output.
|
|
|
merge;;
|
|
|
The conflict resolution program to use during a manual merge.
|
|
|
Default is "hgmerge".
|
|
|
quiet;;
|
|
|
Reduce the amount of output printed. True or False. Default is False.
|
|
|
remotecmd;;
|
|
|
remote command to use for clone/push/pull operations. Default is 'hg'.
|
|
|
ssh;;
|
|
|
command to use for SSH connections. Default is 'ssh'.
|
|
|
strict;;
|
|
|
Require exact command names, instead of allowing unambiguous
|
|
|
abbreviations. True or False. Default is False.
|
|
|
timeout;;
|
|
|
The timeout used when a lock is held (in seconds), a negative value
|
|
|
means no timeout. Default is 600.
|
|
|
username;;
|
|
|
The committer of a changeset created when running "commit".
|
|
|
Typically a person's name and email address, e.g. "Fred Widget
|
|
|
<fred@example.com>". Default is $EMAIL or username@hostname.
|
|
|
verbose;;
|
|
|
Increase the amount of output printed. True or False. Default is False.
|
|
|
|
|
|
|
|
|
web::
|
|
|
Web interface configuration.
|
|
|
accesslog;;
|
|
|
Where to output the access log. Default is stdout.
|
|
|
address;;
|
|
|
Interface address to bind to. Default is all.
|
|
|
allow_archive;;
|
|
|
List of archive format (bz2, gz, zip) allowed for downloading.
|
|
|
Default is empty.
|
|
|
allowbz2;;
|
|
|
(DEPRECATED) Whether to allow .tar.bz2 downloading of repo revisions.
|
|
|
Default is false.
|
|
|
allowgz;;
|
|
|
(DEPRECATED) Whether to allow .tar.gz downloading of repo revisions.
|
|
|
Default is false.
|
|
|
allowpull;;
|
|
|
Whether to allow pulling from the repository. Default is true.
|
|
|
allow_push;;
|
|
|
Whether to allow pushing to the repository. If empty or not set,
|
|
|
push is not allowed. If the special value "*", any remote user
|
|
|
can push, including unauthenticated users. Otherwise, the remote
|
|
|
user must have been authenticated, and the authenticated user name
|
|
|
must be present in this list (separated by whitespace or ",").
|
|
|
The contents of the allow_push list are examined after the
|
|
|
deny_push list.
|
|
|
allowzip;;
|
|
|
(DEPRECATED) Whether to allow .zip downloading of repo revisions.
|
|
|
Default is false. This feature creates temporary files.
|
|
|
baseurl;;
|
|
|
Base URL to use when publishing URLs in other locations, so
|
|
|
third-party tools like email notification hooks can construct URLs.
|
|
|
Example: "http://hgserver/repos/"
|
|
|
contact;;
|
|
|
Name or email address of the person in charge of the repository.
|
|
|
Default is "unknown".
|
|
|
deny_push;;
|
|
|
Whether to deny pushing to the repository. If empty or not set,
|
|
|
push is not denied. If the special value "*", all remote users
|
|
|
are denied push. Otherwise, unauthenticated users are all denied,
|
|
|
and any authenticated user name present in this list (separated by
|
|
|
whitespace or ",") is also denied. The contents of the deny_push
|
|
|
list are examined before the allow_push list.
|
|
|
description;;
|
|
|
Textual description of the repository's purpose or contents.
|
|
|
Default is "unknown".
|
|
|
errorlog;;
|
|
|
Where to output the error log. Default is stderr.
|
|
|
ipv6;;
|
|
|
Whether to use IPv6. Default is false.
|
|
|
name;;
|
|
|
Repository name to use in the web interface. Default is current
|
|
|
working directory.
|
|
|
maxchanges;;
|
|
|
Maximum number of changes to list on the changelog. Default is 10.
|
|
|
maxfiles;;
|
|
|
Maximum number of files to list per changeset. Default is 10.
|
|
|
port;;
|
|
|
Port to listen on. Default is 8000.
|
|
|
push_ssl;;
|
|
|
Whether to require that inbound pushes be transported over SSL to
|
|
|
prevent password sniffing. Default is true.
|
|
|
stripes;;
|
|
|
How many lines a "zebra stripe" should span in multiline output.
|
|
|
Default is 1; set to 0 to disable.
|
|
|
style;;
|
|
|
Which template map style to use.
|
|
|
templates;;
|
|
|
Where to find the HTML templates. Default is install path.
|
|
|
|
|
|
|
|
|
AUTHOR
|
|
|
------
|
|
|
Bryan O'Sullivan <bos@serpentine.com>.
|
|
|
|
|
|
Mercurial was written by Matt Mackall <mpm@selenic.com>.
|
|
|
|
|
|
SEE ALSO
|
|
|
--------
|
|
|
hg(1), hgignore(5)
|
|
|
|
|
|
COPYING
|
|
|
-------
|
|
|
This manual page is copyright 2005 Bryan O'Sullivan.
|
|
|
Mercurial is copyright 2005, 2006 Matt Mackall.
|
|
|
Free use of this software is granted under the terms of the GNU General
|
|
|
Public License (GPL).
|
|
|
|