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

[Ben Peart <peartben@gmail.com>]

Thanks for the review.  I'm not an English major so appreciate the 
feedback on my attempts to document the feature.

On 9/20/2017 6:00 AM, Martin Ågren wrote:
> 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. 

I understand the unintuitive comment but the other such options in the 
code base are just above the fsmonitor options as it is modeled on how 
'assume-unchanged' and 'skip-worktree' work.  Consistency is certainly 
helps the intuitiveness as once you have learned the model, it applies 
in other places.

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.
> 

For better and for worse, I choose to be consistent with how the options 
work (especially the untracked-cache option immediately above).  This is 
one weakness of reviewing patches via email - you don't see the patch in 
context with everything around it.

>> +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/
> 

Thanks!

diff --git a/Documentation/git-update-index.txt 
b/Documentation/git-update-index.txt
index 95231dbfcb..7c2f880a22 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -476,7 +476,7 @@ inform it as to what files have been modified. This 
enables git to avoid
  having to lstat() every file to find modified files.

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

  If you want to enable (or disable) this feature, it is easier to use


>> +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.
> 

I'm going to sound like a broken record here. :) The description favored 
consistency with the untracked cache feature immediate above this entry. 
  It is literally a copy/paste/edit.

This is based on the assumption that the text had already been reviewed 
and found to be acceptable.  This also means if you have figured it out 
for one option, when you read the next, you're understanding can carry 
forward speeding up your comprehension.

> 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
>