3. A Quick Start Guide to TortoiseHg

Welcome to TortoiseHg and the Mercurial! TortoiseHg is a Windows Explorer shell extension and a set of graphical applications that serve as a friendly front-end to the Mercurial distributed version control system (DVCS). All TortoiseHg functionality is reachable from Explorer context menus as well as from a command line application named hgtk. Mercurial commands are also available from the standard hg command line application.

3.1. Configuring TortoiseHg

Your first step should be to make sure that you are correctly identified to TortoiseHg. You do this by opening the global settings dialog. Right click on the desktop background and select TortoiseHg ‣ Global Settings.

Desktop Context Menu

Open “Global Settings” from the desktop

This opens the TortoiseHg settings dialog, editing your global (user) configuration. If you are using the command line, the global settings dialog can be opened by hgtk userconfig.

Settings Dialog

TortoiseHg Settings Dialog

First select the Commit page and enter a name in the Username field.


If you neglect to configure a username TortoiseHg will ask you to enter one when you try to commit, which is the first time a username is actually required.


There are no hard fast rules on how to format your username, the field is free form, but the following convention is commonly used:

FullName <email>

for example

Donald Duck <donaldduck@example.net>

The email address is stripped when viewing history in the changelog viewer, and the built-in web server obfuscates email addresses to prevent SPAM.

Next, select the TortoiseHg page and select the Three-way Merge Tool entry. In the drop down list you will find all of the merge tools detected on your computer (kdiff3 is provided by the Windows installer) and a number of internal merge behaviors. Select your preferred merge tool.

If you prefer for TortoiseHg to also use your selected merge tool for visual diffs, you can leave the Visual Diff Tool unspecified. Otherwise, select your favorite visual diff tool from the drop down list of detected visual diff tools.

If there are no options in either drop-down list, you must install a diff/merge tool that is supported by our mergetools.rc or configure your own tool.


If you installed TortoiseHg from source, you need to add our contrib/mergetools.ini file to your HGRC path in some way. One approach is to %include it from your ~/.hgrc file.

Feel free to configure other global settings while you have the dialog open. You will have the chance later to override these global settings with repository local settings, if required.

Click the Ok button to save the changes you have made and close the settings dialog.


Most TortoiseHg tools require a restart to pick up changes made in the settings dialog.

3.2. Getting Acquainted

Mercurial supports many different collaboration models. This chapter describes just one of those models: a single central repository. The central repository model does not scale as well as other models, but it is the most familiar to those coming from other revision tools and thus is the most common approach people start with.

To get started, suppose you volunteer to create the central repository. There are ways to convert non-Mercurial repositories into Mercurial repositories, but this example assumes you are starting from scratch.

3.3. Initialize the repository

Create the initial repository on your local machine by using the Create Repository Here shell menu option, or in a command shell within the folder, type hgtk init. You only need to do this in once in the root folder of your project.

Init dialog

Repository Init Dialog

We suggest you keep Add special files (.hgignore, ...) checked, and do not check Make repo compatible with Mercurial 1.0 unless you have a strong reason to do so.

After pressing Create, Mercurial creates a subdirectory in your project folder named .hg. This is where Mercurial keeps all its version data. It is called the repository or store, while the directory containing the source files is called the working directory. You never need to specify the .hg directory when running commands, you only need to specify the working directory root. It is mentioned here just so you better understand how Mercurial works.


It is dangerous to manually edit the files in .hg directory, repository corruption can occur. .hg/hgrc is perhaps the only exception to this rule.

3.4. Add files

