Skip to content

Commit 3248486

Browse files
jeffhostetlergitster
jeffhostetler
authored and
gitster
committed
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>
1 parent 9c307e8 commit 3248486

File tree

3 files changed

+126
-17
lines changed

3 files changed

+126
-17
lines changed

‎Documentation/config/core.txt‎

Lines changed: 46 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -62,22 +62,54 @@ core.protectNTFS::
6262
Defaults to `true` on Windows, and `false` elsewhere.
6363

6464
core.fsmonitor::
65-
If set, the value of this variable is used as a command which
66-
will identify all files that may have changed since the
67-
requested date/time. This information is used to speed up git by
68-
avoiding unnecessary processing of files that have not changed.
69-
See the "fsmonitor-watchman" section of linkgit:githooks[5].
65+
If set to true, enable the built-in file system monitor
66+
daemon for this working directory (linkgit:git-fsmonitor--daemon[1]).
67+
+
68+
Like hook-based file system monitors, the built-in file system monitor
69+
can speed up Git commands that need to refresh the Git index
70+
(e.g. `git status`) in a working directory with many files. The
71+
built-in monitor eliminates the need to install and maintain an
72+
external third-party tool.
73+
+
74+
The built-in file system monitor is currently available only on a
75+
limited set of supported platforms. Currently, this includes Windows
76+
and MacOS.
77+
+
78+
Otherwise, this variable contains the pathname of the "fsmonitor"
79+
hook command.
80+
+
81+
This hook command is used to identify all files that may have changed
82+
since the requested date/time. This information is used to speed up
83+
git by avoiding unnecessary scanning of files that have not changed.
84+
+
85+
See the "fsmonitor-watchman" section of linkgit:githooks[5].
86+
+
87+
Note that if you concurrently use multiple versions of Git, such
88+
as one version on the command line and another version in an IDE
89+
tool, that the definition of `core.fsmonitor` was extended to
90+
allow boolean values in addition to hook pathnames. Git versions
91+
2.35.1 and prior will not understand the boolean values and will
92+
consider the "true" or "false" values as hook pathnames to be
93+
invoked. Git versions 2.26 thru 2.35.1 default to hook protocol
94+
V2 and will fall back to no fsmonitor (full scan). Git versions
95+
prior to 2.26 default to hook protocol V1 and will silently
96+
assume there were no changes to report (no scan), so status
97+
commands may report incomplete results. For this reason, it is
98+
best to upgrade all of your Git versions before using the built-in
99+
file system monitor.
70100

71101
core.fsmonitorHookVersion::
72-
Sets the version of hook that is to be used when calling fsmonitor.
73-
There are currently versions 1 and 2. When this is not set,
74-
version 2 will be tried first and if it fails then version 1
75-
will be tried. Version 1 uses a timestamp as input to determine
76-
which files have changes since that time but some monitors
77-
like watchman have race conditions when used with a timestamp.
78-
Version 2 uses an opaque string so that the monitor can return
79-
something that can be used to determine what files have changed
80-
without race conditions.
102+
Sets the protocol version to be used when invoking the
103+
"fsmonitor" hook.
104+
+
105+
There are currently versions 1 and 2. When this is not set,
106+
version 2 will be tried first and if it fails then version 1
107+
will be tried. Version 1 uses a timestamp as input to determine
108+
which files have changes since that time but some monitors
109+
like Watchman have race conditions when used with a timestamp.
110+
Version 2 uses an opaque string so that the monitor can return
111+
something that can be used to determine what files have changed
112+
without race conditions.
81113

82114
core.trustctime::
83115
If false, the ctime differences between the index and the

‎Documentation/git-fsmonitor--daemon.txt‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
git-fsmonitor--daemon(1)
2+
========================
3+
4+
NAME
5+
----
6+
git-fsmonitor--daemon - A Built-in File System Monitor
7+
8+
SYNOPSIS
9+
--------
10+
[verse]
11+
'git fsmonitor--daemon' start
12+
'git fsmonitor--daemon' run
13+
'git fsmonitor--daemon' stop
14+
'git fsmonitor--daemon' status
15+
16+
DESCRIPTION
17+
-----------
18+
19+
A daemon to watch the working directory for file and directory
20+
changes using platform-specific file system notification facilities.
21+
22+
This daemon communicates directly with commands like `git status`
23+
using the link:technical/api-simple-ipc.html[simple IPC] interface
24+
instead of the slower linkgit:githooks[5] interface.
25+
26+
This daemon is built into Git so that no third-party tools are
27+
required.
28+
29+
OPTIONS
30+
-------
31+
32+
start::
33+
Starts a daemon in the background.
34+
35+
run::
36+
Runs a daemon in the foreground.
37+
38+
stop::
39+
Stops the daemon running in the current working
40+
directory, if present.
41+
42+
status::
43+
Exits with zero status if a daemon is watching the
44+
current working directory.
45+
46+
REMARKS
47+
-------
48+
49+
This daemon is a long running process used to watch a single working
50+
directory and maintain a list of the recently changed files and
51+
directories. Performance of commands such as `git status` can be
52+
increased if they just ask for a summary of changes to the working
53+
directory and can avoid scanning the disk.
54+
55+
When `core.fsmonitor` is set to `true` (see linkgit:git-config[1])
56+
commands, such as `git status`, will ask the daemon for changes and
57+
automatically start it (if necessary).
58+
59+
For more information see the "File System Monitor" section in
60+
linkgit:git-update-index[1].
61+
62+
CAVEATS
63+
-------
64+
65+
The fsmonitor daemon does not currently know about submodules and does
66+
not know to filter out file system events that happen within a
67+
submodule. If fsmonitor daemon is watching a super repo and a file is
68+
modified within the working directory of a submodule, it will report
69+
the change (as happening against the super repo). However, the client
70+
will properly ignore these extra events, so performance may be affected
71+
but it will not cause an incorrect result.
72+
73+
GIT
74+
---
75+
Part of the linkgit:git[1] suite

‎Documentation/git-update-index.txt‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -498,7 +498,9 @@ FILE SYSTEM MONITOR
498498
This feature is intended to speed up git operations for repos that have
499499
large working directories.
500500

501-
It enables git to work together with a file system monitor (see the
501+
It enables git to work together with a file system monitor (see
502+
linkgit:git-fsmonitor--daemon[1]
503+
and the
502504
"fsmonitor-watchman" section of linkgit:githooks[5]) that can
503505
inform it as to what files have been modified. This enables git to avoid
504506
having to lstat() every file to find modified files.
@@ -509,8 +511,8 @@ looking for new files.
509511

510512
If you want to enable (or disable) this feature, it is easier to use
511513
the `core.fsmonitor` configuration variable (see
512-
linkgit:git-config[1]) than using the `--fsmonitor` option to
513-
`git update-index` in each repository, especially if you want to do so
514+
linkgit:git-config[1]) than using the `--fsmonitor` option to `git
515+
update-index` in each repository, especially if you want to do so
514516
across all repositories you use, because you can set the configuration
515517
variable in your `$HOME/.gitconfig` just once and have it affect all
516518
repositories you touch.

0 commit comments

Comments
 (0)