Crate include_exclude_watcher 

Async file watcher with glob-based include/exclude patterns.

This crate provides an efficient recursive file watcher using Linux’s inotify, with built-in support for glob patterns to filter events. Unlike most file watchers that require you to filter events after receiving them, this watcher only sets up watches on directories that could potentially match your patterns, reducing resource usage on large directory trees.

Features

• Selective directory watching: Only watches directories that could match your include patterns
• Glob patterns: Supports *, **, ?, and character classes like [a-z]
• Include/exclude filtering: Gitignore-style pattern matching with exclude taking precedence
• Pattern files: Load patterns from .gitignore-style files
• Event filtering: Watch only creates, deletes, updates, or any combination
• Type filtering: Match only files, only directories, or both
• Debouncing: Built-in debounce support to batch rapid changes
• Async/await: Native tokio integration

Platform Support

Linux only (uses inotify directly). PRs welcome for other platforms.

Quick Start

use include_exclude_watcher::{Watcher, WatchEvent};

#[tokio::main]
async fn main() -> std::io::Result<()> {
    Watcher::new()
        .set_base_dir("./src")
        .add_include("**/*.rs")
        .add_exclude("**/target/**")
        .run(|event, path| {
            println!("{:?}: {}", event, path.display());
        })
        .await
}

Debounced Watching

When files change rapidly (e.g., during a build), you often want to wait for changes to settle before taking action:

use include_exclude_watcher::Watcher;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    Watcher::new()
        .set_base_dir("./src")
        .add_include("**/*.rs")
        .run_debounced(500, |first_changed_path| {
            println!("Files changed! First: {}", first_changed_path.display());
        })
        .await
}

Pattern Syntax

Patterns use glob syntax similar to .gitignore:

Pattern	Matches
*	Any characters except /
**	Any characters including / (matches across directories)
?	Any single character except /
[abc]	Any character in the set
[a-z]	Any character in the range

Pattern Behavior

• Patterns without / match anywhere in the tree (like gitignore). For example, *.rs matches foo.rs and src/bar.rs.
• Patterns with / are anchored to the base directory. For example, src/*.rs matches src/main.rs but not src/sub/lib.rs.

Examples

Pattern	Description
*.rs	All Rust files anywhere
src/*.rs	Rust files directly in src/
**/test_*.rs	Test files anywhere
target/**	Everything under target/
*.{rs,toml}	Rust and TOML files (character class)

Loading Patterns from Files

You can load exclude patterns from gitignore-style files:

use include_exclude_watcher::Watcher;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    Watcher::new()
        .set_base_dir("/project")
        .add_include("**/*")
        .add_ignore_file(".gitignore")
        .add_ignore_file(".watchignore")
        .run(|event, path| {
            println!("{:?}: {}", event, path.display());
        })
        .await
}

Pattern file format:

• Lines starting with # are comments
• Empty lines are ignored
• All other lines are exclude patterns
• Note: ! negation patterns are not supported (excludes always take precedence)

Filtering Events

You can filter which events to receive and what types to match:

use include_exclude_watcher::Watcher;

Watcher::new()
    .add_include("**/*.rs")
    .watch_create(true)   // Receive create events
    .watch_delete(true)   // Receive delete events
    .watch_update(false)  // Ignore modifications
    .match_files(true)    // Match regular files
    .match_dirs(false)    // Ignore directories
    .run(|event, path| {
        // Only file creates and deletes
    })
    .await

Structs

Watcher

Builder for configuring and running a file watcher.

Enums

WatchEvent

Type of file system event.

Type Aliases

WatchBuilderDeprecated

Backwards compatibility alias for Watcher.