| Message ID | b375b0ac798a673301a09903dcdfb22bedda7393.1664048782.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 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...
On Mon, Sep 26, 2022 at 11:15 AM Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote: > On Sat, Sep 24 2022, Eric DeCosta via GitGitGadget 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> > > --- > > -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. > > > 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... These changes may have been in response to my review[1], though I did say that such a change was outside the scope of this series. Perhaps I need to choose my wording more carefully? [1]: https://lore.kernel.org/git/CAPig+cQ5SMw+0Cwtw47LQM59-mQjJaOPe_LTybAC2j=3F9OywA@mail.gmail.com/
> -----Original Message----- > From: Eric Sunshine <sunshine@sunshineco.com> > Sent: Monday, September 26, 2022 10:16 PM > To: Ævar Arnfjörð Bjarmason <avarab@gmail.com> > Cc: Eric DeCosta via GitGitGadget <gitgitgadget@gmail.com>; Git List > <git@vger.kernel.org>; Jeff Hostetler <git@jeffhostetler.com>; Torsten > Bögershausen <tboegi@web.de>; Ramsay Jones > <ramsay@ramsayjones.plus.com>; Johannes Schindelin > <Johannes.Schindelin@gmx.de>; Eric DeCosta <edecosta@mathworks.com> > Subject: Re: [PATCH v12 6/6] fsmonitor: add documentation for allowRemote > and socketDir options > > On Mon, Sep 26, 2022 at 11:15 AM Ævar Arnfjörð Bjarmason > <avarab@gmail.com> wrote: > > On Sat, Sep 24 2022, Eric DeCosta via GitGitGadget 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> > > > --- > > > -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. > > > > > 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... > > These changes may have been in response to my review[1], though I did say > that such a change was outside the scope of this series. Perhaps I need to > choose my wording more carefully? > > [1]: https://lore.kernel.org/git/CAPig+cQ5SMw+0Cwtw47LQM59- > mQjJaOPe_LTybAC2j=3F9OywA@mail.gmail.com/ <https://protect- > us.mimecast.com/s/STwOCG6A7DIYgAqYc7Wdth?domain=lore.kernel.org> > Your wording was fine. Next time I'll know better and leave it for another patch set. -Eric
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 SYNOPSIS -------- @@ -17,7 +17,7 @@ DESCRIPTION ----------- 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. 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 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. +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. + +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. + GIT --- Part of the linkgit:git[1] suite