DVCS software: Mercurial

Sam Hart

2009-09-03 00:17:12

The first thing we needed for our distributed team-based development was a source code version management tool. As we mentioned previously, classic VCSes had a number of limitations we wanted to avoid, so we went with a Distributed Version Control System.

There are a large number of DVCSes available, however, we had a few specific requirements that had to be met.

Git is a popular DVCS that is quite powerful, however we found it to be difficult (and often irritating) to use. Additionally, the Windows support previously required installation of CYGWIN, which we found caused problems in the XNA environment*.

Bazaar is another popular DVCS, however it is one which traditionally has had some serious performance problems (thus, we've had some bad experiences with it :-) Additionally, Bazaar has some wonky ways of setting up central repositories that tend to require a lot more micromanagement than we wanted (we wanted to spend our time coding our game, not approving other people's bundles or dealing with giving testers temporary and limited shell access to the server hosting our repositories).


At the end of the day, we picked Mercurial (or "Hg"). We already knew it was fast, powerful, and easy to use from our previous Linux development, but we soon discovered that the TortoiseHG Windows-specific tool helped it integrate nicely into Windows.

In the above picture, you can see that TortoiseHg provides an extension to Windows Explorer, which gives you Hg GUI access from within your file explorer. This also makes Hg accessible from within Visual Studio, which utilizes the explorer, as you can see in the next screenshot.

And best of all, installing Mercurial/TortoiseHG is complete and total cake. Simply head on over to TortoiseHG's website and download the installer. This installer provides TortoiseHG, Mercurial's command-line utility, and everything you need to get going.

In order to learn Mercurial, there are plenty of web-based tutorials and help pages online. A couple of good places to start are Mercurial's Tutorial section and TortoiseHG's gentle introduction to using TortoiseHG on Windows.

Using Hg with a Visual Studio XNA project

One "gotcha" with using Hg to host a repository that contains a Visual Studio XNA project is trying to determine what files to add to the repository and what files to have Hg ignore. Visual Studio tends to fill your project tree with all manner of temporary build, debug, and binary files that you simply don't need to share among your team. Luckily, we can tell Hg to ignore these files so they don't accidentally get added to our repository (and then updated every time you run your game in debug mode, filling your repository changelog with useless changesets).

Inside the root (or top parent) directory of your XNA project's repository you can place a file called ".hgignore" which can be populated with a list of files, directories, or file globs that Hg should ignore. This file is one of the major reasons we recommend installing a command-line text editor like Nano as you probably wont be able to create a file called ".hgignore" in something like Notepad without an extension being added to the file (e.g., "hgignore.txt").

As for what to put in the file, there is a manual page online which will help with the format, but you will have to know what files or globs will be Visual Studio cruft.

What we have used looks something like this:

# use glob syntax.
syntax: glob


Where "SupaGame" is the name of the project. Feel free to copy this, change the project name to your project, and use it. If your project is not in a sub-directory (e.g., the project just starts in the top-level directory of the repository), then your .hgignore file may look more like this:

# use glob syntax.
syntax: glob


One bit of warning however, we are not 100% certain this completely covers everything that we should have Hg ignore. This is what we've used for Duologue and our other work, however it may be overly aggressive or may be missing files that should be included in it. Also, with new versions of XNA and Visual Studio, this list may change.

[*] : Admittedly, when we tried this the only option available was CYGWIN and XNA was only at version 2.0. Apparently, Git now has a non-CYGWIN version. Also, XNA is up to version 3.1 at the time of this writing. So, who knows? Maybe now the conflict is gone.