hgrc.5.txt
415 lines
| 15.6 KiB
| text/plain
|
TextLexer
/ doc / hgrc.5.txt
|
r671 | 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 | ||||
----- | ||||
|
r1583 | Mercurial reads configuration data from several files, if they exist. | ||
The names of these files depend on the system on which Mercurial is | ||||
installed. | ||||
|
r951 | |||
|
r1583 | (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:: | ||||
|
r1304 | (Unix) /etc/mercurial/hgrc:: | ||
(Windows) C:\Mercurial\Mercurial.ini:: | ||||
|
r1583 | 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. | ||||
|
r671 | |||
|
r1304 | (Unix) $HOME/.hgrc:: | ||
|
r2318 | (Windows) C:\Documents and Settings\USERNAME\Mercurial.ini:: | ||
(Windows) $HOME\Mercurial.ini:: | ||||
|
r1583 | 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. | ||||
|
r2318 | On Windows system, one of these is chosen exclusively according | ||
to definition of HOME environment variable. | ||||
|
r671 | |||
|
r1304 | (Unix, Windows) <repo>/.hg/hgrc:: | ||
|
r671 | Per-repository configuration options that only apply in a | ||
particular repository. This file is not version-controlled, and | ||||
|
r1583 | will not get transferred during a "clone" operation. Options in | ||
this file override options in all other configuration files. | ||||
|
r671 | |||
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. | ||||
|
r1308 | decode/encode:: | ||
|
r1258 | 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. | ||||
|
r1293 | 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". | ||||
|
r1258 | |||
|
r1293 | 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: | ||||
|
r1258 | |||
[encode] | ||||
# uncompress gzip files on checkin to improve delta compression | ||||
# note: not necessarily a good idea, just an example | ||||
|
r1293 | *.gz = pipe: gunzip | ||
|
r1258 | |||
[decode] | ||||
|
r1293 | # recompress gzip files when writing them to the working dir (we | ||
# can safely omit "pipe:", because it's the default) | ||||
|
r1258 | *.gz = gzip | ||
|
r1293 | 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 | ||||
|
r2200 | email:: | ||
Settings for extensions that send email messages. | ||||
from;; | ||||
Optional. Email address to use in "From" header and SMTP envelope | ||||
of outgoing messages. | ||||
|
r2292 | method;; | ||
Optional. Method to use to send email messages. If value is | ||||
"smtp" (default), use SMTP (see section "[mail]" 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 | ||||
|
r2200 | |||
|
r2211 | 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. | ||||
|
r671 | hooks:: | ||
|
r2155 | 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. | ||||
|
r1485 | |||
Example .hg/hgrc: | ||||
[hooks] | ||||
# do not use the site-wide hook | ||||
|
r1714 | incoming = | ||
incoming.email = /my/email/hook | ||||
incoming.autobuild = /my/build/hook | ||||
|
r1485 | |||
|
r1727 | 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". | ||||
|
r1171 | changegroup;; | ||
|
r1730 | Run after a changegroup has been added via push, pull or | ||
|
r1732 | unbundle. ID of the first new changeset is in $HG_NODE. | ||
|
r1171 | commit;; | ||
|
r1714 | Run after a changeset has been created in the local repository. | ||
|
r1727 | ID of the newly created changeset is in $HG_NODE. Parent | ||
changeset IDs are in $HG_PARENT1 and $HG_PARENT2. | ||||
|
r1714 | incoming;; | ||
Run after a changeset has been pulled, pushed, or unbundled into | ||||
|
r1727 | the local repository. The ID of the newly arrived changeset is in | ||
$HG_NODE. | ||||
|
r1736 | 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. | ||||
|
r1730 | 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. | ||||
|
r671 | precommit;; | ||
|
r1721 | Run before starting a local commit. Exit status 0 allows the | ||
|
r1726 | commit to proceed. Non-zero status will cause the commit to fail. | ||
|
r1727 | Parent changeset IDs are in $HG_PARENT1 and $HG_PARENT2. | ||
|
r1736 | 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. | ||||
|
r1720 | 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 | ||||
|
r1727 | 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. | ||||
|
r1730 | 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 | ||||
|
r1734 | in $HG_NODE. Exit status 0 allows the transaction to commit. | ||
|
r1730 | Non-zero status will cause the transaction to be rolled back and | ||
the push, pull or unbundle will fail. | ||||
|
r1721 | 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 | ||||
|
r1727 | be rolled back. ID of changeset is in $HG_NODE. Parent changeset | ||
IDs are in $HG_PARENT1 and $HG_PARENT2. | ||||
|
r2266 | 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. | ||||
|
r1720 | tag;; | ||
|
r1727 | 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. | ||||
|
r2266 | 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. | ||||
|
r1726 | |||
|
r2288 | 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. | ||||
|
r671 | |||
|
r2155 | 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. | ||||
A Python hook must return a "true" value to succeed. Returning a | ||||
"false" value or raising an exception is treated as failure of the | ||||
hook. | ||||
|
r671 | 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. | ||||
|
r1171 | passwd;; | ||
Optional. Password to authenticate with at the proxy server. | ||||
user;; | ||||
Optional. User name to authenticate with at the proxy server. | ||||
|
r671 | |||
|
r2200 | smtp:: | ||
Configuration for extensions that need to send email messages. | ||||
host;; | ||||
Optional. Host name of mail server. Default: "mail". | ||||
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. | ||||
|
r671 | paths:: | ||
Assigns symbolic names to repositories. The left side is the | ||||
symbolic name, and the right gives the directory or URL that is the | ||||
|
r2277 | 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. | ||||
|
r671 | |||
ui:: | ||||
User interface controls. | ||||
debug;; | ||||
|
r702 | Print debugging information. True or False. Default is False. | ||
|
r671 | editor;; | ||
|
r702 | The editor to use during a commit. Default is $EDITOR or "vi". | ||
|
r2003 | 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 | ||||
|
r2209 | "ignore.other = ~/.hgignore2". For details of the ignore file | ||
format, see the hgignore(5) man page. | ||||
|
r702 | interactive;; | ||
Allow to prompt the user. True or False. Default is True. | ||||
|
r1907 | logtemplate;; | ||
Template string for commands that print changesets. | ||||
|
r1914 | style;; | ||
Name of style to use for command output. | ||||
|
r671 | merge;; | ||
The conflict resolution program to use during a manual merge. | ||||
|
r702 | Default is "hgmerge". | ||
|
r671 | quiet;; | ||
|
r702 | Reduce the amount of output printed. True or False. Default is False. | ||
|
r1171 | remotecmd;; | ||
remote command to use for clone/push/pull operations. Default is 'hg'. | ||||
ssh;; | ||||
command to use for SSH connections. Default is 'ssh'. | ||||
|
r1787 | timeout;; | ||
The timeout used when a lock is held (in seconds), a negative value | ||||
|
r1788 | means no timeout. Default is 600. | ||
|
r671 | username;; | ||
The committer of a changeset created when running "commit". | ||||
Typically a person's name and email address, e.g. "Fred Widget | ||||
|
r1985 | <fred@example.com>". Default is $EMAIL or username@hostname, unless | ||
username is set to an empty string, which enforces specifying the | ||||
username manually. | ||||
|
r671 | verbose;; | ||
|
r702 | Increase the amount of output printed. True or False. Default is False. | ||
|
r962 | |||
|
r671 | |||
|
r938 | web:: | ||
Web interface configuration. | ||||
accesslog;; | ||||
Where to output the access log. Default is stdout. | ||||
|
r1171 | address;; | ||
Interface address to bind to. Default is all. | ||||
allowbz2;; | ||||
Whether to allow .tar.bz2 downloading of repo revisions. Default is false. | ||||
allowgz;; | ||||
Whether to allow .tar.gz downloading of repo revisions. Default is false. | ||||
|
r964 | allowpull;; | ||
Whether to allow pulling from the repository. Default is true. | ||||
|
r1079 | allowzip;; | ||
Whether to allow .zip downloading of repo revisions. Default is false. | ||||
This feature creates temporary files. | ||||
|
r2197 | 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/" | ||||
|
r1171 | 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. | ||||
style;; | ||||
Which template map style to use. | ||||
templates;; | ||||
Where to find the HTML templates. Default is install path. | ||||
|
r1079 | |||
|
r938 | |||
|
r671 | AUTHOR | ||
------ | ||||
Bryan O'Sullivan <bos@serpentine.com>. | ||||
Mercurial was written by Matt Mackall <mpm@selenic.com>. | ||||
SEE ALSO | ||||
-------- | ||||
|
r2209 | hg(1), hgignore(5) | ||
|
r671 | |||
COPYING | ||||
------- | ||||
This manual page is copyright 2005 Bryan O'Sullivan. | ||||
|
r2209 | Mercurial is copyright 2005, 2006 Matt Mackall. | ||
|
r671 | Free use of this software is granted under the terms of the GNU General | ||
Public License (GPL). | ||||