(Windows)
(Linux and OS X)
Cross-platform filesystem notification library for Rust.
As used by: [cargo watch], [cobalt], [handlebars-iron], [rdiff], and [watchexec]. (Want to be added to this list? Open a pull request!)
toml
[dependencies]
notify = "3.0.0"
```rust extern crate notify; use notify::{RecommendedWatcher, RecursiveMode, Watcher}; use std::sync::mpsc::channel;
fn watch() -> notify::Result<()> { // Create a channel to receive the events. let (tx, rx) = channel();
// Automatically select the best implementation for your platform. // You can also access each implementation directly e.g. INotifyWatcher. let mut watcher: RecommendedWatcher = try!(Watcher::new(tx));
// Add a path to be watched. All files and directories at that path and // below will be monitored for changes. try!(watcher.watch("/home/test/notify", RecursiveMode::Recursive));
// This is a simple loop, but you may want to use more complex logic here, // for example to handle I/O. loop { match rx.recv() { Ok(notify::Event{ path: Some(path),op:Ok(op) }) => { println!("{:?} {:?}", op, path); }, Err(e) => println!("watch error {}", e), _ => () } } }
fn main() { if let Err(err) = watch() { println!("Error! {:?}", err) } } ```
The documentation for the previous major version is [available on docs.rs][docs-v2]. 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.x by default [debounces the events][docs-debounce] (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 and RawEvent type, see [the
documentation][docs-raw].
Notify 2.x always tried to watch paths recursively in the case of
directories. Notify 3.x gives you the choice of what mode you'd like to use
per-watch, using the RecursiveMode enum. The
watch(...) 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.x. Nonetheless, these are breaking changes:
To upgrade to Notify 3.x with minimal behaviour change:
Watcher::new with Watcher::new_raw.Event with EventRaw.notify::RecursiveMode and add RecursiveMode::Recursive as second
argument to the watch() function.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.
Pull requests and bug reports happily accepted!
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.