hgrc(5) — Linux manual page

NAME | SYNOPSIS | FILES | SYNTAX | SECTIONS | AUTHOR | SEE ALSO | COPYING | AUTHOR | COLOPHON

HGRC(5)                     Mercurial Manual                     HGRC(5)

NAME         top

       hgrc - configuration files for Mercurial

SYNOPSIS         top

       The Mercurial system uses a set of configuration files to control
       aspects of its behavior.

       The configuration files use a simple ini-file format. A
       configuration file consists of sections, led by a [section]
       header and followed by name = value entries:

       [ui]
       username = Firstname Lastname <firstname.lastname@example.net>
       verbose = True

       The above entries will be referred to as ui.username and
       ui.verbose, respectively. See the Syntax section below.

FILES         top

       Mercurial reads configuration data from several files, if they
       exist.  These files do not exist by default and you will have to
       create the appropriate configuration files yourself: global
       configuration like the username setting is typically put into
       %USERPROFILE%\mercurial.ini or $HOME/.hgrc and local
       configuration is put into the per-repository <repo>/.hg/hgrc
       file.

       The names of these files depend on the system on which Mercurial
       is installed. *.rc files from a single directory are read in
       alphabetical order, later ones overriding earlier ones. Where
       multiple paths are given below, settings from earlier paths
       override later ones.

       (All) <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 Plan 9 and 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.

       (Plan 9) $home/lib/hgrc
       (Unix) $HOME/.hgrc
       (Windows) %USERPROFILE%\.hgrc
       (Windows) %USERPROFILE%\Mercurial.ini
       (Windows) %HOME%\.hgrc
       (Windows) %HOME%\Mercurial.ini

          Per-user configuration file(s), for the user running
          Mercurial. On Windows 9x, %HOME% is replaced by %APPDATA%.
          Options in these files apply to all Mercurial commands
          executed by this user in any directory. Options in these files
          override per-system and per-installation options.

       (Plan 9) /lib/mercurial/hgrc
       (Plan 9) /lib/mercurial/hgrc.d/*.rc
       (Unix) /etc/mercurial/hgrc
       (Unix) /etc/mercurial/hgrc.d/*.rc

          Per-system configuration files, for the system on which
          Mercurial is running. Options in these files apply to all
          Mercurial commands executed by any user in any directory.
          Options in these files override per-installation options.

       (Plan 9) <install-root>/lib/mercurial/hgrc
       (Plan 9) <install-root>/lib/mercurial/hgrc.d/*.rc
       (Unix) <install-root>/etc/mercurial/hgrc
       (Unix) <install-root>/etc/mercurial/hgrc.d/*.rc

          Per-installation configuration files, searched for in the
          directory where Mercurial is installed. <install-root> is the
          parent directory of the hg executable (or symlink) being run.
          For example, if installed in /shared/tools/bin/hg, Mercurial
          will look in /shared/tools/etc/mercurial/hgrc. Options in
          these files apply to all Mercurial commands executed by any
          user in any directory.

       (Windows) <install-dir>\Mercurial.ini or
       (Windows) <install-dir>\hgrc.d\*.rc or
       (Windows) HKEY_LOCAL_MACHINE\SOFTWARE\Mercurial

          Per-installation/system configuration files, for the system on
          which Mercurial is running. Options in these files apply to
          all Mercurial commands executed by any user in any directory.
          Registry keys contain PATH-like strings, every part of which
          must reference a Mercurial.ini file or be a directory where
          *.rc files will be read.  Mercurial checks each of these
          locations in the specified order until one or more
          configuration files are detected.

       Note   The registry key
              HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Mercurial is used
              when running 32-bit Python on 64-bit Windows.

SYNTAX         top

       A configuration file consists of sections, led by a [section]
       header and followed by name = value entries (sometimes called
       configuration keys):

       [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. Lines beginning with # or ; are ignored and may be used
       to provide comments.

       Configuration keys can be set multiple times, in which case
       Mercurial will use the value that was configured last. As an
       example:

       [spam]
       eggs=large
       ham=serrano
       eggs=small

       This would set the configuration key named eggs to small.

       It is also possible to define a section multiple times. A section
       can be redefined on the same and/or on different configuration
       files. For example:

       [foo]
       eggs=large
       ham=serrano
       eggs=small

       [bar]
       eggs=ham
       green=
          eggs

       [foo]
       ham=prosciutto
       eggs=medium
       bread=toasted

       This would set the eggs, ham, and bread configuration keys of the
       foo section to medium, prosciutto, and toasted, respectively. As
       you can see there only thing that matters is the last value that
       was set for each of the configuration keys.

       If a configuration key is set multiple times in different
       configuration files the final value will depend on the order in
       which the different configuration files are read, with settings
       from earlier paths overriding later ones as described on the
       Files section above.

       A line of the form %include file will include file into the
       current configuration file. The inclusion is recursive, which
       means that included files can include other files. Filenames are
       relative to the configuration file in which the %include
       directive is found.  Environment variables and ~user constructs
       are expanded in file. This lets you do something like:

       %include ~/.hgrc.d/$HOST.rc

       to include a different configuration file on each computer you
       use.

       A line with %unset name will remove name from the current
       section, if it has been set previously.

       The values are either free-form text strings, lists of text
       strings, or Boolean values. Boolean values can be set to true
       using any of "1", "yes", "true", or "on" and to false using "0",
       "no", "false", or "off" (all case insensitive).

       List values are separated by whitespace or comma, except when
       values are placed in double quotation marks:

       allow_read = "John Doe, PhD", brian, betty

       Quotation marks can be escaped by prefixing them with a
       backslash. Only quotation marks at the beginning of a word is
       counted as a quotation (e.g., foo"bar baz is the list of foo"bar
       and baz).

SECTIONS         top

       This section describes the different sections that may appear in
       a Mercurial configuration file, the purpose of each section, its
       possible keys, and their possible values.

   alias
       Defines command aliases.  Aliases allow you to define your own
       commands in terms of other commands (or aliases), optionally
       including arguments. Positional arguments in the form of $1, $2,
       etc in the alias definition are expanded by Mercurial before
       execution. Positional arguments not already used by $N in the
       definition are put at the end of the command to be executed.

       Alias definitions consist of lines of the form:

       <alias> = <command> [<argument>]...

       For example, this definition:

       latest = log --limit 5

       creates a new command latest that shows only the five most recent
       changesets. You can define subsequent aliases using earlier ones:

       stable5 = latest -b stable

       Note   It is possible to create aliases with the same names as
              existing commands, which will then override the original
              definitions. This is almost always a bad idea!

       An alias can start with an exclamation point (!) to make it a
       shell alias. A shell alias is executed with the shell and will
       let you run arbitrary commands. As an example,

       echo = !echo $@

       will let you do hg echo foo to have foo printed in your terminal.
       A better example might be:

       purge = !$HG status --no-status --unknown -0 | xargs -0 rm

       which will make hg purge delete all unknown files in the
       repository in the same manner as the purge extension.

       Positional arguments like $1, $2, etc. in the alias definition
       expand to the command arguments. Unmatched arguments are removed.
       $0 expands to the alias name and $@ expands to all arguments
       separated by a space. These expansions happen before the command
       is passed to the shell.

       Shell aliases are executed in an environment where $HG expands to
       the path of the Mercurial that was used to execute the alias.
       This is useful when you want to call further Mercurial commands
       in a shell alias, as was done above for the purge alias. In
       addition, $HG_ARGS expands to the arguments given to Mercurial.
       In the hg echo foo call above, $HG_ARGS would expand to echo foo.

       Note   Some global configuration options such as -R are processed
              before shell aliases and will thus not be passed to
              aliases.

   annotate
       Settings used when displaying file annotations. All values are
       Booleans and default to False. See diff section for related
       options for the diff command.

       ignorews

              Ignore white space when comparing lines.

       ignorewsamount

              Ignore changes in the amount of white space.

       ignoreblanklines

              Ignore changes whose lines are all blank.

   auth
       Authentication credentials for HTTP authentication. This section
       allows you to store usernames and passwords for use when logging
       into HTTP servers. See the [web] configuration section if you
       want to configure who can login to your HTTP server.

       Each line has the following format:

       <name>.<argument> = <value>

       where <name> is used to group arguments into authentication
       entries. Example:

       foo.prefix = hg.intevation.org/mercurial
       foo.username = foo
       foo.password = bar
       foo.schemes = http https

       bar.prefix = secure.example.org
       bar.key = path/to/file.key
       bar.cert = path/to/file.cert
       bar.schemes = https

       Supported arguments:

       prefix

              Either * or a URI prefix with or without the scheme part.
              The authentication entry with the longest matching prefix
              is used (where * matches everything and counts as a match
              of length 1). If the prefix doesn't include a scheme, the
              match is performed against the URI with its scheme
              stripped as well, and the schemes argument, q.v., is then
              subsequently consulted.

       username

              Optional. Username to authenticate with. If not given, and
              the remote site requires basic or digest authentication,
              the user will be prompted for it. Environment variables
              are expanded in the username letting you do foo.username =
              $USER. If the URI includes a username, only [auth] entries
              with a matching username or without a username will be
              considered.

       password

              Optional. Password to authenticate with. If not given, and
              the remote site requires basic or digest authentication,
              the user will be prompted for it.

       key

              Optional. PEM encoded client certificate key file.
              Environment variables are expanded in the filename.

       cert

              Optional. PEM encoded client certificate chain file.
              Environment variables are expanded in the filename.

       schemes

              Optional. Space separated list of URI schemes to use this
              authentication entry with. Only used if the prefix doesn't
              include a scheme. Supported schemes are http and https.
              They will match static-http and static-https respectively,
              as well.  Default: https.

       If no suitable authentication entry is found, the user is
       prompted for credentials as usual if required by the remote.

   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.  For each
       file only the first matching filter applies.

       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 and may corrupt the contents of your
              files.

       This filter mechanism is used internally by the eol extension to
       translate line ending characters between Windows (CRLF) and Unix
       (LF) format. We suggest you use the eol extension for
       convenience.

   defaults
       (defaults are deprecated. Don't use them. Use aliases instead)

       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. Everything except for
       unified is a Boolean and defaults to False. See annotate section
       for related options for the annotate command.

       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.

       unified

              Number of lines of context to show.

   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.

       method

              Optional. Method to use to send email messages. If value
              is smtp (default), use SMTP (see the [smtp] section 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.

       charsets

              Optional. Comma-separated list of character sets
              considered convenient for recipients. Addresses, headers,
              and parts not containing patches of outgoing messages will
              be encoded in the first character set to which conversion
              from local encoding ($HGENCODING, ui.fallbackencoding)
              succeeds. If correct conversion fails, the text in
              question is sent as is. Defaults to empty (explicit) list.

              Order of outgoing email character sets:

              1. us-ascii: always first, regardless of settings

              2. email.charsets: in order given by user

              3. ui.fallbackencoding: if not in email.charsets

              4. $HGENCODING: if not in email.charsets

              5. utf-8: always last, regardless of settings

       Email example:

       [email]
       from = Joseph User <joe.user@example.com>
       method = /usr/sbin/sendmail
       # charsets for western Europeans
       # us-ascii, utf-8 omitted, as they are tried first and last
       charsets = iso-8859-1, iso-8859-15, windows-1252

   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.

       To explicitly disable an extension that is enabled in an hgrc of
       broader scope, prepend its path with !, as in foo = !/ext/path or
       foo = ! when path is not supplied.

       Example for ~/.hgrc:

       [extensions]
       # (the mq extension will get loaded from Mercurial's path)
       mq =
       # (this extension will get loaded from the file specified)
       myfeature = ~/.hgext/myfeature.py

   format
       usestore

              Enable or disable the "store" repository format which
              improves compatibility with systems that fold case or
              otherwise mangle filenames. Enabled by default. Disabling
              this option will allow you to store longer filenames in
              some situations at the expense of compatibility and
              ensures that the on-disk format of newly created
              repositories will be compatible with Mercurial before
              version 0.9.4.

       usefncache

              Enable or disable the "fncache" repository format which
              enhances the "store" repository format (which has to be
              enabled to use fncache) to allow longer filenames and
              avoids using Windows reserved names, e.g. "nul". Enabled
              by default. Disabling this option ensures that the on-disk
              format of newly created repositories will be compatible
              with Mercurial before version 1.1.

       dotencode

              Enable or disable the "dotencode" repository format which
              enhances the "fncache" repository format (which has to be
              enabled to use dotencode) to avoid issues with filenames
              starting with ._ on Mac OS X and spaces on Windows.
              Enabled by default. Disabling this option ensures that the
              on-disk format of newly created repositories will be
              compatible with Mercurial before version 1.7.

   graph
       Web graph view configuration. This section let you change graph
       elements display properties by branches, for instance to make the
       default branch stand out.

       Each line has the following format:

       <branch>.<argument> = <value>

       where <branch> is the name of the branch being customized.
       Example:

       [graph]
       # 2px width
       default.width = 2
       # red color
       default.color = FF0000

       Supported arguments:

       width

              Set branch edges width in pixels.

       color

              Set branch edges color in hexadecimal RGB notation.

   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.  Hooks can be prioritized
       by adding a prefix of priority to the hook name on a new line and
       setting the priority.  The default priority is 0 if not
       specified.

       Example .hg/hgrc:

       [hooks]
       # update working directory after adding changesets
       changegroup.update = hg update
       # do not use the site-wide hook
       incoming =
       incoming.email = /my/email/hook
       incoming.autobuild = /my/build/hook
       # force autobuild hook to run before other incoming hooks
       priority.incoming.autobuild = 1

       Most hooks are run with environment variables set that give
       useful additional 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.

       post-<command>

              Run after successful invocations of the associated
              command. The contents of the command line are passed as
              $HG_ARGS and the result code in $HG_RESULT. Parsed command
              line arguments are passed as $HG_PATS and $HG_OPTS. These
              contain string representations of the python data
              internally passed to <command>. $HG_OPTS is a dictionary
              of options (with unspecified options set to their
              defaults).  $HG_PATS is a list of arguments. Hook failure
              is ignored.

       pre-<command>

              Run before executing the associated command. The contents
              of the command line are passed as $HG_ARGS. Parsed command
              line arguments are passed as $HG_PATS and $HG_OPTS. These
              contain string representations of the data internally
              passed to <command>. $HG_OPTS is a  dictionary of options
              (with unspecified options set to their defaults). $HG_PATS
              is a list of arguments. If the hook returns failure, the
              command doesn't execute and Mercurial returns the failure
              code.

       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.

       prelistkeys

              Run before listing pushkeys (like bookmarks) in the
              repository. Non-zero status will cause failure. The key
              namespace is in $HG_NAMESPACE.

       preoutgoing

              Run before collecting 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.

       prepushkey

              Run before a pushkey (like a bookmark) is added to the
              repository. Non-zero status will cause the key to be
              rejected. The key namespace is in $HG_NAMESPACE, the key
              is in $HG_KEY, the old value (if any) is in $HG_OLD, and
              the new value is in $HG_NEW.

       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 repository 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.

       listkeys

              Run after listing pushkeys (like bookmarks) in the
              repository. The key namespace is in $HG_NAMESPACE.
              $HG_VALUES is a dictionary containing the keys and values.

       pushkey

              Run after a pushkey (like a bookmark) is added to the
              repository. The key namespace is in $HG_NAMESPACE, the key
              is in $HG_KEY, the old value (if any) is in $HG_OLD, and
              the new value is in $HG_NEW.

       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 repository 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 the update succeeded,
              $HG_ERROR=0. If the update failed (e.g. because conflicts
              not resolved), $HG_ERROR=1.

       Note   It is generally better to use standard hooks rather than
              the generic pre- and post- command hooks as they are
              guaranteed to be called in the appropriate contexts for
              influencing transactions.  Also, hooks like "commit" will
              be called in all contexts that generate a commit (e.g.
              tag) and not just the commit command.

       Note   Environment variables with empty values may not be passed
              to hooks on platforms such as Windows. As an example,
              $HG_PARENT2 will have an empty value under Unix-like
              platforms for non-merge changesets, while it will not be
              available at all under Windows.

       The syntax for Python hooks is as follows:

       hookname = python:modulename.submodule.callable
       hookname = python:/path/to/python/module.py: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 a failure.

   hostfingerprints
       Fingerprints of the certificates of known HTTPS servers.  A HTTPS
       connection to a server with a fingerprint configured here will
       only succeed if the servers certificate matches the fingerprint.
       This is very similar to how ssh known hosts works.  The
       fingerprint is the SHA-1 hash value of the DER encoded
       certificate.  The CA chain and web.cacerts is not used for
       servers with a fingerprint.

       For example:

       [hostfingerprints]
       hg.intevation.org = 44:ed:af:1f:97:11:b6:01:7a:48:45:fc:10:3c:b7:f9:d4:89:2a:9d

       This feature is only supported when using Python 2.6 or later.

   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.

       always

              Optional. Always use the proxy, even for localhost and any
              entries in http_proxy.no. True or False. Default: False.

   merge-patterns
       This section specifies merge tools to associate with particular
       file patterns. Tools matched here will take precedence over the
       default merge tool. Patterns are globs by default, rooted at the
       repository root.

       Example:

       [merge-patterns]
       **.c = kdiff3
       **.jpg = myimgmerge

   merge-tools
       This section configures external merge tools to use for
       file-level merges.

       Example ~/.hgrc:

       [merge-tools]
       # Override stock tool location
       kdiff3.executable = ~/bin/kdiff3
       # Specify command line
       kdiff3.args = $base $local $other -o $output
       # Give higher priority
       kdiff3.priority = 1

       # Define new tool
       myHtmlTool.args = -m $local $other $base $output
       myHtmlTool.regkey = Software\FooSoftware\HtmlMerge
       myHtmlTool.priority = 1

       Supported arguments:

       priority

              The priority in which to evaluate this tool.  Default: 0.

       executable

              Either just the name of the executable or its pathname.
              On Windows, the path can use environment variables with
              ${ProgramFiles} syntax.  Default: the tool name.

       args

              The arguments to pass to the tool executable. You can
              refer to the files being merged as well as the output file
              through these variables: $base, $local, $other, $output.
              Default: $local $base $other

       premerge

              Attempt to run internal non-interactive 3-way merge tool
              before launching external tool.  Options are true, false,
              or keep to leave markers in the file if the premerge
              fails.  Default: True

       binary

              This tool can merge binary files. Defaults to False,
              unless tool was selected by file pattern match.

       symlink

              This tool can merge symlinks. Defaults to False, even if
              tool was selected by file pattern match.

       check

              A list of merge success-checking options:

              changed

                     Ask whether merge was successful when the merged
                     file shows no changes.

              conflicts

                     Check whether there are conflicts even though the
                     tool reported success.

              prompt

                     Always prompt for merge success, regardless of
                     success reported by tool.

       fixeol

              Attempt to fix up EOL changes caused by the merge tool.
              Default: False

       gui

              This tool requires a graphical interface to run. Default:
              False

       regkey

              Windows registry key which describes install location of
              this tool. Mercurial will search for this key first under
              HKEY_CURRENT_USER and then under HKEY_LOCAL_MACHINE.
              Default: None

       regkeyalt

              An alternate Windows registry key to try if the first key
              is not found.  The alternate key uses the same regname and
              regappend semantics of the primary key.  The most common
              use for this key is to search for 32bit applications on
              64bit operating systems.  Default: None

       regname

              Name of value to read from specified registry key.
              Defaults to the unnamed (default) value.

       regappend

              String to append to the value read from the registry,
              typically the executable name of the tool.  Default: None

   patch
       Settings used when applying patches, for instance through the
       'import' command or with Mercurial Queues extension.

       eol

              When set to 'strict' patch content and patched files end
              of lines are preserved. When set to lf or crlf, both files
              end of lines are ignored when patching and the result line
              endings are normalized to either LF (Unix) or CRLF
              (Windows). When set to auto, end of lines are again
              ignored while patching but line endings in patched files
              are normalized to their original setting on a per-file
              basis. If target file does not exist or has no end of
              line, patch line endings are preserved.  Default: strict.

   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.

       Custom paths can be defined by assigning the path to a name that
       later can be used from the command line. Example:

       [paths]
       my_path = http://example.com/path

       To push to the path defined in my_path run the command:

       hg push my_path

   phases
       Specifies default handling of phases. See hg help phases for more
       information about working with phases.

       publish

              Controls draft phase behavior when working as a server.
              When true, pushed changesets are set to public in both
              client and server and pulled or cloned changesets are set
              to public in the client.  Default: True

       new-commit

              Phase of newly-created commits.  Default: draft

   profiling
       Specifies profiling type, format, and file output. Two profilers
       are supported: an instrumenting profiler (named ls), and a
       sampling profiler (named stat).

       In this section description, 'profiling data' stands for the raw
       data collected during profiling, while 'profiling report' stands
       for a statistical text report generated from the profiling data.
       The profiling is done using lsprof.

       type

              The type of profiler to use.  Default: ls.

              ls

                     Use Python's built-in instrumenting profiler. This
                     profiler works on all platforms, but each line
                     number it reports is the first line of a function.
                     This restriction makes it difficult to identify the
                     expensive parts of a non-trivial function.

              stat

                     Use a third-party statistical profiler, statprof.
                     This profiler currently runs only on Unix systems,
                     and is most useful for profiling commands that run
                     for longer than about 0.1 seconds.

       format

              Profiling format.  Specific to the ls instrumenting
              profiler.  Default: text.

              text

                     Generate a profiling report. When saving to a file,
                     it should be noted that only the report is saved,
                     and the profiling data is not kept.

              kcachegrind

                     Format profiling data for kcachegrind use: when
                     saving to a file, the generated file can directly
                     be loaded into kcachegrind.

       frequency

              Sampling frequency.  Specific to the stat sampling
              profiler.  Default: 1000.

       output

              File path where profiling data or report should be saved.
              If the file exists, it is replaced. Default: None, data is
              printed on stderr

       sort

              Sort field.  Specific to the ls instrumenting profiler.
              One of callcount, reccallcount, totaltime and inlinetime.
              Default: inlinetime.

       limit

              Number of lines to show. Specific to the ls instrumenting
              profiler.  Default: 30.

       nested

              Show at most this number of lines of drill-down info after
              each main entry.  This can help explain the difference
              between Total and Inline.  Specific to the ls
              instrumenting profiler.  Default: 5.

   revsetalias
       Alias definitions for revsets. See hg help revsets for details.

   server
       Controls generic server settings.

       uncompressed

              Whether to allow clients to clone a repository using the
              uncompressed streaming protocol. This transfers about 40%
              more data than a regular clone, but uses less memory and
              CPU on both server and client. Over a LAN (100 Mbps or
              better) or a very fast WAN, an uncompressed streaming
              clone is a lot faster (~10x) than a regular clone. Over
              most WAN connections (anything slower than about 6 Mbps),
              uncompressed streaming is slower, because of the extra
              data transfer overhead. This mode will also temporarily
              hold the write lock while determining what data to
              transfer.  Default is True.

       preferuncompressed

              When set, clients will try to use the uncompressed
              streaming protocol. Default is False.

       validate

              Whether to validate the completeness of pushed changesets
              by checking that all new file revisions specified in
              manifests are present. Default is False.

   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: 465
              (if tls is smtps) or 25 (otherwise).

       tls

              Optional. Method to enable TLS when connecting to mail
              server: starttls, smtps or none. Default: none.

       verifycert

              Optional. Verification for the certificate of mail server,
              when tls is starttls or smtps. "strict", "loose" or False.
              For "strict" or "loose", the certificate is verified as
              same as the verification for HTTPS connections (see
              [hostfingerprints] and [web] cacerts also). For "strict",
              sending email is also aborted, if there is no
              configuration for mail server in [hostfingerprints] and
              [web] cacerts.  --insecure for hg email overwrites this as
              "loose". Default: "strict".

       username

              Optional. User name for authenticating with the SMTP
              server.  Default: none.

       password

              Optional. Password for authenticating with the SMTP
              server. If not specified, interactive sessions will prompt
              the user for a password; non-interactive sessions will
              fail. Default: none.

       local_hostname

              Optional. It's the hostname that the sender can use to
              identify itself to the MTA.

   subpaths
       Subrepository source URLs can go stale if a remote server changes
       name or becomes temporarily unavailable. This section lets you
       define rewrite rules of the form:

       <pattern> = <replacement>

       where pattern is a regular expression matching a subrepository
       source URL and replacement is the replacement string used to
       rewrite it. Groups can be matched in pattern and referenced in
       replacements. For instance:

       http://server/(.*)-hg/ = http://hg.server/\1/

       rewrites http://server/foo-hg/ into http://hg.server/foo/ .

       Relative subrepository paths are first made absolute, and the
       rewrite rules are then applied on the full (absolute) path. The
       rules are applied in definition order.

   trusted
       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, as various hgrc features allow arbitrary commands to be
       run. This issue is often encountered when configuring hooks or
       extensions for shared repositories or servers. However, the web
       interface will use some safe settings from the [web] section.

       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 *. These settings must be placed in an
       already-trusted file to take effect, such as $HOME/.hgrc of the
       user or service running Mercurial.

       users

              Comma-separated list of trusted users.

       groups

              Comma-separated list of trusted groups.

   ui
       User interface controls.

       archivemeta

              Whether to include the .hg_archival.txt file containing
              meta data (hashes for the repository base and for tip) in
              archives created by the hg archive command or downloaded
              via hgweb.  Default is True.

       askusername

              Whether to prompt for a username when committing. If True,
              and neither $HGUSER nor $EMAIL has been specified, then
              the user will be prompted to enter a username. If no
              username is entered, the default USER@HOST is used
              instead.  Default is False.

       commitsubrepos

              Whether to commit modified subrepositories when committing
              the parent repository. If False and one subrepository has
              uncommitted changes, abort the commit.  Default is False.

       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.

       merge

              The conflict resolution program to use during a manual
              merge.  For more information on merge tools see hg help
              merge-tools.  For configuring merge tools see the
              [merge-tools] section.

       portablefilenames

              Check for portable filenames. Can be warn, ignore or
              abort.  Default is warn.  If set to warn (or true), a
              warning message is printed on POSIX platforms, if a file
              with a non-portable filename is added (e.g. a file with a
              name that can't be created on Windows because it contains
              reserved parts like AUX, reserved characters like :, or
              would cause a case collision with an existing file).  If
              set to ignore (or false), no warning is printed.  If set
              to abort, the command is aborted.  On Windows, this
              configuration option is ignored and the command aborted.

       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.

       reportoldssl

              Warn if an SSL certificate is unable to be due to using
              Python 2.5 or earlier. True or False. Default is True.

       report_untrusted

              Warn if a .hg/hgrc file is ignored due to not being owned
              by a trusted user or group. True or False. Default is
              True.

       slash

              Display paths using a slash (/) as the path separator.
              This only makes a difference on systems where the default
              path separator is not the slash character (e.g. Windows
              uses the backslash character (\)).  Default is False.

       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.

       style

              Name of style to use for command output.

       timeout

              The timeout used when a lock is held (in seconds), a
              negative value means no timeout. Default is 600.

       traceback

              Mercurial always prints a traceback when an unknown
              exception occurs. Setting this to True will make Mercurial
              print a traceback on all exceptions, even those recognized
              by Mercurial (such as IOError or MemoryError). Default is
              False.

       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. If the username in hgrc is empty, it
              has to be specified manually or in a different hgrc file
              (e.g. $HOME/.hgrc, if the admin set username =  in the
              system hgrc). Environment variables in the username are
              expanded.

       verbose

              Increase the amount of output printed. True or False.
              Default is False.

   web
       Web interface configuration. The settings in this section apply
       to both the builtin webserver (started by hg serve) and the
       script you run through a webserver (hgweb.cgi and the derivatives
       for FastCGI and WSGI).

       The Mercurial webserver does no authentication (it does not
       prompt for usernames and passwords to validate who users are),
       but it does do authorization (it grants or denies access for
       authenticated users based on settings in this section). You must
       either configure your webserver to do authentication for you, or
       disable the authorization checks.

       For a quick setup in a trusted environment, e.g., a private LAN,
       where you want it to accept pushes from anybody, you can use the
       following command line:

       $ hg --config web.allow_push=* --config web.push_ssl=False serve

       Note that this will allow anybody to push anything to the server
       and that this should not be used for public servers.

       The full set of options is:

       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
              repository revisions.  Default is False.

       allowgz

              (DEPRECATED) Whether to allow .tar.gz downloading of
              repository 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. The contents of the allow_push list are examined
              after the deny_push list.

       allow_read

              If the user has not already been denied repository access
              due to the contents of deny_read, this list determines
              whether to grant repository access to the user. If this
              list is not empty, and the user is unauthenticated or not
              present in the list, then access is denied for the user.
              If the list is empty or not set, then access is permitted
              to all users by default. Setting allow_read to the special
              value * is equivalent to it not being set (i.e. access is
              permitted to all users). The contents of the allow_read
              list are examined after the deny_read list.

       allowzip

              (DEPRECATED) Whether to allow .zip downloading of
              repository revisions. Default is False. This feature
              creates temporary files.

       archivesubrepos

              Whether to recurse into subrepositories when archiving.
              Default is False.

       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/ .

       cacerts

              Path to file containing a list of PEM encoded certificate
              authority certificates. Environment variables and ~user
              constructs are expanded in the filename. If specified on
              the client, then it will verify the identity of remote
              HTTPS servers with these certificates.

              This feature is only supported when using Python 2.6 or
              later. If you wish to use it with earlier versions of
              Python, install the backported version of the ssl library
              that is available from http://pypi.python.org .

              To disable SSL verification temporarily, specify
              --insecure from command line.

              You can use OpenSSL's CA certificate file if your platform
              has one. On most Linux systems this will be
              /etc/ssl/certs/ca-certificates.crt. Otherwise you will
              have to generate this file manually. The form must be as
              follows:

              -----BEGIN CERTIFICATE-----
              ... (certificate in base64 PEM encoding) ...
              -----END CERTIFICATE-----
              -----BEGIN CERTIFICATE-----
              ... (certificate in base64 PEM encoding) ...
              -----END CERTIFICATE-----

       cache

              Whether to support caching in hgweb. Defaults to True.

       collapse

              With descend enabled, repositories in subdirectories are
              shown at a single level alongside repositories in the
              current path. With collapse also enabled, repositories
              residing at a deeper level than the current path are
              grouped behind navigable directory entries that lead to
              the locations of these repositories. In effect, this
              setting collapses each collection of repositories found
              within a subdirectory into a single entry for that
              subdirectory. Default is False.

       comparisoncontext

              Number of lines of context to show in side-by-side file
              comparison. If negative or the value full, whole files are
              shown. Default is 5.  This setting can be overridden by a
              context request parameter to the comparison command,
              taking the same values.

       contact

              Name or email address of the person in charge of the
              repository.  Defaults to ui.username or $EMAIL or
              "unknown" if unset or empty.

       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 is also denied. The contents of the
              deny_push list are examined before the allow_push list.

       deny_read

              Whether to deny reading/viewing of the repository. If this
              list is not empty, unauthenticated users are all denied,
              and any authenticated user name present in this list is
              also denied access to the repository. If set to the
              special value *, all remote users are denied access
              (rarely needed ;). If deny_read is empty or not set, the
              determination of repository access depends on the presence
              and content of the allow_read list (see description). If
              both deny_read and allow_read are empty or not set, then
              access is permitted to all users by default. If the
              repository is being served via hgwebdir, denied users will
              not be able to see it in the list of repositories. The
              contents of the deny_read list have priority over (are
              examined before) the contents of the allow_read list.

       descend

              hgwebdir indexes will not descend into subdirectories.
              Only repositories directly in the current path will be
              shown (other repositories are still available from the
              index corresponding to their containing path).

       description

              Textual description of the repository's purpose or
              contents.  Default is "unknown".

       encoding

              Character encoding name. Default is the current locale
              charset.  Example: "UTF-8"

       errorlog

              Where to output the error log. Default is stderr.

       guessmime

              Control MIME types for raw download of file content.  Set
              to True to let hgweb guess the content type from the file
              extension. This will serve HTML files as text/html and
              might allow cross-site scripting attacks when serving
              untrusted repositories. Default is False.

       hidden

              Whether to hide the repository in the hgwebdir index.
              Default is False.

       ipv6

              Whether to use IPv6. Default is False.

       logoimg

              File name of the logo image that some templates display on
              each page.  The file name is relative to staticurl. That
              is, the full path to the logo image is
              "staticurl/logoimg".  If unset, hglogo.png will be used.

       logourl

              Base URL to use for logos. If unset,
              http://mercurial.selenic.com/ will be used.

       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.

       maxshortchanges

              Maximum number of changes to list on the shortlog, graph
              or filelog pages. Default is 60.

       name

              Repository name to use in the web interface. Default is
              current working directory.

       port

              Port to listen on. Default is 8000.

       prefix

              Prefix path to serve from. Default is '' (server root).

       push_ssl

              Whether to require that inbound pushes be transported over
              SSL to prevent password sniffing. Default is True.

       staticurl

              Base URL to use for static files. If unset, static files
              (e.g. the hgicon.png favicon) will be served by the CGI
              script itself. Use this setting to serve them directly
              with the HTTP server.  Example: http://hgserver/static/ .

       stripes

              How many lines a "zebra stripe" should span in multi-line
              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.

   websub
       Web substitution filter definition. You can use this section to
       define a set of regular expression substitution patterns which
       let you automatically modify the hgweb server output.

       The default hgweb templates only apply these substitution
       patterns on the revision description fields. You can apply them
       anywhere you want when you create your own templates by adding
       calls to the "websub" filter (usually after calling the "escape"
       filter).

       This can be used, for example, to convert issue references to
       links to your issue tracker, or to convert "markdown-like" syntax
       into HTML (see the examples below).

       Each entry in this section names a substitution filter.  The
       value of each entry defines the substitution expression itself.
       The websub expressions follow the old interhg extension syntax,
       which in turn imitates the Unix sed replacement syntax:

       patternname = s/SEARCH_REGEX/REPLACE_EXPRESSION/[i]

       You can use any separator other than "/". The final "i" is
       optional and indicates that the search must be case insensitive.

       Examples:

       [websub]
       issues = s|issue(\d+)|<a href="http://bts.example.org/issue\1">issue\1</a>|i
       italic = s/\b_(\S+)_\b/<i>\1<\/i>/
       bold = s/\*\b(\S+)\b\*/<b>\1<\/b>/

   worker
       Parallel master/worker configuration. We currently perform
       working directory updates in parallel on Unix-like systems, which
       greatly helps performance.

       numcpus

              Number of CPUs to use for parallel operations. Default is
              4 or the number of CPUs on the system, whichever is
              larger. A zero or negative value is treated as use the
              default.

