diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 30bf204..e7c7367 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -107,7 +107,7 @@ jobs: mkdir "$dst" strip "$bin" || true mv "$bin" "$dst/" - mv README.md LICENSE completions doc/watchexec.1{,.html} "$dst/" + mv cli/README.md LICENSE completions doc/watchexec.1{,.html} "$dst/" - name: Archive (tar) if: '! startsWith(matrix.name, ''windows-'')' shell: bash diff --git a/README.md b/README.md index f222cc3..ff2d425 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,6 @@ -# watchexec - [![CI status](https://github.com/watchexec/watchexec/actions/workflows/check.yml/badge.svg)](https://github.com/watchexec/watchexec/actions/workflows/check.yml) -[![Crates.io status](https://badgen.net/crates/v/watchexec)](https://crates.io/crates/watchexec) -[![Docs status](https://docs.rs/watchexec/badge.svg)](https://docs.rs/watchexec) + +# Watchexec Software development often involves running the same commands over and over. Boring! @@ -13,169 +11,46 @@ Example use cases: * Automatically run unit tests * Run linters/syntax checkers + ## Features -* Simple invocation and use +* Simple invocation and use, does not require a cryptic command line involving `xargs` * Runs on OS X, Linux, and Windows * Monitors current directory and all subdirectories for changes - * Uses most efficient event polling mechanism for your platform (except for [BSD](https://github.com/notify-rs/notify#todo)) * Coalesces multiple filesystem events into one, for editors that use swap/backup files during saving -* By default, uses `.gitignore` and `.ignore` to determine which files to ignore notifications for -* Support for watching files with a specific extension -* Support for filtering/ignoring events based on [glob patterns](https://docs.rs/globset/*/globset/#syntax) -* Launches the command in a new process group -* Sets the following environment variables in the process: - * If a single file changed (depending on the event type): - * `$WATCHEXEC_CREATED_PATH`, the path of the file that was created - * `$WATCHEXEC_REMOVED_PATH`, the path of the file that was removed - * `$WATCHEXEC_RENAMED_PATH`, the path of the file that was renamed - * `$WATCHEXEC_WRITTEN_PATH`, the path of the file that was modified - * `$WATCHEXEC_META_CHANGED_PATH`, the path of the file whose metadata changed - * If multiple files changed: - * `$WATCHEXEC_COMMON_PATH`, the longest common path of all of the files that triggered a change - * This can be disabled or limited with `--no-environment` and `--no-meta` -* Optionally clears screen between executions -* Optionally restarts the command with every modification (good for servers) -* Does not require a language runtime +* Loads `.gitignore` and `.ignore` files +* Uses process groups to keep hold of forking programs +* Provides the paths that changed in environment variables +* Does not require a language runtime, not tied to any particular language or ecosystem +* [And more!](./cli/#features) -## Anti-Features -* Not tied to any particular language or ecosystem -* Does not require a cryptic command line involving `xargs` +## Quick start -## Usage Examples +Watch all JavaScript, CSS and HTML files in the current directory and all subdirectories for changes, running `npm run build` when a change is detected: -Watch all JavaScript, CSS and HTML files in the current directory and all subdirectories for changes, running `make` when a change is detected: - - $ watchexec --exts js,css,html make - -Call `make test` when any file changes in this directory/subdirectory, except for everything below `target`: - - $ watchexec -i target make test - -Call `ls -la` when any file changes in this directory/subdirectory: - - $ watchexec -- ls -la + $ watchexec -e js,css,html npm run build Call/restart `python server.py` when any Python file in the current directory (and all subdirectories) changes: - $ watchexec -e py -r python server.py + $ watchexec -r -e py -- python server.py -Call/restart `my_server` when any file in the current directory (and all subdirectories) changes, sending `SIGKILL` to stop the command: +More usage examples: [in the CLI README](./cli/#usage-examples)! - $ watchexec -r -s SIGKILL my_server -Send a SIGHUP to the command upon changes (Note: using `-n` here we're executing `my_server` directly, instead of wrapping it in a shell: +## Install - $ watchexec -n -s SIGHUP my_server +- As pre-built binary: https://github.com/watchexec/watchexec/releases +- With your package manager for Arch, Homebrew, Nix, Scoop, Chocolatey… +- From source with Cargo: `cargo install watchexec-cli` -Run `make` when any file changes, using the `.gitignore` file in the current directory to filter: +All options in detail: [in the CLI README](./cli/#installation). - $ watchexec make -Run `make` when any file in `lib` or `src` changes: +## Extend - $ watchexec -w lib -w src make - -Run `bundle install` when the `Gemfile` changes: - - $ watchexec -w Gemfile bundle install - -Run two commands: - - $ watchexec 'date; make' - -If you come from `entr`, note that the watchexec command is run in a shell by default. You can use `-n` or `--shell=none` to not do that: - - $ watchexec -n -- echo ';' lorem ipsum - -On Windows, you may prefer to use Powershell: - - $ watchexec --shell=powershell -- test-connection localhost - -## Installation - -### All platforms - -#### Cargo - -Requires Rust 1.43 or later. - - # From 1.16.0: - $ cargo install watchexec-cli - - # Until 1.15.3: - $ cargo install watchexec - -#### [Binstall](https://github.com/ryankurte/cargo-binstall) - - # From 1.16.0: - $ cargo binstall watchexec-cli - - # Until 1.15.3: - $ cargo binstall watchexec - -#### Pre-built - -Use the GitHub Releases tab to obtain the tarball/zipfile appropriate for your platform and architecture, extract it, and place it in your `PATH`. - -### macOS - -#### Homebrew - - $ brew install watchexec - -#### Nix - - $ nix-env -iA nixpkgs.watchexec - -#### Webi - - $ curl -sS https://webinstall.dev/watchexec | bash - -### Linux - -PRs for packaging in unsupported distros are welcome. - -#### Debian - -A deb package is available for several architectures in the GitHub Releases. - -#### Arch Linux - -Available in the **community** repository: - - $ pacman -S watchexec - -#### NixOS - - $ nix-env -iA nixos.watchexec - -#### Webi - - $ curl -sS https://webinstall.dev/watchexec/ | bash - -### Windows - -#### Scoop - - #> scoop install watchexec - -#### Chocolatey - - #> choco install watchexec - -#### Webi - - #> curl.exe -A MS https://webinstall.dev/watchexec | powershell - -## Shell completions - -Currently available shell completions: - -- zsh: `completions/zsh` should be installed to `/usr/share/zsh/site-functions/_watchexec` - -## Credits - -* [notify](https://github.com/passcod/notify) for doing most of the heavy-lifting -* [globset](https://crates.io/crates/globset) for super-fast glob matching +- [watchexec library](./lib/): to create more specialised watchexec-powered tools! such as: + - [cargo watch](https://github.com/passcod/cargo-watch): for Rust/Cargo projects. +- [clearscreen](https://github.com/watchexec/clearscreen): to clear the (terminal) screen on every platform. +- [notify](https://github.com/notify-rs/notify): to respond to file modifications (third-party), +- [globset](https://crates.io/crates/globset): to match globs (third-party). diff --git a/cli/Cargo.toml b/cli/Cargo.toml index f2208e6..76f6abd 100644 --- a/cli/Cargo.toml +++ b/cli/Cargo.toml @@ -11,7 +11,7 @@ categories = ["command-line-utilities"] documentation = "https://github.com/watchexec/watchexec" homepage = "https://github.com/watchexec/watchexec" repository = "https://github.com/watchexec/watchexec" -readme = "../README.md" +readme = "README.md" edition = "2018" diff --git a/cli/README.md b/cli/README.md new file mode 100644 index 0000000..43db3d1 --- /dev/null +++ b/cli/README.md @@ -0,0 +1,162 @@ +# Watchexec CLI + +A simple standalone tool that watches a path and runs a command whenever it detects modifications. + +Example use cases: + +* Automatically run unit tests +* Run linters/syntax checkers + +## Features + +* Simple invocation and use +* Runs on OS X, Linux, and Windows +* Monitors current directory and all subdirectories for changes + * Uses most efficient event polling mechanism for your platform (except for [BSD](https://github.com/notify-rs/notify#todo)) +* Coalesces multiple filesystem events into one, for editors that use swap/backup files during saving +* By default, uses `.gitignore` and `.ignore` to determine which files to ignore notifications for +* Support for watching files with a specific extension +* Support for filtering/ignoring events based on [glob patterns](https://docs.rs/globset/*/globset/#syntax) +* Launches the command in a new process group +* Sets the following environment variables in the process: + * If a single file changed (depending on the event type): + * `$WATCHEXEC_CREATED_PATH`, the path of the file that was created + * `$WATCHEXEC_REMOVED_PATH`, the path of the file that was removed + * `$WATCHEXEC_RENAMED_PATH`, the path of the file that was renamed + * `$WATCHEXEC_WRITTEN_PATH`, the path of the file that was modified + * `$WATCHEXEC_META_CHANGED_PATH`, the path of the file whose metadata changed + * If multiple files changed: + * `$WATCHEXEC_COMMON_PATH`, the longest common path of all of the files that triggered a change + * This can be disabled or limited with `--no-environment` and `--no-meta` +* Optionally clears screen between executions +* Optionally restarts the command with every modification (good for servers) +* Does not require a language runtime + +## Anti-Features + +* Not tied to any particular language or ecosystem +* Does not require a cryptic command line involving `xargs` + +## Usage Examples + +Watch all JavaScript, CSS and HTML files in the current directory and all subdirectories for changes, running `make` when a change is detected: + + $ watchexec --exts js,css,html make + +Call `make test` when any file changes in this directory/subdirectory, except for everything below `target`: + + $ watchexec -i target make test + +Call `ls -la` when any file changes in this directory/subdirectory: + + $ watchexec -- ls -la + +Call/restart `python server.py` when any Python file in the current directory (and all subdirectories) changes: + + $ watchexec -e py -r python server.py + +Call/restart `my_server` when any file in the current directory (and all subdirectories) changes, sending `SIGKILL` to stop the command: + + $ watchexec -r -s SIGKILL my_server + +Send a SIGHUP to the command upon changes (Note: using `-n` here we're executing `my_server` directly, instead of wrapping it in a shell: + + $ watchexec -n -s SIGHUP my_server + +Run `make` when any file changes, using the `.gitignore` file in the current directory to filter: + + $ watchexec make + +Run `make` when any file in `lib` or `src` changes: + + $ watchexec -w lib -w src make + +Run `bundle install` when the `Gemfile` changes: + + $ watchexec -w Gemfile bundle install + +Run two commands: + + $ watchexec 'date; make' + +If you come from `entr`, note that the watchexec command is run in a shell by default. You can use `-n` or `--shell=none` to not do that: + + $ watchexec -n -- echo ';' lorem ipsum + +On Windows, you may prefer to use Powershell: + + $ watchexec --shell=powershell -- test-connection localhost + +## Installation + +### All platforms + +#### Cargo + +Requires Rust 1.43 or later. + + $ cargo install watchexec-cli + +#### [Binstall](https://github.com/ryankurte/cargo-binstall) + + $ cargo binstall watchexec-cli + +#### Pre-built + +Use the GitHub Releases tab to obtain the tarball/zipfile appropriate for your platform and architecture, extract it, and place it in your `PATH`. + +### macOS + +#### Homebrew + + $ brew install watchexec + +#### Nix + + $ nix-env -iA nixpkgs.watchexec + +#### Webi + + $ curl -sS https://webinstall.dev/watchexec | bash + +### Linux + +PRs for packaging in unsupported distros are welcome. + +#### Debian + +A deb package is available for several architectures in the GitHub Releases. + +#### Arch Linux + +Available in the **community** repository: + + $ pacman -S watchexec + +#### NixOS + + $ nix-env -iA nixos.watchexec + +#### Webi + + $ curl -sS https://webinstall.dev/watchexec/ | bash + +### Windows + +#### Scoop + + #> scoop install watchexec + +#### Chocolatey + + #> choco install watchexec + +#### Webi + + #> curl.exe -A MS https://webinstall.dev/watchexec | powershell + +## Shell completions + +Currently available shell completions: + +- zsh: `completions/zsh` should be installed to `/usr/share/zsh/site-functions/_watchexec` diff --git a/lib/Cargo.toml b/lib/Cargo.toml index b70751a..36275a8 100644 --- a/lib/Cargo.toml +++ b/lib/Cargo.toml @@ -10,7 +10,7 @@ keywords = ["watcher", "filesystem", "watchexec"] documentation = "https://github.com/watchexec/watchexec" homepage = "https://github.com/watchexec/watchexec" repository = "https://github.com/watchexec/watchexec" -readme = "../README.md" +readme = "README.md" edition = "2018" diff --git a/lib/README.md b/lib/README.md new file mode 100644 index 0000000..22ccb4d --- /dev/null +++ b/lib/README.md @@ -0,0 +1,62 @@ +[![Crates.io page](https://badgen.net/crates/v/watchexec)](https://crates.io/crates/watchexec) +[![API Docs](https://docs.rs/watchexec/badge.svg)][docs] +[![Crate license: Apache 2.0](https://badgen.net/badge/license/Apache%202.0)][license] +![MSRV: 1.43.0 (breaking)](https://badgen.net/badge/MSRV/1.43.0%20%28breaking%29/green) +[![CI status](https://github.com/watchexec/watchexec/actions/workflows/check.yml/badge.svg)](https://github.com/watchexec/watchexec/actions/workflows/check.yml) + +# Watchexec library + +_The library which powers [Watchexec CLI](https://github.com/watchexec/watchexec) and other tools._ + +- **[API documentation][docs]**. +- Licensed under [Apache 2.0][license]. +- Minimum Supported Rust Version: 1.43.0. + +[docs]: https://docs.rs/watchexec +[license]: ../LICENSE + + +## Quick start + +```rust +use watchexec::{ + config::ConfigBuilder, + error::Result, + pathop::PathOp, + run::{ + ExecHandler, + Handler, + watch, + }, +}; + +fn main() -> Result<()> { + let config = ConfigBuilder::default() + .clear_screen(true) + .run_initially(true) + .paths(vec![ "/path/to/dir".into() ]) + .cmd(vec![ "date; seq 1 10".into() ]) + .build()?; + + let handler = MyHandler(ExecHandler::new(options)?); + watch(&handler) +} + +struct MyHandler(ExecHandler); + +impl Handler for MyHandler { + fn args(&self) -> Config { + self.0.args() + } + + fn on_manual(&self) -> Result { + println!("Running manually!"); + self.0.on_manual() + } + + fn on_update(&self, ops: &[PathOp]) -> Result { + println!("Running manually {:?}", ops); + self.0.on_update(ops) + } +} +```