Install and setup Mercurial

Modern Mercurial

Mercurial is a versioning tool like Git (same generation and similar theoretical bases). For very simple things, it is quite similar to Git. However, there are also important differences.

Github and Gitlab do not support Mercurial. Git became for open-source THE tool used for versioning all kinds of projects.

However, Mercurial has been used in companies of all sizes for years and grew up as a great tool, with advantages compared to Git, in particular in terms of simple user interface, safety (no force push needed, no destructive history edition), performance for big repositories (with a growing part written in Rust) and collaborative history edition (with this Mercurial extensions evolve and topic).

In this page, we discuss how to install and setup modern Mercurial using the topic, evolve and hg-git extensions. General Mercurial installation instructions are given here https://www.mercurial-scm.org/install, however, unless you really know what you’re doing, I strongly suggest that you just follow the following instructions.

Important

It is really easy with other installation methods to get a broken installation without the topic, evolve and hg-git extensions and you need them to contribute to projects using modern Mercurial and to projects hosted on Github and Gitlab instances.

Installing with tools like conda or pip is possible but really not a good idea for Mercurial. Unless you really know what you do, it’s very easy to obtain a broken installation with apt or similar package management tools.

You can check your installation by running hg help topic, which has to print the help for the topic command.

Since Mercurial is a Python application, recent versions can be installed with tools like UV, Pipx or Pixi. However, for Windows it is still better to just install TortoiseHG as presented below.

Warning

These instructions suppose that you have UV (see https://docs.astral.sh/uv/#installation) or Pipx installed. If these tools do not work correctly, see Install and setup useful applications with pipx.

1. Preliminary: visual diff and merge tools

If you don’t use TortoiseHG, you should really install a visual diff and merge tool, for example Meld.

Windows

Download and execute the installer here: https://meldmerge.org/

macOS

Install meld with:

brew install --cask meld

Debian-Ubuntu-Mint

sudo apt install meld

2. Install Mercurial and its extensions

Note

On Linux and macOS, if you don’t have any preference, you should use UV.

Windows ➜ TortoiseHG

TortoiseHg, Mercurial and few important extensions can be installed with Winget:

winget install TortoiseHg.TortoiseHg -e --accept-package-agreements

Alternatively, one can download an installer and run it to install TortoiseHG.

UV

uv tool install mercurial --with hg-git,hg-evolve

On macOS, it can be useful to also add --with certifi

Pipx

pipx install mercurial
pipx inject mercurial hg-git hg-evolve

Potentially useful to fix ssl issues (macOS)

pipx inject mercurial certifi

Pixi

pixi global install mercurial --with hg-git --with hg-evolve

On macOS, it can be useful to also add --with certifi

3. Check that hg corresponds to the Mercurial installed with UV/Pipx/Pixi

The recent and good Mercurial that you just installed with the previous step can be hidden by another Mercurial. This is a current cause of issue. Let’s check that by running:

hg debuginstall -T "{pythonexe}\n"

Not using the right hg?

The simplest solution is to uninstall the old Mercurial installed with another method.

Alternatively, the directory where UV/Pipx/Pixi puts the executables has to be before other directories where older Mercurial can be present so that hg really corresponds to the Mercurial install with UV/Pipx/Pixi. You can check the environment variable $PATH. See Install and setup useful applications with pipx.

4. Setup Mercurial (config file ~/.hgrc and completion)

You need a file ~/.hgrc containing something like this file. A decent Mercurial configuration file can be created with hg config --edit. Alternatively (recommended for beginners), one can use hg-setup to create the user configuration file and initialize shell completion:

UV

uvx hg-setup init

or (if you get an error)

uv tool install hg-setup
hg-setup init

pipx

pipx run hg-setup init

Complete information, save the config file and quit hg-setup

You should now have a file .hgrc (or mercurial.ini on Windows) in your home directory.

The line starting with hggit is optional and enables the extension hg-git. This extension is useful to work on projects using Git, for example hosted on Github and Gitlab.

The extensions churn, shelve, rebase, absorb, evolve and topic are very useful for more advanced users. Note that evolve and topic comes from the package hg-evolve.

5. Check that everything is fine. Are evolve, topic and hggit extensions indeed enabled?

hg version -v

Important

If evolve, topic and hggit are not mentioned in the output of hg version -v, there is a problem that needs to be fixed.

If everything is fine, you should be able to get some help provided by the extensions. Check it (press on q to quit the help screen)!

hg help evolve
hg help topic
hg help hggit

When everything is fine, you should be able to clone Mercurial repos with something like

hg clone https://foss.heptapod.net/fluiddyn/fluidhowto

You should also be able to clone Git repos with something like:

hg clone https://github.com/paugier/nbabel.git

or, alternatively and better, but you need to setup a SSH key on Github (take time to do this since it is really useful!):

hg clone git@github.com:paugier/nbabel.git

Note

It is fine to use the same SSH key for other applications, for example Gitlab or Heptapod instances. You only share the public key.