Hi Ævar,

On Fri, 2 Jul 2021, Ævar Arnfjörð Bjarmason wrote:

> On Thu, Jul 01 2021, Jeff Hostetler via GitGitGadget wrote:
>
> > From: Jeff Hostetler <jeffhost@microsoft.com>
> >
> > Create a manual page describing the `git fsmonitor--daemon` feature.
> >
> > Signed-off-by: Jeff Hostetler <jeffhost@microsoft.com>
> > ---
> >  Documentation/git-fsmonitor--daemon.txt | 75 +++++++++++++++++++++++++
> >  1 file changed, 75 insertions(+)
> >  create mode 100644 Documentation/git-fsmonitor--daemon.txt
> >
> > diff --git a/Documentation/git-fsmonitor--daemon.txt b/Documentation/git-fsmonitor--daemon.txt
> > new file mode 100644
> > index 00000000000..154e7684daa
> > --- /dev/null
> > +++ b/Documentation/git-fsmonitor--daemon.txt
> > @@ -0,0 +1,75 @@
> > +git-fsmonitor--daemon(1)
> > +========================
> > +
> > +NAME
> > +----
> > +git-fsmonitor--daemon - A Built-in File System Monitor
> > +
> > +SYNOPSIS
> > +--------
> > +[verse]
> > +'git fsmonitor--daemon' start
> > +'git fsmonitor--daemon' run
> > +'git fsmonitor--daemon' stop
> > +'git fsmonitor--daemon' status
> > +
> > +DESCRIPTION
> > +-----------
> > +
> > +A daemon to watch the working directory for file and directory
> > +changes using platform-specific file system notification facilities.
> > +
> > +This daemon communicates directly with commands like `git status`
> > +using the link:technical/api-simple-ipc.html[simple IPC] interface
> > +instead of the slower linkgit:githooks[5] interface.
> > +
> > +This daemon is built into Git so that no third-party tools are
> > +required.
> > +
> > +OPTIONS
> > +-------
> > +
> > +start::
> > +	Starts a daemon in the background.
> > +
> > +run::
> > +	Runs a daemon in the foreground.
> > +
> > +stop::
> > +	Stops the daemon running in the current working
> > +	directory, if present.
> > +
> > +status::
> > +	Exits with zero status if a daemon is watching the
> > +	current working directory.
> > +
> > +REMARKS
> > +-------
> > +
> > +This daemon is a long running process used to watch a single working
> > +directory and maintain a list of the recently changed files and
> > +directories.  Performance of commands such as `git status` can be
> > +increased if they just ask for a summary of changes to the working
> > +directory and can avoid scanning the disk.
> > +
> > +When `core.useBuiltinFSMonitor` is set to `true` (see
> > +linkgit:git-config[1]) commands, such as `git status`, will ask the
> > +daemon for changes and automatically start it (if necessary).
> > +
> > +For more information see the "File System Monitor" section in
> > +linkgit:git-update-index[1].
> > +
> > +CAVEATS
> > +-------
> > +
> > +The fsmonitor daemon does not currently know about submodules and does
> > +not know to filter out file system 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.
> > +
> > +GIT
> > +---
> > +Part of the linkgit:git[1] suite
>
> Later in the series we incrementally add features to the daemon, so this
> is describing a state that doesn't exist yet at this point.
>
> I think it would be better to start with a stup here and add
> documentation as we add features, e.g. the patch tha adds "start" should
> add that to the synopsis + options etc.

Incidentally, I had structured the patch series that way until Jeff took
over from me last year. And it was definitely not more reviewable because
it was not clear from the get-go what I intended this command to do.

Therefore, I object to your suggestion.

Ciao,
Johannes

P.S.: I will not address your other reviews in this patch series, mostly
because I am technically off from work this week.