Downloading Mercurial and TortoiseHg

Downloading Mercurial and TortoiseHg

Let's kick things off with a description of how to get set up with the tools that you'll need. Obviously, you'll need Mercurial. Mercurial is a command-line program. Any time you want to interact with Mercurial, such as committing some changes to the repository, you would run a certain specific command.

Perhaps you'll think less of me as a programmer for saying this, but I have a mild aversion to the command line. I use it all the time, for all sorts of things, but I avoid it when I can do things through a GUI.

So instead of working directly with Mercurial on the command line, I use a tool called TortoiseHg.

Side Note: Perhaps you're wondering what the Hg is for. Hg is the symbol for the element Mercury. (Remember from the Periodic Table) in chemistry class?)

You can get TortoiseHg for Windows (32-bit and 64-bit) and Linux. On Windows, the download contains everything you need to get going, including Mercurial itself. Since you're probably on this site to learn C#, learn XNA or MonoGame, or something else like that, I'll assume you're on a Windows machine for the rest of these tutorials. (Everything should look pretty similar on Linux, but I haven't ever tried it over there, so I can be sure.)

So go ahead and download the appropriate version for you computer here:

I'll assume you can figure out whether you need the 32-bit or the 64-bit version on your own, but if in doubt, if you computer is new within the last few years, it's probably 64-bit.

Once it's downloaded, go ahead and run the installer. You may notice that it wants to shut down Windows Explorer. (Note: that's not Internet Explorer. It's the actual shell that you can use to browse files and displays the start menu, task bar, and system tray.)

Accessing the Tools

This tutorial isn't going to cover how to actually use Mercurial (that's what the rest of this tutorial set is for) but I think now is an appropriate time to point out how you're going to get to them. There are three primary tools that you'll use to work with Mercurial: the command line, the TortoiseHg shell extensions, and the Hg Workbench.

Command Line

As I said, I have a tendency to prefer GUIs to command lines, but there are plenty of people who like the command line, and plenty of times that even those of us who prefer GUIs will find value in command lines. So let's start here.

After installation, you should be able to open the windows command shell (cmd.exe) and type the command hg:

    Microsoft Windows [Version 6.1.7601]
    Copyright (c) 2009 Microsoft Corporation.  All rights reserved.

    Mercurial Distributed SCM

    basic commands:

     add           add the specified files on the next commit
     annotate      show changeset information by line for each file
     clone         make a copy of an existing repository
     commit        commit the specified files or all outstanding changes
     diff          diff repository (or selected files)
     export        dump the header and diffs for one or more changesets
     forget        forget the specified files on the next commit
     init          create a new repository in the given directory
     log           show revision history of entire repository or files
     merge         merge working directory with another revision
     pull          pull changes from the specified source
     push          push changes to the specified destination
     remove        remove the specified files on the next commit
     serve         start stand-alone webserver
     status        show changed files in the working directory
     summary       summarize working directory state
     update        update working directory (or switch revisions)

    use "hg help" for the full list of commands or "hg -v" for details


This directly runs Mercurial (hg.exe). Because the installer put Mercurial on the system's PATH variable, you can run Mercurial commands from anywhere. You don't need to be in any special directory to run it.

I'm not going to walk you through all of the available commands right now. Like I said, my focus will be on the GUI tools, but I'll try to point out the command line equivalent for those tools when we discuss them in later tutorials.

TortoiseHg Shell Extensions

The TortoiseHg Shell Extensions are the thing I use the most when working with Mercurial. What I like about the shell extensions is, you don't need to run a special program to do the most common tasks. (That means you won't need an extra Mercurial window open at all times, nor will you need a command prompt open at all times.)

Like with the command line, right now, all I want to do is point out how you'll get to these tools when you need them, not how to actually use them. That will start in the next tutorial.

To do this, open a Windows Explorer window. Again, that's not Internet Explorer. It's the window that shows you all of the files and directories on your computer. If you don't have a preferred way of getting to this, one quick way on Windows 7 (there are similar ways on XP, Vista, and Windows 8) is to hit the Start menu, then click on Computer. You can then browse to the directory where your code lives (or where you want it to live if you're starting from scratch).

To see the shell extensions, right-click (pretty much anywhere) and you should see a menu item that says TortoiseHg as shown in the image below. (If you don't see it, it TortoiseHg didn't install correctly. You may want to try rebooting your computer or starting the installation process over again.)


Clicking on TortoiseHg shows you all of the commands that are currently available for whatever you've got selected.

Like I said, we'll look at how to use these commands soon enough.

One that is worth mentioning is the menu item for TortoiseHg > About TortoiseHg. Clicking on this shows a dialog with the current version of TortoiseHg, as well as Mercurial itself. Note that the version of TortoiseHg and Mercurial do not always line up exactly. (For instance, mine tells me I'm using TortoiseHg version 2.9.2 at the moment, and Mercurial 2.7.2.) These are two separate programs, with TortoiseHg being a GUI wrapper around the underlying program, so they will often have different versions.

By the way, to see the version of Mercurial from command line, you'd run the following:

    hg version

Hg Workbench

The last thing I want to introduce to you is the Hg Workbench. This is a full-fledged GUI tool that manages your Mercurial repositories. At the beginning, we won't use it much. When you have multiple repositories, and you want to push changes that you've made out to other places, you'll start to use it a lot more.

To get to Hg Workbench, right-click anywhere and choose Hg Workbench. (It's just above the TortoiseHg command we just looked at.) Again, if you're missing this, it means TortoiseHg didn't get installed correctly.

Hg Workbench looks like this:


It's not much to look at now, and that's OK. We'll come back to here when we've got something useful to do here. For now though, this gives us a quick overview of what got installed and how we're going to use Mercurial.

We've now got Mercurial installed, and taken a (very quick) look at the three tools that can be used for working with Mercurial: the command line, the Mercurial Shell Extensions, and Hg Workbench.

We're now ready to dive in and start using Mercurial!