Using fsmonitor and the untracked cache

git status has to answer two questions: which tracked files changed, and which untracked files exist. Without help it answers both by examining the whole working tree — a stat call for every tracked file and a scan of every directory for untracked ones. In a tree with hundreds of thousands of files that takes seconds, and every editor, prompt and Git command that checks status pays it. The built-in filesystem monitor daemon (core.fsmonitor) listens for change events from the operating system, so Git examines only paths that changed since last time. The untracked cache remembers directory contents and skips directories whose modification time has not changed. Together they turn status from proportional to tree size into proportional to what changed. This page enables them, checks they are working, and covers the situations where they should be off, within large repository performance.

When to use this approach

  • git status takes more than a second in your working tree.
  • Shell prompts or editors showing Git status feel sluggish.
  • The tree has hundreds of thousands of files, as large monorepos do.
  • You have already reduced the tree with sparse checkout for large monorepos and status is still slow.

Step 1 — Measure status and find the slow phase

Trace status to see whether time goes to checking tracked files (refresh) or scanning for untracked ones.

time git status >/dev/null
GIT_TRACE2_PERF=1 git status 2>&1 >/dev/null | grep -E 'refresh|untracked|read_directory' | awk -F'|' '{print $(NF-1), $NF}' | tail -n 8

Large “refresh” time is what fsmonitor removes; large “read_directory” or untracked time is what the untracked cache removes. Often both matter.

How status finds changes with and without helpWithout help, git status checks every tracked file's metadata and reads every directory to find untracked files. With fsmonitor, the daemon reports which paths changed since the last query, so only those are checked. With the untracked cache, directories whose modification time is unchanged are not re-read.Defaultfsmonitor + untracked cachetracked filesstat every fileonly changed pathsuntracked filesread every directoryonly changed directoriescost grows withtree sizeamount changedafter the first run, status time tracks your edits, not the repository size

Step 2 — Enable the built-in fsmonitor daemon

Git ships a filesystem monitor daemon on macOS and Windows; on Linux, recent Git versions support it as well. Enable it per repository.

git config core.fsmonitor true
git config core.untrackedCache true
git fsmonitor--daemon status       # starts automatically on the next command
git status >/dev/null              # first run primes the daemon
time git status >/dev/null         # subsequent runs use it

On platforms where the built-in daemon is unavailable, core.fsmonitor can name a hook script that queries an external watcher such as Watchman; the effect is the same.

Step 3 — Verify both are actually in use

Configuration being set does not prove the feature works — an unsupported filesystem silently disables it. Check directly.

git fsmonitor--daemon status                    # "fsmonitor-daemon is watching '/path/to/repo'"
git update-index --test-untracked-cache          # checks the filesystem supports it
git update-index --untracked-cache               # turns it on in the index
GIT_TRACE_FSMONITOR=1 git status 2>&1 >/dev/null | head -n 5

Step 4 — Handle network drives, containers and VMs

Filesystem events are unreliable or absent on network filesystems, some container bind mounts and shared folders in virtual machines. The daemon refuses to watch remote filesystems by default, which is the right choice; keep large repositories on local disks.

git config fsmonitor.allowRemote false      # the default; do not override without testing carefully
df -T . | tail -n 1                           # check the filesystem type of the working tree
Should fsmonitor be enabled here?On a developer's local disk with a large tree, enable both fsmonitor and the untracked cache. On a network drive or shared folder, leave fsmonitor off because change events are unreliable, and move the repository to local disk if possible. In ephemeral CI checkouts, leave both off because each job runs status only a few times.Where does the working tree live?local disk, developerEnable bothdaemon + cachenetwork / shared folderfsmonitor offmove to local diskephemeral CI checkoutLeave offno time to warm upa daemon that never sees events is worse than no daemon

Step 5 — Leave CI alone

A CI job clones, builds and exits. The daemon would start, scan everything once and be thrown away, and the untracked cache has nothing to reuse. Leave both disabled in CI, and make sure a global configuration meant for developers does not enable them there.

# In CI, override anything inherited from an image's global config
git config --global core.fsmonitor false
git config --global core.untrackedCache false

Step 6 — Roll out to the team with includeIf

Enable the features for large repositories only, using conditional includes keyed on the repository location, so small repositories do not run a daemon each.

# ~/.gitconfig
[includeIf "gitdir:~/src/monorepo/"]
    path = ~/.config/git/large-repo.gitconfig
# ~/.config/git/large-repo.gitconfig
[core]
    fsmonitor = true
    untrackedCache = true
[feature]
    manyFiles = true

feature.manyFiles also enables a newer index format suited to large trees. The pattern is covered in shipping a team gitconfig with includeIf.

git status in a large treeIllustrative timings in a working tree of about four hundred thousand files. Default status takes several seconds. The untracked cache removes most of the directory scan. Adding fsmonitor removes the per-file checks, bringing a warm status well under half a second.seconds for a warm git status (illustrative)default4.8 s+ untracked cache2.1 s+ fsmonitor0.3 sthe first status after enabling is slow; measure the second

Step 7 — Troubleshoot a daemon that seems stuck

If status suddenly misses a change or reports stale results, restart the daemon and rebuild the cache. Both are safe; the worst outcome is one slow status.

git fsmonitor--daemon stop
git update-index --no-untracked-cache && git update-index --untracked-cache
git status

Validation checklist

Frequently Asked Questions

Does fsmonitor change what status reports?

No. It changes how Git finds candidate changes, not the answer. If results ever differ, restarting the daemon fixes it, and that is a bug worth reporting.

How much memory does the daemon use?

Proportional to the number of directories watched, typically modest. One daemon runs per repository, which is why enabling it only for large repositories is sensible.

Does the untracked cache help if I have few untracked files?

Yes. The cost it removes is reading directories to look for untracked files, which happens whether or not any are found.