status: modernize git-status "slow untracked files" advice

[thirdparty/git.git] / Documentation / git-status.txt

diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 5e438a7fdc1ca4e8684c52c3773a6f722b26c287..a051b1e8f383abc618397ea7e2ac2f173d30a111 100644 (file)
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -457,6 +457,66 @@ during the write may conflict with other simultaneous processes, causing
 them to fail. Scripts running `status` in the background should consider
 using `git --no-optional-locks status` (see linkgit:git[1] for details).
 
+UNTRACKED FILES AND PERFORMANCE
+-------------------------------
+
+`git status` can be very slow in large worktrees if/when it
+needs to search for untracked files and directories. There are
+many configuration options available to speed this up by either
+avoiding the work or making use of cached results from previous
+Git commands. There is no single optimum set of settings right
+for everyone. We'll list a summary of the relevant options to help
+you, but before going into the list, you may want to run `git status`
+again, because your configuration may already be caching `git status`
+results, so it could be faster on subsequent runs.
+
+* The `--untracked-files=no` flag or the
+       `status.showUntrackedfiles=false` config (see above for both):
+       indicate that `git status` should not report untracked
+       files. This is the fastest option. `git status` will not list
+       the untracked files, so you need to be careful to remember if
+       you create any new files and manually `git add` them.
+
+* `advice.statusUoption=false` (see linkgit:git-config[1]):
+       setting this variable to `false` disables the warning message
+       given when enumerating untracked files takes more than 2
+       seconds.  In a large project, it may take longer and the user
+       may have already accepted the trade off (e.g. using "-uno" may
+       not be an acceptable option for the user), in which case, there
+       is no point issuing the warning message, and in such a case,
+       disabling the warning may be the best.
+
+* `core.untrackedCache=true` (see linkgit:git-update-index[1]):
+       enable the untracked cache feature and only search directories
+       that have been modified since the previous `git status` command.
+       Git remembers the set of untracked files within each directory
+       and assumes that if a directory has not been modified, then
+       the set of untracked files within has not changed.  This is much
+       faster than enumerating the contents of every directory, but still
+       not without cost, because Git still has to search for the set of
+       modified directories. The untracked cache is stored in the
+       `.git/index` file. The reduced cost of searching for untracked
+       files is offset slightly by the increased size of the index and
+       the cost of keeping it up-to-date. That reduced search time is
+       usually worth the additional size.
+
+* `core.untrackedCache=true` and `core.fsmonitor=true` or
+       `core.fsmonitor=<hook_command_pathname>` (see
+       linkgit:git-update-index[1]): enable both the untracked cache
+       and FSMonitor features and only search directories that have
+       been modified since the previous `git status` command.  This
+       is faster than using just the untracked cache alone because
+       Git can also avoid searching for modified directories.  Git
+       only has to enumerate the exact set of directories that have
+       changed recently. While the FSMonitor feature can be enabled
+       without the untracked cache, the benefits are greatly reduced
+       in that case.
+
+Note that after you turn on the untracked cache and/or FSMonitor
+features it may take a few `git status` commands for the various
+caches to warm up before you see improved command times.  This is
+normal.
+
 SEE ALSO
 --------
 linkgit:gitignore[5]