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 old tools like conda or pip is possible but really not a good idea for Mercurial.

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 or Pipx installed. If these tools do not work correctly, see Install and setup useful applications with pipx.

• 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 dehesselle-meld with:

  brew install --cask dehesselle-meld
  

  Debian-Ubuntu-Mint

  sudo apt install meld
  

• Install Mercurial and its extensions

  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 --with 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

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

  hg debuginstall
  

  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.

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

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