Notify

Cross-platform filesystem notification library for Rust.

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

API Documentation
Crate page
Version Next progress
Earliest supported Rust version: 1.26.1

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

Notify is abandoned

Sorry.

Notify has been years of my life and as much as it’s a tough decision, I’m also greatly relieved. It’s been great, it’s been not so great; it’s now time. I got some distance, took a hard look at it all, and realised I don’t want to do this any more. For way longer than I should have let this go on for, Notify sparked negative joy, and I’m Marie-Kondo-ing it out.

The logistics: several people have commit bit, and several people have publish bit, and the project is also covered by the Rust Bus.

If you want to take over or get commit/publish bits and you’re a trusted/respected community member, just ask. If you’re not a trusted/respected community member, try forking first.

I will not merge PRs, I will not commit unless it’s an emergency, I will not respond to issues or comments unless I really really feel like it, and the goal is total disengagement.

So Long 🔭 And Thanks For All The Fish 🐬

Installation

[dependencies]
notify = "4.0.13"

Usage

extern crate notify;

use notify::{RecommendedWatcher, Watcher, RecursiveMode};
use std::sync::mpsc::channel;
use std::time::Duration;

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, Duration::from_secs(2)));

    // 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(event) => println!("{:?}", event),
            Err(e) => println!("watch error: {:?}", e),
        }
    }
}

fn main() {
    if let Err(e) = watch() {
        println!("error: {:?}", e)
    }
}

Looking overly verbose? Too much boilerplate? Have a look at hotwatch, a friendly wrapper:

// Taken from the hotwatch readme
use hotwatch::{Hotwatch, Event};

let mut hotwatch = Hotwatch::new().expect("Hotwatch failed to initialize.");
hotwatch.watch("war.png", |event: Event| {
    if let Event::Write(path) = event {
        println!("War has changed.");
    }
}).expect("Failed to watch file!");

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.

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, and released in the Public Domain using the Creative Commons Zero Declaration.

notify 4.0.13