php-spark/plugins/com.noccy.watcher/README.md

# Watcher Plugin for Spark

Note: While the plugin currently supports wildcards, it does not scale well.
Keep the watched files to a minimum or increase the interval if you experience
issues.

## Usage

    $ spark watch

## Installation

1. Install Spark with global plugins
2. Initialize your project: `spark init`
3. Enable the plugin with `spark plugin --enable com.noccy.watcher`
4. Configure your `.spark/watchers.json` file

## Configuration

*watchers.json*

```json
{
  "watchers": [
    {
      "name": "name-of-rule",
      "watch": [ "file1", "dir1/*" ],
      "initial-trigger": true,
      "actions": [
        "@build"
      ]
    }
  ]
}
```

- `name` contains an optional name of the rule.
- `initial-trigger` controls whether the rule is triggered on startup. If false
  or not specified, the actions will be triggered when the file is modified
  after startup.
- `watch` is an array of files or wildcards to watch.
- `actions` are script actions to invoke.

The executed action will have access to the `WATCHER_RULE` and `WATCHER_FILES`
variables for expansion.

## Known issues

- The *inotify* monitor will trigger whenever a file is changed in a watched
  directory, even if an explicit file is set. For example, changing the file
  `./templates/index.html` will trigger the rule for `./templates/style.scss`.
  If you can't live with that, export `SPARK_NO_INOTIFY=1` before invoking!
- The *mtime* monitor will poll the mtime of each watched file every check.
  This works great if you are explicit in what you are watching.