Table of Contents
- -While the core of Mercurial is quite complete from a - functionality standpoint, it's deliberately shorn of fancy - features. This approach of preserving simplicity keeps the - software easy to deal with for both maintainers and users.
-However, Mercurial doesn't box you in with an inflexible - command set: you can add features to it as - extensions (sometimes known as - plugins). We've already discussed a few of - these extensions in earlier chapters.
-When you provide a directory name, Mercurial will interpret - this as “operate on every file in this directory and its - subdirectories”. Mercurial traverses the files and - subdirectories in a directory in alphabetical order. When it - encounters a subdirectory, it will traverse that subdirectory - before continuing with the current directory.
- - - --
-
Section 3.3, “Simplifying the pull-merge-commit sequence” - covers the
fetchextension; - this combines pulling new changes and merging them with local - changes into a single command, fetch.
-In Chapter 10, Handling repository events with hooks, we covered - several extensions that are useful for hook-related - functionality:
acladds - access control lists;bugzillaadds integration with the - Bugzilla bug tracking system; andnotifysends notification emails on - new changes.
-The Mercurial Queues patch management extension is - so invaluable that it merits two chapters and an appendix all - to itself. Chapter 12, Managing change with Mercurial Queues covers the - basics; Chapter 13, Advanced uses of Mercurial Queues discusses advanced topics; - and Appendix B, Mercurial Queues reference goes into detail on - each - command.
-
In this chapter, we'll cover some of the other extensions that - are available for Mercurial, and briefly touch on some of the - machinery you'll need to know about if you want to write an - extension of your own.
-In Section 14.1, “Improve performance with the
inotifyextension”, - we'll discuss the possibility of huge - performance improvements using theinotifyextension.
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 Linux-specific. Because it interfaces directly - to the Linux kernel'sinotifysubsystem, - it does not work on other operating systems.
-It should work on any Linux distribution that - was released after early 2005. Older distributions are - likely to have a kernel that lacks -
inotify, or a version of -glibcthat does not have the necessary - interfacing support.
-Not all filesystems are suitable for use with - the
inotifyextension. - Network filesystems such as NFS are a non-starter, for - example, particularly if you're running Mercurial on several - systems, all mounting the same network filesystem. The - kernel'sinotifysystem has no way of - knowing about changes made on another system. Most local - filesystems (e.g. ext3, XFS, ReiserFS) should work - fine.
-
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]](figs/note.png) |
-Note | -
|---|---|
There are two Python
- |
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! |
-
-
-
-
Clone the Python
-inotify- binding repository. Build and install it.hg clone http://hg.kublai.com/python/inotify -cd inotify -python setup.py build --force -sudo python setup.py install --skip-build
-
- -
-
Clone the
-crewMercurial repository. - Clone theinotifypatch - repository so that Mercurial Queues will be able to apply - patches to your cope of thecrewrepository.hg clone http://hg.intevation.org/mercurial/crew -hg clone crew inotify -hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches
-
- Make sure that you have the Mercurial Queues - extension,
mq, enabled. If - you've never used MQ, read Section 12.5, “Getting started with Mercurial Queues” to get started - quickly.
--
-
Go into the
-inotifyrepo, and apply all - of theinotifypatches - using thehg - -aoption to the qpush command.cd inotify -hg qpush -a
-
- If you get an error message from qpush, you should not continue. - Instead, ask for help.
--
-
Build and install the patched version of - Mercurial.
-python setup.py build --force -sudo python setup.py install --skip-build
-
-
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 80997726a0ea myfile ---- a/myfile Wed Jan 06 06:50:18 2010 +0000 -+++ b/myfile Wed Jan 06 06:50:18 2010 +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.80997726a0ea/myfile 2010-01-06 06:50:18.613674526 +0000 -+++ /tmp/extdiffNErQlu/a/myfile 2010-01-06 06:50:18.437687076 +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.80997726a0ea/myfile Wed Jan 6 06:50:18 2010 ---- /tmp/extdiffNErQlu/a/myfile Wed Jan 6 06:50:18 2010 -*************** -*** 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 Section 13.9.2, “Viewing the history of a patch”.
It can be cumbersome to remember the options to both the
- extdiff command and
- the diff viewer you want to use, so the extdiff extension lets you define
- new commands that will invoke your diff
- viewer with exactly the right options.
All you need to do is edit your ~/.hgrc, and add a section named
- extdiff. Inside this
- section, you can define multiple commands. Here's how to add
- a kdiff3 command. Once you've defined
- this, you can type “hg kdiff3”
- and the extdiff extension
- will run kdiff3 for you.
[extdiff] -cmd.kdiff3 =-
If you leave the right hand side of the definition empty,
- as above, the extdiff
- extension uses the name of the command you defined as the name
- of the external program to run. But these names don't have to
- be the same. Here, we define a command named
- “hg wibble”, which runs
- kdiff3.
[extdiff] - cmd.wibble = kdiff3-
You can also specify the default options that you want to
- invoke your diff viewing program with. The prefix to use is
- “opts.”, followed by the name
- of the command to which the options apply. This example
- defines a “hg vimdiff” command
- that runs the vim editor's
- DirDiff extension.
[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.
-Not every project has exactly the same conventions for
- sending changes in email; the patchbomb extension tries to
- accommodate a number of variations through command line
- options.
-
-
You can write a subject for the introductory - message on the command line using the
hg -s- option. This takes one argument, the text of the subject - to use.
-To change the email address from which the - messages originate, use the
hg -f- option. This takes one argument, the email address to - use.
-The default behavior is to send unified diffs - (see Section 12.4, “Understanding patches” for a - description of the - format), one per message. You can send a binary bundle - instead with the
hg -b- option.
-Unified diffs are normally prefaced with a - metadata header. You can omit this, and send unadorned - diffs, with the
hg - --plainoption.
-Diffs are normally sent “inline”, - in the same body part as the description of a patch. This - makes it easiest for the largest number of readers to - quote and respond to parts of a diff, as some mail clients - will only quote the first MIME body part in a message. If - you'd prefer to send the description and the diff in - separate body parts, use the
hg -a- option.
-Instead of sending mail messages, you can - write them to an
mbox-format mail - folder using thehg -m- option. That option takes one argument, the name of the - file to write to.
-If you would like to add a - diffstat-format summary to each patch, - and one to the introductory message, use the
hg -d- option. The diffstat command displays - a table containing the name of each file patched, the - number of lines affected, and a histogram showing how much - each file is modified. This gives readers a qualitative - glance at how complex a patch is.
-