fix(vim.fs): default to follow=false #32859

Problem:
Following symlinks can have surprising behavior and slow performance.

Solution:
Do not set it by default.

runtime/doc/lua.txt

@@ -2985,7 +2985,7 @@ vim.fs.dir({path}, {opts})                                      *vim.fs.dir()*
                 • skip: (fun(dir_name: string): boolean)|nil Predicate to
                   control traversal. Return false to stop searching the
                   current directory. Only useful when depth > 1
-                • follow: boolean|nil Follow symbolic links. (default: true)
+                • follow: boolean|nil Follow symbolic links. (default: false)
 
     Return: ~
         (`Iterator`) over items in {path}. Each iteration yields two values:
@@ -3058,7 +3058,7 @@ vim.fs.find({names}, {opts})                                   *vim.fs.find()*
                  • {limit}? (`number`, default: `1`) Stop the search after
                    finding this many matches. Use `math.huge` to place no
                    limit on the number of matches.
-                 • {follow}? (`boolean`, default: `true`) Follow symbolic
+                 • {follow}? (`boolean`, default: `false`) Follow symbolic
                    links.
 
     Return: ~

runtime/doc/news.txt

@@ -330,8 +330,8 @@ LUA
 • |vim.json.encode()| has an option to enable forward slash escaping
 • |vim.fs.abspath()| converts paths to absolute paths.
 • |vim.fs.relpath()| gets relative path compared to base path.
-• |vim.fs.dir()| and |vim.fs.find()| now follow symbolic links by default,
-  the behavior can be turn off using the new `follow` option.
+• |vim.fs.dir()| and |vim.fs.find()| can now follow symbolic links,
+  the behavior can be turn on using the new `follow` option.
 • |vim.text.indent()| indents/dedents text.
 
 OPTIONS

runtime/lua/vim/fs.lua

@@ -136,7 +136,7 @@ end
 ---             - skip: (fun(dir_name: string): boolean)|nil Predicate
 ---               to control traversal. Return false to stop searching the current directory.
 ---               Only useful when depth > 1
----             - follow: boolean|nil Follow symbolic links. (default: true)
+---             - follow: boolean|nil Follow symbolic links. (default: false)
 ---
 ---@return Iterator over items in {path}. Each iteration yields two values: "name" and "type".
 ---        "name" is the basename of the item relative to {path}.
@@ -179,7 +179,7 @@ function M.dir(path, opts)
         if
           opts.depth
           and level < opts.depth
-          and (t == 'directory' or (t == 'link' and opts.follow ~= false and (vim.uv.fs_stat(
+          and (t == 'directory' or (t == 'link' and opts.follow and (vim.uv.fs_stat(
             M.joinpath(path, f)
           ) or {}).type == 'directory'))
           and (not opts.skip or opts.skip(f) ~= false)
@@ -217,7 +217,7 @@ end
 --- @field limit? number
 ---
 --- Follow symbolic links.
---- (default: `true`)
+--- (default: `false`)
 --- @field follow? boolean
 
 --- Find files or directories (or other items as specified by `opts.type`) in the given path.
@@ -357,11 +357,7 @@ function M.find(names, opts)
 
         if
           type_ == 'directory'
-          or (
-            type_ == 'link'
-            and opts.follow ~= false
-            and (vim.uv.fs_stat(f) or {}).type == 'directory'
-          )
+          or (type_ == 'link' and opts.follow and (vim.uv.fs_stat(f) or {}).type == 'directory')
         then
           dirs[#dirs + 1] = f
         end