fsmonitor: document builtin fsmonitor

Document how `core.fsmonitor` can be set to a boolean to enable
or disable the builtin FSMonitor.

Update references to `core.fsmonitor` and `core.fsmonitorHookVersion` and
pointers to `Watchman` to refer to it.

Create `git-fsmonitor--daemon` manual page and describe its features.

Signed-off-by: Jeff Hostetler <jeffhost@microsoft.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
pull/1232/head
Jeff Hostetler 6 months ago committed by Junio C Hamano
parent 9c307e8afd
commit 3248486920
  1. 60
      Documentation/config/core.txt
  2. 75
      Documentation/git-fsmonitor--daemon.txt
  3. 8
      Documentation/git-update-index.txt

@ -62,22 +62,54 @@ core.protectNTFS::
Defaults to `true` on Windows, and `false` elsewhere.
core.fsmonitor::
If set, the value of this variable is used as a command which
will identify all files that may have changed since the
requested date/time. This information is used to speed up git by
avoiding unnecessary processing of files that have not changed.
See the "fsmonitor-watchman" section of linkgit:githooks[5].
If set to true, enable the built-in file system monitor
daemon for this working directory (linkgit:git-fsmonitor--daemon[1]).
+
Like hook-based file system monitors, the built-in file system monitor
can speed up Git commands that need to refresh the Git index
(e.g. `git status`) in a working directory with many files. The
built-in monitor eliminates the need to install and maintain an
external third-party tool.
+
The built-in file system monitor is currently available only on a
limited set of supported platforms. Currently, this includes Windows
and MacOS.
+
Otherwise, this variable contains the pathname of the "fsmonitor"
hook command.
+
This hook command is used to identify all files that may have changed
since the requested date/time. This information is used to speed up
git by avoiding unnecessary scanning of files that have not changed.
+
See the "fsmonitor-watchman" section of linkgit:githooks[5].
+
Note that if you concurrently use multiple versions of Git, such
as one version on the command line and another version in an IDE
tool, that the definition of `core.fsmonitor` was extended to
allow boolean values in addition to hook pathnames. Git versions
2.35.1 and prior will not understand the boolean values and will
consider the "true" or "false" values as hook pathnames to be
invoked. Git versions 2.26 thru 2.35.1 default to hook protocol
V2 and will fall back to no fsmonitor (full scan). Git versions
prior to 2.26 default to hook protocol V1 and will silently
assume there were no changes to report (no scan), so status
commands may report incomplete results. For this reason, it is
best to upgrade all of your Git versions before using the built-in
file system monitor.
core.fsmonitorHookVersion::
Sets the version of hook that is to be used when calling fsmonitor.
There are currently versions 1 and 2. When this is not set,
version 2 will be tried first and if it fails then version 1
will be tried. Version 1 uses a timestamp as input to determine
which files have changes since that time but some monitors
like watchman have race conditions when used with a timestamp.
Version 2 uses an opaque string so that the monitor can return
something that can be used to determine what files have changed
without race conditions.
Sets the protocol version to be used when invoking the
"fsmonitor" hook.
+
There are currently versions 1 and 2. When this is not set,
version 2 will be tried first and if it fails then version 1
will be tried. Version 1 uses a timestamp as input to determine
which files have changes since that time but some monitors
like Watchman have race conditions when used with a timestamp.
Version 2 uses an opaque string so that the monitor can return
something that can be used to determine what files have changed
without race conditions.
core.trustctime::
If false, the ctime differences between the index and the

@ -0,0 +1,75 @@
git-fsmonitor--daemon(1)
========================
NAME
----
git-fsmonitor--daemon - A Built-in File System Monitor
SYNOPSIS
--------
[verse]
'git fsmonitor--daemon' start
'git fsmonitor--daemon' run
'git fsmonitor--daemon' stop
'git fsmonitor--daemon' status
DESCRIPTION
-----------
A daemon to watch the working directory for file and directory
changes using platform-specific file system 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 file system 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.
GIT
---
Part of the linkgit:git[1] suite

@ -498,7 +498,9 @@ FILE SYSTEM MONITOR
This feature is intended to speed up git operations for repos that have
large working directories.
It enables git to work together with a file system monitor (see the
It enables git to work together with a file system monitor (see
linkgit:git-fsmonitor--daemon[1]
and the
"fsmonitor-watchman" section of linkgit:githooks[5]) that can
inform it as to what files have been modified. This enables git to avoid
having to lstat() every file to find modified files.
@ -509,8 +511,8 @@ looking for new files.
If you want to enable (or disable) this feature, it is easier to use
the `core.fsmonitor` configuration variable (see
linkgit:git-config[1]) than using the `--fsmonitor` option to
`git update-index` in each repository, especially if you want to do so
linkgit:git-config[1]) than using the `--fsmonitor` option to `git
update-index` in each repository, especially if you want to do so
across all repositories you use, because you can set the configuration
variable in your `$HOME/.gitconfig` just once and have it affect all
repositories you touch.

Loading…
Cancel
Save