Mercurial/Setup

[[Category:SCM][Category:HG]]

Setting up Mercurial

Installing Mercurial

Mercurial source and binary distributions are available here. Many Linux distributions, OpenSolaris and cygwin (Windows) offer Mercurial packages as well. Installing from source requires a working Python installation. Windows users have the choice between a cygwin based Mercurial and TortoiseHg, the latter one "is an all-inclusive Mercurial binary installer package for Windows".

Some cygwin versions exhibit a bug which affects hg and other tools. If your cygwin hg complains about: "*** fatal error - could not load shell32, Win32 error 487" use TortoiseHg instead.

Configuring Mercurial

Mercurial can be configured via system, user and repository configure files. The most interesting one is the user specific configuration file in $HOME/.hgrc. Example:

[ui]
# The user name will appear as author tag on commits.
username=Jens-Heiner Rechtien <hr@openoffice.org>
# Domain developers only: OOo ssh authentication for pushing 
# to 'outgoing' repositories.
ssh=ssh -C -i <path_to_OOo_ssh_identity>

[extensions]
# Required if 'cws fetch' is used to fetch a CWS.
hgext.mq=
# Enables the bundled win32text extension. See [hooks] section.
hgext.win32text=

[hooks]
# Reject commits which would introduce windows-style CR/LF.
# Enabling this hook is strongly suggested for OOo development.
pretxncommit.crlf = python:hgext.win32text.forbidcrlf

Let's examine this configuration file entry for entry:

[ui]
username=Jens-Heiner Rechtien <hr@openoffice.org>

The author tag of a changeset is set on commit, and becomes part of the history. Set this entry to identify yourself as author, common usage is to use your name and OOo email address here.

[ui]
ssh=ssh -C -i <path_to_OOo_ssh_identity>

OOo domain developers can create "child workspaces", which are effectively public feature branches. Publishing changes on hg.services.openoffice.org requires SSH access, which is configured here. Be sure to use a compressed ssh connection (-C).

[extensions]
hgext.mq=
hgext.win32text=

Mercurial supports a huge number of useful extensions, many of them come bundled. Enable here whatever you want to use. The 'mq' extension is required if you want to use the 'cws fetch' tool since it makes use of 'hg strip' which is part of the 'mq' extension. The 'win32text' extension ist strongly suggested for all OOo developers who work on windows at least occasionally, it provides a hook which prevents you from commiting files with CR/LF in them.

[hooks]
pretxncommit.crlf = python:hgext.win32text.forbidcrlf

This is one of the hooks provided by 'win32text'. Disable it on the peril of aggravating the whole OOo developer community.