Notify

Cross-platform filesystem notification library for Rust.

This is the readme for the 5.0.0-pre.1 pre-release!

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

wip 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. (Want to be added to this list? Open a pull request!)

Why a prerelease?

It’s taking a while to bring 5.0 to the standard and featureset I wish for it, while at the same time I have less time than ever to spend on this project. In short, don’t expect 5.0.0 before Q4 2019. I am aware, though, that people want to use the features that are finished so far. This is what this prerelease is.

It has all the fixes and implemented features so far, with the new Event interface for the "debounced" watcher, but keeping the previous events for the immediate (previously known as "raw") watcher. It is fairly stable in terms of functionality, and the debounced (default) API is as close as its final 5.0.0 form as it can be.

The idea is to pin to =5.0.0-pre.1, and ignore further prereleases. You’ll get long-standing fixes compared to 4.0.x, some new features, and API stability for the next few months.

The 4.0.x branch will continue being passively maintained during this time though, and it’s what out there in the ecosystem right now, so it’s always an option to go for the latest 4.0 release.

If you want to live at the bleeding edge, you can of course track main or future prereleases. Keep in mind that there will be breakage, there will be changes, and entire features may disappear and reappear between prereleases. It’s gonna be pretty unstable for a while.

(What happened to 5.0.0-pre.0? I broke it. I'm sorry. .1 is just like it, though.)

Installation

[dependencies]
crossbeam-channel = "0.3.8"
notify = "=5.0.0-pre.1"

Usage

use crossbeam_channel::unbounded;
use notify::{RecursiveMode, Result, watcher};
use std::time::Duration;

fn main() -> Result<()> {
    // Create a channel to receive the events.
    let (tx, rx) = unbounded();

    // Automatically select the best implementation for your platform.
    // You can also access each implementation directly e.g. INotifyWatcher.
    let mut watcher = watcher(tx, 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.
    loop {
        match rx.recv() {
            Ok(event) => println!("changed: {:?}", event),
            Err(err) => println!("watch error: {:?}", err),
        };
    }

    Ok(())
}

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 (tx, rx) = unbounded();
let mut watcher = immediate_watcher(tx)?;

Serde

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

notify = { version = "=5.0.0-pre.1", 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.

Next generation

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.

License

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.

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.

notify 5.0.0-pre.1