Struct Watcher 

pub struct Watcher { /* private fields */ }

Builder for configuring and running a file watcher.

Use method chaining to configure the watcher, then call run or run_debounced to start watching.

Example

use include_exclude_watcher::Watcher;

Watcher::new()
    .set_base_dir("/project")
    .add_include("src/**/*.rs")
    .add_include("Cargo.toml")
    .add_exclude("**/target/**")
    .run(|event, path| {
        println!("{:?}: {}", event, path.display());
    })
    .await

Implementations

impl Watcher

pub fn new() -> Self

Create a new file watcher with default settings.

Defaults:

• Base directory: current working directory
• Includes: none (must be added, or watches everything)
• Excludes: none
• Event types: create, delete, update all enabled; initial disabled
• Match types: both files and directories
• Path format: relative paths

pub fn debug_watches(self, enabled: bool) -> Self

Enable debug watch events.

When enabled, WatchEvent::DebugWatch events will be emitted for each directory that is watched. Useful for debugging pattern matching.

pub fn add_include(self, pattern: impl Into<String>) -> Self

Add a single include pattern.

Patterns use glob syntax:

• * matches any sequence of characters except /
• ** matches any sequence of characters including /
• ? matches any single character except /
• [abc] matches any character in the set

Patterns without a / match anywhere in the tree (like gitignore). For example, *.rs is equivalent to **/*.rs.

pub fn add_includes( self, patterns: impl IntoIterator<Item = impl Into<String>>, ) -> Self

Add multiple include patterns.

pub fn add_exclude(self, pattern: impl Into<String>) -> Self

Add a single exclude pattern.

Excludes take precedence over includes. Uses the same glob syntax as includes.

pub fn add_excludes( self, patterns: impl IntoIterator<Item = impl Into<String>>, ) -> Self

Add multiple exclude patterns.

pub fn add_ignore_file(self, path: impl AsRef<Path>) -> Self

Add patterns from a gitignore-style file.

Lines starting with # are comments. All other non-empty lines are exclude patterns. Note: ! negation patterns are not supported (a warning will be printed) because excludes always take precedence over includes in this library.

If the file doesn’t exist, this method does nothing (no error).

Example

use include_exclude_watcher::Watcher;

Watcher::new()
    .set_base_dir("/project")
    .add_include("*")
    .add_ignore_file(".gitignore")
    .add_ignore_file(".watchignore")
    .run(|event, path| {
        println!("{:?}: {}", event, path.display());
    })
    .await

pub fn set_base_dir(self, base_dir: impl Into<PathBuf>) -> Self

Set the base directory for watching.

All patterns are relative to this directory. Defaults to the current working directory.

pub fn watch_create(self, enabled: bool) -> Self

Set whether to watch for file/directory creation events.

Default: true

pub fn watch_delete(self, enabled: bool) -> Self

Set whether to watch for file/directory deletion events.

Default: true

pub fn watch_update(self, enabled: bool) -> Self

Set whether to watch for file modification events.

Default: true

pub fn watch_initial(self, enabled: bool) -> Self

Set whether to emit initial events for preexisting files/directories.

When enabled, WatchEvent::Initial events will be emitted for all files and directories that match the patterns at startup, before any file system events are processed. This is useful for building an initial inventory of matching files.

Default: false

Example

use include_exclude_watcher::Watcher;

Watcher::new()
    .add_include("**/*.rs")
    .watch_initial(true)
    .run(|event, path| {
        // First receives Initial events for all existing .rs files,
        // then receives Create/Update/Delete events for changes
    })
    .await

pub fn match_files(self, enabled: bool) -> Self

Set whether to match regular files.

Default: true

pub fn match_dirs(self, enabled: bool) -> Self

Set whether to match directories.

Default: true

pub fn return_absolute(self, enabled: bool) -> Self

Set whether to return absolute paths.

When false (default), paths passed to the callback are relative to the base directory. When true, paths are absolute.

pub async fn run<F>(self, callback: F) -> Result<()>

where F: FnMut(WatchEvent, PathBuf),

Run the watcher with the provided callback.

This method runs forever, calling the callback for each matching event. The callback receives the event type and the path (relative or absolute depending on configuration).

If no include patterns are specified, watches everything.

pub async fn run_debounced<F>(self, ms: u64, callback: F) -> Result<()>

where F: FnMut(),

Run the watcher with debouncing.

Waits for file changes, then waits until no changes have occurred for at least ms milliseconds before calling the callback. This is useful for batching rapid changes (like when a build tool writes many files).

The callback takes no arguments since the specific paths are not tracked during debouncing.

Trait Implementations

impl Default for Watcher

fn default() -> Self

Returns the “default value” for a type.