Child pages
  • FileWatcher implementation contract
Skip to end of metadata
Go to start of metadata

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

Discovery

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

Protocol

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

Commands

ROOTS – Advisory command, which lists all the paths, where changes are expected to be reported.
If the path is prefixed with '|' symbol, this path is only required to be monitored flat (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:

EXIT – Request for the notifier to shutdown itself

Results / Responses

Notifications all have similar format of a <keyword> followed by a newline followed by a path followed by one more newline. Keywords are:
CREATE – new file or folder created
DELETE – a file or folder deleted
STATS – file metadata changed (e.g. R/O attribute or timestamp)
CHANGE – content of a file changed
DIRTY – something changed 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

Example:

Note that notifier doesn't have to issue all the 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 CREATE/DELETE/CHANGE/STATS.

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

This is expected to be issued as response to ROOTS command and (additionally) any time notifier has an update on the list of unwatchable roots. The list 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 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:

  • No labels