Mercurial

TeamCity uses the typical Mercurial command line client: hg command. Mercurial 1.5.2+ is supported.

Note that:

Remote Run from IDE is not supported. Please use Branch Remote Run Trigger instead.
Checkout rules for agent-side checkout are not supported except for the .=><target_dir> rule.

For common VCS Root properties, see this section. The section below contains the description of Mercurial-specific fields and options.

TeamCity supports Mercurial out of the box.

General Settings

Option	Description
Pull changes from	The URL of your hosting.
Default branch	Set to the default branch which used in the absence of branch specification or when the branch of the branch specification cannot be found. Note that parameter references are supported here.
Branch specification	In this area list all the branches you want to be monitored for changes. The syntax is similar to checkout rules: `+\|-:branch_name`, where `branch_name` is specific to the VCS (with the optional * placeholder). Note that only one asterisk is allowed and each rule has to start with a new line. Bookmarks can also be used in the branch and branch specification fields. If a bookmark has the same name as a regular branch, a regular branch wins. More in the related TeamCity blogpost. Bookmarks support requires Mercurial 2.4 installed on the TeamCity server.
Use tags as branches	Allows you to use tags in branch specification. By default, tags are ignored.
Detect subrepo changes	By default, subrepositories are not monitored for changes.
Username for tags/merge	A custom username used for labeling
Use uncompressed transfer	Uncompressed transfer is faster for repositories in the LAN.
HG command path	The path to the hg executable. Used on TeamCity server only if included into whitelist. See more below.

Path to hg executable detection

When an agent starts, the hg-plugin detects Mercurial installed on the agent machine.

The plugin tries to run the hg version command using the path specified by teamcity.hg.agent.path parameter. You can change this parameter in < >\conf\buildAgent.properties.

If this parameter is not set, the plugin uses hg as a path to the command, assuming it is somewhere in the $PATH. If the command is executed successfully and mercurial has an appropriate version (1.5.2+), then the hg-plugin reports the path to hg in the teamcity.hg.agent.path parameter.

During the build, the plugin uses the hg specified in the HG command path field of a VCS root settings. To use the detected hg, put %\teamcity.hg.agent.path% in this field. Configurations with such settings will be run only on agents which report the path to hg.

Since TeamCity 2017.2.2, the server side of the plugin checks the value of the teamcity.hg.customServerHgPathWhitelist internal property. The property contains the ;-separated list of allowed hg paths to use on the server. If the path specified in VCS root is in whitelist, then it is used on the server. If not, the path specified in the teamcity.hg.server.path internal property is used. If this property is not set, TeamCity server uses hg from the $PATH.

Agent Settings

These are the settings used in case of the agent-side checkout (default mode since TeamCity 10.0), which requires Mercurial installed on all agents.

Option	Description
Mercurial config	Specify the Mercurial configuration options to be applied to the repository during agent-side checkout, e.g. enter the following to enable the `largefiles` extension: `[extensions]` `largefiles =` The configuration format is described here. Before 2017.2.2 this option was also used on TeamCity server. This was disabled for security reasons.
Purge settings	Defines whether to purge files and directories not being tracked by Mercurial in the current repository. You can choose to remove only unknown files and empty directories, or to remove ignored files as well. Added files and (unmodified or modified) tracked files are preserved.
Use mirrors	When enabled, TeamCity creates a local agent mirror first (under agent's `system/mercurial` directory) and then clones to the working directory from this local mirror. This option speeds up clean checkout, because only the build working directory is cleaned. Also, if a single root is used in several build configurations, a clone will be faster.

Option

Description

Mercurial config

Specify the Mercurial configuration options to be applied to the repository during agent-side checkout, e.g. enter the following to enable the largefiles extension: [extensions] largefiles = The configuration format is described here.

Before 2017.2.2 this option was also used on TeamCity server. This was disabled for security reasons.

Purge settings

Defines whether to purge files and directories not being tracked by Mercurial in the current repository. You can choose to remove only unknown files and empty directories, or to remove ignored files as well. Added files and (unmodified or modified) tracked files are preserved.

Use mirrors

When enabled, TeamCity creates a local agent mirror first (under agent's system/mercurial directory) and then clones to the working directory from this local mirror. This option speeds up clean checkout, because only the build working directory is cleaned. Also, if a single root is used in several build configurations, a clone will be faster.

Internal Properties

This section describes hg-related internal properties. You can modify the defaults to adjust the Mercurial settings as needed.

Server-side internal properties:

Property	Default	Description
teamcity.hg.pull.timeout.seconds	3600	Maximum time in seconds for pull operation to run
teamcity.hg.server.path	hg	Path to the hg executable on the server (see Path to hg executable detection for the details).
teamcity.hg.customServerHgPathWhitelist		;-separated list of allowed paths to hg executable to use on TeamCity server machine

Agent configuration for Mercurial:

Property	Default	Description
teamcity.hg.pull.timeout.seconds	3600	Maximum time in seconds for pull operation to run
teamcity.hg.agent.path	hg	Path to hg executable on the agent (see Path to hg executable detection for the details).

Last modified: 20 April 2023