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.
This tutorial assumes you already have TortoiseHg properly installed, and you have your project folder open in your file browser.
First you need to make sure that you are correctly identified in TortoiseHg. You do this by adjusting the global settings of TortoiseHg. Right click in your source folder and select TortoiseHg ‣ Global Settings
Context menu with no files selected
You must then select the Commit tab and enter a name in the Username field.
Note
If you forget to configure your username TortoiseHg will ask you to enter one when you commit, the only time the name is actually required.
Note
There are no hard rules on how to format your user name, 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.
If you are not using one of our Windows installers, you will also have to configure a visual diff tool. Type hgtk userconfig and on the TortoiseHg tab you will find Visual Diff Command. If there are no options in the drop-down list, you must enable and configure Mercurial’s ExtDiff extension and then restart the userconfig application.
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.
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.
Warning
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.
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:
Note
The .hgignore file, contained in the working directory root, is typically tracked (checked in).
Note
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.
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.
Note
You lose the ability to easily undo the last commit when you close the commit tool.
Commit Tool
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
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.
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 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
Which may sound complicated, but most of the time it is just pushing the buttons in the commit and changelog tools.
Note
Merges can be safely restarted if necessary.
Mercurial makes collaboration easy, fast, and productive. Learn more at Mercurial’s wiki.