feat(explorer): add filesystem watchers (#1304)

* feat(explorer): add experimental watchers

This commit introduces watchers to update the tree.
This behavior is introduced behind an "filesystem_watchers" option
which should prevent instabilities.
It will become the default at some point.

Co-authored-by: Alexander Courtis <alex@courtis.org>

doc/nvim-tree-lua.txt

@@ -200,6 +200,10 @@ Values may be functions. Warning: this may result in unexpected behaviour.
         custom = {},
         exclude = {},
       },
+      filesystem_watchers = {
+        enable = false,
+        interval = 100,
+      },
       git = {
         enable = true,
         ignore = true,
@@ -249,6 +253,7 @@ Values may be functions. Warning: this may result in unexpected behaviour.
           diagnostics = false,
           git = false,
           profile = false,
+          watcher = false,
         },
       },
     } -- END_DEFAULT_OPTS
@@ -419,6 +424,26 @@ Git integration with icons and colors.
   milliseconds but a few seconds), it will not render anything until the git
   process returned the data.
 
+
+*nvim-tree.filesystem_watchers*
+Will use file system watcher (libuv fs_poll) to watch the filesystem for
+changes.
+Using this will disable BufEnter / BufWritePost events in nvim-tree which
+were used to update the whole tree. With this feature, the tree will be
+updated only for the appropriate folder change, resulting in better
+performance.
+This will be experimental for a few weeks and will become the default.
+
+    *nvim-tree.filesystem_watchers.enable*
+    Enable / disable the feature.
+      Type: `boolean`, Default: `false`
+
+    *nvim-tree.filesystem_watchers.interval*
+    Milliseconds between polls for each directory.
+    Increase to at least 1000ms if changes are not visible. See
+    https://github.com/luvit/luv/blob/master/docs.md#uvfs_poll_startfs_poll-path-interval-callback
+      Type: `number`, Default: `100` (ms)
+
 *nvim-tree.view*
 Window / buffer setup.