Notify
Cross-platform filesystem notification library for Rust.
As used by: cargo watch, cobalt, handlebars-iron, rdiff, docket, and watchexec. (Want to be added to this list? Open a pull request!)
Version 5 status: branch next
.
Installation
[]
= "4.0.0"
Usage
extern crate notify;
use ;
use channel;
use Duration;
Version 2.x
The documentation for the previous major version is available on docs.rs. While version 2.x will no longer be maintained and we encourage all library authors to switch to version 3+ (a short guide is provided below), it is still a dependency of many packages. Here is a list of changes you may need to take note of:
-
Notify 2.x by default provided the events immediately as reported from the backend API. Notify 3+ by default debounces the events — if the backend reports two similar events in close succession, Notify will only report one. The old behaviour may be obtained through the
Watcher::new_raw()
function andRawEvent
type, see the documentation. -
Notify 2.x always tried to watch paths recursively in the case of directories. Notify 3+ gives you the choice of what mode you'd like to use per-watch, using the
RecursiveMode
enum. Thewatch(...)
function thus takes the mode as a second argument. -
Notify 2.x had two behaviour bugs with the inotify backend, that are corrected in Notify 3+. Nonetheless, these are breaking changes:
- inotify did not remove watches recursively; and
- inotify did not watch newly created folders.
To upgrade to Notify 3+ with minimal behaviour change:
- Replace
Watcher::new
withWatcher::new_raw
. - Replace
Event
withEventRaw
. - Import
notify::RecursiveMode
and addRecursiveMode::Recursive
as second argument to thewatch()
function.
Platforms
- Linux / Android: inotify
- macOS: FSEvents
- Windows: ReadDirectoryChangesW
- All platforms: polling
FSEvents
Due to the inner security model of FSEvents (see FileSystemEventSecurity), some event cannot be observed easily when trying to follow files that do not belong to you. In this case, reverting to the pollwatcher can fix the issue, with a slight performance cost.
Todo
- BSD / macOS / iOS: kqueue
- Solaris 11: FEN
Pull requests and bug reports happily accepted!
Origins
Inspired by Go's fsnotify and Node.js's Chokidar, born out of need for cargo watch, and general frustration at the non-existence of C/Rust cross-platform notify libraries.
Written by Félix Saparelli and awesome contributors, and released in the Public Domain using the Creative Commons Zero Declaration.