This is a tutorial on TortoiseHG that I adapted from the one I wrote for Game Creation Society (you can view the original here). I’ll try to outline an average workflow using TortoiseHg, so if you want more detailed explanations, intuitions, or documentation, you should check out the in-depth Mercurial book here: http://hgbook.red-bean.com/read/.¬†You don’t need prior knowledge of Mercurial to follow along, but I do assume that you’re using some kind of server to host your repository. Hopefully you’ll find this useful!


In order to use Mercurial, you’ll need a client to interact with the repositories on our server. If you’re on Windows or Debian (and hopefully Mac in a few months), TortoiseHg is a very easy-to-use option. It has a polished interface, all the tools you’ll need, and great integration with Windows Explorer/Gnome Nautilus. You can download it from here: http://tortoisehg.bitbucket.org/download/index.html.

Once you install it and restart your computer, you can now use TortoiseHg just by right-clicking anywhere in Explorer*! Here’s a quick sample project to demonstrate the basics.

*Apparently if you use the Libraries feature of Windows 7, the TortoiseHg context menu entry won’t appear when you right click on blank space.

Setting up a repository

If you intend to share your code between multiple computers, then the easiest way to set up a repository is to initialize one on a centralized server. This isn’t feasible for everyone, but one free alternative is BitBucket. If you’re only using Mercurial in order to track your own revisions, however, you can just set up the repository locally. For this tutorial, I’ll assume that you’re using a server for your repository, but most of the tutorial remains the same.

If you’re using a central repostiory, ssh into your server and type

hg init REPO_NAME

This will create a Mercurial repository in a folder called REPO_NAME. If you create this in the home folder of some server called www.server.com, then the address of your repository might be something like ssh://username@server.com/REPO_NAME.

Once you have a working repository on the server, let’s move on to the TortoiseHg part. The first thing you’ll want to do is clone the repository to your computer. Here are some pretty pictures to demonstrate:

Right click somewhere in Explorer and select the “Clone” option.

Depending on where you put your repository, you may be able to access it from a public http address. This is a fast way to read from the repository, but you usually won’t be able to send anything to it through this address. In GCS, for example, the standard read-only URL for our project repositories is: http://hg.gamecreation.org/PROJECT_NAME. The ssh address, which allows you to establish a secure connection to send data through, is ssh://PROJECT_NAME@gamecreation.org/hg

Once TortoiseHg finishes cloning the repository, you should see it in Explorer, with the green checkmark showing that it’s up to date.

Before we can do anything with the repository, we should make sure we set some settings. First, go to “Explorer Extension Settings”.

Scroll through the Sub menu items to select “Synchronize”, then press “<- Top” to add it to the context menu. This will be one of your most frequently used commands, so this will save you some time!

Then, go to “Repository Settings”, and click on the “Commit” tab.

Enter a meaningful username, then click on the “Synchronize” tab, and select “update” in the pulldown menu next to “After Pull Operation”.

In Mercurial, when you pull changes from the server’s repository, the changes don’t immediately go into effect in your local working directory. For the sake of convenience, selecting “update” will make sure your working copy is always up to date.

While you’re still in the “Synchronize” tab, if there is a default repository path, select it and click Edit; if not, click Add. Because you will not be able to push changes through the http read-only path, changing this to the ssh path will make sure you always have a secure connection that you push changes to. The format for this path is ssh://PROJECT_NAME@gamecreation.org/hg.

Now that you’ve edited all of the essential options, you can start to work in your repository! Let’s created a todo list, called TODO.txt, and add some text to it. Mercurial doesn’t know about TODO.txt yet, so add and commit it to the repository. Right click somewhere and click Hg Commit.

In the lower left panel, the file you just created has a question mark under the status column; this means Mercurial doens’t know about the file yet. By checking the box, it will add TODO.txt to the repository, and start tracking any changes you make to it. Once you add a commit message and check any files you want to add to the repository, click Commit to check in all of your changes to your local repository.

