Git Reference ยท Hooks
The fsmonitor-watchman hook
Reference for the Git fsmonitor hook protocol: core.fsmonitor, the version and token arguments, the NUL-separated output, and the Watchman sample hook.
In a large working tree, git status spends most of its time asking the file system what changed. A file-system monitor lets Git skip that scan. When core.fsmonitor points at a hook, Git asks the hook, before it checks the tree: "which paths changed since the last time I asked?", and then only looks at those paths.
The hook is a program you write or install; the sample fsmonitor-watchman.sample talks to Facebook's Watchman service. Git does not call it as a regular named hook from .git/hooks: you must set core.fsmonitor to its path. Newer Git versions also have a built-in daemon (core.fsmonitor=true, git fsmonitor--daemon) on supported platforms, which is easier to use than a custom hook.
git config core.fsmonitor .git/hooks/fsmonitor-watchman # Git runs: <hook> <version> <token> # The hook prints: <new-token> NUL <path> NUL <path> NUL ...
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Syntax
git config core.fsmonitor <path-to-hook> # or true / false
| Argument | Description |
|---|---|
| version | The protocol version Git uses to call the hook. Version 2 is the current one; version 1 used a time in nanoseconds instead of a token. |
| token | Identifies the point in time of the previous query, so the hook knows what "since last time" means. Treat it as opaque. In the runs behind this page it was a nanosecond timestamp. |
Output: the new token followed by a NUL byte, then the paths that changed since that token, each followed by a NUL byte, relative to the top of the working tree. A single path / means "I lost track, treat everything as changed". Exit status: non-zero makes Git ignore the monitor and do a full scan.
Usage notes
- The sample hook is
.git/hooks/fsmonitor-watchman.samplein new repositories. It is written in Perl and needs thewatchmancommand. Copy it, drop.sample, and setcore.fsmonitor. - Git stores the token in the index (the FSMN extension). It trusts the paths reported and skips checking everything else, so a hook that forgets a changed file hides that change from
git status. A buggy monitor is worse than none. - If the hook fails, prints bad output, or reports
/, Git falls back to scanning the whole tree and continues, sogit statusstays correct. When version 2 fails, Git retries once with the deprecated version 1, which is why the second example prints two lines. core.untrackedCache=truepairs well with it, because untracked directories can then be skipped too.- It speeds up
git status,git diffandgit addin trees with many files (hundreds of thousands). In small repositories it only adds a process start. core.fsmonitor=trueuses the built-infsmonitor--daemonwhere available instead of an external hook. Start it withgit fsmonitor--daemon start. A path value here selects the hook protocol instead.- Set it per repository, not globally, unless you know every repository benefits. Watchman has to be running and watching the tree.
- Network file systems and some virtual file systems do not deliver change events. Do not use a monitor on them.
- The older
core.fsmonitorhook interface (version 1) is deprecated; write new hooks for version 2.