Merge pull request #3234 from dscho/fsmonitor-v2

Replace the FSMonitor v1 patches with v2

Author: dscho

Documentation/config/core.txt

@@ -62,47 +62,50 @@ 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.
+	If set, 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: FSMonitor hooks (and this config setting) are ignored if the
-built-in FSMonitor is enabled (see `core.useBuiltinFSMonitor`).
+Note: The value of this config setting is ignored if the (experimental)
+built-in file system monitor is enabled (see `core.useBuiltinFSMonitor`).
 
 core.fsmonitorHookVersion::
-	Sets the version of hook that is to be used when calling the
-	FSMonitor hook (as configured via `core.fsmonitor`).
+	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.
+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.
 +
-Note: FSMonitor hooks (and this config setting) are ignored if the
-built-in FSMonitor is enabled (see `core.useBuiltinFSMonitor`).
+Note: The value of this config setting is ignored if the
+built-in file system monitor is enabled (see `core.useBuiltinFSMonitor`).
 
 core.useBuiltinFSMonitor::
-	If set to true, enable the built-in filesystem event watcher (for
-	technical details, see linkgit:git-fsmonitor--daemon[1]).
+	(EXPERIMENTAL) If set to true, enable the built-in file system monitor
+	daemon for this working directory (linkgit:git-fsmonitor--daemon[1]).
 +
-Like external (hook-based) FSMonitors, the built-in FSMonitor can speed up
-Git commands that need to refresh the Git index (e.g. `git status`) in a
-worktree with many files. The built-in FSMonitor facility eliminates the
-need to install and maintain an external third-party monitoring tool.
+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 FSMonitor is currently available only on a limited set of
-supported platforms.
+The built-in file system monitor is currently available only on a
+limited set of supported platforms.  Currently, this includes Windows
+and MacOS.
 +
-Note: if this config setting is set to `true`, any FSMonitor hook
-configured via `core.fsmonitor` (and possibly `core.fsmonitorHookVersion`)
-is ignored.
+Note: if this config setting is set to `true`, the values of
+`core.fsmonitor` and `core.fsmonitorHookVersion` are ignored.
 
 core.trustctime::
 	If false, the ctime differences between the index and the

Documentation/git-fsmonitor--daemon.txt

@@ -3,87 +3,61 @@ git-fsmonitor--daemon(1)
 
 NAME
 ----
-git-fsmonitor--daemon - Builtin file system monitor daemon
+git-fsmonitor--daemon - (EXPERIMENTAL) A Built-in File System Monitor
 
 SYNOPSIS
 --------
 [verse]
-'git fsmonitor--daemon' --start
-'git fsmonitor--daemon' --run
-'git fsmonitor--daemon' --stop
-'git fsmonitor--daemon' --is-running
-'git fsmonitor--daemon' --is-supported
-'git fsmonitor--daemon' --query <token>
-'git fsmonitor--daemon' --query-index
-'git fsmonitor--daemon' --flush
+'git fsmonitor--daemon' start
+'git fsmonitor--daemon' run
+'git fsmonitor--daemon' stop
+'git fsmonitor--daemon' status
 
 DESCRIPTION
 -----------
 
-Monitors files and directories in the working directory for changes using
-platform-specific file system notification facilities.
+NOTE! This command is still only an experiment, subject to change dramatically
+(or even to be abandoned).
 
-It 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.
+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 the fsmonitor daemon in the background.
+start::
+	Starts a daemon in the background.
 
---run::
-	Runs the fsmonitor daemon in the foreground.
+run::
+	Runs a daemon in the foreground.
 
---stop::
-	Stops the fsmonitor daemon running for the current working
+stop::
+	Stops the daemon running in the current working
 	directory, if present.
 
---is-running::
-	Exits with zero status if the fsmonitor daemon is watching the
+status::
+	Exits with zero status if a daemon is watching the
 	current working directory.
 
---is-supported::
-	Exits with zero status if the fsmonitor daemon feature is supported
-	on this platform.
-
---query <token>::
-	Connects to the fsmonitor daemon (starting it if necessary) and
-	requests the list of changed files and directories since the
-	given token.
-	This is intended for testing purposes.
-
---query-index::
-	Read the current `<token>` from the File System Monitor index
-	extension (if present) and use it to query the fsmonitor daemon.
-	This is intended for testing purposes.
-
---flush::
-	Force the fsmonitor daemon to flush its in-memory cache and
-	re-sync with the file system.
-	This is intended for testing purposes.
-
 REMARKS
 -------
-The fsmonitor daemon is a long running process that will watch a single
-working directory.  Commands, such as `git status`, should automatically
-start it (if necessary) when `core.useBuiltinFSMonitor` is set to `true`
-(see linkgit:git-config[1]).
-
-Configure the built-in FSMonitor via `core.useBuiltinFSMonitor` in each
-working directory separately, or globally via `git config --global
-core.useBuiltinFSMonitor true`.
 
-Tokens are opaque strings.  They are used by the fsmonitor daemon to
-mark a point in time and the associated internal state.  Callers should
-make no assumptions about the content of the token.  In particular,
-the should not assume that it is a timestamp.
+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.
 
-Query commands send a request-token to the daemon and it responds with
-a summary of the changes that have occurred since that token was
-created.  The daemon also returns a response-token that the client can
-use in a future query.
+When `core.useBuiltinFSMonitor` 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].
@@ -96,8 +70,8 @@ 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
-should properly ignore these extra events, so performance may be affected
-but it should not cause an incorrect result.
+will properly ignore these extra events, so performance may be affected
+but it will not cause an incorrect result.
 
 GIT
 ---

Documentation/git-update-index.txt

@@ -510,17 +510,18 @@ performance by avoiding the cost of scanning the entire working directory
 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
-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.
-
-When the `core.fsmonitor` configuration variable is changed, the
-file system monitor is added to or removed from the index the next time
-a command reads the index. When `--[no-]fsmonitor` are used, the file
-system monitor is immediately added to or removed from the index.
+the `core.fsmonitor` or `core.useBuiltinFSMonitor` 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 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.
+
+When the `core.fsmonitor` or `core.useBuiltinFSMonitor` configuration
+variable is changed, the file system monitor is added to or removed
+from the index the next time a command reads the index. When
+`--[no-]fsmonitor` are used, the file system monitor is immediately
+added to or removed from the index.
 
 CONFIGURATION
 -------------

Makefile

@@ -467,8 +467,8 @@ all::
 # directory, and the JSON compilation database 'compile_commands.json' will be
 # created at the root of the repository.
 #
-# If your platform supports an built-in fsmonitor backend, set
-# FSMONITOR_DAEMON_BACKEND to the name of the corresponding
+# If your platform supports a built-in fsmonitor backend, set
+# FSMONITOR_DAEMON_BACKEND to the "<name>" of the corresponding
 # `compat/fsmonitor/fsmonitor-fs-listen-<name>.c` that implements the
 # `fsmonitor_fs_listen__*()` routines.
 #
@@ -715,6 +715,7 @@ TEST_BUILTINS_OBJS += test-dump-split-index.o
 TEST_BUILTINS_OBJS += test-dump-untracked-cache.o
 TEST_BUILTINS_OBJS += test-example-decorate.o
 TEST_BUILTINS_OBJS += test-fast-rebase.o
+TEST_BUILTINS_OBJS += test-fsmonitor-client.o
 TEST_BUILTINS_OBJS += test-genrandom.o
 TEST_BUILTINS_OBJS += test-genzeros.o
 TEST_BUILTINS_OBJS += test-hash-speed.o