#acl HlpLabGroup:read,write,delete,revert,admin All:read
#format wiki
#pragma section-numbers 2
#language en

= Mercurial =

== What is Mercurial ==
[[http://www.selenic.com/mercurial/wiki/|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 [[http://developer.mozilla.org/en/docs/Mercurial|Mozilla]] and [[http://openjdk.java.net/|Java]].

== 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.

== 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.

=== 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: 
{{{#!highlight cfg numbers=disable
[ui]
username = Firstname Lastname <username@yourdepartment.rochester.edu>

[diff]
git = 1

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

[extensions]
hgext.mq =
color =
}}}

=== Mac extra config ===
Create a file called `/usr/local/bin/opendiff-w` (if it doesn't exist already) with the contents
{{{#!highlight sh numbers=disable
#!/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:

{{{#!highlight cfg numbers=disable
[merge-tools]
filemerge.executable = opendiff-w
filemerge.args = $local $other -ancestor $base -merge $output
}}}

=== Unix extra config ===
This sets [[http://meld.sourceforge.net/|Meld]] as the merge program. Add into the existing `[ui]` section.
{{{#!highlight cfg numbers=disable
[ui]
merge = meld
}}}

=== Mac/Unix common extra config ===
Installing [[http://colordiff.sourceforge.net/|ColorDiff]] and adding this (into the existing sections where appropriate) gives you color diffs on the command line:
{{{#!highlight cfg numbers=disable
[defaults]
cdiff = -q

[extensions]
hgext.extdiff =

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

=== Windows extra config ===
To use Mercurial effectively on Windows you'll need to also install [[http://tortoisesvn.tigris.org/|TortoiseSVN]] (for Tortise``Merge) and [[http://www.cygwin.com/|Cygwin]] (for command line `ssh`). It's also nice to install [[http://tortoisehg.sourceforge.net/|TortoiseHg]] for Windows Explorer integration with Mercurial. Starting with version 0.4.1, Tortoise``Hg 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`:
{{{#!highlight cfg numbers=disable
[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
}}}

== Serving your repo on the web ==
[[MercurialHgWeb|HgWeb configuration]]