​

Names

Its important to name your commands appropriately, Mercurial will automatically rename Lambda and StatefulLambda commands to match a convention. Command names are used to identify the command within a larger structure, this is especially important when it comes to errors within commands.

When naming a command this ‘rename’ function is used

‘MyCoolCommandName’ will come out as ‘my-cool-command-name’. If its important, we can use a backslash at the start of the command name to prevent modification:

This will come out as ‘MyCoolCommandName’

Its best to just follow the all lower case dash separated system for commands so that you get what you expect.

​

Errors

When your code in a command throws an error Mercurial will catch it and spit out an s-expression representation of the command.

For a simple command that is being run directly, this is just the name of the command, and Mercurial will tell you the phase that it crashed in.

We’ll use this command to demonstrate.

When lambda is scheduled, this error message will be displayed as part of the stack trace:

exception thrown in initialise:
lambda

We’ll get the actual cause exception as well, but this is just to help us identify where it came from.

First, we get told that the exception was thrown in the ‘initialise’ phase, and second, that the command was named ‘lambda’. Cool!

Ok, now lets look at a group:

When group is scheduled, this error message will be displayed as part of the stack trace:

exception thrown in initialise:
caused by: lambda
cause is marked as 'ERR' in this command s-expr
(parallel (
	ERR
	other))

We’ll get the actual cause exception as well, but this is just to help us identify where it came from.

First, we get told that the exception was thrown in the ‘initialise’ phase, second, that the command was named ‘lambda’, third we get given an s-expression representation of the group that it was in, and it is marked as ERR.

S-expressions are easy to read, and make it easy to group information together.

As we look at each of the group and utility commands, we will also explore their representation.