watchexec/README.md

# watchexec

[![Build Status](https://travis-ci.org/mattgreen/watchexec.svg?branch=master)](https://travis-ci.org/mattgreen/watchexec)
[![Build status](https://ci.appveyor.com/api/projects/status/ivxu31g4rcf4740t?svg=true)](https://ci.appveyor.com/project/mattgreen/watchexec)
[![Crates.io status](https://img.shields.io/crates/v/watchexec.svg)](https://crates.io/crates/watchexec)

Software development often involves running the same commands over and over. Boring!

`watchexec` is 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/passcod/rsnotify#todo))
* Coalesces multiple filesystem events into one, for editors that use swap/backup files during saving
* By default, uses `.gitignore` 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
* Launches child processes in a new process group
* Sets the following environment variables in the child process:
    * `$WATCHEXEC_UPDATED_PATH` the path of the first file that triggered a change
    * `$WATCHEXEC_COMMON_PATH` the longest common path of all of the files that triggered a change
* 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 child process:

    $ watchexec -r -s SIGKILL my_server

Send a SIGHUP to the child process upon changes (Note: with using `-n | --no-shell` 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

## Installation

### Cargo

watchexec requires Rust 1.9 or later. You can install it using cargo:

    $ cargo install watchexec

### OS X with Homebrew

    $ brew install watchexec

### Linux

For now, use the GitHub Releases tab to obtain the binary. PRs for packaging in various distros are welcomed.

### Windows

Use the GitHub Releases tab to obtain the binary. In the future, I'll look at adding it to Chocolatey.

## Building

Rust 1.9 or later is required.

## Credits

* [notify](https://github.com/passcod/rsnotify) for doing most of the heavy-lifting
* [globset](https://crates.io/crates/globset) for super-fast glob matching
Fix headers in Readme file. Just added spaces so the markdown recognises the headers. 2017-03-27 10:56:06 +02:00			`# watchexec`
Rename to watchexec 2016-09-18 22:42:11 +02:00
Add badges 2016-10-15 20:03:23 +02:00			`[![Build Status](https://travis-ci.org/mattgreen/watchexec.svg?branch=master)](https://travis-ci.org/mattgreen/watchexec)`
			`[![Build status](https://ci.appveyor.com/api/projects/status/ivxu31g4rcf4740t?svg=true)](https://ci.appveyor.com/project/mattgreen/watchexec)`
Add crates.io badge 2016-11-03 21:33:41 +01:00			`[![Crates.io status](https://img.shields.io/crates/v/watchexec.svg)](https://crates.io/crates/watchexec)`
Add badges 2016-10-15 20:03:23 +02:00
Rename to watchexec 2016-09-18 22:42:11 +02:00			`Software development often involves running the same commands over and over. Boring!`

			`watchexec` is 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`

Fix headers in Readme file. Just added spaces so the markdown recognises the headers. 2017-03-27 10:56:06 +02:00			`## Features`
Rename to watchexec 2016-09-18 22:42:11 +02:00
			`* Simple invocation and use`
			`* Runs on OS X, Linux and Windows`
Document dropped --watch option 2016-11-17 14:46:23 +01:00			`* Monitors current directory and all subdirectories for changes`
Infer path, add -e option to monitor files based on file extensions 2016-09-23 19:59:57 +02:00			`* Uses most efficient event polling mechanism for your platform (except for [BSD](https://github.com/passcod/rsnotify#todo))`
Rename to watchexec 2016-09-18 22:42:11 +02:00			`* Coalesces multiple filesystem events into one, for editors that use swap/backup files during saving`
Triggering appveyor to build 2016-10-15 16:47:35 +02:00			* By default, uses `.gitignore` to determine which files to ignore notifications for
Infer path, add -e option to monitor files based on file extensions 2016-09-23 19:59:57 +02:00			`* Support for watching files with a specific extension`
Update README for 0.8.0 2016-09-22 16:03:23 +02:00			`* Support for filtering/ignoring events based on glob patterns`
No need to use before_exec() to call setpgid() 2016-10-20 18:09:51 +02:00			`* Launches child processes in a new process group`
Creating method to update the watch_exec variable with the greatest common path found among the changed filepaths 2016-10-29 01:27:08 +02:00			`* Sets the following environment variables in the child process:`
			* `$WATCHEXEC_UPDATED_PATH` the path of the first file that triggered a change
			* `$WATCHEXEC_COMMON_PATH` the longest common path of all of the files that triggered a change
Rename to watchexec 2016-09-18 22:42:11 +02:00			`* Optionally clears screen between executions`
Add -r option to restart commands on subsequent events; closes #4 2016-09-24 19:52:54 +02:00			`* Optionally restarts the command with every modification (good for servers)`
Rename to watchexec 2016-09-18 22:42:11 +02:00			`* Does not require a language runtime`

Fix headers in Readme file. Just added spaces so the markdown recognises the headers. 2017-03-27 10:56:06 +02:00			`## Anti-Features`
Rename to watchexec 2016-09-18 22:42:11 +02:00
			`* Not tied to any particular language or ecosystem`
			* Does not require a cryptic command line involving `xargs`

Fix headers in Readme file. Just added spaces so the markdown recognises the headers. 2017-03-27 10:56:06 +02:00			`## Usage Examples`
Rename to watchexec 2016-09-18 22:42:11 +02:00
Infer path, add -e option to monitor files based on file extensions 2016-09-23 19:59:57 +02:00			Watch all JavaScript, CSS and HTML files in the current directory and all subdirectories for changes, running `make` when a change is detected:
Rename to watchexec 2016-09-18 22:42:11 +02:00
Infer path, add -e option to monitor files based on file extensions 2016-09-23 19:59:57 +02:00			`$ watchexec --exts js,css,html make`
Rename to watchexec 2016-09-18 22:42:11 +02:00
Update README for 0.8.0 2016-09-22 16:03:23 +02:00			Call `make test` when any file changes in this directory/subdirectory, except for everything below `target`:

Fix inconsistency in README 2016-10-17 20:55:28 +02:00			`$ watchexec -i target make test`
Rename to watchexec 2016-09-18 22:42:11 +02:00
Add example that uses --; closes #28 2016-12-15 01:45:31 +01:00			Call `ls -la` when any file changes in this directory/subdirectory:

			`$ watchexec -- ls -la`

Add -r option to restart commands on subsequent events; closes #4 2016-09-24 19:52:54 +02:00			Call/restart `python server.py` when any Python file in the current directory (and all subdirectories) changes:

			`$ watchexec -e py -r python server.py`

Add -k option to send SIGKILL instead of SIGTERM; closes #31 2016-12-19 17:37:12 +01:00			Call/restart `my_server` when any file in the current directory (and all subdirectories) changes, sending `SIGKILL` to stop the child process:

Adapt README to --signal option 2017-03-14 23:47:11 +01:00			`$ watchexec -r -s SIGKILL my_server`
Add -k option to send SIGKILL instead of SIGTERM; closes #31 2016-12-19 17:37:12 +01:00
Add documentation for --no-shell 2017-04-06 22:51:52 +02:00			Send a SIGHUP to the child process upon changes (Note: with using `-n \| --no-shell` here, we're executing `my_server` directly, instead of wrapping it in a shell:
Add SIGHUP example to README 2017-03-23 23:51:40 +01:00
Add documentation for --no-shell 2017-04-06 22:51:52 +02:00			`$ watchexec -n -s SIGHUP my_server`
Add SIGHUP example to README 2017-03-23 23:51:40 +01:00
Update README 2016-10-12 15:12:42 +02:00			Run `make` when any file changes, using the `.gitignore` file in the current directory to filter:

			`$ watchexec make`

Update docs for 1.7.0 2017-02-05 19:29:38 +01:00			Run `make` when any file in `lib` or `src` changes:

			`$ watchexec -w lib -w src make`

Fix headers in Readme file. Just added spaces so the markdown recognises the headers. 2017-03-27 10:56:06 +02:00			`## Installation`
Rename to watchexec 2016-09-18 22:42:11 +02:00
Fix headers in Readme file. Just added spaces so the markdown recognises the headers. 2017-03-27 10:56:06 +02:00			`### Cargo`
Add Cargo instructions; closes #8 2016-10-18 03:26:01 +02:00
Update README 2016-11-23 19:11:25 +01:00			`watchexec requires Rust 1.9 or later. You can install it using cargo:`
README: Add rustup command for installing with nightly I had to figure out how to install watchexec with nightly using rustup. A lot of people are probably not familiar with it, so include the commands. 2016-10-26 03:16:33 +02:00
Add Cargo instructions; closes #8 2016-10-18 03:26:01 +02:00			`$ cargo install watchexec`

Fix headers in Readme file. Just added spaces so the markdown recognises the headers. 2017-03-27 10:56:06 +02:00			`### OS X with Homebrew`
Add Homebrew link 2016-09-19 18:49:18 +02:00
Update Homebrew instructions 2017-01-19 17:35:38 +01:00			`$ brew install watchexec`
Rename to watchexec 2016-09-18 22:42:11 +02:00
Fix headers in Readme file. Just added spaces so the markdown recognises the headers. 2017-03-27 10:56:06 +02:00			`### Linux`
Add install instructions for non-macOS users 2016-10-17 17:53:43 +02:00
			`For now, use the GitHub Releases tab to obtain the binary. PRs for packaging in various distros are welcomed.`

Fix headers in Readme file. Just added spaces so the markdown recognises the headers. 2017-03-27 10:56:06 +02:00			`### Windows`
Add install instructions for non-macOS users 2016-10-17 17:53:43 +02:00
			`Use the GitHub Releases tab to obtain the binary. In the future, I'll look at adding it to Chocolatey.`

Fix headers in Readme file. Just added spaces so the markdown recognises the headers. 2017-03-27 10:56:06 +02:00			`## Building`
Add watcher module, back to requiring nightly builds 2016-10-20 20:27:11 +02:00
Update README 2016-11-23 19:11:25 +01:00			`Rust 1.9 or later is required.`
Add watcher module, back to requiring nightly builds 2016-10-20 20:27:11 +02:00
Fix headers in Readme file. Just added spaces so the markdown recognises the headers. 2017-03-27 10:56:06 +02:00			`## Credits`
Rename to watchexec 2016-09-18 22:42:11 +02:00
Add Homebrew link 2016-09-19 18:49:18 +02:00			`* [notify](https://github.com/passcod/rsnotify) for doing most of the heavy-lifting`
Update credits 2016-11-09 03:57:09 +01:00			`* [globset](https://crates.io/crates/globset) for super-fast glob matching`