Getting started with Mercurial for version control

Mercurial is a distributed version control system written in Python. Because it's written in a high-level language, you can write a Mercurial extension with a few Python functions.

There are several ways to install Mercurial, which are explained in the official documentation. My favorite one is not there: using pip. This is the most amenable way to develop local extensions!

For now, Mercurial only supports Python 2.7, so you will need to create a Python 2.7 virtual environment:

python2 -m virtualenv mercurial-env
./mercurial-env/bin/pip install mercurial

To have a short command, and to satisfy everyone's insatiable need for chemistry-based humor, the command is called hg.

$ source mercurial-env/bin/activate
(mercurial-env)$ mkdir test-dir
(mercurial-env)$ cd test-dir
(mercurial-env)$ hg init
(mercurial-env)$ hg status
(mercurial-env)$

The status is empty since you do not have any files. Add a couple of files:

(mercurial-env)$ echo 1 > one
(mercurial-env)$ echo 2 > two
(mercurial-env)$ hg status
? one
? two
(mercurial-env)$ hg addremove
adding one
adding two
(mercurial-env)$ hg commit -m 'Adding stuff'
(mercurial-env)$ hg log 
changeset:   0:1f1befb5d1e9
tag:         tip
user:        Moshe Zadka <moshez@zadka.club>
date:        Fri Mar 29 12:42:43 2019 -0700
summary:     Adding stuff

The addremove command is useful: it adds any new files that are not ignored to the list of managed files and removes any files that have been removed.

As I mentioned, Mercurial extensions are written in Python—they are just regular Python modules.

This is an example of a short Mercurial extension:

from mercurial import registrar
from mercurial.i18n import _

cmdtable = {}
command = registrar.command(cmdtable)

@command('say-hello',
    [('w', 'whom', '', _('Whom to greet'))])
def say_hello(ui, repo, **opts):
    ui.write("hello ", opts['whom'], "\n")

A simple way to test it is to put it in a file in the virtual environment manually:

$ vi ../mercurial-env/lib/python2.7/site-packages/hello_ext.py

Then you need to enable the extension. You can start by enabling it only in the current repository:

$ cat >> .hg/hgrc
[extensions]
hello_ext =

Now, a greeting is possible:

(mercurial-env)$ hg say-hello --whom world
hello world

Most extensions will do more useful stuff—possibly even things to do with Mercurial. The repo object is a mercurial.hg.repository object.

Refer to the official documentation for more about Mercurial's API. And visit the official repo for more examples and inspiration.