Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
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

Bash A hook that always says everything changed

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.

Bash A failing hook is harmless

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

Terminal
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.sample in new repositories. It is written in Perl and needs the watchman command. Copy it, drop .sample, and set core.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, so git status stays correct. When version 2 fails, Git retries once with the deprecated version 1, which is why the second example prints two lines.
  • core.untrackedCache=true pairs well with it, because untracked directories can then be skipped too.
  • It speeds up git status, git diff and git add in trees with many files (hundreds of thousands). In small repositories it only adds a process start.
  • core.fsmonitor=true uses the built-in fsmonitor--daemon where available instead of an external hook. Start it with git 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.fsmonitor hook interface (version 1) is deprecated; write new hooks for version 2.