docs: adjust fswatch overflow message to mention docs with info

- Add :h fswatch-limitations that notifies user about default inotify
  limitations on linux and how to adjust them
- Check for Event queue overflow message from fswatch and refer user to
  new documentation

Signed-off-by: Tomas Slusny <slusnucky@gmail.com>

2 files changed, 13 insertions, 0 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index e1e3f88a1d..135a1b42de 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -530,6 +530,16 @@ Example: File-change detection                                    *watch-file*
     vim.api.nvim_command(
       "command! -nargs=1 Watch call luaeval('watch_file(_A)', expand('<args>'))")
 <
+                                                         *fswatch-limitations*
+When on Linux and using fswatch, you may need to increase the maximum number
+of `inotify` watches and queued events as the default limit can be too low. To
+increase the limit, run: >sh
+    sysctl fs.inotify.max_user_watches=100000
+    sysctl fs.inotify.max_queued_events=100000
+<
+This will increase the limit to 100000 watches and queued events. These lines
+can be added to `/etc/sysctl.conf` to make the changes persistent.
+
 Example: TCP echo-server                                          *tcp-server*
     1. Save this code to a file.
     2. Execute it with ":luafile %".
diff --git a/runtime/lua/vim/_watch.lua b/runtime/lua/vim/_watch.lua
index cf2689861a..542e770246 100644
--- a/runtime/lua/vim/_watch.lua
+++ b/runtime/lua/vim/_watch.lua
@@ -289,6 +289,9 @@ function M.fswatch(path, opts, callback)
       end
 
       if data and #vim.trim(data) > 0 then
+        if vim.fn.has('linux') == 1 and vim.startswith(data, 'Event queue overflow') then
+          data = 'inotify(7) limit reached, see :h fswatch-limitations for more info.'
+        end
         vim.schedule(function()
           vim.notify('fswatch: ' .. data, vim.log.levels.ERROR)
         end)