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 (use `--watch` to override)
	* 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

Watch all files below `src` and subdirectories for changes, running `make test` when a change is detected:

    $ watchexec --watch src make test

Call `make test` when any file changes in this directory/subdirectory, except for everything below `target`:

    $ watchexec -i target make test

Call/restart `python server.py` when any Python file in the current directory (and all subdirectories) changes:

    $ watchexec -e py -r python server.py

Run `make` when any file changes, using the `.gitignore` file in the current directory to filter:

    $ watchexec make

##Installation

###Cargo (nightly Rust only)

If you're running nightly Rust, install it using cargo:

    $ cargo install watchexec

If you're using rustup, install it like this:

    $ rustup toolchain install nightly
    $ rustup run nightly cargo install watchexec

###OS X with Homebrew

    $ brew install https://raw.githubusercontent.com/mattgreen/watchexec/master/pkg/brew/watchexec.rb

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

Currently, **watchexec requires a recent nightly Rust** to build, due to use of unstable features.

##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`
Update README a little for CI 2016-10-15 16:25:37 +02:00			* Monitors current directory and all subdirectories for changes (use `--watch` to override)
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
Infer path, add -e option to monitor files based on file extensions 2016-09-23 19:59:57 +02:00			Watch all files below `src` and subdirectories for changes, running `make test` when a change is detected:
Update README for 0.8.0 2016-09-22 16:03:23 +02:00
Infer path, add -e option to monitor files based on file extensions 2016-09-23 19:59:57 +02:00			`$ watchexec --watch src make test`
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 -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`

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`

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

Add watcher module, back to requiring nightly builds 2016-10-20 20:27:11 +02:00			`###Cargo (nightly Rust only)`
Add Cargo instructions; closes #8 2016-10-18 03:26:01 +02:00
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			`If you're running nightly Rust, install it using cargo:`

Add Cargo instructions; closes #8 2016-10-18 03:26:01 +02:00			`$ cargo install watchexec`

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			`If you're using rustup, install it like this:`

			`$ rustup toolchain install nightly`
			`$ rustup run nightly cargo install watchexec`

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

Update brew install instructions to use repo-local formula 2016-09-26 14:04:56 +02:00			`$ brew install https://raw.githubusercontent.com/mattgreen/watchexec/master/pkg/brew/watchexec.rb`
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`

			`Currently, watchexec requires a recent nightly Rust to build, due to use of unstable features.`

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`