Split readmes
This commit is contained in:
parent
6a0ac73547
commit
c517b98782
|
@ -107,7 +107,7 @@ jobs:
|
||||||
mkdir "$dst"
|
mkdir "$dst"
|
||||||
strip "$bin" || true
|
strip "$bin" || true
|
||||||
mv "$bin" "$dst/"
|
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)
|
- name: Archive (tar)
|
||||||
if: '! startsWith(matrix.name, ''windows-'')'
|
if: '! startsWith(matrix.name, ''windows-'')'
|
||||||
shell: bash
|
shell: bash
|
||||||
|
|
175
README.md
175
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)
|
[![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!
|
Software development often involves running the same commands over and over. Boring!
|
||||||
|
|
||||||
|
@ -13,169 +11,46 @@ Example use cases:
|
||||||
* Automatically run unit tests
|
* Automatically run unit tests
|
||||||
* Run linters/syntax checkers
|
* Run linters/syntax checkers
|
||||||
|
|
||||||
|
|
||||||
## Features
|
## 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
|
* Runs on OS X, Linux, and Windows
|
||||||
* Monitors current directory and all subdirectories for changes
|
* 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
|
* 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
|
* Loads `.gitignore` and `.ignore` files
|
||||||
* Support for watching files with a specific extension
|
* Uses process groups to keep hold of forking programs
|
||||||
* Support for filtering/ignoring events based on [glob patterns](https://docs.rs/globset/*/globset/#syntax)
|
* Provides the paths that changed in environment variables
|
||||||
* Launches the command in a new process group
|
* Does not require a language runtime, not tied to any particular language or ecosystem
|
||||||
* Sets the following environment variables in the process:
|
* [And more!](./cli/#features)
|
||||||
* 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
|
## Quick start
|
||||||
* 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 `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 -e js,css,html npm run build
|
||||||
|
|
||||||
$ 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:
|
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
|
- [watchexec library](./lib/): to create more specialised watchexec-powered tools! such as:
|
||||||
|
- [cargo watch](https://github.com/passcod/cargo-watch): for Rust/Cargo projects.
|
||||||
Run `bundle install` when the `Gemfile` changes:
|
- [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),
|
||||||
$ watchexec -w Gemfile bundle install
|
- [globset](https://crates.io/crates/globset): to match globs (third-party).
|
||||||
|
|
||||||
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
|
|
||||||
|
|
|
@ -11,7 +11,7 @@ categories = ["command-line-utilities"]
|
||||||
documentation = "https://github.com/watchexec/watchexec"
|
documentation = "https://github.com/watchexec/watchexec"
|
||||||
homepage = "https://github.com/watchexec/watchexec"
|
homepage = "https://github.com/watchexec/watchexec"
|
||||||
repository = "https://github.com/watchexec/watchexec"
|
repository = "https://github.com/watchexec/watchexec"
|
||||||
readme = "../README.md"
|
readme = "README.md"
|
||||||
|
|
||||||
edition = "2018"
|
edition = "2018"
|
||||||
|
|
||||||
|
|
|
@ -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`
|
|
@ -10,7 +10,7 @@ keywords = ["watcher", "filesystem", "watchexec"]
|
||||||
documentation = "https://github.com/watchexec/watchexec"
|
documentation = "https://github.com/watchexec/watchexec"
|
||||||
homepage = "https://github.com/watchexec/watchexec"
|
homepage = "https://github.com/watchexec/watchexec"
|
||||||
repository = "https://github.com/watchexec/watchexec"
|
repository = "https://github.com/watchexec/watchexec"
|
||||||
readme = "../README.md"
|
readme = "README.md"
|
||||||
|
|
||||||
edition = "2018"
|
edition = "2018"
|
||||||
|
|
||||||
|
|
|
@ -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)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
Loading…
Reference in New Issue