Cross-platform filesystem notification library for Rust.
Caution! This is a bleeding-edge 5.0 prerelease!
You likely want either [the latest 4.0 release] or [5.0.0-pre.0].
Notably, at this stage the debounced interface has been completely removed. You can find its previous implementation at either version above.
(Looking for desktop notifications instead? Have a look at [notify-rust] or [alert-after]!)
As used by: [alacritty], [cargo watch], [cobalt], [docket], [mdBook], pax, [rust-analyzer], [timetrack], [watchexec], [xi-editor], and others. (Want to be added to this list? Open a pull request!)
toml
[dependencies]
notify = "5.0.0"
The examples below are aspirational only, to preview what the final release may look 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", 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.
While this current version continues to be developed and maintained, next
generation experiments and designs around the library live in the
next branch. There is no solid
ETA, beyond that most of it will not be released before async/await is
stabilised in Rust. For an overview and background, see this draft
announce.
Instead of one large release, though, smaller components of the design, once
they have gone through revising and maturing, will be incorporated in the
main branch. The first large piece, a new event classification system, has
already landed.
Notify is currently undergoing a transition to using the
Artistic License 2.0 from the current 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 code will be
entirely free of CC0 code, the license will be formally changed (and that will
incur a major version bump). As part of this, when you contribute to Notify you
currently 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].