Installing Mercurial¶

Having a modern Mercurial installed is important. Features, bug fixes, and performance enhancements are always being added to Mercurial. Staying up to date on releases is important to getting the most out of your tools.

Note

Mercurial has a strong commitment to backwards compatibility.

If you are scared that upgrading will break workflows or command behavior, don’t be. It is very rare for Mercurial to intentionally break backwards compatibility.

Recommended Versions¶

Mozilla recommends running the latest stable release of Mercurial. The latest stable release is always listed at https://www.mercurial-scm.org/. As of October 2018, the latest stable release is 4.7.2.

Danger

Mercurial versions before 3.7.3 have known vulnerabilities that can lead to arbitrary code execution when pulling from repositories.

Mercurial versions before 4.4.1 have known vulnerabilities that can result in arbitrary client-side code execution when processing subrepositories.

Mercurial versions before 4.6.1 have possible vulnerabilities that could result in arbitrary client-side code execution when pulling from repositories.

Mercurial versions before 4.7.2 have a possible out-of-bounds memory access that could result in security issues.

Version 4.7.2 or newer should always be used.

Mercurial makes a major X.Y release every three months, typically around the first of the month. Release months are February, May, August, and November. A X.Y.Z point release is performed each month after or as needed (if a severe issue is encountered).

If you are conservative about software updates, it is OK to wait to upgrade until the X.Y.1 point release following a major version bump.

Installing on Windows¶

If you are a Firefox developer, you should install Mercurial indirectly through MozillaBuild. Mercurial can be upgraded within MozillaBuild by running pip install --upgrade Mercurial.

If you are not a Firefox developer, download a Windows installer direct from the Mercurial project.

Installing on OS X¶

Mercurial is not installed on OS X by default. You will need to install it from a package manager or install it from source.

mach bootstrap¶

If you have a clone of a Firefox repository, simply run mach bootstrap to install/upgrade Mercurial. Keep in mind this will install all packages required for Firefox development. If this is not wanted, follow a set of instructions below.

Homebrew¶

Homebrew typically keeps their Mercurial package up to date. Install Mercurial through Homebrew by running:

$ brew install mercurial

You may want to run brew update first to ensure your package database is up to date.

MacPorts¶

MacPorts typically keeps their Mercurial package up to date. Install through MacPorts by running:

$ port install mercurial

From Source¶

See the section below about how to install Mercurial from source.

Installing on Linux, BSD, and other UNIX-style OSs¶

The instructions for installing Mercurial on many popular distributions are available on Mercurial’s web site. However, many distros don’t keep their Mercurial package reasonably current. You often need to perform a source install.

Installing from Pip¶

Mercurial source packages can be installed via pip - Python’s preferred package management tool.

Installing Mercurial via pip is simple:

$ pip install Mercurial

To upgrade Mercurial:

$ pip install --upgrade Mercurial

By default, pip install may try to write to /usr/local or /usr/lib or other parts of your system that require elevated permissions to write to. To perform an install into your user directory:

$ pip install --user Mercurial

That may install Mercurial to a directory not in PATH, such as ~/.local/bin. You may need to adjust your shell’s startup file to add this directory to PATH. To see exactly where it installs things in --user mode, run pip show Mercurial. There will be a line like Location: /home/myuser/.local/lib/python2.7/site-packages. The hg executable is likely in a bin directory at the same level of the lib/ directory.

Installing from Source¶

Installing Mercurial from source is simple and should not be dismissed because it isn’t coming from a package.

Download a source archive from Mercurial. Alternatively, clone the Mercurial source code and check out the version you wish to install:

$ hg clone https://www.mercurial-scm.org/repo/hg
$ cd hg
$ hg up 4.7.2

Once you have the source code, run make to install Mercurial:

$ make install

If you would like to install Mercurial to a custom prefix:

$ make install PREFIX=/usr/local
$ make install PREFIX=/home/gps

Note

Mercurial has some Python C extensions that make performance-critical parts of Mercurial significantly faster. You may need to install a system package such as python-dev to enable you to build Python C extensions.

Tip

Are you concerned about a manual Mercurial install polluting your filesystem? Don’t be.

A Mercurial source install is fully self-contained. If you install to a prefix, you only need a reference to the PREFIX/bin/hg executable to run Mercurial. You can create a symlink to PREFIX/bin/hg anywhere in PATH and Mercurial should just work.

Verifying Your Installation¶

To verify Mercurial is installed properly and has a basic configuration in place, run:

$ hg debuginstall

If it detects problems, correct them.

If you have a clone of the Firefox repository, you are highly encouraged to run mach vcs-setup to launch an interactive wizard that will help you optimally configure Mercurial for use at Mozilla.

Reasons to Upgrade¶

General Advice¶

Mercurial releases tend to be faster and have fewer bugs than previous releases. These are compelling reasons to stay up to date.

Avoid Mercurial versions older than 3.7.3 due to issues below.

Security Issues¶

Versions of Mercurial before 3.7.3 are vulnerable to multiple security issues that can lead to executing arbitrary code when cloning or pulling from repositories. Avoid versions older than 3.7.3!

Cloning and Pulling Performance¶

Mercurial 4.1 introduced supported for compression data over the wire protocol with zstandard. This is substantially faster than zlib and can result in faster clones and pulls due to faster compression and fewer bytes transferred over the wire.

Mercurial 3.6 contains a number of enhancements to performance of cloning and pull operations, especially on Windows. Clone times for mozilla-central on Windows can be several minutes faster with 3.6.

Revset Performance¶

Mercurial 3.5 and 3.6 contained a number of performance improvements to revision sets. If you are a user of hg wip or hg smartlog, these commands will likely be at least 4x faster on Mercurial 3.6.

Revsets are used internally by Mercurial. So these improvements result in performance improvements for a hodgepodge of operations.

Tags Cache Performance¶

Mercurial 3.4 contains improvements to the tags cache that prevent it from frequently doing CPU-intensive computations in some workflows.

Important

Users of evolve will have horrible performance due to the tags cache implementation in versions older than 3.4 and should upgrade to 3.4+.

Performance Issues with Large Repositories¶

Mercurial 3.0 through 3.1.1 contained a significant performance regression that manifests when cloning or pulling tens of thousands of changesets. These versions of Mercurial should be avoided when interacting with large repositories, such as mozilla-central.

Mercurial 3.3 introduced a class of performance regressions most likely encountered as part of running hg blame or hg graft. The regressions are largely fixed in 3.4.

CVE-2014-9390¶

Mercurial versions older than 3.2.3 should be avoided due to a security issue (CVE-2014-9390) impacting Windows and OS X users.

Supporting Old Versions¶

Mozilla has written a handful of Mercurial extensions. Supporting N versions of Mercurial is easier than supporting N+1 versions, especially as Mercurial’s API is rapidly evolving. It is extra work to support old versions when new versions work just fine.

Newer Wire Protocol¶

Mercurial 3.5 featured a new wire protocol that performs pushes and pulls more efficiently.

Cloning from Pre-Generated Bundle Files¶

Mercurial 3.6 supports transparently cloning from pre-generated bundle files. When you clone from hg.mozilla.org, many of the larger repositories will be served from a CDN. This results in a faster and more reliable clone.

Mercurial 4.1 will download zstandard-compressed bundles from hg.mozilla.org by default. These are substantially smaller than gzip-based bundles.