README.md

Notify

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.3.

(Looking for desktop notifications instead? Have a look at notify-rust or alert-after!)

• incomplete Guides and in-depth docs
• API Documentation
• Crate page
• Changelog
• Earliest supported Rust version: 1.32.0

As used by: alacritty, cargo watch, cobalt, docket, mdBook, pax rdiff, rust-analyzer, timetrack, watchexec, xi-editor, and others.

Installation

[dependencies]
crossbeam-channel = "0.4.0"
notify = "5.0.0-pre.3"

Usage

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.

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(())
}

With a channel

To get a channel for advanced or flexible cases, use:

let rx = watcher.channel();

loop {
    match rx.recv() {
        // ...
    }
}

To pass in a channel manually:

let (tx, rx) = crossbeam_channel::unbounded();
let mut watcher: RecommendedWatcher = Watcher::with_channel(tx, Duration::from_secs(2))?;

for event in rx.iter() {
    // ...
}

With precise events

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:

use notify::Config;
watcher.configure(Config::PreciseEvents(true));

With notice events

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:

use notify::Config;
watcher.configure(Config::NoticeEvents(true));

With ongoing events

Sometimes frequent writes may be missed or not noticed often enough. Ongoing write events can be enabled to emit more events even while debouncing:

use notify::Config;
watcher.configure(Config::OngoingEvents(Some(Duration::from_millis(500))));

Without debouncing

To receive events as they are emitted, without debouncing at all:

let mut watcher = immediate_watcher()?;

With a channel:

let (tx, rx) = unbounded();
let mut watcher: RecommendedWatcher = Watcher::immediate_with_channel(tx)?;

Serde

Events can be serialisable via serde. To enable the feature:

notify = { version = "5.0.0-pre.3", features = ["serde"] }

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.

License

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.

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.