Subject: Re: [PATCH v3 02/34] fsmonitor--daemon: man page

From: Ævar Arnfjörð Bjarmason <[email-masked]>
Date: Fri, 02 Jul 2021 00:29:02 +0200

On Thu, Jul 01 2021, Jeff Hostetler via GitGitGadget wrote:

> From: Jeff Hostetler <[email-masked]>
>
> Create a manual page describing the `git fsmonitor--daemon` feature.
>
> Signed-off-by: Jeff Hostetler <[email-masked]>
> ---
>  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.

See the outstanding ab/config-based-hooks-base for a small example of
that.