Speed Up Git Status with the Built-in File Monitor

Git's built-in filesystem monitor can make commands such as git status cheaper in a large working tree. This guide checks whether the installed Git can use it, enables it for one repository, verifies the daemon, and shows how to undo the change. Allow about five minutes. You need a Git working tree and permission to edit its local configuration.

1. Check the Git version and platform support

Start inside the repository that you want to test. The command is normally run as your ordinary user. Do not begin by setting core.fsmonitor: support is platform and build dependent, and a configuration value alone does not make an unsupported daemon work.

cd /path/to/repository
git --version
git fsmonitor--daemon status

On a supported installation, an inactive daemon normally makes status exit non-zero. That is different from an unsupported build. For example, the Git 2.43.0 installed on the machine used for this guide reports:

git version 2.43.0
fatal: fsmonitor--daemon not supported on this platform

If you see that message, stop here and leave core.fsmonitor unset. The commands below describe the workflow for a Git build that includes the monitor for your platform. Check git --version again after upgrading Git; do not assume that a newer package is available from your current distribution repository.

Checkpoint: support confirmed

You should have a version string and a status result that is not an unsupported-platform error. If you are unsure, keep the monitor disabled until the command completes without that error.

2. Check the repository filesystem

The daemon watches one working directory and communicates with Git through a Unix domain socket on Linux. Network-mounted repositories are refused by default and are not guaranteed to work even when you override that protection. Keep the repository and its .git directory on a native local filesystem for this test.

On Linux, the monitor uses inotify. Large repositories can run into the per-user watch limit, so record the current value before changing anything:

test -d .git && echo "Git directory found"
cat /proc/sys/fs/inotify/max_user_watches

A low watch limit is a capacity problem, not a reason to apply a random system setting. If the daemon later reports an inotify watch-limit error, consult your distribution's sysctl guidance first.

3. Enable the monitor for this repository

This changes only the repository's local Git configuration. It does not require elevated privileges. The setting tells commands such as git status to use the built-in daemon and to start it when needed.

git config --local core.fsmonitor true
git config --local --get core.fsmonitor

Expected output:

true

Do not use sudo for this command. Using it can write configuration or create runtime files under the wrong user's home directory, leaving your normal Git process unable to communicate with the daemon.

4. Start and verify the daemon

Run a normal status command first. With the setting enabled, Git can start the daemon automatically.

git status --short
git fsmonitor--daemon status
echo "status exit code: $?"

The second command should exit with code 0 when a daemon is watching the current working directory. It may print no useful text, because its documented purpose is the exit status. The first status command should still show the repository's real changes. Create a harmless test file if you want to prove that changes continue to be noticed, then remove it afterwards.

printf 'fsmonitor test\n' > .fsmonitor-test
git status --short
rm -- .fsmonitor-test
git status --short

Seeing the test file as untracked and then seeing it disappear is a basic client check. It is not a benchmark. The benefit depends on repository size, filesystem speed and how often Git has to refresh the index.

Foreground mode for troubleshooting

start launches the daemon in the background. If it fails, run it in the foreground so its error is visible:

git fsmonitor--daemon stop
git fsmonitor--daemon run

run occupies the terminal until you interrupt it. This is a service-disrupting diagnostic action: do not leave it running in a shell you need for other work. Press Ctrl-C to stop it, then check from another terminal with git fsmonitor--daemon status. A foreground run is not required for ordinary use.

5. Handle common failure boundaries

If status says the platform is unsupported, remove the setting and use ordinary Git status:

git config --local --unset core.fsmonitor || true
git fsmonitor--daemon stop || true
git status --short

If the repository is on a network mount, move or clone it to local storage before testing. The fsmonitor.allowRemote setting exists to override the refusal, but the manual marks network-mounted use as experimental. Do not enable it merely to silence an error.

If a daemon is stale or you no longer want it, stopping it is safe and reversible. The configuration can remain enabled, in which case a later Git command may start it again. To disable the feature completely:

git fsmonitor--daemon stop
git config --local --unset core.fsmonitor

The daemon does not understand submodules as separate event sources. A change inside a submodule can therefore be reported to the superproject as an extra event, although Git's client filters it and should not produce an incorrect result. Expect some lost performance benefit in repositories with many submodules.