Child pages
  • FileWatcher implementation contract

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

This describes protocol for command line tool to be used to notify IDEA on filesystem changes.1.


Regardless of the platform, IDEA will try to execute binary named 'fsnotifier' in 'bin' folder of its distribution. Whatefer Whatever executable found
under that name must comply to the following protocol :specification.2.


All the communication is being performed using standard input (for commands from IDEA to notifier) and standard output (for command reponds responses and notification output).




:ROOTS: Advisory command, which lists all the paths, where changes are expected to be reported, recursively.
If the path is prefixed with '|' symbol, this path is only required to be monitored flat . No recursive watching is required.(i.e. changes from subdirectories of that directory may not bee reported).

Format is as follows: ROOTS keyword, followed by list of paths, followed by # sign, each on separate line:

Code Block









EXIT: Request for the notifier to shutdown itself

Results /



Notification results Notifications all have similar format as of a <keyword> , followed by a newline , followed by a path followed by one more newline.
Keywords can beare:
CREATE - issued to report new file or folder created
DELETE - issued to report – a file or folder deleted
STATS - flags (like – file metadata changed (e.g. R/O attribute or timestamp) changed
CHANGE - Content – content of the a file changed
DIRTY - something changed at the path. For directories, files added or deleted, or contents of the files in directory may have been changed
RECDIRTY - something changed at the path, recursively
RESET - everything changed. Complete manual rescan is required.


under a directory, children scan is required
RECDIRTY – something changed under a directory or somewhere below it, recursive scan is required
RESET – everything changed, complete scan is required


Code Block

Note that notifier doesn't have report to issue all the commands notifications that apply to certain change. Just use what's easier to implement. For instance, it's totally
OK to use just DIRTY and RECDIRTY instead of reporting detailed createCREATE/deleteDELETE/changeCHANGE/statsSTATS.

Certain parts of the local file system may not have notification capabilities. Those paths must be reported using UNWATCHEABLE command like:

Code Block









This may is expected to be issued as response to ROOTS command , or at and (additionally) any time notifier has an update on the list of unwatcheable unwatchable roots. The list must be at least
complete with regards to the roots passed should not include any paths outside subtree specified by ROOTS command.

At any time in the communication notifier has the right to give up on providing adequate results and inform subscriber by issuing GIVEUP command.
This command shall normally be used if the platform is unsupported by notifier, like MacOS Mac OS X prior to 10.5 (Leopard).

Notifier may ask IDEA to display warning notification by issuing MESSAGE command. Text of notification should be in the next line and may contain HTML formatting including links:

Code Block
Something's wrong. Click <a href="">here</a>.