On Sat, Sep 24 2022, Eric DeCosta via GitGitGadget wrote:
> From: Eric DeCosta <edecosta@xxxxxxxxxxxxx>
>
> 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@xxxxxxxxxxxxx>
> ---
> 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...
