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