Cross-platform filesystem notification library for Rust.
Caution! This is unstable code!
You likely want either [the latest 4.0 release] or [5.0.0-pre.14].
(Looking for desktop notifications instead? Have a look at [notify-rust] or [alert-after]!)
As used by: [alacritty], [cargo watch], [cobalt], [docket], [mdBook], [pax], [rdiff], [rust-analyzer], [timetrack], [watchexec], [xi-editor], and others.
toml
[dependencies]
crossbeam-channel = "0.4.0"
notify = "5.0.0-pre.14"
The examples below are aspirational only, to preview what the final release may have looked like. They may not work. Refer to the API documentation instead.
```rust use notify::{RecommendedWatcher, RecursiveMode, Result, watcher}; use std::time::Duration;
fn main() -> Result<()> { // Automatically select the best implementation for your platform. // You can also access each implementation directly e.g. INotifyWatcher. let mut watcher = watcher(Duration::from_secs(2))?;
// Add a path to be watched. All files and directories at that path and
// below will be monitored for changes.
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.
for event in &watcher {
match event {
Ok(event) => println!("changed: {:?}", event.path),
Err(err) => println!("watch error: {:?}", err),
};
}
Ok(())
} ```
To get a channel for advanced or flexible cases, use:
```rust let rx = watcher.channel();
loop { match rx.recv() { // ... } } ```
To pass in a channel manually:
```rust let (tx, rx) = crossbeamchannel::unbounded(); let mut watcher: RecommendedWatcher = Watcher::withchannel(tx, Duration::from_secs(2))?;
for event in rx.iter() { // ... } ```
By default, Notify issues generic events that carry little additional information beyond what path was affected. On some platforms, more is available; stay aware though that how exactly that manifests varies. To enable precise events, use:
rust
use notify::Config;
watcher.configure(Config::PreciseEvents(true));
Sometimes you want to respond to some events straight away, but not give up the advantages of debouncing. Notice events appear once immediately when the occur during a debouncing period, and then a second time as usual at the end of the debouncing period:
rust
use notify::Config;
watcher.configure(Config::NoticeEvents(true));
Sometimes frequent writes may be missed or not noticed often enough. Ongoing write events can be enabled to emit more events even while debouncing:
rust
use notify::Config;
watcher.configure(Config::OngoingEvents(Some(Duration::from_millis(500))));
To receive events as they are emitted, without debouncing at all:
rust
let mut watcher = immediate_watcher()?;
With a channel:
rust
let (tx, rx) = unbounded();
let mut watcher: RecommendedWatcher = Watcher::immediate_with_channel(tx)?;
Events can be serialisable via [serde]. To enable the feature:
toml
notify = { version = "5.0.0-pre.14", features = ["serde"] }
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.
Notify was undergoing a transition to using the
Artistic License 2.0 from CC Zero 1.0. A part of
the code is only under CC0, and another part, including all new code since
commit [3378ac5a], is under both CC0 and Artistic. When the project was to be
entirely free of CC0 code, the license would be formally changed (and that would
have incurred a major version bump). As part of this, contributions to Notify since
would agree to release under both.
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].