diff --git a/.gitattributes b/.gitattributes index 8d93c93..30b27be 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1 +1,3 @@ Cargo.lock merge=binary +doc/watchexec.* merge=binary +completions/* merge=binary diff --git a/crates/cli/src/args.rs b/crates/cli/src/args.rs index 974430a..1706f4c 100644 --- a/crates/cli/src/args.rs +++ b/crates/cli/src/args.rs @@ -16,7 +16,7 @@ include!(env!("BOSION_PATH")); /// change is detected (among other event sources). By default, watchexec uses efficient /// kernel-level mechanisms to watch for changes. /// -/// At startup, the specified is run once, and watchexec begins monitoring for changes. +/// At startup, the specified command is run once, and watchexec begins monitoring for changes. /// /// Examples: /// diff --git a/crates/events/README.md b/crates/events/README.md index 08a2516..070b285 100644 --- a/crates/events/README.md +++ b/crates/events/README.md @@ -9,8 +9,14 @@ _Watchexec's event types._ [docs]: https://docs.rs/watchexec-events [license]: ../../LICENSE -This is particularly useful if you're building a tool that runs under Watchexec, and want to easily -read its events (with `--emit-events-to=json-file` and `--emit-events-to=json-stdin`). +Fundamentally, events in watchexec have three purposes: + +1. To trigger the launch, restart, or other interruption of a process; +2. To be filtered upon according to whatever set of criteria is desired; +3. To carry information about what caused the event, which may be provided to the process. + +Outside of Watchexec, this library is particularly useful if you're building a tool that runs under +it, and want to easily read its events (with `--emit-events-to=json-file` and `--emit-events-to=json-stdin`). ```rust ,no_run use std::io::{stdin, Result}; diff --git a/crates/events/src/lib.rs b/crates/events/src/lib.rs index 5860db5..2705022 100644 --- a/crates/events/src/lib.rs +++ b/crates/events/src/lib.rs @@ -1,10 +1,4 @@ -//! Synthetic event type, derived from inputs, triggers actions. -//! -//! Fundamentally, events in watchexec have three purposes: -//! -//! 1. To trigger the launch, restart, or other interruption of a process; -//! 2. To be filtered upon according to whatever set of criteria is desired; -//! 3. To carry information about what caused the event, which may be provided to the process. +#![doc = include_str!("../README.md")] #[doc(inline)] pub use event::*; diff --git a/crates/ignore-files/src/discover.rs b/crates/ignore-files/src/discover.rs index 6126411..e5bcf22 100644 --- a/crates/ignore-files/src/discover.rs +++ b/crates/ignore-files/src/discover.rs @@ -23,7 +23,7 @@ use crate::{IgnoreFile, IgnoreFilter}; /// /// Importantly, this should be called from the origin of the project, not a subfolder. This /// function will not discover the project origin, and will not traverse parent directories. Use the -/// [`project::origins`](crate::project::origins) function for that. +/// `project-origins` crate for that. /// /// This function also does not distinguish between project folder types, and collects all files for /// all supported VCSs and other project types. Use the `applies_to` field to filter the results. diff --git a/crates/ignore-files/src/error.rs b/crates/ignore-files/src/error.rs index d16b2b2..b96eb98 100644 --- a/crates/ignore-files/src/error.rs +++ b/crates/ignore-files/src/error.rs @@ -33,7 +33,7 @@ pub enum Error { // TODO: extract glob error into diagnostic }, - /// Multiple related [`Error`]s. + /// Multiple related [`Error`](enum@Error)s. #[error("multiple: {0:?}")] #[diagnostic(code(ignore_file::set))] Multi(#[related] Vec), diff --git a/crates/ignore-files/src/filter.rs b/crates/ignore-files/src/filter.rs index 2f3893c..d05f426 100644 --- a/crates/ignore-files/src/filter.rs +++ b/crates/ignore-files/src/filter.rs @@ -14,7 +14,7 @@ use crate::{Error, IgnoreFile}; /// /// This reads and compiles ignore files, and should be used for handling ignore files. It's created /// with a project origin and a list of ignore files, and new ignore files can be added later -/// (unless [`finish`](IgnoreFilterer::finish()) is called). +/// (unless [`finish`](IgnoreFilter::finish()) is called). #[derive(Clone, Debug)] pub struct IgnoreFilter { origin: PathBuf, @@ -25,7 +25,7 @@ pub struct IgnoreFilter { impl IgnoreFilter { /// Create a new empty filterer. /// - /// Prefer [`new()`](IgnoreFilterer::new()) if you have ignore files ready to use. + /// Prefer [`new()`](IgnoreFilter::new()) if you have ignore files ready to use. pub fn empty(origin: impl AsRef) -> Self { let origin = origin.as_ref(); Self { @@ -37,7 +37,7 @@ impl IgnoreFilter { /// Read ignore files from disk and load them for filtering. /// - /// Use [`empty()`](IgnoreFilterer::empty()) if you want an empty filterer, + /// Use [`empty()`](IgnoreFilter::empty()) if you want an empty filterer, /// or to construct one outside an async environment. pub async fn new(origin: impl AsRef + Send, files: &[IgnoreFile]) -> Result { let origin = origin.as_ref(); @@ -219,8 +219,8 @@ impl IgnoreFilter { /// /// Returns `false` if the folder should be ignored. /// - /// Note that this is a slightly different implementation than the [`Filterer`] trait, as the - /// latter handles events with multiple associated paths. + /// Note that this is a slightly different implementation than watchexec's Filterer trait, as + /// the latter handles events with multiple associated paths. pub fn check_dir(&self, path: &Path) -> bool { let _span = trace_span!("check_dir", ?path).entered(); diff --git a/crates/lib/src/error/runtime.rs b/crates/lib/src/error/runtime.rs index 8907401..a13b395 100644 --- a/crates/lib/src/error/runtime.rs +++ b/crates/lib/src/error/runtime.rs @@ -9,6 +9,62 @@ use crate::{ /// Errors which _may_ be recoverable, transient, or only affect a part of the operation, and should /// be reported to the user and/or acted upon programatically, but will not outright stop watchexec. +/// +/// Some errors that are classified here are spurious and may be ignored; in general you should not +/// use the convenience print handlers for handling these errors beyond prototyping. For example, +/// "waiting on process" errors should not be printed to the user by default: +/// +/// ``` +/// # use std::convert::Infallible; +/// # use tracing::error; +/// # use watchexec::{config::InitConfig, ErrorHook, error::RuntimeError, handler::SyncFnHandler}; +/// # let mut config = InitConfig::default(); +/// config.on_error(SyncFnHandler::from( +/// |err: ErrorHook| -> std::result::Result<(), Infallible> { +/// if let RuntimeError::IoError { +/// about: "waiting on process group", +/// .. +/// } = err.error +/// { +/// error!("{}", err.error); +/// return Ok(()); +/// } +/// +/// // ... +/// +/// Ok(()) +/// }, +/// )); +/// ``` +/// +/// On the other hand, some errors may not be fatal to this library's understanding, but will be to +/// your application. In those cases, you should "elevate" these errors, which will transform them +/// to [`CriticalError`](super::CriticalError)s: +/// +/// ``` +/// # use std::convert::Infallible; +/// # use watchexec::{config::InitConfig, ErrorHook, error::{RuntimeError, FsWatcherError}, handler::SyncFnHandler}; +/// # let mut config = InitConfig::default(); +/// config.on_error(SyncFnHandler::from( +/// |err: ErrorHook| -> std::result::Result<(), Infallible> { +/// if let RuntimeError::FsWatcher { +/// err: +/// FsWatcherError::Create { .. } +/// | FsWatcherError::TooManyWatches { .. } +/// | FsWatcherError::TooManyHandles { .. }, +/// .. +/// } = err.error +/// { +/// err.elevate(); +/// return Ok(()); +/// } +/// +/// // ... +/// +/// Ok(()) +/// }, +/// )); +/// ``` #[derive(Debug, Diagnostic, Error)] #[non_exhaustive] #[diagnostic(url(docsrs))] diff --git a/crates/lib/src/lib.rs b/crates/lib/src/lib.rs index ca54af7..8915eff 100644 --- a/crates/lib/src/lib.rs +++ b/crates/lib/src/lib.rs @@ -88,9 +88,6 @@ //! printing even error log messages for this crate unless it's for debugging. Instead, make use of //! the [`InitConfig::on_error()`][config::InitConfig::on_error()] method to define a handler for //! errors occurring at runtime that are _meant_ for you to handle (by printing out or otherwise). -//! -//! This crate does not itself use `unsafe`. However, it depends on a number of libraries which do, -//! most because they interact with the operating system. #![doc(html_favicon_url = "https://watchexec.github.io/logo:watchexec.svg")] #![doc(html_logo_url = "https://watchexec.github.io/logo:watchexec.svg")] diff --git a/crates/signals/README.md b/crates/signals/README.md index 224b5ba..3249975 100644 --- a/crates/signals/README.md +++ b/crates/signals/README.md @@ -10,6 +10,7 @@ _Watchexec's signal type._ [license]: ../../LICENSE ```rust +use std::str::FromStr; use watchexec_signals::Signal; fn main() { diff --git a/crates/signals/src/lib.rs b/crates/signals/src/lib.rs index ac37d0f..969ec49 100644 --- a/crates/signals/src/lib.rs +++ b/crates/signals/src/lib.rs @@ -1,15 +1,4 @@ -//! Notifications (signals or Windows control events) sent to a process. -//! -//! This signal type in Watchexec is used for any of: -//! - signals sent to the main process by some external actor, -//! - signals received from a sub process by the main process, -//! - signals sent to a sub process by Watchexec. -//! -//! ## Features -//! -//! - `fromstr`: Enables parsing of signals from strings. -//! - `serde`: Enables [`serde`][serde] support. Note that this is stricter than string parsing. -//! - `miette`: Enables [`miette`][miette] support for [`SignalParseError`][SignalParseError]. +#![doc = include_str!("../README.md")] use std::fmt; @@ -19,7 +8,12 @@ use std::str::FromStr; #[cfg(unix)] use nix::sys::signal::Signal as NixSignal; -/// A notification sent to a process. +/// A notification (signals or Windows control events) sent to a process. +/// +/// This signal type in Watchexec is used for any of: +/// - signals sent to the main process by some external actor, +/// - signals received from a sub process by the main process, +/// - signals sent to a sub process by Watchexec. /// /// On Windows, only some signals are supported, as described. Others will be ignored. /// diff --git a/doc/watchexec.1 b/doc/watchexec.1 index 434c28d..afb8be2 100644 --- a/doc/watchexec.1 +++ b/doc/watchexec.1 @@ -10,7 +10,7 @@ Execute commands when watched files change. .PP Recursively monitors the current directory for changes, executing the command when a filesystem change is detected (among other event sources). By default, watchexec uses efficient kernel\-level mechanisms to watch for changes. .PP -At startup, the specified is run once, and watchexec begins monitoring for changes. +At startup, the specified command is run once, and watchexec begins monitoring for changes. .PP Examples: .PP diff --git a/doc/watchexec.1.md b/doc/watchexec.1.md index 9b4a3bd..bb7b0b3 100644 --- a/doc/watchexec.1.md +++ b/doc/watchexec.1.md @@ -30,7 +30,7 @@ command when a filesystem change is detected (among other event sources). By default, watchexec uses efficient kernel-level mechanisms to watch for changes. -At startup, the specified \ is run once, and watchexec begins +At startup, the specified command is run once, and watchexec begins monitoring for changes. Examples: diff --git a/doc/watchexec.1.pdf b/doc/watchexec.1.pdf index e3121a2..413afad 100644 Binary files a/doc/watchexec.1.pdf and b/doc/watchexec.1.pdf differ