Robot
/
watchexec
mirror of https://github.com/watchexec/watchexec.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Split readmes

This commit is contained in:
Félix Saparelli 2021-05-09 03:39:13 +12:00
parent 6a0ac73547
commit c517b98782
6 changed files with 252 additions and 153 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/release.yml vendored
View File

@ -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

175
README.md
View File

@ -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).

2
cli/Cargo.toml
View File

@ -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"

162
cli/README.md Normal file
View File

@ -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`

2
lib/Cargo.toml
View File

@ -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"

62
lib/README.md Normal file
View File

@ -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<bool> {
println!("Running manually!");
self.0.on_manual()
}
fn on_update(&self, ops: &[PathOp]) -> Result<bool> {
println!("Running manually {:?}", ops);
self.0.on_update(ops)
}
}
```