fsmonitor

This extension is currently being distributed along with Mercurial.

Author: Facebook, Inc.

This extension was previously known as hgwatchman before being merged into Mercurial.

1. Overview

Integrates the [[https://facebook.github.io/watchman/|file-monitoring program Watchman] with Mercurial to produce faster status results.

On a particular Linux system, for a real-world repository with over 400,000 files hosted on ext4, vanilla hg status takes 1.3 seconds. On the same system, with fsmonitor it takes about 0.3 seconds.

2. Configuration

Configure your .hgrc to enable the extension by adding following lines:

[extensions]
fsmonitor =

fsmonitor requires no configuration -- it will tell Watchman about your repository as necessary. You'll need to install Watchman from https://facebook.github.io/watchman/ and make sure it is in your PATH.

The following configuration options exist:

[fsmonitor]
mode = {off, on, paranoid}

When mode = off, fsmonitor will disable itself (similar to not loading the extension at all). When mode = on, fsmonitor will be enabled (the default). When mode = paranoid, fsmonitor will query both Watchman and the filesystem, and ensure that the results are consistent.

[fsmonitor]
timeout = (float)

A value, in seconds, that determines how long fsmonitor will wait for Watchman to return results. Defaults to 2.0.

[fsmonitor]
blacklistusers = (list of userids)

A list of usernames for which fsmonitor will disable itself altogether.

[fsmonitor]
walk_on_invalidate = (boolean)

Whether or not to walk the whole repo ourselves when our cached state has been invalidated, for example when Watchman has been restarted or .hgignore rules have been changed. Walking the repo in that case can result in competing for I/O with Watchman. For large repos it is recommended to set this value to false. You may wish to set this to true if you have a very fast filesystem that can outpace the IPC overhead of getting the result data for the full repo from Watchman. Defaults to false.

3. Platforms Supported

• Linux: Stable. Watchman and fsmonitor are both known to work reliably, even under severe loads.

• Mac OS X: Stable. The Mercurial test suite passes with fsmonitor turned on, on case-insensitive HFS+. There has been a reasonable amount of user testing under normal loads.

• Solaris, BSD: Alpha. watchman and fsmonitor are believed to work, but very little testing has been done.

• Windows: 'Alpha'. Not in a release version of watchman or fsmonitor yet.

4. Known Issues

• fsmonitor will disable itself if any of the following extensions are enabled: largefiles, inotify, eol; or if the repository has subrepos.

• fsmonitor will produce incorrect results if nested repos that are not subrepos exist. *Workaround*: add nested repo paths to your .hgignore.

The issues related to nested repos and subrepos are probably not fundamental ones. Patches to fix them are welcome.

CategoryExtensionsByOthers