Documentation/git-fsmonitor--daemon.adoc

git-fsmonitor{litdd}daemon(1)
=============================

NAME
----
git-fsmonitor--daemon - A Built-in Filesystem Monitor

SYNOPSIS
--------
[verse]
'git fsmonitor{litdd}daemon' start
'git fsmonitor{litdd}daemon' run
'git fsmonitor{litdd}daemon' stop
'git fsmonitor{litdd}daemon' status

DESCRIPTION
-----------

A daemon to watch the working directory for file and directory
changes using platform-specific filesystem notification facilities.

This daemon communicates directly with commands like `git status`
using the link:technical/api-simple-ipc.html[simple IPC] interface
instead of the slower linkgit:githooks[5] interface.

This daemon is built into Git so that no third-party tools are
required.

OPTIONS
-------

start::
	Starts a daemon in the background.

run::
	Runs a daemon in the foreground.

stop::
	Stops the daemon running in the current working
	directory, if present.

status::
	Exits with zero status if a daemon is watching the
	current working directory.

REMARKS
-------

This daemon is a long running process used to watch a single working
directory and maintain a list of the recently changed files and
directories.  Performance of commands such as `git status` can be
increased if they just ask for a summary of changes to the working
directory and can avoid scanning the disk.

When `core.fsmonitor` is set to `true` (see linkgit:git-config[1])
commands, such as `git status`, will ask the daemon for changes and
automatically start it (if necessary).

For more information see the "File System Monitor" section in
linkgit:git-update-index[1].

CAVEATS
-------

The fsmonitor daemon does not currently know about submodules and does
not know to filter out filesystem events that happen within a
submodule.  If fsmonitor daemon is watching a super repo and a file is
modified within the working directory of a submodule, it will report
the change (as happening against the super repo).  However, the client
will properly ignore these extra events, so performance may be affected
but it will not cause an incorrect result.

By default, the fsmonitor daemon refuses to work with network-mounted
repositories; this may be overridden by setting `fsmonitor.allowRemote` to
`true`. Note, however, that the fsmonitor daemon is not guaranteed to work
correctly with all network-mounted repositories, so such use is considered
experimental.

On Mac OS and Linux, the inter-process communication (IPC) between various Git
commands and the fsmonitor daemon is done via a Unix domain socket (UDS) -- a
special type of file -- which is supported by native Mac OS and Linux filesystems,
but not on network-mounted filesystems, NTFS, or FAT32.  Other filesystems
may or may not have the needed support; the fsmonitor daemon is not guaranteed
to work with these filesystems and such use is considered experimental.

By default, the socket is created in the `.git` directory.  However, if the
`.git` directory is on a network-mounted filesystem, it will instead be
created at `$HOME/.git-fsmonitor-*` unless `$HOME` itself is on a
network-mounted filesystem, in which case you must set the configuration
variable `fsmonitor.socketDir` to the path of a directory on a native
filesystem in which to create the socket file.

If none of the above directories (`.git`, `$HOME`, or `fsmonitor.socketDir`)
is on a native filesystem the fsmonitor daemon will report an
error that will cause the daemon and the currently running command to exit.

LINUX CAVEATS
~~~~~~~~~~~~~

On Linux, the fsmonitor daemon uses inotify to monitor filesystem events.
The inotify system has per-user limits on the number of watches that can
be created.  The default limit is typically 8192 watches per user.

For large repositories with many directories, you may need to increase
this limit.  Check the current limit with:

    cat /proc/sys/fs/inotify/max_user_watches

To temporarily increase the limit:

    sudo sysctl fs.inotify.max_user_watches=65536

To make the change permanent, add to `/etc/sysctl.conf`:

    fs.inotify.max_user_watches=65536

CONFIGURATION
-------------

include::includes/cmd-config-section-all.adoc[]

include::config/fsmonitor--daemon.adoc[]

GIT
---
Part of the linkgit:git[1] suite