Merge pull request #1590 from bradlc/glob

Add `glob` message property documentation

docs/guidelines/plugin.md

@@ -222,13 +222,17 @@ result.messages.push({
 })
 ```
 
-Specify recursive directory dependencies using the `dir-dependency` message type:
+Directory dependencies should be specified using the `dir-dependency` message
+type. By default all files within the directory (recursively) are considered
+dependencies. An optional `glob` property can be used to indicate that only
+files matching a specific glob pattern should be considered.
 
 ```js
 result.messages.push({
   type: 'dir-dependency',
   plugin: 'postcss-import',
   dir: '/imported',
+  glob: '**/*.css', // optional
   parent: result.opts.from
 })
 ```

docs/guidelines/runner.md

@@ -77,7 +77,7 @@ is described in [API docs].
 
 PostCSS plugins may declare file or directory dependencies by attaching
 messages to the `result`. Runners should watch these and ensure that the
-CSS is rebuilt when they change. Directories should be watched recursively.
+CSS is rebuilt when they change.
 
 ```js
 for (let message of result.messages) {
@@ -89,6 +89,12 @@ for (let message of result.messages) {
 }
 ```
 
+Directories should be watched recursively by default, but `dir-dependency`
+messages may contain an optional `glob` property indicating which files
+within the directory are depended on (e.g. `**/*.css`). If `glob` is
+specified then runners should only watch files matching the glob pattern,
+where possible.
+
 
 ## 4. Output