comparison doc/hgrc.5.txt @ 14456:ff4126ce9301

help: move part of hgrc.5 man page config help topic
author Yun Lee <yun.lee.bj@gmail.com>
date Mon, 30 May 2011 10:21:39 +0200
parents 59853c30e31e
children d5f616132c10
comparison
equal deleted inserted replaced
14455:59853c30e31e 14456:ff4126ce9301
20 -------- 20 --------
21 21
22 The Mercurial system uses a set of configuration files to control 22 The Mercurial system uses a set of configuration files to control
23 aspects of its behavior. 23 aspects of its behavior.
24 24
25 Files 25 .. include:: ../mercurial/help/config.txt
26 -----
27
28 Mercurial reads configuration data from several files, if they exist.
29 The names of these files depend on the system on which Mercurial is
30 installed. ``*.rc`` files from a single directory are read in
31 alphabetical order, later ones overriding earlier ones. Where multiple
32 paths are given below, settings from earlier paths override later
33 ones.
34
35 | (Unix, Windows) ``<repo>/.hg/hgrc``
36
37 Per-repository configuration options that only apply in a
38 particular repository. This file is not version-controlled, and
39 will not get transferred during a "clone" operation. Options in
40 this file override options in all other configuration files. On
41 Unix, most of this file will be ignored if it doesn't belong to a
42 trusted user or to a trusted group. See the documentation for the
43 trusted_ section below for more details.
44
45 | (Unix) ``$HOME/.hgrc``
46 | (Windows) ``%USERPROFILE%\.hgrc``
47 | (Windows) ``%USERPROFILE%\Mercurial.ini``
48 | (Windows) ``%HOME%\.hgrc``
49 | (Windows) ``%HOME%\Mercurial.ini``
50
51 Per-user configuration file(s), for the user running Mercurial. On
52 Windows 9x, ``%HOME%`` is replaced by ``%APPDATA%``. Options in these
53 files apply to all Mercurial commands executed by this user in any
54 directory. Options in these files override per-system and per-installation
55 options.
56
57 | (Unix) ``/etc/mercurial/hgrc``
58 | (Unix) ``/etc/mercurial/hgrc.d/*.rc``
59
60 Per-system configuration files, for the system on which Mercurial
61 is running. Options in these files apply to all Mercurial commands
62 executed by any user in any directory. Options in these files
63 override per-installation options.
64
65 | (Unix) ``<install-root>/etc/mercurial/hgrc``
66 | (Unix) ``<install-root>/etc/mercurial/hgrc.d/*.rc``
67
68 Per-installation configuration files, searched for in the
69 directory where Mercurial is installed. ``<install-root>`` is the
70 parent directory of the **hg** executable (or symlink) being run. For
71 example, if installed in ``/shared/tools/bin/hg``, Mercurial will look
72 in ``/shared/tools/etc/mercurial/hgrc``. Options in these files apply
73 to all Mercurial commands executed by any user in any directory.
74
75 | (Windows) ``<install-dir>\Mercurial.ini``
76 | (Windows) ``<install-dir>\hgrc.d\*.rc``
77 | (Windows) ``HKEY_LOCAL_MACHINE\SOFTWARE\Mercurial``
78
79 Per-installation/system configuration files, for the system on
80 which Mercurial is running. Options in these files apply to all
81 Mercurial commands executed by any user in any directory. Registry
82 keys contain PATH-like strings, every part of which must reference
83 a ``Mercurial.ini`` file or be a directory where ``*.rc`` files will
84 be read. Mercurial checks each of these locations in the specified
85 order until one or more configuration files are detected. If the
86 pywin32 extensions are not installed, Mercurial will only look for
87 site-wide configuration in ``C:\Mercurial\Mercurial.ini``.
88
89 Syntax
90 ------
91
92 A configuration file consists of sections, led by a ``[section]`` header
93 and followed by ``name = value`` entries (sometimes called
94 ``configuration keys``)::
95
96 [spam]
97 eggs=ham
98 green=
99 eggs
100
101 Each line contains one entry. If the lines that follow are indented,
102 they are treated as continuations of that entry. Leading whitespace is
103 removed from values. Empty lines are skipped. Lines beginning with
104 ``#`` or ``;`` are ignored and may be used to provide comments.
105
106 Configuration keys can be set multiple times, in which case mercurial
107 will use the value that was configured last. As an example::
108
109 [spam]
110 eggs=large
111 ham=serrano
112 eggs=small
113
114 This would set the configuration key named ``eggs`` to ``small``.
115
116 It is also possible to define a section multiple times. A section can
117 be redefined on the same and/or on different hgrc files. For example::
118
119 [foo]
120 eggs=large
121 ham=serrano
122 eggs=small
123
124 [bar]
125 eggs=ham
126 green=
127 eggs
128
129 [foo]
130 ham=prosciutto
131 eggs=medium
132 bread=toasted
133
134 This would set the ``eggs``, ``ham``, and ``bread`` configuration keys
135 of the ``foo`` section to ``medium``, ``prosciutto``, and ``toasted``,
136 respectively. As you can see there only thing that matters is the last
137 value that was set for each of the configuration keys.
138
139 If a configuration key is set multiple times in different
140 configuration files the final value will depend on the order in which
141 the different configuration files are read, with settings from earlier
142 paths overriding later ones as described on the ``Files`` section
143 above.
144
145 A line of the form ``%include file`` will include ``file`` into the
146 current configuration file. The inclusion is recursive, which means
147 that included files can include other files. Filenames are relative to
148 the configuration file in which the ``%include`` directive is found.
149 Environment variables and ``~user`` constructs are expanded in
150 ``file``. This lets you do something like::
151
152 %include ~/.hgrc.d/$HOST.rc
153
154 to include a different configuration file on each computer you use.
155
156 A line with ``%unset name`` will remove ``name`` from the current
157 section, if it has been set previously.
158
159 The values are either free-form text strings, lists of text strings,
160 or Boolean values. Boolean values can be set to true using any of "1",
161 "yes", "true", or "on" and to false using "0", "no", "false", or "off"
162 (all case insensitive).
163
164 List values are separated by whitespace or comma, except when values are
165 placed in double quotation marks::
166
167 allow_read = "John Doe, PhD", brian, betty
168
169 Quotation marks can be escaped by prefixing them with a backslash. Only
170 quotation marks at the beginning of a word is counted as a quotation
171 (e.g., ``foo"bar baz`` is the list of ``foo"bar`` and ``baz``).
172
173 Sections
174 --------
175
176 This section describes the different sections that may appear in a
177 Mercurial "hgrc" file, the purpose of each section, its possible keys,
178 and their possible values.
179
180 ``alias``
181 """""""""
182
183 Defines command aliases.
184 Aliases allow you to define your own commands in terms of other
185 commands (or aliases), optionally including arguments. Positional
186 arguments in the form of ``$1``, ``$2``, etc in the alias definition
187 are expanded by Mercurial before execution. Positional arguments not
188 already used by ``$N`` in the definition are put at the end of the
189 command to be executed.
190
191 Alias definitions consist of lines of the form::
192
193 <alias> = <command> [<argument]...
194
195 For example, this definition::
196
197 latest = log --limit 5
198
199 creates a new command ``latest`` that shows only the five most recent
200 changesets. You can define subsequent aliases using earlier ones::
201
202 stable5 = latest -b stable
203
204 .. note:: It is possible to create aliases with the same names as
205 existing commands, which will then override the original
206 definitions. This is almost always a bad idea!
207
208 An alias can start with an exclamation point (``!``) to make it a
209 shell alias. A shell alias is executed with the shell and will let you
210 run arbitrary commands. As an example, ::
211
212 echo = !echo
213
214 will let you do ``hg echo foo`` to have ``foo`` printed in your
215 terminal. A better example might be::
216
217 purge = !$HG status --no-status --unknown -0 | xargs -0 rm
218
219 which will make ``hg purge`` delete all unknown files in the
220 repository in the same manner as the purge extension.
221
222 Shell aliases are executed in an environment where ``$HG`` expand to
223 the path of the Mercurial that was used to execute the alias. This is
224 useful when you want to call further Mercurial commands in a shell
225 alias, as was done above for the purge alias. In addition,
226 ``$HG_ARGS`` expand to the arguments given to Mercurial. In the ``hg
227 echo foo`` call above, ``$HG_ARGS`` would expand to ``echo foo``.
228
229 ``auth``
230 """"""""
231
232 Authentication credentials for HTTP authentication. This section
233 allows you to store usernames and passwords for use when logging
234 *into* HTTP servers. See the web_ configuration section if you want to
235 configure *who* can login to your HTTP server.
236
237 Each line has the following format::
238
239 <name>.<argument> = <value>
240
241 where ``<name>`` is used to group arguments into authentication
242 entries. Example::
243
244 foo.prefix = hg.intevation.org/mercurial
245 foo.username = foo
246 foo.password = bar
247 foo.schemes = http https
248
249 bar.prefix = secure.example.org
250 bar.key = path/to/file.key
251 bar.cert = path/to/file.cert
252 bar.schemes = https
253
254 Supported arguments:
255
256 ``prefix``
257 Either ``*`` or a URI prefix with or without the scheme part.
258 The authentication entry with the longest matching prefix is used
259 (where ``*`` matches everything and counts as a match of length
260 1). If the prefix doesn't include a scheme, the match is performed
261 against the URI with its scheme stripped as well, and the schemes
262 argument, q.v., is then subsequently consulted.
263 ``username``
264 Optional. Username to authenticate with. If not given, and the
265 remote site requires basic or digest authentication, the user will
266 be prompted for it. Environment variables are expanded in the
267 username letting you do ``foo.username = $USER``.
268 ``password``
269 Optional. Password to authenticate with. If not given, and the
270 remote site requires basic or digest authentication, the user
271 will be prompted for it.
272 ``key``
273 Optional. PEM encoded client certificate key file. Environment
274 variables are expanded in the filename.
275 ``cert``
276 Optional. PEM encoded client certificate chain file. Environment
277 variables are expanded in the filename.
278 ``schemes``
279 Optional. Space separated list of URI schemes to use this
280 authentication entry with. Only used if the prefix doesn't include
281 a scheme. Supported schemes are http and https. They will match
282 static-http and static-https respectively, as well.
283 Default: https.
284
285 If no suitable authentication entry is found, the user is prompted
286 for credentials as usual if required by the remote.
287
288
289 ``decode/encode``
290 """""""""""""""""
291
292 Filters for transforming files on checkout/checkin. This would
293 typically be used for newline processing or other
294 localization/canonicalization of files.
295
296 Filters consist of a filter pattern followed by a filter command.
297 Filter patterns are globs by default, rooted at the repository root.
298 For example, to match any file ending in ``.txt`` in the root
299 directory only, use the pattern ``*.txt``. To match any file ending
300 in ``.c`` anywhere in the repository, use the pattern ``**.c``.
301 For each file only the first matching filter applies.
302
303 The filter command can start with a specifier, either ``pipe:`` or
304 ``tempfile:``. If no specifier is given, ``pipe:`` is used by default.
305
306 A ``pipe:`` command must accept data on stdin and return the transformed
307 data on stdout.
308
309 Pipe example::
310
311 [encode]
312 # uncompress gzip files on checkin to improve delta compression
313 # note: not necessarily a good idea, just an example
314 *.gz = pipe: gunzip
315
316 [decode]
317 # recompress gzip files when writing them to the working dir (we
318 # can safely omit "pipe:", because it's the default)
319 *.gz = gzip
320
321 A ``tempfile:`` command is a template. The string ``INFILE`` is replaced
322 with the name of a temporary file that contains the data to be
323 filtered by the command. The string ``OUTFILE`` is replaced with the name
324 of an empty temporary file, where the filtered data must be written by
325 the command.
326
327 .. note:: The tempfile mechanism is recommended for Windows systems,
328 where the standard shell I/O redirection operators often have
329 strange effects and may corrupt the contents of your files.
330
331 This filter mechanism is used internally by the ``eol`` extension to
332 translate line ending characters between Windows (CRLF) and Unix (LF)
333 format. We suggest you use the ``eol`` extension for convenience.
334
335
336 ``defaults``
337 """"""""""""
338
339 (defaults are deprecated. Don't use them. Use aliases instead)
340
341 Use the ``[defaults]`` section to define command defaults, i.e. the
342 default options/arguments to pass to the specified commands.
343
344 The following example makes :hg:`log` run in verbose mode, and
345 :hg:`status` show only the modified files, by default::
346
347 [defaults]
348 log = -v
349 status = -m
350
351 The actual commands, instead of their aliases, must be used when
352 defining command defaults. The command defaults will also be applied
353 to the aliases of the commands defined.
354
355
356 ``diff``
357 """"""""
358
359 Settings used when displaying diffs. Everything except for ``unified`` is a
360 Boolean and defaults to False.
361
362 ``git``
363 Use git extended diff format.
364 ``nodates``
365 Don't include dates in diff headers.
366 ``showfunc``
367 Show which function each change is in.
368 ``ignorews``
369 Ignore white space when comparing lines.
370 ``ignorewsamount``
371 Ignore changes in the amount of white space.
372 ``ignoreblanklines``
373 Ignore changes whose lines are all blank.
374 ``unified``
375 Number of lines of context to show.
376
377 ``email``
378 """""""""
379
380 Settings for extensions that send email messages.
381
382 ``from``
383 Optional. Email address to use in "From" header and SMTP envelope
384 of outgoing messages.
385 ``to``
386 Optional. Comma-separated list of recipients' email addresses.
387 ``cc``
388 Optional. Comma-separated list of carbon copy recipients'
389 email addresses.
390 ``bcc``
391 Optional. Comma-separated list of blind carbon copy recipients'
392 email addresses.
393 ``method``
394 Optional. Method to use to send email messages. If value is ``smtp``
395 (default), use SMTP (see the SMTP_ section for configuration).
396 Otherwise, use as name of program to run that acts like sendmail
397 (takes ``-f`` option for sender, list of recipients on command line,
398 message on stdin). Normally, setting this to ``sendmail`` or
399 ``/usr/sbin/sendmail`` is enough to use sendmail to send messages.
400 ``charsets``
401 Optional. Comma-separated list of character sets considered
402 convenient for recipients. Addresses, headers, and parts not
403 containing patches of outgoing messages will be encoded in the
404 first character set to which conversion from local encoding
405 (``$HGENCODING``, ``ui.fallbackencoding``) succeeds. If correct
406 conversion fails, the text in question is sent as is. Defaults to
407 empty (explicit) list.
408
409 Order of outgoing email character sets:
410
411 1. ``us-ascii``: always first, regardless of settings
412 2. ``email.charsets``: in order given by user
413 3. ``ui.fallbackencoding``: if not in email.charsets
414 4. ``$HGENCODING``: if not in email.charsets
415 5. ``utf-8``: always last, regardless of settings
416
417 Email example::
418
419 [email]
420 from = Joseph User <joe.user@example.com>
421 method = /usr/sbin/sendmail
422 # charsets for western Europeans
423 # us-ascii, utf-8 omitted, as they are tried first and last
424 charsets = iso-8859-1, iso-8859-15, windows-1252
425
426
427 ``extensions``
428 """"""""""""""
429
430 Mercurial has an extension mechanism for adding new features. To
431 enable an extension, create an entry for it in this section.
432
433 If you know that the extension is already in Python's search path,
434 you can give the name of the module, followed by ``=``, with nothing
435 after the ``=``.
436
437 Otherwise, give a name that you choose, followed by ``=``, followed by
438 the path to the ``.py`` file (including the file name extension) that
439 defines the extension.
440
441 To explicitly disable an extension that is enabled in an hgrc of
442 broader scope, prepend its path with ``!``, as in ``foo = !/ext/path``
443 or ``foo = !`` when path is not supplied.
444
445 Example for ``~/.hgrc``::
446
447 [extensions]
448 # (the mq extension will get loaded from Mercurial's path)
449 mq =
450 # (this extension will get loaded from the file specified)
451 myfeature = ~/.hgext/myfeature.py
452
453
454 ``hostfingerprints``
455 """"""""""""""""""""
456
457 Fingerprints of the certificates of known HTTPS servers.
458 A HTTPS connection to a server with a fingerprint configured here will
459 only succeed if the servers certificate matches the fingerprint.
460 This is very similar to how ssh known hosts works.
461 The fingerprint is the SHA-1 hash value of the DER encoded certificate.
462 The CA chain and web.cacerts is not used for servers with a fingerprint.
463
464 For example::
465
466 [hostfingerprints]
467 hg.intevation.org = 38:76:52:7c:87:26:9a:8f:4a:f8:d3:de:08:45:3b:ea:d6:4b:ee:cc
468
469 This feature is only supported when using Python 2.6 or later.
470
471
472 ``format``
473 """"""""""
474
475 ``usestore``
476 Enable or disable the "store" repository format which improves
477 compatibility with systems that fold case or otherwise mangle
478 filenames. Enabled by default. Disabling this option will allow
479 you to store longer filenames in some situations at the expense of
480 compatibility and ensures that the on-disk format of newly created
481 repositories will be compatible with Mercurial before version 0.9.4.
482
483 ``usefncache``
484 Enable or disable the "fncache" repository format which enhances
485 the "store" repository format (which has to be enabled to use
486 fncache) to allow longer filenames and avoids using Windows
487 reserved names, e.g. "nul". Enabled by default. Disabling this
488 option ensures that the on-disk format of newly created
489 repositories will be compatible with Mercurial before version 1.1.
490
491 ``dotencode``
492 Enable or disable the "dotencode" repository format which enhances
493 the "fncache" repository format (which has to be enabled to use
494 dotencode) to avoid issues with filenames starting with ._ on
495 Mac OS X and spaces on Windows. Enabled by default. Disabling this
496 option ensures that the on-disk format of newly created
497 repositories will be compatible with Mercurial before version 1.7.
498
499 ``merge-patterns``
500 """"""""""""""""""
501
502 This section specifies merge tools to associate with particular file
503 patterns. Tools matched here will take precedence over the default
504 merge tool. Patterns are globs by default, rooted at the repository
505 root.
506
507 Example::
508
509 [merge-patterns]
510 **.c = kdiff3
511 **.jpg = myimgmerge
512
513 ``merge-tools``
514 """""""""""""""
515
516 This section configures external merge tools to use for file-level
517 merges.
518
519 Example ``~/.hgrc``::
520
521 [merge-tools]
522 # Override stock tool location
523 kdiff3.executable = ~/bin/kdiff3
524 # Specify command line
525 kdiff3.args = $base $local $other -o $output
526 # Give higher priority
527 kdiff3.priority = 1
528
529 # Define new tool
530 myHtmlTool.args = -m $local $other $base $output
531 myHtmlTool.regkey = Software\FooSoftware\HtmlMerge
532 myHtmlTool.priority = 1
533
534 Supported arguments:
535
536 ``priority``
537 The priority in which to evaluate this tool.
538 Default: 0.
539 ``executable``
540 Either just the name of the executable or its pathname. On Windows,
541 the path can use environment variables with ${ProgramFiles} syntax.
542 Default: the tool name.
543 ``args``
544 The arguments to pass to the tool executable. You can refer to the
545 files being merged as well as the output file through these
546 variables: ``$base``, ``$local``, ``$other``, ``$output``.
547 Default: ``$local $base $other``
548 ``premerge``
549 Attempt to run internal non-interactive 3-way merge tool before
550 launching external tool. Options are ``true``, ``false``, or ``keep``
551 to leave markers in the file if the premerge fails.
552 Default: True
553 ``binary``
554 This tool can merge binary files. Defaults to False, unless tool
555 was selected by file pattern match.
556 ``symlink``
557 This tool can merge symlinks. Defaults to False, even if tool was
558 selected by file pattern match.
559 ``check``
560 A list of merge success-checking options:
561
562 ``changed``
563 Ask whether merge was successful when the merged file shows no changes.
564 ``conflicts``
565 Check whether there are conflicts even though the tool reported success.
566 ``prompt``
567 Always prompt for merge success, regardless of success reported by tool.
568
569 ``checkchanged``
570 True is equivalent to ``check = changed``.
571 Default: False
572 ``checkconflicts``
573 True is equivalent to ``check = conflicts``.
574 Default: False
575 ``fixeol``
576 Attempt to fix up EOL changes caused by the merge tool.
577 Default: False
578 ``gui``
579 This tool requires a graphical interface to run. Default: False
580 ``regkey``
581 Windows registry key which describes install location of this
582 tool. Mercurial will search for this key first under
583 ``HKEY_CURRENT_USER`` and then under ``HKEY_LOCAL_MACHINE``.
584 Default: None
585 ``regkeyalt``
586 An alternate Windows registry key to try if the first key is not
587 found. The alternate key uses the same ``regname`` and ``regappend``
588 semantics of the primary key. The most common use for this key
589 is to search for 32bit applications on 64bit operating systems.
590 Default: None
591 ``regname``
592 Name of value to read from specified registry key. Defaults to the
593 unnamed (default) value.
594 ``regappend``
595 String to append to the value read from the registry, typically
596 the executable name of the tool.
597 Default: None
598
599
600 ``hooks``
601 """""""""
602
603 Commands or Python functions that get automatically executed by
604 various actions such as starting or finishing a commit. Multiple
605 hooks can be run for the same action by appending a suffix to the
606 action. Overriding a site-wide hook can be done by changing its
607 value or setting it to an empty string.
608
609 Example ``.hg/hgrc``::
610
611 [hooks]
612 # update working directory after adding changesets
613 changegroup.update = hg update
614 # do not use the site-wide hook
615 incoming =
616 incoming.email = /my/email/hook
617 incoming.autobuild = /my/build/hook
618
619 Most hooks are run with environment variables set that give useful
620 additional information. For each hook below, the environment
621 variables it is passed are listed with names of the form ``$HG_foo``.
622
623 ``changegroup``
624 Run after a changegroup has been added via push, pull or unbundle.
625 ID of the first new changeset is in ``$HG_NODE``. URL from which
626 changes came is in ``$HG_URL``.
627 ``commit``
628 Run after a changeset has been created in the local repository. ID
629 of the newly created changeset is in ``$HG_NODE``. Parent changeset
630 IDs are in ``$HG_PARENT1`` and ``$HG_PARENT2``.
631 ``incoming``
632 Run after a changeset has been pulled, pushed, or unbundled into
633 the local repository. The ID of the newly arrived changeset is in
634 ``$HG_NODE``. URL that was source of changes came is in ``$HG_URL``.
635 ``outgoing``
636 Run after sending changes from local repository to another. ID of
637 first changeset sent is in ``$HG_NODE``. Source of operation is in
638 ``$HG_SOURCE``; see "preoutgoing" hook for description.
639 ``post-<command>``
640 Run after successful invocations of the associated command. The
641 contents of the command line are passed as ``$HG_ARGS`` and the result
642 code in ``$HG_RESULT``. Parsed command line arguments are passed as
643 ``$HG_PATS`` and ``$HG_OPTS``. These contain string representations of
644 the python data internally passed to <command>. ``$HG_OPTS`` is a
645 dictionary of options (with unspecified options set to their defaults).
646 ``$HG_PATS`` is a list of arguments. Hook failure is ignored.
647 ``pre-<command>``
648 Run before executing the associated command. The contents of the
649 command line are passed as ``$HG_ARGS``. Parsed command line arguments
650 are passed as ``$HG_PATS`` and ``$HG_OPTS``. These contain string
651 representations of the data internally passed to <command>. ``$HG_OPTS``
652 is a dictionary of options (with unspecified options set to their
653 defaults). ``$HG_PATS`` is a list of arguments. If the hook returns
654 failure, the command doesn't execute and Mercurial returns the failure
655 code.
656 ``prechangegroup``
657 Run before a changegroup is added via push, pull or unbundle. Exit
658 status 0 allows the changegroup to proceed. Non-zero status will
659 cause the push, pull or unbundle to fail. URL from which changes
660 will come is in ``$HG_URL``.
661 ``precommit``
662 Run before starting a local commit. Exit status 0 allows the
663 commit to proceed. Non-zero status will cause the commit to fail.
664 Parent changeset IDs are in ``$HG_PARENT1`` and ``$HG_PARENT2``.
665 ``prelistkeys``
666 Run before listing pushkeys (like bookmarks) in the
667 repository. Non-zero status will cause failure. The key namespace is
668 in ``$HG_NAMESPACE``.
669 ``preoutgoing``
670 Run before collecting changes to send from the local repository to
671 another. Non-zero status will cause failure. This lets you prevent
672 pull over HTTP or SSH. Also prevents against local pull, push
673 (outbound) or bundle commands, but not effective, since you can
674 just copy files instead then. Source of operation is in
675 ``$HG_SOURCE``. If "serve", operation is happening on behalf of remote
676 SSH or HTTP repository. If "push", "pull" or "bundle", operation
677 is happening on behalf of repository on same system.
678 ``prepushkey``
679 Run before a pushkey (like a bookmark) is added to the
680 repository. Non-zero status will cause the key to be rejected. The
681 key namespace is in ``$HG_NAMESPACE``, the key is in ``$HG_KEY``,
682 the old value (if any) is in ``$HG_OLD``, and the new value is in
683 ``$HG_NEW``.
684 ``pretag``
685 Run before creating a tag. Exit status 0 allows the tag to be
686 created. Non-zero status will cause the tag to fail. ID of
687 changeset to tag is in ``$HG_NODE``. Name of tag is in ``$HG_TAG``. Tag is
688 local if ``$HG_LOCAL=1``, in repository if ``$HG_LOCAL=0``.
689 ``pretxnchangegroup``
690 Run after a changegroup has been added via push, pull or unbundle,
691 but before the transaction has been committed. Changegroup is
692 visible to hook program. This lets you validate incoming changes
693 before accepting them. Passed the ID of the first new changeset in
694 ``$HG_NODE``. Exit status 0 allows the transaction to commit. Non-zero
695 status will cause the transaction to be rolled back and the push,
696 pull or unbundle will fail. URL that was source of changes is in
697 ``$HG_URL``.
698 ``pretxncommit``
699 Run after a changeset has been created but the transaction not yet
700 committed. Changeset is visible to hook program. This lets you
701 validate commit message and changes. Exit status 0 allows the
702 commit to proceed. Non-zero status will cause the transaction to
703 be rolled back. ID of changeset is in ``$HG_NODE``. Parent changeset
704 IDs are in ``$HG_PARENT1`` and ``$HG_PARENT2``.
705 ``preupdate``
706 Run before updating the working directory. Exit status 0 allows
707 the update to proceed. Non-zero status will prevent the update.
708 Changeset ID of first new parent is in ``$HG_PARENT1``. If merge, ID
709 of second new parent is in ``$HG_PARENT2``.
710 ``listkeys``
711 Run after listing pushkeys (like bookmarks) in the repository. The
712 key namespace is in ``$HG_NAMESPACE``. ``$HG_VALUES`` is a
713 dictionary containing the keys and values.
714 ``pushkey``
715 Run after a pushkey (like a bookmark) is added to the
716 repository. The key namespace is in ``$HG_NAMESPACE``, the key is in
717 ``$HG_KEY``, the old value (if any) is in ``$HG_OLD``, and the new
718 value is in ``$HG_NEW``.
719 ``tag``
720 Run after a tag is created. ID of tagged changeset is in ``$HG_NODE``.
721 Name of tag is in ``$HG_TAG``. Tag is local if ``$HG_LOCAL=1``, in
722 repository if ``$HG_LOCAL=0``.
723 ``update``
724 Run after updating the working directory. Changeset ID of first
725 new parent is in ``$HG_PARENT1``. If merge, ID of second new parent is
726 in ``$HG_PARENT2``. If the update succeeded, ``$HG_ERROR=0``. If the
727 update failed (e.g. because conflicts not resolved), ``$HG_ERROR=1``.
728
729 .. note:: It is generally better to use standard hooks rather than the
730 generic pre- and post- command hooks as they are guaranteed to be
731 called in the appropriate contexts for influencing transactions.
732 Also, hooks like "commit" will be called in all contexts that
733 generate a commit (e.g. tag) and not just the commit command.
734
735 .. note:: Environment variables with empty values may not be passed to
736 hooks on platforms such as Windows. As an example, ``$HG_PARENT2``
737 will have an empty value under Unix-like platforms for non-merge
738 changesets, while it will not be available at all under Windows.
739
740 The syntax for Python hooks is as follows::
741
742 hookname = python:modulename.submodule.callable
743 hookname = python:/path/to/python/module.py:callable
744
745 Python hooks are run within the Mercurial process. Each hook is
746 called with at least three keyword arguments: a ui object (keyword
747 ``ui``), a repository object (keyword ``repo``), and a ``hooktype``
748 keyword that tells what kind of hook is used. Arguments listed as
749 environment variables above are passed as keyword arguments, with no
750 ``HG_`` prefix, and names in lower case.
751
752 If a Python hook returns a "true" value or raises an exception, this
753 is treated as a failure.
754
755
756 ``http_proxy``
757 """"""""""""""
758
759 Used to access web-based Mercurial repositories through a HTTP
760 proxy.
761
762 ``host``
763 Host name and (optional) port of the proxy server, for example
764 "myproxy:8000".
765 ``no``
766 Optional. Comma-separated list of host names that should bypass
767 the proxy.
768 ``passwd``
769 Optional. Password to authenticate with at the proxy server.
770 ``user``
771 Optional. User name to authenticate with at the proxy server.
772 ``always``
773 Optional. Always use the proxy, even for localhost and any entries
774 in ``http_proxy.no``. True or False. Default: False.
775
776 ``smtp``
777 """"""""
778
779 Configuration for extensions that need to send email messages.
780
781 ``host``
782 Host name of mail server, e.g. "mail.example.com".
783 ``port``
784 Optional. Port to connect to on mail server. Default: 25.
785 ``tls``
786 Optional. Method to enable TLS when connecting to mail server: starttls,
787 smtps or none. Default: none.
788 ``username``
789 Optional. User name for authenticating with the SMTP server.
790 Default: none.
791 ``password``
792 Optional. Password for authenticating with the SMTP server. If not
793 specified, interactive sessions will prompt the user for a
794 password; non-interactive sessions will fail. Default: none.
795 ``local_hostname``
796 Optional. It's the hostname that the sender can use to identify
797 itself to the MTA.
798
799
800 ``patch``
801 """""""""
802
803 Settings used when applying patches, for instance through the 'import'
804 command or with Mercurial Queues extension.
805
806 ``eol``
807 When set to 'strict' patch content and patched files end of lines
808 are preserved. When set to ``lf`` or ``crlf``, both files end of
809 lines are ignored when patching and the result line endings are
810 normalized to either LF (Unix) or CRLF (Windows). When set to
811 ``auto``, end of lines are again ignored while patching but line
812 endings in patched files are normalized to their original setting
813 on a per-file basis. If target file does not exist or has no end
814 of line, patch line endings are preserved.
815 Default: strict.
816
817
818 ``paths``
819 """""""""
820
821 Assigns symbolic names to repositories. The left side is the
822 symbolic name, and the right gives the directory or URL that is the
823 location of the repository. Default paths can be declared by setting
824 the following entries.
825
826 ``default``
827 Directory or URL to use when pulling if no source is specified.
828 Default is set to repository from which the current repository was
829 cloned.
830 ``default-push``
831 Optional. Directory or URL to use when pushing if no destination
832 is specified.
833
834
835 ``profiling``
836 """""""""""""
837
838 Specifies profiling format and file output. In this section
839 description, 'profiling data' stands for the raw data collected
840 during profiling, while 'profiling report' stands for a statistical
841 text report generated from the profiling data. The profiling is done
842 using lsprof.
843
844 ``format``
845 Profiling format.
846 Default: text.
847
848 ``text``
849 Generate a profiling report. When saving to a file, it should be
850 noted that only the report is saved, and the profiling data is
851 not kept.
852 ``kcachegrind``
853 Format profiling data for kcachegrind use: when saving to a
854 file, the generated file can directly be loaded into
855 kcachegrind.
856 ``output``
857 File path where profiling data or report should be saved. If the
858 file exists, it is replaced. Default: None, data is printed on
859 stderr
860
861 ``server``
862 """"""""""
863
864 Controls generic server settings.
865
866 ``uncompressed``
867 Whether to allow clients to clone a repository using the
868 uncompressed streaming protocol. This transfers about 40% more
869 data than a regular clone, but uses less memory and CPU on both
870 server and client. Over a LAN (100 Mbps or better) or a very fast
871 WAN, an uncompressed streaming clone is a lot faster (~10x) than a
872 regular clone. Over most WAN connections (anything slower than
873 about 6 Mbps), uncompressed streaming is slower, because of the
874 extra data transfer overhead. This mode will also temporarily hold
875 the write lock while determining what data to transfer.
876 Default is True.
877
878 ``validate``
879 Whether to validate the completeness of pushed changesets by
880 checking that all new file revisions specified in manifests are
881 present. Default is False.
882
883 ``subpaths``
884 """"""""""""
885
886 Defines subrepositories source locations rewriting rules of the form::
887
888 <pattern> = <replacement>
889
890 Where ``pattern`` is a regular expression matching the source and
891 ``replacement`` is the replacement string used to rewrite it. Groups
892 can be matched in ``pattern`` and referenced in ``replacements``. For
893 instance::
894
895 http://server/(.*)-hg/ = http://hg.server/\1/
896
897 rewrites ``http://server/foo-hg/`` into ``http://hg.server/foo/``.
898
899 All patterns are applied in definition order.
900
901 ``trusted``
902 """""""""""
903
904 Mercurial will not use the settings in the
905 ``.hg/hgrc`` file from a repository if it doesn't belong to a trusted
906 user or to a trusted group, as various hgrc features allow arbitrary
907 commands to be run. This issue is often encountered when configuring
908 hooks or extensions for shared repositories or servers. However,
909 the web interface will use some safe settings from the ``[web]``
910 section.
911
912 This section specifies what users and groups are trusted. The
913 current user is always trusted. To trust everybody, list a user or a
914 group with name ``*``. These settings must be placed in an
915 *already-trusted file* to take effect, such as ``$HOME/.hgrc`` of the
916 user or service running Mercurial.
917
918 ``users``
919 Comma-separated list of trusted users.
920 ``groups``
921 Comma-separated list of trusted groups.
922
923
924 ``ui``
925 """"""
926
927 User interface controls.
928
929 ``archivemeta``
930 Whether to include the .hg_archival.txt file containing meta data
931 (hashes for the repository base and for tip) in archives created
932 by the :hg:`archive` command or downloaded via hgweb.
933 Default is True.
934 ``askusername``
935 Whether to prompt for a username when committing. If True, and
936 neither ``$HGUSER`` nor ``$EMAIL`` has been specified, then the user will
937 be prompted to enter a username. If no username is entered, the
938 default ``USER@HOST`` is used instead.
939 Default is False.
940 ``commitsubrepos``
941 Whether to commit modified subrepositories when committing the
942 parent repository. If False and one subrepository has uncommitted
943 changes, abort the commit.
944 Default is True.
945 ``debug``
946 Print debugging information. True or False. Default is False.
947 ``editor``
948 The editor to use during a commit. Default is ``$EDITOR`` or ``vi``.
949 ``fallbackencoding``
950 Encoding to try if it's not possible to decode the changelog using
951 UTF-8. Default is ISO-8859-1.
952 ``ignore``
953 A file to read per-user ignore patterns from. This file should be
954 in the same format as a repository-wide .hgignore file. This
955 option supports hook syntax, so if you want to specify multiple
956 ignore files, you can do so by setting something like
957 ``ignore.other = ~/.hgignore2``. For details of the ignore file
958 format, see the |hgignore(5)|_ man page.
959 ``interactive``
960 Allow to prompt the user. True or False. Default is True.
961 ``logtemplate``
962 Template string for commands that print changesets.
963 ``merge``
964 The conflict resolution program to use during a manual merge.
965 For more information on merge tools see :hg:`help merge-tools`.
966 For configuring merge tools see the merge-tools_ section.
967 ``portablefilenames``
968 Check for portable filenames. Can be ``warn``, ``ignore`` or ``abort``.
969 Default is ``warn``.
970 If set to ``warn`` (or ``true``), a warning message is printed on POSIX
971 platforms, if a file with a non-portable filename is added (e.g. a file
972 with a name that can't be created on Windows because it contains reserved
973 parts like ``AUX``, reserved characters like ``:``, or would cause a case
974 collision with an existing file).
975 If set to ``ignore`` (or ``false``), no warning is printed.
976 If set to ``abort``, the command is aborted.
977 On Windows, this configuration option is ignored and the command aborted.
978 ``quiet``
979 Reduce the amount of output printed. True or False. Default is False.
980 ``remotecmd``
981 remote command to use for clone/push/pull operations. Default is ``hg``.
982 ``report_untrusted``
983 Warn if a ``.hg/hgrc`` file is ignored due to not being owned by a
984 trusted user or group. True or False. Default is True.
985 ``slash``
986 Display paths using a slash (``/``) as the path separator. This
987 only makes a difference on systems where the default path
988 separator is not the slash character (e.g. Windows uses the
989 backslash character (``\``)).
990 Default is False.
991 ``ssh``
992 command to use for SSH connections. Default is ``ssh``.
993 ``strict``
994 Require exact command names, instead of allowing unambiguous
995 abbreviations. True or False. Default is False.
996 ``style``
997 Name of style to use for command output.
998 ``timeout``
999 The timeout used when a lock is held (in seconds), a negative value
1000 means no timeout. Default is 600.
1001 ``traceback``
1002 Mercurial always prints a traceback when an unknown exception
1003 occurs. Setting this to True will make Mercurial print a traceback
1004 on all exceptions, even those recognized by Mercurial (such as
1005 IOError or MemoryError). Default is False.
1006 ``username``
1007 The committer of a changeset created when running "commit".
1008 Typically a person's name and email address, e.g. ``Fred Widget
1009 <fred@example.com>``. Default is ``$EMAIL`` or ``username@hostname``. If
1010 the username in hgrc is empty, it has to be specified manually or
1011 in a different hgrc file (e.g. ``$HOME/.hgrc``, if the admin set
1012 ``username =`` in the system hgrc). Environment variables in the
1013 username are expanded.
1014 ``verbose``
1015 Increase the amount of output printed. True or False. Default is False.
1016
1017
1018 ``web``
1019 """""""
1020
1021 Web interface configuration. The settings in this section apply to
1022 both the builtin webserver (started by :hg:`serve`) and the script you
1023 run through a webserver (``hgweb.cgi`` and the derivatives for FastCGI
1024 and WSGI).
1025
1026 The Mercurial webserver does no authentication (it does not prompt for
1027 usernames and passwords to validate *who* users are), but it does do
1028 authorization (it grants or denies access for *authenticated users*
1029 based on settings in this section). You must either configure your
1030 webserver to do authentication for you, or disable the authorization
1031 checks.
1032
1033 For a quick setup in a trusted environment, e.g., a private LAN, where
1034 you want it to accept pushes from anybody, you can use the following
1035 command line::
1036
1037 $ hg --config web.allow_push=* --config web.push_ssl=False serve
1038
1039 Note that this will allow anybody to push anything to the server and
1040 that this should not be used for public servers.
1041
1042 The full set of options is:
1043
1044 ``accesslog``
1045 Where to output the access log. Default is stdout.
1046 ``address``
1047 Interface address to bind to. Default is all.
1048 ``allow_archive``
1049 List of archive format (bz2, gz, zip) allowed for downloading.
1050 Default is empty.
1051 ``allowbz2``
1052 (DEPRECATED) Whether to allow .tar.bz2 downloading of repository
1053 revisions.
1054 Default is False.
1055 ``allowgz``
1056 (DEPRECATED) Whether to allow .tar.gz downloading of repository
1057 revisions.
1058 Default is False.
1059 ``allowpull``
1060 Whether to allow pulling from the repository. Default is True.
1061 ``allow_push``
1062 Whether to allow pushing to the repository. If empty or not set,
1063 push is not allowed. If the special value ``*``, any remote user can
1064 push, including unauthenticated users. Otherwise, the remote user
1065 must have been authenticated, and the authenticated user name must
1066 be present in this list. The contents of the allow_push list are
1067 examined after the deny_push list.
1068 ``allow_read``
1069 If the user has not already been denied repository access due to
1070 the contents of deny_read, this list determines whether to grant
1071 repository access to the user. If this list is not empty, and the
1072 user is unauthenticated or not present in the list, then access is
1073 denied for the user. If the list is empty or not set, then access
1074 is permitted to all users by default. Setting allow_read to the
1075 special value ``*`` is equivalent to it not being set (i.e. access
1076 is permitted to all users). The contents of the allow_read list are
1077 examined after the deny_read list.
1078 ``allowzip``
1079 (DEPRECATED) Whether to allow .zip downloading of repository
1080 revisions. Default is False. This feature creates temporary files.
1081 ``baseurl``
1082 Base URL to use when publishing URLs in other locations, so
1083 third-party tools like email notification hooks can construct
1084 URLs. Example: ``http://hgserver/repos/``.
1085 ``cacerts``
1086 Path to file containing a list of PEM encoded certificate
1087 authority certificates. Environment variables and ``~user``
1088 constructs are expanded in the filename. If specified on the
1089 client, then it will verify the identity of remote HTTPS servers
1090 with these certificates. The form must be as follows::
1091
1092 -----BEGIN CERTIFICATE-----
1093 ... (certificate in base64 PEM encoding) ...
1094 -----END CERTIFICATE-----
1095 -----BEGIN CERTIFICATE-----
1096 ... (certificate in base64 PEM encoding) ...
1097 -----END CERTIFICATE-----
1098
1099 This feature is only supported when using Python 2.6 or later. If you wish
1100 to use it with earlier versions of Python, install the backported
1101 version of the ssl library that is available from
1102 ``http://pypi.python.org``.
1103
1104 You can use OpenSSL's CA certificate file if your platform has one.
1105 On most Linux systems this will be ``/etc/ssl/certs/ca-certificates.crt``.
1106 Otherwise you will have to generate this file manually.
1107
1108 To disable SSL verification temporarily, specify ``--insecure`` from
1109 command line.
1110 ``cache``
1111 Whether to support caching in hgweb. Defaults to True.
1112 ``contact``
1113 Name or email address of the person in charge of the repository.
1114 Defaults to ui.username or ``$EMAIL`` or "unknown" if unset or empty.
1115 ``deny_push``
1116 Whether to deny pushing to the repository. If empty or not set,
1117 push is not denied. If the special value ``*``, all remote users are
1118 denied push. Otherwise, unauthenticated users are all denied, and
1119 any authenticated user name present in this list is also denied. The
1120 contents of the deny_push list are examined before the allow_push list.
1121 ``deny_read``
1122 Whether to deny reading/viewing of the repository. If this list is
1123 not empty, unauthenticated users are all denied, and any
1124 authenticated user name present in this list is also denied access to
1125 the repository. If set to the special value ``*``, all remote users
1126 are denied access (rarely needed ;). If deny_read is empty or not set,
1127 the determination of repository access depends on the presence and
1128 content of the allow_read list (see description). If both
1129 deny_read and allow_read are empty or not set, then access is
1130 permitted to all users by default. If the repository is being
1131 served via hgwebdir, denied users will not be able to see it in
1132 the list of repositories. The contents of the deny_read list have
1133 priority over (are examined before) the contents of the allow_read
1134 list.
1135 ``descend``
1136 hgwebdir indexes will not descend into subdirectories. Only repositories
1137 directly in the current path will be shown (other repositories are still
1138 available from the index corresponding to their containing path).
1139 ``description``
1140 Textual description of the repository's purpose or contents.
1141 Default is "unknown".
1142 ``encoding``
1143 Character encoding name. Default is the current locale charset.
1144 Example: "UTF-8"
1145 ``errorlog``
1146 Where to output the error log. Default is stderr.
1147 ``hidden``
1148 Whether to hide the repository in the hgwebdir index.
1149 Default is False.
1150 ``ipv6``
1151 Whether to use IPv6. Default is False.
1152 ``logourl``
1153 Base URL to use for logos. If unset, ``http://mercurial.selenic.com/``
1154 will be used.
1155 ``name``
1156 Repository name to use in the web interface. Default is current
1157 working directory.
1158 ``maxchanges``
1159 Maximum number of changes to list on the changelog. Default is 10.
1160 ``maxfiles``
1161 Maximum number of files to list per changeset. Default is 10.
1162 ``port``
1163 Port to listen on. Default is 8000.
1164 ``prefix``
1165 Prefix path to serve from. Default is '' (server root).
1166 ``push_ssl``
1167 Whether to require that inbound pushes be transported over SSL to
1168 prevent password sniffing. Default is True.
1169 ``staticurl``
1170 Base URL to use for static files. If unset, static files (e.g. the
1171 hgicon.png favicon) will be served by the CGI script itself. Use
1172 this setting to serve them directly with the HTTP server.
1173 Example: ``http://hgserver/static/``.
1174 ``stripes``
1175 How many lines a "zebra stripe" should span in multiline output.
1176 Default is 1; set to 0 to disable.
1177 ``style``
1178 Which template map style to use.
1179 ``templates``
1180 Where to find the HTML templates. Default is install path.
1181
1182 26
1183 Author 27 Author
1184 ------ 28 ------
1185 Bryan O'Sullivan <bos@serpentine.com>. 29 Bryan O'Sullivan <bos@serpentine.com>.
1186 30