Mercurial: how-to guide to distributed version control

Mercurial is one of the 2 famous free / open source, distributed source control management tools. You may also have heard of Git, another great tool. Both Mercurial & Git are the front runners in distributed version control systems. 2 nice articles compare Mercurial to Git. One called Git vs. Mercurial: Please Relax comparing Git to MacGyver and Mercurial to James Bond. The other article The Differences Between Mercurial and Git. The conclusion was both are great tools so stop worrying and start using the one which you are most comfortable with. I went down the Mercurial route.

Mercurial - Work easier, Work faster

Mercurial is a distributed version control systems (DVCS) which keeps track of software revisions and allows many developers to work on a given project without necessarily being connected to a common network. This is a peer-to-peer approach, as opposed to the client-server approach of centralized systems like Subversion or CVS. It is a more cleaner, faster and refined way of working. More on this is explained on Wiki here.

Let’s get started with Mercurial

As explained above you Mercurial is a DVCS. So you will have a “local” version of Mercurial which may have a number of “repositories” on your development machine. A repository is essentially a package which identifies your application. One for each application. Your code will get “committed” to this local version daily as you work. When you have a working piece of functionality only then you will “push” it to “central”. Central is typically hosted on a remote server (hosted in-house or via a 3rd party like BitBucket) where everyone else in your team can push or clone code to. Typically “central” is hooked up to a continuous integration tool to facilitate nightly builds. More on that in another post. So whatever code you push there make sure it is working!

Local (dev) install or Mercurial

1. Download Mercurial on your development box from here:

2. Run the install file and follow through with the default questions.

3. Your done.

Quickstart – starting your 1st Mercurial Repository


In your terminal / dos window, navigate to a folder where you will either clone a project to or create one and do the following.

Clone a project and push changes

$ hg clone
$ cd hello
$ (edit files)
$ hg add (new files)
$ hg commit -m 'My changes'
$ hg push

Create a project and commit

$ hg init (project-directory)
$ cd (project-directory)
$ (add some files)
$ hg add
$ hg commit -m 'Initial commit'

Let’s look at each command in more detail:

hg init

Run this 1st time in your working directory to mark that folder as your project repository which you want Mercurial to version control. Mercurial will create a hidden folder there called “.hg”. This is where all the detail (changesets and manifests) on your commits is stored.

hg clone http://(my-domain)/hg/(project-repository)

Run this in your working directory where you want to drag code down from central Mercurial (See below on Central).

hg status

To see what is not yet added & committed yet to the repository.

hg add

If you have new files this command adds them to your repository.

hg commit

Commit your changes to “local” Mercurial. Make this a habit of doing it frequently (at least once a day). Mercurial will ask you to put in comments with your commit. Also make this a habit to put in as much detail into your comments as possible to help others understand your changes + if you have a reference to Jira case / other Agile tracker add this in as well.

hg pull -u

To pull changes and update.

hg push http://(my-domain)/hg/(project-repository)

To push your local repository changes to a central repository.

Tools for Mercurial

Netbeans – IDE Integration

If you are using Netbeans for development and have pointed it to a project where you “hg init” was ran, Netbeans will automatically recognize this and integrate Mercurial into your workflow. In Netbeans, do this by right clicking on your project folder and look under “Mercurial” sub-folder. Get it from here:

MacHG – GUI for managing repositories on the Mac

This is the nicest GUI for Mercurial that I could find for the Mac. It allows you in a nice graphical way to manage a collection of files, to add things to the collection, to save a snapshot of the collection, to restore the collection to an earlier state and in general to work with the files. Get it from here:
Alternatively go through a list of other tools here:

“Central” – home of all repositories

The following is only required if you want to setup Mercurial “central”. A single place (mothership) for all developers to push working code to for storage & versioning. This is also the place where you would hook up a continuous integration tool to facilitate nightly builds.

Bitbucket: free Mercurial code hosting

If you do not have enough resources to run Mercurial “central” in-house or want someone else to manage that for you then use one of the hosted solutions on the internet. Bitbucket from Atlassian (kick ass Aussie firm) can provide you with unlimited private code hosting, free. Yes I use it and I love it. Less maintenance & headaches and everything you learnt above can be applied here.

BitBucket by Atlassian - free Mercurial code hosting

Get your free account here:

Home solution: In-house Mercurial code hosting

Ok the following will require Ubuntu terminal access to the Ubuntu box where you want to install Mercurial “central”. All of the code below can be highlighted and pasted to run directly in your terminal window to make this process fast.

The following is based on the steps I followed from Emran Hasan’s Blog with some changes to the configuration to make it work on Ubuntu 10.10 based additional input from Stack Overflow.

1. Install Mercurial

sudo apt-get update
sudo apt-get install mercurial

2. Create a store for Mercurial configuration & repository files

