Speed up Git's part in listing files in status buffer

In [1: 83d89ee5bb] we did speed up Magit's part in this task, but also
removed optimization used to speed up Git's part.  Bring those back.

Also respect all local values of `status.showUntrackedFiles' again.

Closes #5298.

1: 2025-01-27 83d89ee5bb1c488544bae60d52f7ee1987b6449e
   Speed up and simplify listing files in status buffer

1 files changed, 18 insertions, 6 deletions

diff --git a/docs/magit.org b/docs/magit.org
index f9752ea..f5c190b 100644
--- a/docs/magit.org
+++ b/docs/magit.org
@@ -2271,25 +2271,37 @@ These functions honor the buffer's file filter, which can be set using
   This option controls whether the above function inserts a list of
   untracked files in the status buffer.
 
+  - If ~nil~, do not list any untracked files.
+  - If ~t~, list untracked files, but if a directory does not contain any
+    untracked files, then only list that directory, not the contained
+    untracked files.
+  - If ~all~, then list each individual untracked files.  This is can be
+    very slow and is discouraged.
+
+  The corresponding values for the Git variable are "no", "normal"
+  and "all".
+
   To disable listing untracked files in a specific repository only,
   add the following to ~.dir-locals.el~:
 
   #+begin_src emacs-lisp
     ((magit-status-mode
-     (magit-status-show-untracked-files . \"no\")))
+     (magit-status-show-untracked-files . "no")))
   #+end_src
 
   Alternatively (and mostly for historic reasons), it is possible to
-  use ~git config~ to disable listing files for a specific repository,
-  using:
+  use ~git config~ to set the repository-local value:
 
   #+begin_src shell-script
     git config set --local status.showUntrackedFiles no
   #+end_src
 
-  This does *not* override the (if any) local value of this Lisp variable.
-  It also is not possible to use the Git variable to enable listing files
-  (in case the global value of this variable is nil).
+  This does *not* override the (if any) local value of this Lisp variable,
+  but it does override its global value.
+
+  See the last section in the git-status(1) manpage, to speed up the part
+  of the work Git is responsible for.  Turning that list into sections is
+  also not free, so Magit only lists ~magit-status-file-list-limit~ files.
 
 - User Option: magit-status-file-list-limit ::