watchexec/lib

Watchexec library

The library which powers Watchexec CLI and other tools.

• API documentation.
• Licensed under Apache 2.0.
• Minimum Supported Rust Version: 1.56.0.
• Status: in preview (2.0.0-pre.N series).

Quick start

use miette::{IntoDiagnostic, Result};
use watchexec::{
    Watchexec,
    action::{Action, Outcome},
    config::{InitConfig, RuntimeConfig},
    handler::{Handler as _, PrintDebug},
};

#[tokio::main]
async fn main() -> Result<()> {
    let mut init = InitConfig::default();
    init.on_error(PrintDebug(std::io::stderr()));

    let mut runtime = RuntimeConfig::default();
    runtime.pathset(["watchexec.conf"]);

    let conf = YourConfigFormat::load_from_file("watchexec.conf").await?;
    conf.apply(&mut runtime);

    let we = Watchexec::new(init, runtime.clone())?;
    let w = we.clone();

    let c = runtime.clone();
    runtime.on_action(move |action: Action| {
        let mut c = c.clone();
        let w = w.clone();
        async move {
            for event in &action.events {
                if event.paths().any(|(p, _)| p.ends_with("/watchexec.conf")) {
                    let conf = YourConfigFormat::load_from_file("watchexec.conf").await?;

                    conf.apply(&mut c);
                    w.reconfigure(c.clone());
                    // tada! self-reconfiguring watchexec on config file change!

                    break;
                }
            }

            action.outcome(Outcome::if_running(
                Outcome::DoNothing,
                Outcome::both(Outcome::Clear, Outcome::Start),
            ));

            Ok(())
        }
    });

    we.main().await.into_diagnostic()?;
    Ok(())
}

Kitchen sink

The library also exposes a large amount of components which are available to make your own tool, or to make anything else you may want:

• Command handling, to build a command with an arbitrary shell, deal with grouped and ungrouped processes the same way, and supervise a process while also listening for & acting on interventions such as sending signals.

• Event sources: Filesystem, Signals, (more to come).

• Finding a common prefix of a set of paths.

• Detecting the origin(s) and types of projects.

• Discovering project-local and global ignore files.

There are also separate, standalone crates used to build Watchexec which you can tap into:

• ClearScreen makes clearing the terminal screen in a cross-platform way easy by default, and provides advanced options to fit your usecase.

• Command Group augments the std and tokio Command with support for process groups, portable between Unix and Windows.

Tagged filters (alpha)

This library is also the home of Watchexec's current two filtering implementations: the v1 behaviour which has proven confusing and inconsistent over the years, and an upcoming complete overhaul called "tagged filtering."

Have a look at the docs!