fix(#3198): document filesystem_watchers.max_events

Author: alex-courtis

doc/nvim-tree-lua.txt

@@ -2511,12 +2511,25 @@ Config: filesystem_watchers             *nvim-tree-config-filesystem-watchers*
       This may be useful when a path is not in `.gitignore` or git integration
       is disabled.
 
+    On runaway consecutive filesystem events for a single directory with an
+    interval < |nvim-tree.filesystem_watchers.debounce_delay|:
+    • The filesystem watcher will be disabled for that directory.
+    • A warning notification will be shown.
+    • Consider adding this directory to |filesystem_watchers.ignore_dirs|
+
+    The runaway threshold is controlled by {max_events} and has been observed
+    when running on Windows PowerShell: an infinite number of filesystem
+    events were raised and Nvim hangs.
+
     Fields: ~
       • {enable}?          (`boolean`) (default: `true`)
       • {debounce_delay}?  (`integer`, default: `50`) Idle milliseconds
                            between filesystem change and tree update.
       • {ignore_dirs}?     (`string[]|(fun(path: string): boolean)`, default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", }`)
-                           Disable for directories.
+                           Disable for specific directories.
+      • {max_events}?      (`integer`, default: `100`) Disable for a single
+                           directory after consecutive events with an interval
+                           < |nvim-tree.filesystem_watchers.debounce_delay|.
 
 
 
@@ -2987,7 +3000,7 @@ Following is the default configuration, see |nvim_tree.config| for details. >lua
       filesystem_watchers = {
         enable = true,
         debounce_delay = 50,
-        max_outstanding_events = 100,
+        max_events = 100,
         ignore_dirs = {
           "/.ccls-cache",
           "/build",

lua/nvim-tree.lua

@@ -462,7 +462,7 @@ local DEFAULT_OPTS = { -- default-config-start
   filesystem_watchers = {
     enable = true,
     debounce_delay = 50,
-    max_outstanding_events = 100,
+    max_events = 100,
     ignore_dirs = {
       "/.ccls-cache",
       "/build",

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

@@ -12,6 +12,13 @@ error("Cannot require a meta file")
 --- - 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.
 ---
+---On runaway consecutive filesystem events for a single directory with an interval < [nvim-tree.filesystem_watchers.debounce_delay]:
+---- The filesystem watcher will be disabled for that directory.
+---- A warning notification will be shown.
+---- Consider adding this directory to [filesystem_watchers.ignore_dirs]
+---
+---The runaway threshold is controlled by {max_events} and has been observed when running on Windows PowerShell: an infinite number of filesystem events were raised and Nvim hangs.
+---
 ---@class nvim_tree.config.filesystem_watchers
 ---
 ---(default: `true`)
@@ -21,6 +28,10 @@ error("Cannot require a meta file")
 ---(default: `50`)
 ---@field debounce_delay? integer
 ---
----Disable for directories.
+---Disable for specific directories.
 ---(default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", }`)
 ---@field ignore_dirs? string[]|(fun(path: string): boolean)
+---
+---Disable for a single directory after consecutive events with an interval < [nvim-tree.filesystem_watchers.debounce_delay].
+---(default: `100`)
+---@field max_events? integer

lua/nvim-tree/explorer/watch.lua

@@ -75,11 +75,11 @@ function M.create_watcher(node)
     watcher.data.outstanding_events = watcher.data.outstanding_events + 1
 
     -- disable watcher when outstanding exceeds max
-    if watcher.data.outstanding_events > M.config.filesystem_watchers.max_outstanding_events then
+    if watcher.data.outstanding_events > M.config.filesystem_watchers.max_events then
       notify.error(string.format(
         "Observed %d consecutive file system events with interval < %dms, exceeding filesystem_watchers.max_events=%s. Disabling watcher for directory '%s'. Consider adding this directory to filesystem_watchers.ignore_dirs",
         watcher.data.outstanding_events,
-        M.config.filesystem_watchers.max_outstanding_events,
+        M.config.filesystem_watchers.max_events,
         M.config.filesystem_watchers.debounce_delay,
         node.absolute_path
       ))