Are you interested in having some of the most common Mercurial operations run as much as a hundred times faster? Read on!

Mercurial has great performance under normal circumstances. For example, when you run the hg status command, Mercurial has to scan almost every directory and file in your repository so that it can display file status. Many other Mercurial commands need to do the same work behind the scenes; for example, the hg diff command uses the status machinery to avoid doing an expensive comparison operation on files that obviously haven't changed.

Because obtaining file status is crucial to good performance, the authors of Mercurial have optimised this code to within an inch of its life. However, there's no avoiding the fact that when you run hg status, Mercurial is going to have to perform at least one expensive system call for each managed file to determine whether it's changed since the last time Mercurial checked. For a sufficiently large repository, this can take a long time.

To put a number on the magnitude of this effect, I created a repository containing 150,000 managed files. I timed hg status as taking ten seconds to run, even when none of those files had been modified.

Many modern operating systems contain a file notification facility. If a program signs up to an appropriate service, the operating system will notify it every time a file of interest is created, modified, or deleted. On Linux systems, the kernel component that does this is called inotify.

Mercurial's inotify extension talks to the kernel's inotify component to optimise hg status commands. The extension has two components. A daemon sits in the background and receives notifications from the inotify subsystem. It also listens for connections from a regular Mercurial command. The extension modifies Mercurial's behavior so that instead of scanning the filesystem, it queries the daemon. Since the daemon has perfect information about the state of the repository, it can respond with a result instantaneously, avoiding the need to scan every directory and file in the repository.

Recall the ten seconds that I measured plain Mercurial as taking to run hg status on a 150,000 file repository. With the inotify extension enabled, the time dropped to 0.1 seconds, a factor of one hundred faster.

Before we continue, please pay attention to some caveats.

The inotify extension is not yet shipped with Mercurial as of May 2007, so it's a little more involved to set up than other extensions. But the performance improvement is worth it!

The extension currently comes in two parts: a set of patches to the Mercurial source code, and a library of Python bindings to the inotify subsystem.

	Note
	There are two Python inotify binding libraries. One of them is called pyinotify, and is packaged by some Linux distributions as python-inotify. This is not the one you'll need, as it is too buggy and inefficient to be practical.

To get going, it's best to already have a functioning copy of Mercurial installed.

	Note
	If you follow the instructions below, you'll be replacing and overwriting any existing installation of Mercurial that you might already have, using the latest “bleeding edge” Mercurial code. Don't say you weren't warned!

Once you've build a suitably patched version of Mercurial, all you need to do to enable the inotify extension is add an entry to your ~/.hgrc.

[extensions] inotify =

When the inotify extension is enabled, Mercurial will automatically and transparently start the status daemon the first time you run a command that needs status in a repository. It runs one status daemon per repository.

The status daemon is started silently, and runs in the background. If you look at a list of running processes after you've enabled the inotify extension and run a few commands in different repositories, you'll thus see a few hg processes sitting around, waiting for updates from the kernel and queries from Mercurial.

The first time you run a Mercurial command in a repository when you have the inotify extension enabled, it will run with about the same performance as a normal Mercurial command. This is because the status daemon needs to perform a normal status scan so that it has a baseline against which to apply later updates from the kernel. However, every subsequent command that does any kind of status check should be noticeably faster on repositories of even fairly modest size. Better yet, the bigger your repository is, the greater a performance advantage you'll see. The inotify daemon makes status operations almost instantaneous on repositories of all sizes!

If you like, you can manually start a status daemon using the inserve command. This gives you slightly finer control over how the daemon ought to run. This command will of course only be available when the inotify extension is enabled.

When you're using the inotify extension, you should notice no difference at all in Mercurial's behavior, with the sole exception of status-related commands running a whole lot faster than they used to. You should specifically expect that commands will not print different output; neither should they give different results. If either of these situations occurs, please report a bug.

Mercurial's built-in hg diff command outputs plaintext unified diffs.

$ hg diff
diff -r cfed5c378cc5 myfile
--- a/myfile	Tue May 05 06:55:34 2009 +0000
+++ b/myfile	Tue May 05 06:55:34 2009 +0000
@@ -1,1 +1,2 @@
 The first line.
+The second line.

If you would like to use an external tool to display modifications, you'll want to use the extdiff extension. This will let you use, for example, a graphical diff tool.

The extdiff extension is bundled with Mercurial, so it's easy to set up. In the extensions section of your ~/.hgrc, simply add a one-line entry to enable the extension.

[extensions]
extdiff =

