Re: [PATCH v7 05/12] fsmonitor: add documentation for the fsmonitor extension.

From: "Martin Ågren" <martin.agren@gmail.com>
To: Ben Peart <benpeart@microsoft.com>
Cc: David.Turner@twosigma.com,
	"Ævar Arnfjörð Bjarmason" <avarab@gmail.com>,
	"Christian Couder" <christian.couder@gmail.com>,
	"Git Mailing List" <git@vger.kernel.org>,
	"Junio C Hamano" <gitster@pobox.com>,
	"Johannes Schindelin" <johannes.schindelin@gmx.de>,
	"Nguyễn Thái Ngọc Duy" <pclouds@gmail.com>,
	"Jeff King" <peff@peff.net>
Subject: Re: [PATCH v7 05/12] fsmonitor: add documentation for the fsmonitor extension.
Date: Wed, 20 Sep 2017 12:00:04 +0200	[thread overview]
Message-ID: <CAN0heSqFsm0BSUzufXjCKNv=JpRpUQzFA9GkKfA6nd_hPhW_qg@mail.gmail.com> (raw)
In-Reply-To: <20170919192744.19224-6-benpeart@microsoft.com>

On 19 September 2017 at 21:27, Ben Peart <benpeart@microsoft.com> wrote:
> diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
> index e19eba62cd..95231dbfcb 100644
> --- a/Documentation/git-update-index.txt
> +++ b/Documentation/git-update-index.txt
> @@ -16,9 +16,11 @@ SYNOPSIS
>              [--chmod=(+|-)x]
>              [--[no-]assume-unchanged]
>              [--[no-]skip-worktree]
> +            [--[no-]fsmonitor-valid]
>              [--ignore-submodules]
>              [--[no-]split-index]
>              [--[no-|test-|force-]untracked-cache]
> +            [--[no-]fsmonitor]
>              [--really-refresh] [--unresolve] [--again | -g]
>              [--info-only] [--index-info]
>              [-z] [--stdin] [--index-version <n>]
> @@ -111,6 +113,12 @@ you will need to handle the situation manually.
>         set and unset the "skip-worktree" bit for the paths. See
>         section "Skip-worktree bit" below for more information.
>
> +--[no-]fsmonitor-valid::
> +       When one of these flags is specified, the object name recorded
> +       for the paths are not updated. Instead, these options
> +       set and unset the "fsmonitor valid" bit for the paths. See
> +       section "File System Monitor" below for more information.
> +

So --no-foo does not undo --foo, but there are three values: --foo,
--no-foo and <nothing/default>. I find that unintuitive, but maybe it's
just me. Maybe there are other such options in the codebase already. How
about --fsmonitor-valid=set, --fsmonitor-valid=unset, and
--no-fsmonitor-valid (which would be the default, and which would forget
any earlier --fsmonitor-valid=...)?

>  -g::
>  --again::
>         Runs 'git update-index' itself on the paths whose index
> @@ -201,6 +209,15 @@ will remove the intended effect of the option.
>         `--untracked-cache` used to imply `--test-untracked-cache` but
>         this option would enable the extension unconditionally.
>
> +--fsmonitor::
> +--no-fsmonitor::

Maybe "--[no-]fsmonitor" for symmetry with how you've done it above and
later.

> +When used in conjunction with the untracked cache, it can further improve
> +performance by avoiding the cost of scaning the entire working directory
> +looking for new files.

s/scaning/scanning/

> +If you want to enable (or disable) this feature, it is easier to use
> +the `core.fsmonitor` configuration variable (see
> +linkgit:git-config[1]) than using the `--fsmonitor` option to
> +`git update-index` in each repository, especially if you want to do so
> +across all repositories you use, because you can set the configuration
> +variable to `true` (or `false`) in your `$HOME/.gitconfig` just once
> +and have it affect all repositories you touch.

This is a mouthful. Maybe you could split it a little, perhaps like so:

  If you want to enable (or disable) this feature, you will probably
  want to use the `core.fsmonitor` configuration variable (see
  linkgit:git-config[1]). By setting it to `true` (or `false`) in your
  `$HOME/.gitconfig`, it will affect all repositories you touch. For a
  more fine-grained control, you can set it per repository, or use the
  `--fsmonitor` option with `git update-index` in each repository.

The part about $HOME/.gitconfig vs per-repo config is perhaps generic
enough that it doesn't belong here. So it'd only be about config vs.
option. Where to place the config item and what implications that has is
arguably orthogonal to knowing that the option exists and what it does.

Martin