Mercurial

1. What is Mercurial

Mercurial is a Source Control Management system (or Version Control System, or several other names) written in Python and C. Unlike older SCMs like CVS or Subversion, and like Git and Bazaar, Mercurial is distributed; meaning that there is no central privileged repository. All users have a full copy of the source and the history. Current major projects that use it include Mozilla and Java.

2. Getting started

See below for some suggestions about configuration. Read the docs on the Mercurial and Mozilla Developer Center pages linked to above, and try

hg help

for decently full help about Mercurial commands.

3. Configuration

The configuration file for Mercurial is .hgrc in your home directory on Unix/Mac OS X, and Mercurial.ini in your profile directory (e.g. C:\Documents and Settings\username\) on Windows.

3.1. Base configuration

The following sets the username and email address associated with your commits, tells Mercurial to use Git-style diffs, sets 4 lines of context around a change when showing a diff, and turns on support for patch queues and colorized output:

[ui]
username = Firstname Lastname <username@yourdepartment.rochester.edu>

[diff]
git = 1

[defaults]
diff=-p -U 4
qdiff = -U 4

[extensions]
hgext.mq =
color =

3.2. Mac extra config

Create a file called /usr/local/bin/opendiff-w (if it doesn't exist already) with the contents

#!/bin/sh
# opendiff returns immediately, without waiting for FileMerge to exit.
# Piping the output makes opendiff wait for FileMerge.
opendiff "$@" | cat

and add the following to your .hgrc, which allows you to use opendiff from the Apple Developer Tools to do merges:

[merge-tools]
filemerge.executable = opendiff-w
filemerge.args = $local $other -ancestor $base -merge $output

3.3. Unix extra config

This sets Meld as the merge program. Add into the existing [ui] section.

[ui]
merge = meld

3.4. Mac/Unix common extra config

Installing ColorDiff and adding this (into the existing sections where appropriate) gives you color diffs on the command line:

[defaults]
cdiff = -q

[extensions]
hgext.extdiff =

[extdiff]
cmd.cdiff = colordiff
opts.cdiff = -uprN

3.5. Windows extra config

To use Mercurial effectively on Windows you'll need to also install TortoiseSVN (for TortiseMerge) and Cygwin (for command line ssh). It's also nice to install TortoiseHg for Windows Explorer integration with Mercurial. Starting with version 0.4.1, TortoiseHg also includes the current version of Mercurial in its installer.

As always, add these to the existing sections, but this time to your Mercurial.ini:

[ui]
merge = TortoiseMerge
editor = vim
ssh = C:\cygwin\bin\ssh.exe

[merge-tools]
TortoiseMerge.executable = C:\Program Files\TortoiseSVN\bin\TortiseMerge.exe
TortoiseMerge.args = /mine:$local /theirs:$other /base:$base -o /merged:$output

4. Serving your repo on the web

HgWeb configuration