| Message ID | ddf4e3e6442b104447154b0a5d4954f274f4b5ef.1663377141.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | fsmonitor: option to allow fsmonitor to run against network-mounted repos | expand |
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.
> -----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. The way you've re-written things is so much clearer! Much appreciated. -Eric
diff --git a/Documentation/git-fsmonitor--daemon.txt b/Documentation/git-fsmonitor--daemon.txt index cc142fb8612..0adccd0eced 100644 --- 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 will properly ignore these extra events, so performance may be affected but it will not cause an incorrect result. +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. + +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 +is on a network-mounted file system, it will create the UDS file in $HOME. If +$HOME itself is on a network-mounted file system or if $HOME is not the desired +location for the UDS file, 'fsmonitor.socketDir' may be set to any valid, local +directory on a file system with proper support. Mac OS native file systems have +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 +daemon is not guaranteed to work with these file systems and such use is +considered experimental. + +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 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). + GIT --- Part of the linkgit:git[1] suite