config: add core.untrackedCache

[thirdparty/git.git] / Documentation / git-update-index.txt

diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index a0afe17450fabb4dccf60f033301eced64c13d7c..c6cbed189ceddd294361502b861f37c29a8adbf1 100644 (file)
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -174,27 +174,30 @@ may not support it yet.
 
 --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 `--force-untracked-cache` (or
-       `--untracked-cache` but this will run the tests again)
-       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.
+       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.
@@ -385,6 +388,37 @@ Although this bit looks similar to assume-unchanged bit, its goal is
 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
 -------------
@@ -410,6 +444,9 @@ It can be useful when the inode change time is regularly modified by
 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
 --------