git status: document trade-offs in choosing parameters to the -u option

In some repostories users experience that "git status" command takes
long time.  The command spends some time searching the file system
for untracked files.

Explain the trade-off struck by the default choice of `normal` to
help users make an appropriate choice better, before talking about
the configuration variable.

Inspired by Torsten Bögershausen.

Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 67e5f53a9ef00991954b6bf95286a418c7e4af23..00d59510123c8aa3747ec68cc2877072ed87e8e9 100644 (file)
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -43,15 +43,21 @@ OPTIONS
        Show untracked files.
 +
 The mode parameter is optional (defaults to 'all'), and is used to
        Show untracked files.
 +
 The mode parameter is optional (defaults to 'all'), and is used to

-specify the handling of untracked files; when -u is not used, the
-default is 'normal', i.e. show untracked files and directories.
+specify the handling of untracked files.

 +
 The possible options are:
 +
 +
 The possible options are:
 +

-       - 'no'     - Show no untracked files
-       - 'normal' - Shows untracked files and directories
+       - 'no'     - Show no untracked files.
+       - 'normal' - Shows untracked files and directories.

        - 'all'    - Also shows individual files in untracked directories.
 +
        - 'all'    - Also shows individual files in untracked directories.
 +

+When `-u` option is not used, untracked files and directories are
+shown (i.e. the same as specifying `normal`), to help you avoid
+forgetting to add newly created files.  Because it takes extra work
+to find untracked files in the filesystem, this mode may take some
+time in a large working tree.  You can use `no` to have `git status`
+return more quickly without showing untracked files.
++

 The default can be changed using the status.showUntrackedFiles
 configuration variable documented in linkgit:git-config[1].
 
 The default can be changed using the status.showUntrackedFiles
 configuration variable documented in linkgit:git-config[1].