Page MenuHomePhabricator

Updated 1,771 Days AgoPublic

Eovim Plugin - Filenotify

Filenotify is an Eovim plugin that warns the user through Eovim's user interface when a file open in Eovim was changed from the outside.

Neovim API

To make filenotify work, Eovim defines two vim APIs:

  • when a file has been read by neovim,
  • when a file has been written by neovim.

Both APIs use the Eovim() function, with "filenotify" as the first argument:

API1st argument2nd argument3rd argument
File Read"filenotify"file name1
File Written"filenotify"file name0

For example, this API can be used as follows:

function! OnReadFile (file_matched)
   call Eovim("filenotify", a:file_matched, 1)

function! OnWriteFile (file_matched)
   call Eovim("filenotify", a:file_matched, 0)

And then triggered using neovim's autocmd:

augroup EovimFileNotify
   autocmd BufNewFile,BufReadPre,FileReadPre * call OnReadFile(expand('<amatch>'))
   autocmd BufWritePre * call OnWriteFile(expand('<amatch>'))
augroup END


Eovim (e.g. the filenotify plugin) is made aware when a file has been read or written thanks to the neovim API presented above. During its lifetime, filenotify follows the following statechart regarding files edited within neovim:

  • Existing files read by neovim are monitored (through an Ecore_File_Monitor).
  • Upon write from inside neovim, filenotify shall receive a message, to try to distinguish external writes from internal writes.
  • If a file is changed and the internal write signal was not received within a given window of time, the file is marked as being changed from the outside.
  • Newly created files do not need to be registered, until they are written to the disk.
  • When a file is closed, it is unregistered.
IMPORTANT: since the detection of the writes is asynchronous and not built-in into neovim, there may be priority inversions where a file is simultaneously written by both neovim and from the outside. In some cases, the filenotify plugin may not detect that the file was written from outside neovim.
Last Author
Last Edited
Mar 26 2018, 12:27 PM