Show 147 quoted lines
> -----Original Message-----
> From: Eric Sunshine <sunshine@sunshineco.com>
> Sent: Saturday, September 17, 2022 2:09 AM
> To: Eric DeCosta via GitGitGadget <gitgitgadget@gmail.com>
> Cc: Git List <git@vger.kernel.org>; Jeff Hostetler <git@jeffhostetler.com>;
> Torsten Bögershausen <tboegi@web.de>; Ævar Arnfjörð Bjarmason
> <avarab@gmail.com>; Ramsay Jones <ramsay@ramsayjones.plus.com>;
> Johannes Schindelin <Johannes.Schindelin@gmx.de>; Eric DeCosta
> <edecosta@mathworks.com>
> 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@gmail.com> 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@mathworks.com>
> > ---
> > 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.
Eric DeCosta <edecosta@mathworks.com>