feat(#3292): add nvim_tree.config.filesystem_watchers.whitelist_dirs

Author: alex-courtis

doc/nvim-tree-lua.txt

@@ -844,6 +844,9 @@ Windows WSL and PowerShell
 - Executable file detection is disabled as this is non-performant and can
   freeze Nvim
 - Some filesystem watcher error related to permissions will not be reported
+- Filesystem watchers can experience severe performance issues. It is strongly
+  recommended to tightly control watcher usage via
+  |nvim_tree.config.filesystem_watchers| {whitelist_dirs}
 
 Powershell
 - Observed Nvim hanging after a runaway (infinite) number of events on a
@@ -1693,11 +1696,17 @@ Config: filesystem_watchers             *nvim-tree-config-filesystem-watchers*
     directory changes, resulting in better performance.
 
     Watchers may be disabled for absolute directory paths via {ignore_dirs}.
+    This may be useful when a path is not in `.gitignore` or git integration
+    is disabled.
     • A list of |regular-expression| to match a path, backslash escaped e.g.
       `"my-proj/\\.build$"` OR
     • A function that is passed an absolute path and returns `true` to disable
-      This may be useful when a path is not in `.gitignore` or git integration
-      is disabled.
+
+    Watchers may be enabled only for specific directories via
+    {whitelist_dirs}. When it is empty (default), watchers are enabled for all
+    directories. Uses same semantics as {ignore_dirs} except that the function
+    returns `true` to enable watchers for that path. This is strongly
+    recommended for windows: |nvim-tree-os-specific|.
 
     After {max_events} consecutive filesystem events on a single directory
     with an interval < {debounce_delay}:
@@ -1711,6 +1720,9 @@ Config: filesystem_watchers             *nvim-tree-config-filesystem-watchers*
                            between filesystem change and tree update.
       • {ignore_dirs}?     (`string[]|(fun(path: string): boolean)`, default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", "/.zig-cache"}`)
                            Disable for specific directories.
+      • {whitelist_dirs}?  (`string[]|(fun(path: string): boolean)`, default:
+                           `{}`) Optionally enable only for specific
+                           directories, obeying {ignore_dirs}
       • {max_events}?      (`integer`, default: `0` or `1000` on windows)
                            Disable for a single directory after {max_events}
                            consecutive events with an interval <
@@ -2199,6 +2211,7 @@ Following is the default configuration, see |nvim_tree.config| for details. >lua
           "/target",
           "/.zig-cache",
         },
+        whitelist_dirs = {},
       },
       actions = {
         use_system_clipboard = true,

lua/nvim-tree/_meta/config/filesystem_watchers.lua

@@ -8,9 +8,13 @@ error("Cannot require a meta file")
 ---With this feature, the tree will be partially updated on specific directory changes, resulting in better performance.
 ---
 ---Watchers may be disabled for absolute directory paths via {ignore_dirs}.
+---This may be useful when a path is not in `.gitignore` or git integration is disabled.
 --- - A list of [regular-expression] to match a path, backslash escaped e.g. `"my-proj/\\.build$"` OR
 --- - A function that is passed an absolute path and returns `true` to disable
----This may be useful when a path is not in `.gitignore` or git integration is disabled.
+---
+---Watchers may be enabled only for specific directories via {whitelist_dirs}. When it is empty (default), watchers are enabled for all directories.
+---Uses same semantics as {ignore_dirs} except that the function returns `true` to enable watchers for that path.
+---This is strongly recommended for windows: [nvim-tree-os-specific].
 ---
 ---After {max_events} consecutive filesystem events on a single directory with an interval < {debounce_delay}:
 ---- The filesystem watcher will be disabled for that directory.
@@ -30,6 +34,10 @@ error("Cannot require a meta file")
 ---(default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", "/.zig-cache"}`)
 ---@field ignore_dirs? string[]|(fun(path: string): boolean)
 ---
+---Optionally enable only for specific directories, obeying {ignore_dirs}
+---(default: `{}`)
+---@field whitelist_dirs? string[]|(fun(path: string): boolean)
+---
 ---Disable for a single directory after {max_events} consecutive events with an interval < {debounce_delay}.
 ---Set to 0 to allow unlimited consecutive events.
 ---(default: `0` or `1000` on windows)

lua/nvim-tree/config.lua

@@ -218,6 +218,7 @@ M.d = { -- config-default-start
       "/target",
       "/.zig-cache",
     },
+    whitelist_dirs = {},
   },
   actions = {
     use_system_clipboard = true,
@@ -348,6 +349,7 @@ local ACCEPTED_TYPES = {
   },
   filesystem_watchers = {
     ignore_dirs = { "function" },
+    whitelist_dirs = { "function" },
   },
   actions = {
     open_file = {

lua/nvim-tree/explorer/watch.lua

@@ -33,6 +33,9 @@ local IGNORED_PATHS = {
   "/dev",
 }
 
+---Return true when a path is:
+---- Blacklisted via {ignore_dirs}
+---- Not whitelisted via {whitelist_dirs}, when it is not an empty table.
 ---@param path string
 ---@return boolean
 local function is_folder_ignored(path)
@@ -42,18 +45,41 @@ local function is_folder_ignored(path)
     end
   end
 
-  if type(M.config.filesystem_watchers.ignore_dirs) == "table" then
-    for _, ignore_dir in ipairs(M.config.filesystem_watchers.ignore_dirs) do
+  ---Return true when p matches an entry in dirs, escaping for windows
+  ---@param p string absolute path
+  ---@param dirs string[] absolute or relative
+  ---@return boolean
+  local function matches_dirs(p, dirs)
+    for _, dir in ipairs(dirs) do
       if utils.is_windows then
-        ignore_dir = ignore_dir:gsub("/", "\\\\") or ignore_dir
+        dir = dir:gsub("/", "\\\\") or dir
       end
 
-      if vim.fn.match(path, ignore_dir) ~= -1 then
+      if vim.fn.match(p, dir) ~= -1 then
         return true
       end
     end
+    return false
+  end
+
+  if type(M.config.filesystem_watchers.ignore_dirs) == "table" then
+    if matches_dirs(path, M.config.filesystem_watchers.ignore_dirs) then
+      return true
+    end
   elseif type(M.config.filesystem_watchers.ignore_dirs) == "function" then
-    return M.config.filesystem_watchers.ignore_dirs(path)
+    if M.config.filesystem_watchers.ignore_dirs(path) then
+      return true
+    end
+  end
+
+  if type(M.config.filesystem_watchers.whitelist_dirs) == "table" and #M.config.filesystem_watchers.whitelist_dirs > 0 then
+    if not matches_dirs(path, M.config.filesystem_watchers.whitelist_dirs) then
+      return true
+    end
+  elseif type(M.config.filesystem_watchers.whitelist_dirs) == "function" then
+    if not M.config.filesystem_watchers.whitelist_dirs(path) then
+      return true
+    end
   end
 
   return false