This introduces a command named extdiff, which by default uses your system's diff command to generate a unified diff in the same form as the built-in hg diff command.

$ hg extdiff
--- a.cfed5c378cc5/myfile	2009-05-05 06:55:34.000000000 +0000
+++ /tmp/extdiffXdA7FH/a/myfile	2009-05-05 06:55:34.000000000 +0000
@@ -1 +1,2 @@
 The first line.
+The second line.

The result won't be exactly the same as with the built-in hg diff variations, because the output of diff varies from one system to another, even when passed the same options.

As the “making snapshot” lines of output above imply, the extdiff command works by creating two snapshots of your source tree. The first snapshot is of the source revision; the second, of the target revision or working directory. The extdiff command generates these snapshots in a temporary directory, passes the name of each directory to an external diff viewer, then deletes the temporary directory. For efficiency, it only snapshots the directories and files that have changed between the two revisions.

Snapshot directory names have the same base name as your repository. If your repository path is /quux/bar/foo, then foo will be the name of each snapshot directory. Each snapshot directory name has its changeset ID appended, if appropriate. If a snapshot is of revision a631aca1083f, the directory will be named foo.a631aca1083f. A snapshot of the working directory won't have a changeset ID appended, so it would just be foo in this example. To see what this looks like in practice, look again at the extdiff example above. Notice that the diff has the snapshot directory names embedded in its header.

The extdiff command accepts two important options. The hg -p option lets you choose a program to view differences with, instead of diff. With the hg -o option, you can change the options that extdiff passes to the program (by default, these options are “-Npru”, which only make sense if you're running diff). In other respects, the extdiff command acts similarly to the built-in hg diff command: you use the same option names, syntax, and arguments to specify the revisions you want, the files you want, and so on.

As an example, here's how to run the normal system diff command, getting it to generate context diffs (using the -c option) instead of unified diffs, and five lines of context instead of the default three (passing 5 as the argument to the -C option).

$ hg extdiff -o -NprcC5
*** a.cfed5c378cc5/myfile	Tue May  5 06:55:34 2009
--- /tmp/extdiffXdA7FH/a/myfile	Tue May  5 06:55:34 2009
***************
*** 1 ****
--- 1,2 ----
  The first line.
+ The second line.

Launching a visual diff tool is just as easy. Here's how to launch the kdiff3 viewer.

hg extdiff -p kdiff3 -o

If your diff viewing command can't deal with directories, you can easily work around this with a little scripting. For an example of such scripting in action with the mq extension and the interdiff command, see the section called “Viewing the history of a patch”.

[extdiff]
cmd.kdiff3 =

[extdiff]
 cmd.wibble = kdiff3

[extdiff]
 cmd.vimdiff = vim
opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)'

Need to have a long chat with Brendan about this.

Many projects have a culture of “change review”, in which people send their modifications to a mailing list for others to read and comment on before they commit the final version to a shared repository. Some projects have people who act as gatekeepers; they apply changes from other people to a repository to which those others don't have access.

Mercurial makes it easy to send changes over email for review or application, via its patchbomb extension. The extension is so named because changes are formatted as patches, and it's usual to send one changeset per email message. Sending a long series of changes by email is thus much like “bombing” the recipient's inbox, hence “patchbomb”.

As usual, the basic configuration of the patchbomb extension takes just one or two lines in your /.hgrc.

[extensions]
patchbomb =

Once you've enabled the extension, you will have a new command available, named email.

The safest and best way to invoke the email command is to always run it first with the hg -n option. This will show you what the command would send, without actually sending anything. Once you've had a quick glance over the changes and verified that you are sending the right ones, you can rerun the same command, with the hg -n option removed.

The email command accepts the same kind of revision syntax as every other Mercurial command. For example, this command will send every revision between 7 and tip, inclusive.

hg email -n 7:tip

You can also specify a repository to compare with. If you provide a repository but no revisions, the email command will send all revisions in the local repository that are not present in the remote repository. If you additionally specify revisions or a branch name (the latter using the hg -b option), this will constrain the revisions sent.

It's perfectly safe to run the email command without the names of the people you want to send to: if you do this, it will just prompt you for those values interactively. (If you're using a Linux or Unix-like system, you should have enhanced readline-style editing capabilities when entering those headers, too, which is useful.)

When you are sending just one revision, the email command will by default use the first line of the changeset description as the subject of the single email message it sends.

If you send multiple revisions, the email command will usually send one message per changeset. It will preface the series with an introductory message, in which you should describe the purpose of the series of changes you're sending.