Re: [PATCH v12 6/6] fsmonitor: add documentation for allowRemote and socketDir options

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Sat, Sep 24 2022, Eric DeCosta via GitGitGadget wrote:

> From: Eric DeCosta <edecosta@mathworks.com>
>
> Add documentation for 'fsmonitor.allowRemote' and 'fsmonitor.socketDir'.
> Call-out experimental nature of 'fsmonitor.allowRemote' and limited file
> system support for 'fsmonitor.socketDir'.
>
> Signed-off-by: Eric DeCosta <edecosta@mathworks.com>
> ---
>  Documentation/git-fsmonitor--daemon.txt | 48 +++++++++++++++++++++++--
>  1 file changed, 45 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-fsmonitor--daemon.txt b/Documentation/git-fsmonitor--daemon.txt
> index cc142fb8612..6ad3e518ae0 100644
> --- a/Documentation/git-fsmonitor--daemon.txt
> +++ b/Documentation/git-fsmonitor--daemon.txt
> @@ -3,7 +3,7 @@ git-fsmonitor{litdd}daemon(1)
>  
>  NAME
>  ----
> -git-fsmonitor--daemon - A Built-in File System Monitor
> +git-fsmonitor--daemon - A Built-in Filesystem Monitor

We have ~400 uses of "filesystem" in-tree, but ~100 for "file system". I
don't mind the change per-se, but this looks like an odd "while at it"
change.

Skmming your series your 1/6 even uses "file system" in the commit message :)

>  A daemon to watch the working directory for file and directory
> -changes using platform-specific file system notification facilities.
> +changes using platform-specific filesystem notification facilities.

More while-at-it...

>  
>  This daemon communicates directly with commands like `git status`
>  using the link:technical/api-simple-ipc.html[simple IPC] interface
> @@ -63,13 +63,55 @@ CAVEATS
>  -------
>  
>  The fsmonitor daemon does not currently know about submodules and does
> -not know to filter out file system events that happen within a
> +not know to filter out filesystem events that happen within a

...and here...

>  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.

But here we get to the real meat of this change...

> +By default, the fsmonitor daemon refuses to work against network-mounted
> +repositories; this may be overridden by setting `fsmonitor.allowRemote` to
> +`true`. Note, however, that the fsmonitor daemon is not guaranteed to work
> +correctly with all network-mounted repositories and such use is considered
> +experimental.
> +
> +On Mac OS, the inter-process communication (IPC) between various Git
> +commands and the fsmonitor daemon is done via a Unix domain socket (UDS) -- a
> +special type of file -- which is supported by native Mac OS filesystems,
> +but not on network-mounted filesystems, NTFS, or FAT32.  Other filesystems
> +may or may not have the needed support; the fsmonitor daemon is not guaranteed
> +to work with these filesystems and such use is considered experimental.
> +
> +By default, the socket is created in the `.git` directory, however, if the
> +`.git` directory is on a network-mounted filesystem, it will be instead be
> +created at `$HOME/.git-fsmonitor-*` unless `$HOME` itself is on a
> +network-mounted filesystem in which case you must set the configuration
> +variable `fsmonitor.socketDir` to the path of a directory on a Mac OS native
> +filesystem in which to create the socket file.
> +
> +If none of the above directories (`.git`, `$HOME`, or `fsmonitor.socketDir`)
> +is on a native Mac OS file filesystem the fsmonitor daemon will report an
> +error that will cause the daemon and the currently running command to exit.

From skimming this looks reasonable.

> +CONFIGURATION
> +-------------
> +
> +When `core.fsmonitor` is set to `true` (see linkgit:git-config[1])
> +the fsmonitor daemon will pay attention to the following configuration
> +variables:
> +
> +`fsmonitor.allowRemote`::
> +	By default, the daemon refuses to work against network-mounted
> +	repositories. Setting `fsmonitor.allowRemote` to `true` overrides
> +	this behavior.
> +
> +`fsmonitor.socketDir`::
> +    This Mac OS-specific option, if set, specifies the directory in
> +    which to create the Unix domain socket used for communication
> +    between fsmonitor and various Git commands. The directory must
> +    reside on a native Mac OS filesystem as discussed above.
> +

But here we should instead create Documentation/config/fsmonitor.txt,
and include it here. See my recent 7a54d740451 (Merge branch
'ab/dedup-config-and-command-docs', 2022-09-14) which made it so for
many commands.

By doing it like this "git config" is no longer the canonical reference
for all config, which it mostly was pre-7a54d740451, then was again
post-7a54d740451, and now we'd have this exception...