Using Mercurial in Automation

Are you looking to consume Mercurial as part of an automated system? This article attempts to answer common questions and to suggest best practices.

Best Practices

Read the Scripting Help Topic

hg help scripting (introduced in Mercurial 3.5) gives a Mercurial generic overview of how machines should consume Mercurial.

Get Design and Code Review from Someone Who Knows Mercurial

Before you write any code or deploy anything, it might be a good idea to get design review or code review from someone who knows Mercurial.

Pop in #vcs on or send an email to

Consider Using the Command Server

Mercurial has a command server mode where a persistent hg process is created and individual commands are dispatched to the server one at a time.

There exists client libraries for communicating with this command server python-hglib is the Python client and it can be installed via pip install python-hglib.

Use of the command server is preferred over direct hg process invocation because:

  1. It is faster.
  2. A written client API will handle dispatching and parsing responses automatically, freeing you up to write meaningful code.

Python + hg process startup overhead is non-trivial (~50 ms). If you are performing many Mercurial commands, use of the command server could have a profound impact on performance.

Use Templates

Most Mercurial commands accept a --template/-T argument to control how output is formatted. You should use this capability when calling commands to ensure output is exactly how you intend. This can often result in making the output easier for machines to parse.


Use -T json to produce JSON output from commands.

Add –traceback to All Commands

In the rare case Mercurial crashes, it is valuable to have crash information to help with debugging. Adding --traceback to all commands will have Mercurial print a stack trace when it crashes.

As an alternative to adding --traceback to every command, add the following to your hgrc:

traceback = on

Always Check Exit Codes

Always check that the exit code from hg commands is what is expected (probably 0).

Specify an Explicit hgrc

Mercurial will automatically inherit the system-wide and per-user hgrc files. This can have unintended consequences, such as the enabling of an extension or defining of specific user credentials.

When invoking the hg command, set the HGRCPATH environment variable to that of a known good config file.


To disallow loading of an external hgrc file, set HGRCPATH to the value /dev/null.


If executing from within a Mercurial repository, the hg process will automatically load the .hg/hgrc file. This is not always intended, especially if you are running commands that don’t interact with a specific repository.

To prevent this, execute your hg process from outside any Mercurial repository. e.g. /.

You can always pass -R /path/to/repo to have Mercurial operate on a specific repository - you don’t need to have cwd be from within the repository.

Other Tips


When debugging Mercurial commands, consider adding --verbose or --debug to the command invocation to get Mercurial to print more information about what it is doing. This output can be especially when reporting bugs.

Like --traceback, these options can be enabled via hgrc files:

debug = True
verbose = True