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>
Jeff Hostetler committed
Mar 25, 2022 at 18:02 UTC
3248486920d0bfc5584747dc7af8414d05282191
3 files changed
+126
-17
Documentation/config/core.txt
+46
-14
@@ -62,22 +62,54 @@ core.protectNTFS::
62
Defaults to `true` on Windows, and `false` elsewhere.
63
64
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.
100
101
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.
113
114
core.trustctime::
115
If false, the ctime differences between the index and the
Documentation/git-fsmonitor--daemon.txt
new
+75
@@ -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
+5
-3
@@ -498,7 +498,9 @@ FILE SYSTEM MONITOR
498
This feature is intended to speed up git operations for repos that have
499
large working directories.
500
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
504
"fsmonitor-watchman" section of linkgit:githooks[5]) that can
505
inform it as to what files have been modified. This enables git to avoid
506
having to lstat() every file to find modified files.
@@ -509,8 +511,8 @@ looking for new files.
511
512
If you want to enable (or disable) this feature, it is easier to use
513
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
516
across all repositories you use, because you can set the configuration
517
variable in your `$HOME/.gitconfig` just once and have it affect all
518
repositories you touch.