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
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:
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).
To see what is not yet added & committed yet to the repository.
If you have new files this command adds them to your repository.
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:
I have it at my desk. It is the best one I could find out of the many I reviewed.
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/
- 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