On 19 September 2017 at 21:27, Ben Peart <benpeart@xxxxxxxxxxxxx> 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
