Subject: Re: [PATCH v3 03/34] fsmonitor--daemon: update fsmonitor documentation

From: Ævar Arnfjörð Bjarmason <[email-masked]>
Date: Fri, 02 Jul 2021 00:31:57 +0200

On Thu, Jul 01 2021, Jeff Hostetler via GitGitGadget wrote:

> From: Jeff Hostetler <[email-masked]>
>
> Update references to `core.fsmonitor` and `core.fsmonitorHookVersion` and
> pointers to `Watchman` to mention the new built-in `fsmonitor--daemon`.
>
> Signed-off-by: Jeff Hostetler <[email-masked]>
> ---
>  Documentation/config/core.txt      | 56 ++++++++++++++++++++++--------
>  Documentation/git-update-index.txt | 27 +++++++-------
>  Documentation/githooks.txt         |  3 +-
>  3 files changed, 59 insertions(+), 27 deletions(-)
>
> diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt
> index c04f62a54a1..4f6e519bc02 100644
> --- a/Documentation/config/core.txt
> +++ b/Documentation/config/core.txt
> @@ -62,22 +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.
> -	See the "fsmonitor-watchman" section of linkgit:githooks[5].
> +	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: The value of this config setting is ignored if the
> +built-in file system monitor is enabled (see `core.useBuiltinFSMonitor`).
>  
>  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.
> ++
> +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 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.
> ++
> +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
> diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
> index 2853f168d97..c7c31b3fcf9 100644
> --- a/Documentation/git-update-index.txt
> +++ b/Documentation/git-update-index.txt
> @@ -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.
> @@ -508,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
>  -------------
> diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
> index b51959ff941..b7d5e926f7b 100644
> --- a/Documentation/githooks.txt
> +++ b/Documentation/githooks.txt
> @@ -593,7 +593,8 @@ fsmonitor-watchman
>  
>  This hook is invoked when the configuration option `core.fsmonitor` is
>  set to `.git/hooks/fsmonitor-watchman` or `.git/hooks/fsmonitor-watchmanv2`
> -depending on the version of the hook to use.
> +depending on the version of the hook to use, unless overridden via
> +`core.useBuiltinFSMonitor` (see linkgit:git-config[1]).
>  
>  Version 1 takes two arguments, a version (1) and the time in elapsed
>  nanoseconds since midnight, January 1, 1970.

Ditto the comment on 02/34, mostly docs for things that don't exist
until in later patches.