alex the african

I’m switching source code control systems from Subversion to Mercurial. I had no idea Mercurial existed until I read this post by Joel Spolsky. He didn’t do a very good job of saying exactly what Mercurial does, but he said enough for me to go googling. I had already worked with a distributed version control system in the shape and form of git. Coming from a Windows background, I found git to be extremely unfriendly. There are a number of visual interfaces to git eg. git gui, but I realized that the most flexible way to use git was from the command line. I don’t like command lines. It wasn’t long before I went on the prowl for a more palatable source code management tool. I got hooked onto Subversion due to the incredibly handy Windows Explorer integration courtesy of TortoiseSVN. I could do my source control activities right where the files were displaying and to date I haven’t had to open the command line once.

Enter Mercurial. I like the whole idea behind distributed version control. The biggest selling point, however, is the fact that merging project branches doesn’t cause premature graying of your hair. I have avoided branching Subversion projects, but at the cost of having to run experiments on the main (only) source code branch. Now with all this talk of branching and merging, it’s kind of funny that the first hurdle you encounter has to do with getting started. It seems to have been assumed by many that you’ll already have a repository by the time you install Mercurial. But then how was that first repository created?

Easy.

Step 1: Initialize the repository

Create Repository

Install TortoiseHg for Windows Explorer integration. It’s best to get the repository going when you already have a folder with files in it. This is the project that you want to keep track of. I shall use my project folder C:\projects\GameOfLife for illustration.

Right-click the folder and select TortoiseHg > Create Repository Here

This opens the TortoiseHg Init dialog where you click Create.

A notification comes up confirming that the repository has been created so click OK, then click Close (on the Init dialog). The folder C:\projects\GameOfLife now has a green checkmark on it indicating that it is under source control. Opening it reveals two new objects: a file .hgignore and a folder .hg.

Init Repository

Step 2:  Setting up the Ignore Filter

It’s common for software project folders to contain files that do not need to be tracked. These files include intermediate compiler output, debugger symbol files etc. You can tell Mercurial to ignore these files so they do not get picked as files requiring some attention. To do this, right-click on the project folder and select TortoiseHg > Edit Ignore Filter

Ignore Filter

The Ignore Filter dialog opens up showing a list of all the files in the project folder (including sub-folders). Click on a file that you do not wish to track and it shows up in the Glob text field.

Click on the Add button to the right of the text field in order to have that file added to the Filters list.

If you want to ignore all the files in a particular subfolder, click on one of the subfolder’s files (eg. GameOfLife/obj/Debug/GameOfLife.pdb) and then replace the file name with *.* (eg. GameOfLife/obj/Debug/*.*)

Click Add to include the new filter in the Filters list

Continue the process of adding filters to your heart’s content then close the Ignore Filter dialog.

Filter List

Step 3: Adding the project files to the repository

Mercurial cannot start keeping track of files until you tell it to, so right-click on the project folder and select TortoiseHg > Add Files.

This brings up the hg add dialog with all the project files checked. Now since you had earlier indicated the files you want to ignore, the file list should just contain the files you want tracked.

Click on Add to get them queued for the commit.

Add Files to Hg

Step 4: Commit changes

Right-click on the project folder and select Hg Commit. Mercurial now has the file states initialized and all changes from this point on can be tracked.