When watching events using `new_fs_event`, the filename argument may be nil

[yorickpeterse]

This was originally reported in nvim-mini/mini.nvim#2204, but the issue is not specific to that project or Neovim. It was also encountered here.

The issue is that when watching a directory, the callback passed to the event's start function may be given nil as the file name argument, yet the documentation states it's a string. This happens on my FreeBSD VM when using the following steps:

1. git clone https://github.com/yorickpeterse/os-image-builders.git repo
2. cd repo
3. lua repro.lua in one terminal, then git status in another terminal in the same directory

The output in this case is:

err:      nil
filename: nil
events:   0

err:      nil
filename: nil
events:   0

The contents of repro.lua are as follows:

local luv = require('luv')
local event = luv.new_fs_event()

event:start('.git', {}, function(err, filename, events)
  print('err:      ' .. tostring(err))
  print('filename: ' .. tostring(filename))
  print('events:   ' .. tostring(#events))
end)

luv.run()

Note that the Lua version has no relevancy: I tried Lua 5.4, Lua 5.3 and the Lua version of Neovim (LuaJIT) and they all experience the same issue.

If filename can indeed be nil this should be mentioned, though based on the data given to the callback I'm not sure it's actually useful to call the function in this case as there's not much you can do but ignore it.

Small side note: I realise now that the #events bit is useless because it's a table with only named keys, but at least under Neovim the reported event (using print(vim.inspect(events)) to pretty print it) is { rename = true }.

[SinisterRectus]

This could just be a documentation omission. The original docs state:

If the handle was started with a directory the filename parameter will be a relative path to a file contained in the directory, or NULL if the file name cannot be determined.