1HGRC(5) HGRC(5)
2
6 hgrc - configuration files for Mercurial
7
9 The Mercurial system uses a set of configuration files to control
10 aspects of its behaviour.
11
14 Mercurial reads configuration data from several files, if they exist.
15 The names of these files depend on the system on which Mercurial is
16 installed.
17 (Unix) <install-root>/etc/mercurial/hgrc.d/*.rc, (Unix)
20 <install-root>/etc/mercurial/hgrc
21 Per-installation configuration files, searched for in the directory
22 where Mercurial is installed. For example, if installed in
23 /shared/tools, Mercurial will look in
24 /shared/tools/etc/mercurial/hgrc. Options in these files apply to
25 all Mercurial commands executed by any user in any directory.
26 (Unix) /etc/mercurial/hgrc.d/*.rc, (Unix) /etc/mercurial/hgrc,
28 (Windows) C:\Mercurial\Mercurial.ini
29 Per-system configuration files, for the system on which Mercurial
30 is running. Options in these files apply to all Mercurial commands
31 executed by any user in any directory. Options in these files
32 override per-installation options.
33 (Unix) $HOME/.hgrc, (Windows) C:\Documents and
35 Settings\USERNAME\Mercurial.ini, (Windows) $HOME\Mercurial.ini
36 Per-user configuration file, for the user running Mercurial.
37 Options in this file apply to all Mercurial commands executed by
38 any user in any directory. Options in this file override
39 per-installation and per-system options. On Windows system, one of
40 these is chosen exclusively according to definition of HOME
41 environment variable.
42 (Unix, Windows) <repo>/.hg/hgrc
44 Per-repository configuration options that only apply in a
45 particular repository. This file is not version-controlled, and
46 will not get transferred during a "clone" operation. Options in
47 this file override options in all other configuration files. On
48 Unix, most of this file will be ignored if it doesn't belong to a
49 trusted user or to a trusted group. See the documentation for the
50 trusted section below for more details.
51
53 A configuration file consists of sections, led by a "[section]" header
54 and followed by "name: value" entries; "name=value" is also accepted.
55 [spam]
58 eggs=ham
59 green=
60 eggs
61 Each line contains one entry. If the lines that follow are indented,
62 they are treated as continuations of that entry.
63 Leading whitespace is removed from values. Empty lines are skipped.
65 The optional values can contain format strings which refer to other
67 values in the same section, or values in a special DEFAULT section.
68 Lines beginning with "#" or ";" are ignored and may be used to provide
70 comments.
71
74 This section describes the different sections that may appear in a
75 Mercurial "hgrc" file, the purpose of each section, its possible keys,
76 and their possible values.
77 decode/encode
80 Filters for transforming files on checkout/checkin. This would
81 typically be used for newline processing or other
82 localization/canonicalization of files.
83 Filters consist of a filter pattern followed by a filter command.
85 Filter patterns are globs by default, rooted at the repository
86 root. For example, to match any file ending in ".txt" in the root
87 directory only, use the pattern "*.txt". To match any file ending
88 in ".c" anywhere in the repository, use the pattern "**.c".
89 The filter command can start with a specifier, either "pipe:" or
91 "tempfile:". If no specifier is given, "pipe:" is used by default.
92 A "pipe:" command must accept data on stdin and return the
94 transformed data on stdout.
95 Pipe example:
97 [encode]
99 # uncompress gzip files on checkin to improve delta compression
100 # note: not necessarily a good idea, just an example
101 *.gz = pipe: gunzip
102 [decode]
104 # recompress gzip files when writing them to the working dir (we
105 # can safely omit "pipe:", because it's the default)
106 *.gz = gzip
107 A "tempfile:" command is a template. The string INFILE is replaced
109 with the name of a temporary file that contains the data to be
110 filtered by the command. The string OUTFILE is replaced with the
111 name of an empty temporary file, where the filtered data must be
112 written by the command.
113 NOTE: the tempfile mechanism is recommended for Windows systems,
115 where the standard shell I/O redirection operators often have
116 strange effects. In particular, if you are doing line ending
117 conversion on Windows using the popular dos2unix and unix2dos
118 programs, you *must* use the tempfile mechanism, as using pipes will
119 corrupt the contents of your files.
120 Tempfile example:
122 [encode]
124 # convert files to unix line ending conventions on checkin
125 **.txt = tempfile: dos2unix -n INFILE OUTFILE
126 [decode]
128 # convert files to windows line ending conventions when writing
129 # them to the working dir
130 **.txt = tempfile: unix2dos -n INFILE OUTFILE
131 defaults
133 Use the [defaults] section to define command defaults, i.e. the
134 default options/arguments to pass to the specified commands.
135 The following example makes 'hg log' run in verbose mode, and
137 ´hg status' show only the modified files, by default.
138 [defaults]
140 log = -v
141 status = -m
142 The actual commands, instead of their aliases, must be used when
144 defining command defaults. The command defaults will also be
145 applied to the aliases of the commands defined.
146 diff
148 Settings used when displaying diffs. They are all boolean and
149 defaults to False.
150 git
152 Use git extended diff format.
153 nodates
155 Don't include dates in diff headers.
156 showfunc
158 Show which function each change is in.
159 ignorews
161 Ignore white space when comparing lines.
162 ignorewsamount
164 Ignore changes in the amount of white space.
165 ignoreblanklines
167 Ignore changes whose lines are all blank.
168 email
170 Settings for extensions that send email messages.
171 from
173 Optional. Email address to use in "From" header and SMTP
174 envelope of outgoing messages.
175 to
177 Optional. Comma-separated list of recipients' email addresses.
178 cc
180 Optional. Comma-separated list of carbon copy recipients' email
181 addresses.
182 bcc
184 Optional. Comma-separated list of blind carbon copy recipients'
185 email addresses. Cannot be set interactively.
186 method
188 Optional. Method to use to send email messages. If value is
189 "smtp" (default), use SMTP (see section "[smtp]" for
190 configuration). Otherwise, use as name of program to run that
191 acts like sendmail (takes "-f" option for sender, list of
192 recipients on command line, message on stdin). Normally,
193 setting this to "sendmail" or "/usr/sbin/sendmail" is enough to
194 use sendmail to send messages.
195 Email example:
197 [email]
199 from = Joseph User <joe.user@example.com>
200 method = /usr/sbin/sendmail
201 extensions
203 Mercurial has an extension mechanism for adding new features. To
204 enable an extension, create an entry for it in this section.
205 If you know that the extension is already in Python's search path,
207 you can give the name of the module, followed by "=", with nothing
208 after the "=".
209 Otherwise, give a name that you choose, followed by "=", followed by
211 the path to the ".py" file (including the file name extension) that
212 defines the extension.
213 Example for ~/.hgrc:
215 [extensions]
217 # (the mq extension will get loaded from mercurial's path)
218 hgext.mq =
219 # (this extension will get loaded from the file specified)
220 myfeature = ~/.hgext/myfeature.py
221 format
223 usestore
225 Enable or disable the "store" repository format which improves
226 compatibility with systems that fold case or otherwise mangle
227 filenames. Enabled by default. Disabling this option will allow
228 you to store longer filenames in some situations at the expense
229 of compatibility.
230 hooks
232 Commands or Python functions that get automatically executed by
233 various actions such as starting or finishing a commit. Multiple
234 hooks can be run for the same action by appending a suffix to the
235 action. Overriding a site-wide hook can be done by changing its
236 value or setting it to an empty string.
237 Example .hg/hgrc:
239 [hooks]
241 # do not use the site-wide hook
242 incoming =
243 incoming.email = /my/email/hook
244 incoming.autobuild = /my/build/hook
245 Most hooks are run with environment variables set that give added
247 useful information. For each hook below, the environment variables
248 it is passed are listed with names of the form "$HG_foo".
249 changegroup
251 Run after a changegroup has been added via push, pull or
252 unbundle. ID of the first new changeset is in $HG_NODE. URL
253 from which changes came is in $HG_URL.
254 commit
256 Run after a changeset has been created in the local repository.
257 ID of the newly created changeset is in $HG_NODE. Parent
258 changeset IDs are in $HG_PARENT1 and $HG_PARENT2.
259 incoming
261 Run after a changeset has been pulled, pushed, or unbundled
262 into the local repository. The ID of the newly arrived
263 changeset is in $HG_NODE. URL that was source of changes came
264 is in $HG_URL.
265 outgoing
267 Run after sending changes from local repository to another. ID
268 of first changeset sent is in $HG_NODE. Source of operation is
269 in $HG_SOURCE; see "preoutgoing" hook for description.
270 post-<command>
272 Run after successful invocations of the associated command. The
273 contents of the command line are passed as $HG_ARGS and the
274 result code in $HG_RESULT. Hook failure is ignored.
275 pre-<command>
277 Run before executing the associated command. The contents of
278 the command line are passed as $HG_ARGS. If the hook returns
279 failure, the command doesn't execute and Mercurial returns the
280 failure code.
281 prechangegroup
283 Run before a changegroup is added via push, pull or unbundle.
284 Exit status 0 allows the changegroup to proceed. Non-zero
285 status will cause the push, pull or unbundle to fail. URL from
286 which changes will come is in $HG_URL.
287 precommit
289 Run before starting a local commit. Exit status 0 allows the
290 commit to proceed. Non-zero status will cause the commit to
291 fail. Parent changeset IDs are in $HG_PARENT1 and $HG_PARENT2.
292 preoutgoing
294 Run before computing changes to send from the local repository
295 to another. Non-zero status will cause failure. This lets you
296 prevent pull over http or ssh. Also prevents against local
297 pull, push (outbound) or bundle commands, but not effective,
298 since you can just copy files instead then. Source of operation
299 is in $HG_SOURCE. If "serve", operation is happening on behalf
300 of remote ssh or http repository. If "push", "pull" or
301 "bundle", operation is happening on behalf of repository on
302 same system.
303 pretag
305 Run before creating a tag. Exit status 0 allows the tag to be
306 created. Non-zero status will cause the tag to fail. ID of
307 changeset to tag is in $HG_NODE. Name of tag is in $HG_TAG. Tag
308 is local if $HG_LOCAL=1, in repo if $HG_LOCAL=0.
309 pretxnchangegroup
311 Run after a changegroup has been added via push, pull or
312 unbundle, but before the transaction has been committed.
313 Changegroup is visible to hook program. This lets you validate
314 incoming changes before accepting them. Passed the ID of the
315 first new changeset in $HG_NODE. Exit status 0 allows the
316 transaction to commit. Non-zero status will cause the
317 transaction to be rolled back and the push, pull or unbundle
318 will fail. URL that was source of changes is in $HG_URL.
319 pretxncommit
321 Run after a changeset has been created but the transaction not
322 yet committed. Changeset is visible to hook program. This lets
323 you validate commit message and changes. Exit status 0 allows
324 the commit to proceed. Non-zero status will cause the
325 transaction to be rolled back. ID of changeset is in $HG_NODE.
326 Parent changeset IDs are in $HG_PARENT1 and $HG_PARENT2.
327 preupdate
329 Run before updating the working directory. Exit status 0 allows
330 the update to proceed. Non-zero status will prevent the update.
331 Changeset ID of first new parent is in $HG_PARENT1. If merge,
332 ID of second new parent is in $HG_PARENT2.
333 tag
335 Run after a tag is created. ID of tagged changeset is in
336 $HG_NODE. Name of tag is in $HG_TAG. Tag is local if
337 $HG_LOCAL=1, in repo if $HG_LOCAL=0.
338 update
340 Run after updating the working directory. Changeset ID of first
341 new parent is in $HG_PARENT1. If merge, ID of second new parent
342 is in $HG_PARENT2. If update succeeded, $HG_ERROR=0. If update
343 failed (e.g. because conflicts not resolved), $HG_ERROR=1.
344 Note: it is generally better to use standard hooks rather than the
346 generic pre- and post- command hooks as they are guaranteed to be
347 called in the appropriate contexts for influencing transactions.
348 Also, hooks like "commit" will be called in all contexts that
349 generate a commit (eg. tag) and not just the commit command.
350 Note2: Environment variables with empty values may not be passed to
352 hooks on platforms like Windows. For instance, $HG_PARENT2 will
353 not be available under Windows for non-merge changesets while being
354 set to an empty value under Unix-like systems.
355 The syntax for Python hooks is as follows:
357 hookname = python:modulename.submodule.callable
359 Python hooks are run within the Mercurial process. Each hook is
361 called with at least three keyword arguments: a ui object (keyword
362 "ui"), a repository object (keyword "repo"), and a "hooktype"
363 keyword that tells what kind of hook is used. Arguments listed as
364 environment variables above are passed as keyword arguments, with no
365 "HG_" prefix, and names in lower case.
366 If a Python hook returns a "true" value or raises an exception, this
368 is treated as failure of the hook.
369 http_proxy
371 Used to access web-based Mercurial repositories through a HTTP
372 proxy.
373 host
375 Host name and (optional) port of the proxy server, for example
376 "myproxy:8000".
377 no
379 Optional. Comma-separated list of host names that should bypass
380 the proxy.
381 passwd
383 Optional. Password to authenticate with at the proxy server.
384 user
386 Optional. User name to authenticate with at the proxy server.
387 smtp
389 Configuration for extensions that need to send email messages.
390 host
392 Host name of mail server, e.g. "mail.example.com".
393 port
395 Optional. Port to connect to on mail server. Default: 25.
396 tls
398 Optional. Whether to connect to mail server using TLS. True or
399 False. Default: False.
400 username
402 Optional. User name to authenticate to SMTP server with. If
403 username is specified, password must also be specified.
404 Default: none.
405 password
407 Optional. Password to authenticate to SMTP server with. If
408 username is specified, password must also be specified.
409 Default: none.
410 local_hostname
412 Optional. It's the hostname that the sender can use to identify
413 itself to the MTA.
414 paths
416 Assigns symbolic names to repositories. The left side is the
417 symbolic name, and the right gives the directory or URL that is the
418 location of the repository. Default paths can be declared by
419 setting the following entries.
420 default
422 Directory or URL to use when pulling if no source is specified.
423 Default is set to repository from which the current repository
424 was cloned.
425 default-push
427 Optional. Directory or URL to use when pushing if no
428 destination is specified.
429 server
431 Controls generic server settings.
432 uncompressed
434 Whether to allow clients to clone a repo using the uncompressed
435 streaming protocol. This transfers about 40% more data than a
436 regular clone, but uses less memory and CPU on both server and
437 client. Over a LAN (100Mbps or better) or a very fast WAN, an
438 uncompressed streaming clone is a lot faster (~10x) than a
439 regular clone. Over most WAN connections (anything slower than
440 about 6Mbps), uncompressed streaming is slower, because of the
441 extra data transfer overhead. Default is False.
442 trusted
444 For security reasons, Mercurial will not use the settings in the
445 .hg/hgrc file from a repository if it doesn't belong to a trusted
446 user or to a trusted group. The main exception is the web
447 interface, which automatically uses some safe settings, since it's
448 common to serve repositories from different users.
449 This section specifies what users and groups are trusted. The
451 current user is always trusted. To trust everybody, list a user
452 or a group with name "*".
453 users
455 Comma-separated list of trusted users.
456 groups
458 Comma-separated list of trusted groups.
459 ui
461 User interface controls.
462 debug
464 Print debugging information. True or False. Default is False.
465 editor
467 The editor to use during a commit. Default is $EDITOR or "vi".
468 fallbackencoding
470 Encoding to try if it's not possible to decode the changelog
471 using UTF-8. Default is ISO-8859-1.
472 ignore
474 A file to read per-user ignore patterns from. This file should
475 be in the same format as a repository-wide .hgignore file. This
476 option supports hook syntax, so if you want to specify multiple
477 ignore files, you can do so by setting something like
478 "ignore.other = ~/.hgignore2". For details of the ignore file
479 format, see the hgignore(5) man page.
480 interactive
482 Allow to prompt the user. True or False. Default is True.
483 logtemplate
485 Template string for commands that print changesets.
486 merge
488 The conflict resolution program to use during a manual merge.
489 Default is "hgmerge".
490 patch
492 command to use to apply patches. Look for gpatch or patch in
493 PATH if unset.
494 quiet
496 Reduce the amount of output printed. True or False. Default is
497 False.
498 remotecmd
500 remote command to use for clone/push/pull operations. Default
501 is hg.
502 report_untrusted
504 Warn if a .hg/hgrc file is ignored due to not being owned by a
505 trusted user or group. True or False. Default is True.
506 slash
508 Display paths using a slash ("/") as the path separator. This
509 only makes a difference on systems where the default path
510 separator is not the slash character (e.g. Windows uses the
511 backslash character ("\")). Default is False.
512 ssh
514 command to use for SSH connections. Default is ssh.
515 strict
517 Require exact command names, instead of allowing unambiguous
518 abbreviations. True or False. Default is False.
519 style
521 Name of style to use for command output.
522 timeout
524 The timeout used when a lock is held (in seconds), a negative
525 value means no timeout. Default is 600.
526 username
528 The committer of a changeset created when running "commit".
529 Typically a person's name and email address, e.g. "Fred Widget
530 <fred@example.com>". Default is $EMAIL or username@hostname. If
531 the username in hgrc is empty, it has to be specified manually
532 or in a different hgrc file (e.g. $HOME/.hgrc, if the admin set
533 "username =" in the system hgrc).
534 verbose
536 Increase the amount of output printed. True or False. Default
537 is False.
538 web
540 Web interface configuration.
541 accesslog
543 Where to output the access log. Default is stdout.
544 address
546 Interface address to bind to. Default is all.
547 allow_archive
549 List of archive format (bz2, gz, zip) allowed for downloading.
550 Default is empty.
551 allowbz2
553 (DEPRECATED) Whether to allow .tar.bz2 downloading of repo
554 revisions. Default is false.
555 allowgz
557 (DEPRECATED) Whether to allow .tar.gz downloading of repo
558 revisions. Default is false.
559 allowpull
561 Whether to allow pulling from the repository. Default is true.
562 allow_push
564 Whether to allow pushing to the repository. If empty or not
565 set, push is not allowed. If the special value "*", any remote
566 user can push, including unauthenticated users. Otherwise, the
567 remote user must have been authenticated, and the authenticated
568 user name must be present in this list (separated by whitespace
569 or ","). The contents of the allow_push list are examined after
570 the deny_push list.
571 allowzip
573 (DEPRECATED) Whether to allow .zip downloading of repo
574 revisions. Default is false. This feature creates temporary
575 files.
576 baseurl
578 Base URL to use when publishing URLs in other locations, so
579 third-party tools like email notification hooks can construct
580 URLs. Example: "http://hgserver/repos/"
581 contact
583 Name or email address of the person in charge of the
584 repository. Default is "unknown".
585 deny_push
587 Whether to deny pushing to the repository. If empty or not set,
588 push is not denied. If the special value "*", all remote users
589 are denied push. Otherwise, unauthenticated users are all
590 denied, and any authenticated user name present in this list
591 (separated by whitespace or ",") is also denied. The contents
592 of the deny_push list are examined before the allow_push list.
593 description
595 Textual description of the repository's purpose or contents.
596 Default is "unknown".
597 encoding
599 Character encoding name. Example: "UTF-8"
600 errorlog
602 Where to output the error log. Default is stderr.
603 hidden
605 Whether to hide the repository in the hgwebdir index. Default
606 is false.
607 ipv6
609 Whether to use IPv6. Default is false.
610 name
612 Repository name to use in the web interface. Default is current
613 working directory.
614 maxchanges
616 Maximum number of changes to list on the changelog. Default is
617 10.
618 maxfiles
620 Maximum number of files to list per changeset. Default is 10.
621 port
623 Port to listen on. Default is 8000.
624 push_ssl
626 Whether to require that inbound pushes be transported over SSL
627 to prevent password sniffing. Default is true.
628 staticurl
630 Base URL to use for static files. If unset, static files (e.g.
631 the hgicon.png favicon) will be served by the CGI script
632 itself. Use this setting to serve them directly with the HTTP
633 server. Example: "http://hgserver/static/"
634 stripes
636 How many lines a "zebra stripe" should span in multiline
637 output. Default is 1; set to 0 to disable.
638 style
640 Which template map style to use.
641 templates
643 Where to find the HTML templates. Default is install path.
644
646 Bryan O'Sullivan <bos@serpentine.com>.
647 Mercurial was written by Matt Mackall <mpm@selenic.com>.
649
652 hg(1), hgignore(5)
653
656 This manual page is copyright 2005 Bryan O'Sullivan. Mercurial is
657 copyright 2005-2007 Matt Mackall. Free use of this software is granted
658 under the terms of the GNU General Public License (GPL).
659 06/25/2007 HGRC(5)