Using a Mercurial Code Repository

Mercurial is a Distributed Concurrent Versions System, rather similar to the Concurrent Versions System that is used for Radiance. The idea is to have central repository that allows different developers to work on the same code base.

Mercurial is fairly easy to use. All Mercurial commands start with hg, followed by the action and options.

Mercurial is well-documented. Here are a couple of guides that you might find of interest. Their order is from Basic to Complex:

  1. Learning Mercurial in Workflows
  2. Mercurial: The Definitive Guide by Bryan O'Sullivan

Cloning a Repo

To start contributing, first create a local copy of the repo on your machine. We are assuming that you want the csh2perl directory under ~/software/, but it can reside anywhere you like.

$ cd ~/software
$ hg clone https://www.jaloxa.eu/devel/hg/csh2perl
warning: www.jaloxa.eu certificate with fingerprint cf:c1:...:6d not verified
  (check hostfingerprints or web.cacerts config setting)
destination directory: csh2perl
requesting all changes
adding changesets
adding manifests
adding file changes
added 18 changesets with 140 changes to 126 files
updating to branch default
124 files updated, 0 files merged, 0 files removed, 0 files unresolved

This has created the directory csh2perl under your ~/software/ directory. We'll talk about the fingerprint warning later. You may safely ignore it for now.

$ cd csh2perl/
total 19836
drwxrwxr-x.  8 axel axel     4096 Jun 26 22:59 .
drwxrwxrwt. 84 axel axel 20254720 Jun 26 22:59 ..
drwxrwxr-x.  2 axel axel     4096 Jun 26 22:58 bin
drwxrwxr-x.  4 axel axel     4096 Jun 26 23:00 .hg
-rw-rw-r--.  1 axel axel       83 Jun 26 22:58 .hgignore
drwxrwxr-x.  3 axel axel     4096 Jun 26 22:58 man
drwxrwxr-x.  2 axel axel     4096 Jun 26 22:58 orig
drwxrwxr-x.  2 axel axel     4096 Jun 26 22:58 status
drwxrwxr-x.  3 axel axel     4096 Jun 26 22:58 tests

You can now browse the code, try it out and tinker with it.

Status of the Repository

The hg status command lists all files in your local repo that are not synchronised. The following status codes are used:

CodeMeaning
Mmodified
Aadded
Rremoved
Cclean
!missing (deleted by non-hg command, but still tracked)
?not tracked
Iignored

It's a good idea to run hg status after each edit to your csh2perl repo. The example below starts off with a clean repo, after which a file is edited. The new status then indiates this changed file.

$ hg status
$ vim bin/myfile.pl
$ hg status
M bin/myfile.pl

Committing Your Changes

If you have edited any files, you'll need to tell Mercurial to check them in. This is called 'committing the changes'. During the commit, you will be prompted to give a brief summary of the changes that you've made. A one-liner will do, but try to be concise.

$ hg status
M bin/myfile.pl
$ hg commit

The editor that Mercurial will fire off for you is defined by the $EDITOR environmental variable. It defaults to vi if $EDITOR is not set. This can be overwritten in your ~/.hgrc file. More to this later.

If you don't want to involve any editor, you can specify the commit message on the command line:

$ hg commit -m "Fixed bug with call to pvalue"

You are encouraged to make relatively small changes, committing frequently as you go along. If you got carried away with your editing, and there is a whole bunch of files waiting to be committed, you may tell Mercurial to only process specific files:

$ hg commit bin/myfile.pl

or

$ hg commit -I bin/myfile.pl

Adding New Files

The last section explained what you need to do if you have edited existing files. If you add new files, e.g. a new Perl script under bin, or a new man page under man/man1/, you need to tell Mercurial, too.

$ hg status
$ touch bin/testscript.pl
$ hg status
? bin/testscript.pl
$ hg add bin/testscript.pl 

Pushing Your Changes

After a commit, your local repo is synced with the files that you have edited locally, but the changes still need to be propagated to the central repo on the server. This is done with hg's push action.

Before we go there, we need to briefly talk about the hg resource file, ~/.hgrc. This is where important setting, such as the Mercurial server and authentication are stored. The csh2perl repo on JALOXA is configured to work securely over https. No authentication is required for pulls. However, if you want to push, you need to authenticate yourself.

Copy and paste the following to a new file '.hgrc' in your home directory:

$ cat ~/.hgrc
# This is a Mercurial configuration file.
[ui]
username = Your Name 
#editor = vim

[paths]
#default = https://username:password@www.jaloxa.eu/devel/hg/csh2perl
csh2perl = https://username:password@www.jaloxa.eu/devel/hg/csh2perl

[hostfingerprints]
www.jaloxa.eu = cf:c1:0f:0f:a6:ed:8d:28:c8:aa:ca:8c:40:67:54:d7:4b:7f:68:6d


Make sure the username and password are valid. Try to get this right. The server will lock you out after too many failed attempts. You should now be able to run

$ hg commit csh2perl

without any complaints or warnings.

There are other changes that you can make to your .hgrc file:

ui.editor
Un-comment this line and change the value to your favourite editor
paths.default
If you un-comment this line (make sure to change username and password!), you can omit the 'csh2perl' part from hg commit.
hostfingerprints
The issuing authority of JALOXA's SSL certificate might not be known to your Mercurial. This setting turns off the warning that we got when we first cloned the repo from the server.

Pulling the Latest Revision

Before you do any editing, it's always a good idea to start off with the very latest revision. This is done by 'pulling' from the server.

$ hg pull

Your local repo is now in sync with the main one, but the actual files are not updated yet. This needs one extra command:

$ hg update

You can now start editing. Remember to frequently commit the changes, and to push them to the server.