> -----Original Message----- > From: Eric Sunshine <sunshine@xxxxxxxxxxxxxx> > Sent: Saturday, September 17, 2022 2:09 AM > To: Eric DeCosta via GitGitGadget <gitgitgadget@xxxxxxxxx> > Cc: Git List <git@xxxxxxxxxxxxxxx>; Jeff Hostetler <git@xxxxxxxxxxxxxxxxx>; > Torsten Bögershausen <tboegi@xxxxxx>; Ævar Arnfjörð Bjarmason > <avarab@xxxxxxxxx>; Ramsay Jones <ramsay@xxxxxxxxxxxxxxxxxxxx>; > Johannes Schindelin <Johannes.Schindelin@xxxxxx>; Eric DeCosta > <edecosta@xxxxxxxxxxxxx> > Subject: Re: [PATCH v8 5/5] fsmonitor: add documentation for allowRemote > and socketDir options > > On Fri, Sep 16, 2022 at 9:12 PM Eric DeCosta via GitGitGadget > <gitgitgadget@xxxxxxxxx> wrote: > > 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> > > --- > > diff --git a/Documentation/git-fsmonitor--daemon.txt > > b/Documentation/git-fsmonitor--daemon.txt > > @@ -70,6 +70,41 @@ the change (as happening against the super repo). > > However, the client > > +By default, the fsmonitor daemon refuses to work against > > +network-mounted repositories; this my be overridden by setting > > +`fsmonitor.allowRemote` to `true`. Note, however, that the fsmonitor > > +daemon is not guaranteed to work correctly with all network-mounted > > +repositores and such use is considered experimental. > > s/repositores/repositories/ > > > +On Mac OS, the inter-process communication (IPC) between various Git > > +commands and the fsmonitor daemon is done via a Unix domain socket > (UDS). > > +Usage of UDS requires the creation of a file which, by default, is > > +created in the .git directory. If the fsmonitor daemon detects that > > +the .git directory > > Typesetting: s/.git/`.git`/g > > > +is on a network-mounted file system, it will create the UDS file in > > +$HOME. If > > There's a gap in the explanation as to _why_ fsmonitor won't use the .git > directory for this file when on a network-mounted filesystem and instead > chooses $HOME. For the reader who is not well-versed in Unix > sockets/filesystems, it may be difficult to understand the logic behind this. > This gap is somewhat filled in a few sentences later, but it makes for > potentially confusing reading until then. > > Should the reader know the name of the socket file or at least the templated > form of the name? The first question which popped into my head upon > reading this was whether it was going to pollute my home directory with > non-hidden files. If this had mentioned something along the lines of > "creation of a file named `.git-fsmonitor-*`" or "creation of a hidden file" > then I would have understood immediately that the file would have been > hidden. > > > +$HOME itself is on a network-mounted file system or if $HOME is not > > +the desired > > To be consistent with formatting elsewhere in the Git documentation, let's > typeset this as `$HOME` (with backticks). > > Aside: The spelling "filesystem" appears almost five times as often as "file > system" in Git documentation, however, this particular file already uses "file > system" and does so consistently, so it makes sense to follow suit as you do > here. Changing to use "filesystem" instead, if such a task is desirable, is > outside the scope of this patch series. > > > +location for the UDS file, 'fsmonitor.socketDir' may be set to any > > +valid, local > > For consistency, let's use backticks here, as well: `fsmonitor.socketDir` > > > +directory on a file system with proper support. Mac OS native file > > +systems have > > Together with the above comment about a gap in the explanation, I found > myself scratching my head about what "proper support" meant (when > pretending to read this as a person not particularly familiar with Unix sockets > or filesystems). > > Also, although this explains how to work around the case when $HOME is > itself network-mounted, what happens if $HOME is network-mounted and > the user does not set `fsmonitor.socketDir`? Does it error out? Does it simply > misbehave in some way? Should it error out? (I would think > "yes".) > > > +the required support. File systems known to lack support include > > +FAT32 and NTFS. Other file systems may or many not have the needed > > +support; the fsmonitor > > s/many/may/ > > > +daemon is not guaranteed to work with these file systems and such use > > +is considered experimental. > > Taking the above comments into account, here's my attempt at a rewrite: > > On Mac OS, the inter-process communication (IPC) between various > Git commands and the fsmonitor daemon occurs via a Unix domain > socket (UDS) -- a special type of file -- which is supported by > the native Mac OS filesystems but not by network-mounted > filesystems, NTFS or FAT32. Other file systems may or many not > have the needed support; the fsmonitor daemon is not guaranteed to > work with these file systems 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 file > system, it will instead be created at `$HOME/.git-fsmonitor-*` > unless `$HOME` itself is on a network-mounted file system, 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. > > > +CONFIGURATION > > +------------- > > +When `core.fsmonitor` is set to `true` (see linkgit:git-config[1]) > > +the fsmonitor daemon will pay attention to the following > > +configuration > > +variables: > > We probably want a blank line after the header underline and before this > paragraph. > > > +fsmonitor.allowRemote:: > > + By default, the daemon refuses to work against network-mounted > > + repositories. Setting `fsmonitor.allowRemote` to `true` overrides > > + this behavior. > > + > > +fsmonitor.socketDir:: > > + This option is only used by the Mac OS implementation of the > fsmonitor > > + daemon. If set, 'fsmonitor.socketDir' must be set to a valid, local > > + directory on a file system that can support Unix domain sockets (UDS). > > Typeset with backticks: `fsmonitor.socketDir` > > The word "valid" seems unnecessary. A possible rewrite: > > 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. The way you've re-written things is so much clearer! Much appreciated. -Eric
