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 -k 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
Rename to watchexec 2016-09-18 22:42:11 +02:00			`#watchexec`

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`

			`##Features`

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

			`##Anti-Features`

			`* Not tied to any particular language or ecosystem`
			* Does not require a cryptic command line involving `xargs`

Infer path, add -e option to monitor files based on file extensions 2016-09-23 19:59:57 +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:

			`$ watchexec -r -k my_server`

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`

Rename to watchexec 2016-09-18 22:42:11 +02:00			`##Installation`

Update README 2016-11-23 19:11:25 +01: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`

Add Homebrew link 2016-09-19 18:49:18 +02:00			`###OS X with Homebrew`

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
Add install instructions for non-macOS users 2016-10-17 17:53:43 +02:00			`###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.`

Add watcher module, back to requiring nightly builds 2016-10-20 20:27:11 +02:00			`##Building`

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
Rename to watchexec 2016-09-18 22:42:11 +02:00			`##Credits`

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`