cd /var/
sudo mkdir hg
sudo mkdir hg/repos
sudo chown -R www-data:www-data hg/repos

3. Creating a configuration file to host multiple repositories on this server & use CGI to serve the files through Apache:

cd /var/hg
sudo cp /usr/share/doc/mercurial/examples/hgweb.cgi .
sudo chmod a+x hgweb.cgi

4. Configure Mercurial (also refered to as “hg”) to point to point to our new config file:

sudo nano /var/hg/hgweb.cgi

and update the config like this:

config = "/var/hg/hgweb.config"

5. Create the file /var/hg/hgweb.config and write the location of the repositories:

sudo nano hgweb.config

and add this to the file:

/var/hg/repos = /var/hg/repos

6. Make “central” accessible via HTTP (optional if you don’t want to setup a SSL certificate).

sudo nano /etc/mercurial/hgrc

add/update this line and save file:

allow_push = * push_ssl = false

7. Now update the Apache configuration so that it executes the CGI when requested with a /hg prefix:

cd /etc/apache2/sites-available
sudo nano default

at the end of the file (before < /VirtualHost >), add the following and save it:

ScriptAlias /hg "/var/hg/hgweb.cgi"
< Directory "/var/hg/repos" >
   AuthType Basic
   AuthName "Mercurial Repositories"
   AuthUserFile /var/hg/hgusers
   Require valid-user
< /Directory >

8. Add permissions for users who will be accessing central. First add admin account:

sudo cd /var/hg htpasswd -mc hgusers admin

then normal user accounts:

sudo htpasswd -m hgusers

Each request will prompt you for a password.

9. Create a repository

cd /var/hg/repos
sudo mkdir (my-repository)
cd (my-repository)
sudo hg init

Note: Recall “hg init” from above (local setup).

10. Restart apache

sudo /etc/init.d/apache2 restart

and browse: http://(my-domain)/hg
you will be prompted to login (using one of the users names you added above) and see the whole Mercurial central repository.

URL access: http://(my-domain)/hg/(project-repository)
Cloning from “central” to your local:

cd (my-local-project-working-directory)
hg clone http://(my-domain)/hg/(project-repository)

And… that concludes this short introduction to Mercurial. Hope you found it useful!

Bonus: Download this Mercurial Cheat Sheet: (847kb)

Mercurial Usage - 1 pager

I have it at my desk. It is the best one I could find out of the many I reviewed.

Happy coding!

Useful links

Hosted Mercurial solutions

More Mercurial education

Bitbucket education


~ Ernest

Author: Ernest W. Semerda

Aussie in Silicon Valley. Veryfi CoFounder (#YC W17 cohort). GSDfaster Founder. View all posts by Ernest W. Semerda

6 thoughts on “Mercurial: how-to guide to distributed version control”

  1. Nice writeup!  Some tools that I am using that integrate with Mercurial are PhpStorm (for those who develop in PHP it works a lot better than NetBeans) and SourceTree on the Mac.

    1. Thanks Mike for your input. PhpStorm is a great product. I used the limited trial version of it and liked every aspect of it. I just wish it would be more affordable like other Mac software. SourceTree looks interesting in that it does more then just Mercurial repos.. however MacHg’s upper hand is that its free open source while SourceTree is not.

      1. @semerda:disqus 
        While I really value open-source, open-source just doesn’t seem to create best-of-breed in some types of software and I’d rather pay to have best-of-breed if the option is to do without.  So I’ll have to support PhpStorm on their prices because PhpStorm is a great IDE for PHP and there is not a good open-source IDE in my opinion. (Some people like Eclipse, but it wouldn’t exist without major investment from IBM and it’s too much of a pig for me to use anyway. Others like NetBeans, but Sun props it up and I think people like it because they’ve not tried PhpStorm! ;-)Since there is not another software besides OS X itself, Safari and Mac Mail that I spend more time using than PhpStorm, I consider US$99 not really a big deal for a personal license (vs. $199 for a corporate license.)  Hell, I paid 25 times that for my Mac computer, what’s 4% more for critical software? Also, they offer free open source licenses and free classroom licenses.  Why should Apple get all the money and bemoan good software companies making a fraction of the profit that Apple does?Frankly if anything I’d rather see PhpStorm raise their prices IF it would mean the software could get even better, because I depend on it so much for my livelihood.
        The only caveat is I really feel for those people in 3rd world countries for whom US$99 is more like a week’s salary instead of an hour’s worth of billable work (OTOH, I would suggest maybe those people for whom US$99 is a week’s salary need to do development work over the web for others, and they will raise that weekly salary by many times!)Anyway, enough of my soap-box.  Again, thanks for the great post and have an awesome day!


Leave a Reply

Your email address will not be published. Required fields are marked *