## page was renamed from HgWatchmanExtension
## page was renamed from Source Info Extension
#pragma section-numbers 2
= 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.

<<TableOfContents>>

== 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.

== Configuration ==

First, you'll need to install Watchman from
https://facebook.github.io/watchman/ and make sure it is in your PATH.

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

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.

== 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.

== 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