[--[no-]skip-worktree]
[--ignore-submodules]
[--[no-]split-index]
- [--[no-|force-]untracked-cache]
+ [--[no-|test-|force-]untracked-cache]
[--really-refresh] [--unresolve] [--again | -g]
[--info-only] [--index-info]
[-z] [--stdin] [--index-version <n>]
--untracked-cache::
--no-untracked-cache::
- Enable or disable untracked cache extension. This could speed
- up for commands that involve determining untracked files such
- as `git status`. The underlying operating system and file
- system must change `st_mtime` field of a directory if files
- are added or deleted in that directory.
+ Enable or disable untracked cache feature. Please use
+ `--test-untracked-cache` before enabling it.
++
+These options take effect whatever the value of the `core.untrackedCache`
+configuration variable (see linkgit:git-config[1]). But a warning is
+emitted when the change goes against the configured value, as the
+configured value will take effect next time the index is read and this
+will remove the intended effect of the option.
+
+--test-untracked-cache::
+ Only perform tests on the working directory to make sure
+ untracked cache can be used. You have to manually enable
+ untracked cache using `--untracked-cache` or
+ `--force-untracked-cache` or the `core.untrackedCache`
+ configuration variable afterwards if you really want to use
+ it. If a test fails the exit code is 1 and a message
+ explains what is not working as needed, otherwise the exit
+ code is 0 and OK is printed.
--force-untracked-cache::
- For safety, `--untracked-cache` performs tests on the working
- directory to make sure untracked cache can be used. These
- tests can take a few seconds. `--force-untracked-cache` can be
- used to skip the tests.
+ Same as `--untracked-cache`. Provided for backwards
+ compatibility with older versions of Git where
+ `--untracked-cache` used to imply `--test-untracked-cache` but
+ this option would enable the extension unconditionally.
\--::
Do not interpret any more arguments as options.
different from assume-unchanged bit's. Skip-worktree also takes
precedence over assume-unchanged bit when both are set.
+Untracked cache
+---------------
+
+This cache is meant to speed up commands that involve determining
+untracked files such as `git status`.
+
+This feature works by recording the mtime of the working tree
+directories and then omitting reading directories and stat calls
+against files in those directories whose mtime hasn't changed. For
+this to work the underlying operating system and file system must
+change the `st_mtime` field of directories if files in the directory
+are added, modified or deleted.
+
+You can test whether the filesystem supports that with the
+`--test-untracked-cache` option. The `--untracked-cache` option used
+to implicitly perform that test in older versions of Git, but that's
+no longer the case.
+
+If you want to enable (or disable) this feature, it is easier to use
+the `core.untrackedCache` configuration variable (see
+linkgit:git-config[1]) than using the `--untracked-cache` 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.
+
+When the `core.untrackedCache` configuration variable is changed, the
+untracked cache is added to or removed from the index the next time a
+command reads the index; while when `--[no-|force-]untracked-cache`
+are used, the untracked cache is immediately added to or removed from
+the index.
Configuration
-------------
something outside Git (file system crawlers and backup systems use
ctime for marking files processed) (see linkgit:git-config[1]).
+The untracked cache extension can be enabled by the
+`core.untrackedCache` configuration variable (see
+linkgit:git-config[1]).
SEE ALSO
--------