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 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: http://mercurial.selenic.com/

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

3. Your done.

Quickstart – starting your 1st Mercurial Repository

Source: http://mercurial.selenic.com/

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 http://selenic.com/repo/hello
$ 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: http://netbeans.org/

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: http://jasonfharris.com/machg/
Alternatively go through a list of other tools here: http://mercurial.selenic.com/wiki/OtherTools

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

Get your free account here: http://bitbucket.org/

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:

[collections]
/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:

[web]
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:
http://www.theroadtosiliconvalley.com/cdn/Mercurial-Usage-v1.0.pdf (847kb)

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

• BitBucket (free all the way): http://bitbucket.org/
• Kiln (45-day free trial): http://www.fogcreek.com/kiln/

More Mercurial education

• Hg Init: a Mercurial tutorial by Joel Spolsky: http://hginit.com/
• Learning Mercurial in Workflows: http://mercurial.selenic.com/guide/
• hg tip – Learn Mercurial one bite-sized tip at a time: http://hgtip.com/

Bitbucket education

• Getting Started with Bitbucket: http://confluence.atlassian.com/display/BITBUCKET/Getting+Started+with+Bitbucket
• Using your Bitbucket Repository: http://confluence.atlassian.com/display/BITBUCKET/Using+your+Bitbucket+Repository

Enjoy!

~ Ernest