After you commit changes to your local repository, you need to give your changes to the server. If you right click and go to Hg Synchronize, you’ll get options for sending and receiving changes across multiple repositories.
Since you want to send your changes, click Push, and if the ssh URL is in the address bar, it will prompt you for your password, and send the changes.

Now, let’s edit the file, to make things interesting. Once you’ve changed a file that Mercurial knows about without committing the change, it will show a red exclamation mark.

I just added a task to the todo list, and now I’d like to commit that change to the repository. Click on “Hg Commit” again.

The lower right panel contains the “diff” for the file selected in the left panel that you’re committing to the repository – it indicates that you added an important entry to the todo list. Now that you’ve added a commit message, press Commit to confirm the changes in my repository. Now, to push the changes to the server. Go back to “Hg Synchronize” and press “Push” again.

Oh no, exclamation marks and red text! This message, “push creates new remote heads”, means that you can’t directly apply your changes to the server’s repository. This happened because someone else must have modified TODO.txt after the last time you pulled changes from the server, but before you decided to push my changes. In order to fix this, do not “force” anything. All you need to do is pull the changes that are on the server, and merge them with your changes. So, as a rule of thumb: always pull changes from the server before you try to push your changes, because otherwise Mercurial will yell at you.

Now, you’re pulling the changes from the server that some other jerk made while you were editing TODO.txt. Wait, what the hell is “+1 heads“? This means that because someone else’s changes happened at the same as mine, the repository branched. There are now two states: one with your changes, and one with someone else’s. Let’s get a better picture of what’s going on so we can merge them together. Right click somewhere in Explorer, and select “Repository Explorer”.

If you can see the funky looking tree to the left, that’s the current state of our repository. If you select the uppermost change in the repository, you can see who did it and what the change is. In order to merge the other change with the changes in the local repostory, right click the other changes and select “Merge with…”.

This will let you merge the two changes, and go on your merry way. Before you click “Merge”, take a look at “Merge tools:” all the way on the right, and see what tools are available to you. TortoiseHg will let you select different merging programs to get the job done, and in our case we’ll just stick with the default that comes with TortoiseHg: TortoiseMerge. If you’re on Linux or Mac, you may want to look up “kdiff3” as an alternative.

This is the TortoiseMerge interface, which will show you the two versions of the files, and what you’d like the resulting merged file to be at the bottom. Apparently, SOMEONE thinks we’re partying too hard. So, we’ll fix that.

If you right click on the right side, you can select blocks of text that you’d like to use in order to resolve the conflict. We also might want to use some of their changes in our merge, so we can actually directly edit the resulting merged file in the bottom.

Now that the file in the bottom is satisfactorally merged, click save, then close TortoiseMerge.

TortoiseHg will happily declare that the files were merged successfully. Hooray! This might not be so easy if you still have more files to merge, or if TortoiseHg wants to confirm that you want to discard the other changes. Either way, once you’re done merging, go ahead and click “Commit”. Now that you’ve merged your changes with the other ones in your repository, you’ll want to actually share them with the world!

Leave a comment for the commit, and review the diffs to make sure you’ve merged the files correctly. Looks good, so click “Commit (-1 head)”. Phew, we finally chopped off that stray head on our repository.

And for awesomely unknown reasons, TortoiseHg gave our merged repository a gold star for excellence! As you can see, our repository is now fully merged, and ready to push to the server, so go back to Hg Synchronize.

Now, push the merged changes to the server, so it knows you were able to come up with a compromise.
And that’s it for the demonstration! Resolving changes is basically as hard as Mercurial gets, and you should be very happy you don’t have to do this in SVN or CVS. If you’re ever unsure of error messages that Mercurial gives you, or want to do something other than clone, commit, push, pull, or update, you should definitely read the in-depth Mercurial book here: ;http://hgbook.red-bean.com/read/.

Hopefully you were able to learn the basics of Mercurial and TortoiseHg by reading along that demonstration! If you want one written by someone who is actually awesome (but uses the Mercurial command line interface, instead of TortoiseHg), go back and read http://hginit.com. Between the two tutorials, you should have a pretty good sense of the basics of Mercurial.

If you have any further questions about Mercurial basics, feel free to comment!