Mercurial Tutorial

Mercurial (Hg) is a distributed version control system. While it has similarities with Subverison, it is decentralized in nature.

Essentials

Introduction

Mercurial keeps source code in repositories. Changes to the source code are made inside the repository and are periodically committed. When you commit changes, they are wrapped into a changeset. A repository is the sum of all changesets committed over time.

Unlike Subversion, Mercurial has no concept of a "master repository." Each user owns a complete local copy of the repository, and they can commit to it without needing any permissions. Users can share changesets by pulling from other people's repositories, or pushing to other repositories (which may require special privileges).

One very noticeable side effect is that when you commit changes in Mercurial, you do not need Internet access. You only need Internet access if want to push changesets to a remote repository. This means you can make as many commits as you want before pushing.

Now for the contradiction: You CAN have a master repository with Mercurial. For some projects it is ideal to have a reference copy. There is no difference between your copy and the master copy -- how it is managed is simply a matter of permissions and policy. For example, AlliedModders has a "sourcemod-central" repository where developers push their changesets. Only SourceMod developers can push to this copy, but anyone can copy it or pull its changes.

Basic Commands

These are a few essential Mercurial operations:

• clone - Copies or downloads a repository.
• add - Adds a file or directory to the local source tree.
• remove - Removes a file or directory from the local source tree.
• commit - Commits any local changes to your local source tree.
• pull - Retrieves changesets from another repository.
• update - Updates source code with all pending pulled changes.
• push - Pushes your changesets to a remote repository.
• merge - Merges two repositories together (explained later).

Installing

The author of this article uses command line Mercurial (on both Linux and Windows). You can download both the command line tools at the Mercurial Site, and there is a TortoiseHg graphical tool for those who would like to try it.

Getting a Repository

To retrieve a repository, you must use the "clone" command. You can clone a local or remote repository. Examples:

hg clone http://hg.alliedmods.net/sourcemod-central sourcemod-central
hg clone sourcemod-central sourcemod-copy

You can also create a new repository:

mkdir project
cd project
hg init

This will create a blank repository and initialize it with Mercurial.

Configuration

Mercurial lets you configure default settings for all repositories and settings specific to one repository.

On Linux, the main configuration file is ~/.hgrc. On Windows 2003/XP and prior, it is C:\Documents and Settings\<account>\Mercurial.ini. On Windows Vista, it is C:\Users\<account>\Mercurial.ini. If the file does not exist, you can create it.

Per-repository configuration is done in <repository>\.hg\hgrc.

Identity

Mercurial lets you configure an identity to associate with your changesets. By default it uses the name of the account your computer is logged in as. Many projects (AlliedModders included) use "Firstname Lastname <email>" instead.

To set up your identity, open either your hgrc file (either the main or local one). Look for a "[ui]" section (or add a new one), and configure something like this:

[ui]
username = David Anderson <[email protected]>

Push and Pull Locations

By default, all "pull" operations on a repository occur from the original location you cloned from. You can change that location by opening up <repository>\.hg\hgrc and looking at the "[paths]" section. You will see a lines like:

[paths]
default = http://hg.alliedmods.net/sourcemod-central

If you are going to be pushing to one main repository fairly often, you may want to set up a default push. For example:

[paths]
default = http://hg.alliedmods.net/sourcemod-central
default-push = ssh://[email protected]//hg/sourcemod-central

Note: Mercurial uses double slashes to specify an absolute file-system path. If you are using SSH with logical paths, you only need one slash. For more information about this, visit the Mercurial documentation. AlliedModders uses absolute paths.

Workflow

Let's go through a typical session of developing with Mercurial. If you are working against a project that has a centralized copy, you may want to make sure you're up to date first. This means pulling its changes and then updating.

For example:

hg pull
hg update

This will grab the remote changes from the location you first cloned from. Then it will apply the changes. You can do this in one go with:

hg pull -u

You can also pull from a different repository if you want:

hg pull -u http://some.other.site/sourcemod-central

Now let's say you make some changes. You edit file A.cpp and you want to commit your change. You can do this with:

hg commit

An editor will pop-up asking you to write a message describing your change. This is required.

Now you edit B.cpp and commit again. You're done for the day, and you have two changesets sitting in your repository. You want to push these upstream. For example:

hg push ssh://[email protected]//hg/sourcemod-central

Or, if you have a default-push configured:

hg push

SSH Authentication

If you are accessing your repository via SSH using the ssh protocol, entering your password is annoying and could be a security risk. You should look into using SSH Keys (full instructions are provided).

External Links

• Mercurial Home Page
• Understanding Mercurial
• Hg Book, free online book about Mercurial
• Mercurial Tutorials