AUTHOR         top

       Bryan O'Sullivan <bos@serpentine.com>.

       Mercurial was written by Matt Mackall <mpm@selenic.com>.

SEE ALSO         top

       hg(1), hgignore(5)

COPYING         top

       This manual page is copyright 2005 Bryan O'Sullivan.  Mercurial
       is copyright 2005-2012 Matt Mackall.  Free use of this software
       is granted under the terms of the GNU General Public License
       version 2 or any later version.

AUTHOR         top

       Bryan O'Sullivan <bos@serpentine.com>

       Organization: Mercurial

COLOPHON         top

       This page is part of the hg (Mercurial source code management
       system) project.  Information about the project can be found at
       ⟨http://mercurial.selenic.com/⟩.  If you have a bug report for
       this manual page, see
       ⟨http://mercurial.selenic.com/wiki/BugTracker⟩.  This page was
       obtained from the project's upstream Mercurial repository
       ⟨http://selenic.com/hg⟩ on 2021-04-01.  (At that time, the date
       of the most recent commit that was found in the repository was
       2021-03-26.)  If you discover any rendering problems in this HTML
       version of the page, or you believe there is a better or more up-
       to-date source for the page, or you have corrections or
       improvements to the information in this COLOPHON (which is not
       part of the original manual page), send a mail to
       man-pages@man7.org

                                                                 HGRC(5)

Pages that refer to this page: hg(1)hgignore(5)