Now it’s time to tell Mercurial which files must be tracked and which files must be ignored. There are a lot of way to do this:

  1. To add files, select them in explorer and then right click and select TortoiseHg ‣ Add Files... in the context menu. A dialog will open for you to double check the selected files and accept the add operation.
  2. Or open the status tool (TortoiseHg ‣ View File Status or hgtk status from the command line). Check the files you want to add and then press the Add button. From the status tool you can launch the ignore filter tool from the context menu of a unknown file (the menu option is named ignore)
  3. Or skip adding new files as a separate step and have the commit tool add them implicitly. The commit tool is very similar to the status tool and allows you to do all of the same tasks. In this tool you can add and commit an untracked file by just checking the file and pressing Commit.
  4. To ignore files, open the ignore filter dialog: TortoiseHg ‣ Edit Ignore Filter or from command line hgtk hgignore. Choose a file from the list or manually type in a Glob or Regular expression filter and then press Add. Changes to the ignore filter take effect immediately.


The .hgignore file, contained in the working directory root, is typically tracked (checked in).


It is good practice to not have many unknown files in your working directory, as it makes it too easy to forget to add vital new files. It is recommended that you keep your .hgignore file up to date.

3.5. Commit

Commit your local repository by right-clicking anywhere in the folder, or on the folder itself, and then selecting Hg Commit ..., or from command line type hgtk commit. Write a commit message, select the files you wish to commit, then press Commit. If, after the commit, you realize that something was wrong with the message or the selected files, you can cancel the last commit using the Undo button. Your previous commit message will be in the message history drop-down, so you do not have to type it in again from scratch.


You lose the ability to easily undo the last commit when you close the commit tool.

Commit dialog

Commit Tool

3.6. Share the repository

Now you are ready to share your work. You do this by making a copy of your repository in a public location that everyone in your group can read. Mercurial calls this copy operation cloning your repository. To clone your repository to a shared drive, open the clone tool TortoiseHg ‣ Clone a Repository, or hgtk clone from command line. Then enter the destination path.

Clone dialog

Clone Dialog

When you create a clone for the purposes of generating a central repository there is no reason for that clone to have a working directory. Checking do not update the new working directory will prevent Mercurial from checking out a working copy of the repository in the central repository clone. It will only have the .hg directory, which stores the entire revision history of the project.

Other team members can clone from this clone with or without a checked out working directory.

3.7. Fetching from the group repository

You want to start collaborating with your team. They tell you something like fetch the repository from x. What does that mean? It means that you want to make a copy of the repository located at x on your local machine. Mercurial calls this cloning and TortiseHg has a dialog for it. Right click in the directory where you want your copy and select TortoiseHg ‣ Clone a Repository, or hgtk clone from command line.

Clone dialog

Clone Dialog

This time you do want to update the working directory because you want to work on the project, uncheck do not update the new working directory so Mercurial updates the working directory with the tip revision in your new clone.

3.8. Working with your repository

Suppose you’ve introduced some changes. It is easy to see that there are a couple of directories with changes pending. You can traverse the directories to find specific changes and commit them from Explorer. A quicker way is to use the commit tool:

Overlay Icons

Overlay Icons on Vista

The commit tool gives you a way to see differences or you can use your visual difference tool (kdiff). Mercurial allows you to commit many changes before you decide to synchronize (share changes) with the group repository.

When you’re ready to publish your changes, you

  1. Commit your changes to your local repository (see above).
  2. Pull changes from the group repository into your repository, TortoiseHg ‣ Repository Browser or hgtk log, choose the path to the group repository in the syncbar and then Pull.
  3. If some changesets were pulled, merge those changes with your local changes and then commit the merge into your local repository. From the changelog viewer (TortoiseHg ‣ Repository Browser or hgtk log) open the context menu over the changeset which you want to merge and select merge with. Finally, in the merge dialog, press Merge and then Commit.
  4. Ensure your merged work still builds and passes your extensive test suite.
  5. Push your changes to the group repository, TortoiseHg ‣ Repository Browser or hgtk log, choose the path to group repository and then Push.

Which may sound complicated, but most of the time it is just pushing the buttons in the commit and changelog tools.


Merges can be safely restarted if necessary.

Mercurial makes collaboration easy, fast, and productive. Learn more at Mercurial’s wiki.