To start this off you need to install Mercurial

sudo [yum or apt-get] install mercurial

The next step is initializing the repository in your home directory and protect others from being able to read files.

$ cd ~
$ hg init
$ chmod 700 .hg/

In my previous post a commenter pointed out something I was not aware of. When using git if you were to run ‘git clean’ all files not under version control would get deleted. You should be doing regular backups anyway, but that is certainly something we do not want to be able to do on accident. The hg equivalent is ‘hg purge’, but purge is a bundled extension that must be enabled, and because it might be enabled we want to explicitly disable that plugin from being able to work in our repository. To do so you put the following line in ~/.hg/hgrc, because that file will take precedence over conf files in etc and your ~/.hgrc file.

[extensions]
hgext.purge = !

You can store anything you would like to in this repository, but there is most likely going to be some files, and very large files at that, that you do not want to store. To fix that we are going to start off by ignoring everything in your home directory and selectively removing files from the list that we want to store. The following commands are going to list all non-hidden files, but listing directories first, the second command lists everything except for ‘.’ and ‘..’ directory references and greps for all hidden files and lists them directories first. One thing to note is that the –group-directories-first option is not available on CentOS and the only distro I can confirm it exists in is Ubuntu.

$ ls -1 --group-directories-first > .hgignore
$ ls -1 --group-directories-first -A | grep '^\.' >> .hgignore
$ cat .hgignore
Applications
bin
Desktop
...
.cache
.checkbox
.compiz
...
.bash_aliases
.bash_history
.bash_logout
...
.xsession-errors

Go through the list and either comment out (prepend with #) or remove from .hgignore any file/directory names that you DO want to store in version control, any file listed in .hgignore will be ignored by mercurial, unless you ‘hg add’ the file or directory.

If you want to see what files will be picked up by an ‘hg add’ you can run ‘hg status’

$ hg status
? .bash_history
? .bash_logout
? .bash_profile
? .bashrc
? .hgignore
? .hgrc
? .mysql_history
? .screenrc
? bin/mysqltuner.pl

If that is satisfactory you can now run ‘hg add’ to add the files listed here.

$ hg add
adding .bash_history
adding .bash_logout
adding .bash_profile
adding .bashrc
adding .hgignore
adding .hgrc
adding .mysql_history
adding .screenrc
adding bin/mysqltuner.pl

And you can verify it by again running ‘hg status’

$ hg status
A .bash_history
A .bash_logout
A .bash_profile
A .bashrc
A .hgignore
A .hgrc
A .mysql_history
A .screenrc
A bin/mysqltuner.pl

So go ahead now and run ‘hg commit’ and we can deal with individual files under ignored directories afterwards. Running ‘hg commit’ should be default use vi as your editor so after writing your description his Esc, then type :wq and it will commit.

Initial commit of home directory files.

Contains mostly bash dot files, but also a script in my bin directory

HG: Enter commit message.  Lines beginning with 'HG:' are removed.
HG: Leave message empty to abort commit.
HG: --
HG: user: Peter Manis <manis@pyverted.com>
HG: branch 'default'
HG: added .bash_history
HG: added .bash_logout
HG: added .bash_profile
HG: added .bashrc
HG: added .hgignore
HG: added .hgrc
HG: added .mysql_history
HG: added .screenrc
HG: added bin/mysqltuner.pl

So there were a couple directories I had in my .hgignore file that I would like to store certain files in version control. The first is .ssh and the second is .irssi. So to do this we run ‘hg add’ and then ‘hg commit’

$ hg add .ssh/config
$ hg add .irssi/config
$ hg status
A .irssi/config
A .ssh/config
$ hg commit
Adding files that are under ignored directories

HG: Enter commit message.  Lines beginning with 'HG:' are removed.
HG: Leave message empty to abort commit.
HG: --
HG: user: Peter Manis <manis@pyverted.com>
HG: branch 'default'
HG: added .irssi/config
HG: added .ssh/config

Let us now take a look at the local commits that we have.

$ hg log
changeset:   1:5ca5d6d283fe
tag:         tip
user:        Peter Manis <manis@pyverted.com>
date:        Thu Aug 13 19:48:16 2009 -0400
summary:     Adding files that are under ignored directories

changeset:   0:d0e3d9042208
user:        Peter Manis <manis@pyverted.com>
date:        Thu Aug 13 19:43:06 2009 -0400
summary:     Initial commit of home directory files.

We now need to prepare to push these local commits to our bitbucket private repository. To do this we need to setup ssh keys

$ ssh-keygen -t rsa -b 2048
Generating public/private rsa key pair.
Enter file in which to save the key (/home/mercurialguide/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/mercurialguide/.ssh/id_rsa.
Your public key has been saved in /home/mercurialguide/.ssh/id_rsa.pub.
The key fingerprint is:
c5:fc:5b:3e:06:2c:3f:f9:17:51:bf:78:f8:60:ac:cb mercurialguide@hostname

Now sign up for a bitbucket account, create your first private repository, I called mine homedir. After you do that you need to go into your “Account” page and add your ssh public key to the list of ssh keys.

$ cat .ssh/id_rsa.pub
ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAwRewbcXoot9nUUZzonryDYKBhxapI69JRW5TNsxfJQEAw4l7VoA681sgHVA2B8T876Tn9uZrzMBgcEz4GMGVsrU31wVNa9p/HtBJCyp1zWKoitoR1wu2FdNRSgsjFOdlMJ6BIxchmG58/hwA88FZXdYgcKMe2WWQP7pDInhHIJhLKPoctXURr6kSM7TWLh4eO81amSE2GB77mCRIoqxI6Y0uQGqO6JDhFUQAPuErCJcfXSkO+Lv9XIyCwhclki2oZUMwvDyYYrHVHWCNZ/azY1C4Ea722CFSWQjAUI9ljA8yaYmLaI4tbgWu9bNQdNy7v9x9EMtq8Q828BF9LGb+tw== mercurialguide@hostname

You will also need to edit your .ssh/config file for bitbucket.

Host bitbucket.org
  User hg
  Compression yes

Now we can push changes to bitbucket

$ hg push ssh://bitbucket.org/manis/homedir/
pushing to ssh://bitbucket.org/manis/homedir/
searching for changes
remote: adding changesets
remote: adding manifests
remote: adding file changes
remote: added 2 changesets with 12 changes to 12 files
remote: bb/acl: manis is allowed. accepted payload.
remote: quota: 103.6 MB in use, 500.0 MB available (20.72% used)

And you’re done! You just setup a remote repository with your home directory files. Now that you have that setup remember that until you ‘hg push’ your changes they are only local.

I never liked the status output of Git, the Mercurial output was much closer to Subversion, which is what I was used to. A quick side note, I have read that most feel Mercurial is an easier move for Subversion users. With my first real Mercurial involvement needing a lot of adds and removes it was nice to have an ‘addremove’ command that quickly took care of this for me. With Git you had to run add on the files, which was not fun if you added a large number of new files. Before anything is said about adding files I will say that yes, if you are adding a lot of new files it is probably from adding a directory, which is more easily added, but I found a number of instances where I had to add a lot of files where it wasn’t that easy and writing out a one liner to do it just isn’t enjoyable.

The ability to serve a web interface straight from the command line was a feature I found very interesting, again being able to setup a complete environment it wasn’t something I really needed, but it was certainly a nice feature to have. Setting up a Mercurial/Apache environment is also much easier than doing it with Git. I love Trac, I use it for everything I can, but it was very difficult to use with Git for a couple reasons. The first was that the versions of software needed for the Trac plugin didn’t mesh well with the CentOS 5 environment it would be hosted on. The 2nd, which is one of my biggest gripes about Git is the revision id Git uses. Git uses full hashes like “b3ef65139dea83be5965a972159aa628847b763c” while Mercurial will use a number and a short hash like “0:3f7766464126″ and revisions can be referenced by either. Here is a visual comparison of the two.

• Git: OhLoh Labs
• Mercurial: Pylons

I’m sure you can see what a difference that makes, the Mercurial revision id is 1/3 the length of the Git.

Mercurial itself is written in Python, and it is pointed out in some of the pages I link to later that this allows the developers to concentrate on adding features and paying more attention to creating the best version control system instead of having to deal with all the issues that can be involved in maintaining more low level code like C/C++. When you don’t have to spend time on garbage collection and finding memory leaks you have more time to add in features like Mercurial’s archiving option. I can simple link to http://webaddress.com/repository/archive/tip.{zip,tar.gz,tar.bz2} and it will create an archive version of the tip, or what is also known as the last revision, but you can also link to tags and create archives based on that. It also allows me to very easily add autogenerated links to my Trac project index as well, seen below.

I think that Mercurial being written in Python influences my decision more than I may realize. I like to have the power to add and change things and considering that I write Python more than I do anything else these days that fits in very nicely. It means that if I want a feature I can write it, I don’t need to know C or C++ and with the design of Python the features can be more easily added and shared with others. An example of a quick and easy extension is the InfoExtension, which if you are used to Subversion will look very much like ’svn info’.

Back in April, Google added support for Mercurial to their project hosting service, which you can see even has integrated branch graphing. More recently Python creator Guido van Rossum announced they will be moving from Subversion to Mercurial along with a followup from Brett Cannon about the decision. There is also a detailed PEP about the selection of a distributed VCS.

These are just some of the things that I really liked about Mercurial, you can read a little more on the following pages:

• Five Features from Mercurial That Would Make Git Suck Less
• Why Mercurial > Git, or How I Learned To Stop Censoring Myself and Participate in Flamewars.