diff --git a/docs/api/watch.md b/docs/api/watch.md
index 002d7a1de..857d10b49 100644
--- a/docs/api/watch.md
+++ b/docs/api/watch.md
@@ -5,105 +5,133 @@ hide_title: true
sidebar_label: watch()
-->
-# `gulp.watch(globs[, opts][, fn])`
+# watch()
-Takes a path string, an array of path strings, a [glob][node-glob] string or an array of [glob][node-glob] strings as `globs` to watch on the filesystem. Also optionally takes `options` to configure the watcher and a `fn` to execute when a file changes.
+Allows watching globs and running a task when a change occurs. Tasks are handled uniformly with the rest of the task system.
-Returns an instance of [`chokidar`][chokidar].
+## Usage
```js
-gulp.watch('js/**/*.js', gulp.parallel('concat', 'uglify'));
+const { watch } = require('gulp');
+
+watch(['input/*.js', '!input/something.js'], function(cb) {
+ // body omitted
+ cb();
+});
```
-In the example, `gulp.watch` runs the function returned by `gulp.parallel` each
-time a file with the `js` extension in `js/` is updated.
+## Signature
+
+```js
+watch(globs, [options], [task])
+```
-## globs
-Type: `String` or `Array`
+### Parameters
-A path string, an array of path strings, a [glob][node-glob] string or an array of [glob][node-glob] strings that indicate which files to watch for changes.
+| parameter | type | note |
+|:--------------:|:-----:|--------|
+| globs
**(required)** | string
array | [Globs][globs-concepts] to watch on the file system. |
+| options | object | Detailed in [Options][options-section] below. |
+| task | function
string | A [task function][tasks-concepts] or composed task - generated by `series()` and `parallel()`. |
-## opts
-Type: `Object`
+### Returns
-* `delay` (milliseconds, default: `200`). The delay to wait before triggering the fn. Useful for waiting on many changes before doing the work on changed files, e.g. find-and-replace on many files.
-* `queue` (boolean, default: `true`). Whether or not a file change should queue the fn execution if the fn is already running. Useful for a long running fn.
-* `ignoreInitial` (boolean, default: `true`). If set to `false` the `fn` is called during [chokidar][chokidar] instantiation as it discovers the file paths. Useful if it is desirable to trigger the `fn` during startup. __Passed through to [chokidar][chokidar], but defaulted to `true` instead of `false`.__
+An instance of [chokidar][chokidar-instance-section] for fine-grained control over your watch setup.
-Options that are passed to [`chokidar`][chokidar].
+### Errors
-Commonly used options:
+When a non-string or array with any non-strings is passed as `globs`, throws an error with the message, "Non-string provided as watch path".
-* `ignored` ([anymatch](https://github.com/es128/anymatch)-compatible definition).
-Defines files/paths to be excluded from being watched.
-* `usePolling` (boolean, default: `false`). When `true` uses a watch method backed
-by stat polling. Usually necessary when watching files on a network mount or on a
-VMs file system.
-* `cwd` (path string). The base directory from which watch paths are to be
-derived. Paths emitted with events will be relative to this.
-* `alwaysStat` (boolean, default: `false`). If relying upon the
-[`fs.Stats`][fs stats] object
-that may get passed as a second argument with `add`, `addDir`, and `change` events
-when available, set this to `true` to ensure it is provided with every event. May
-have a slight performance penalty.
+When a string or array is passed as `task`, throws an error with the message, "watch task has to be a function (optionally generated by using gulp.parallel or gulp.series)".
-Read about the full set of options in [`chokidar`'s README][chokidar].
+### Options
-## fn
-Type: `Function`
-If the `fn` is passed, it will be called when the watcher emits a `change`, `add` or `unlink` event. It is automatically debounced with a default delay of 200 milliseconds and subsequent calls will be queued and called upon completion. These defaults can be changed using the `options`.
+| name | type | default | note |
+|:-------:|:------:|-----------|--------|
+| ignoreInitial | boolean | true | If false, the task is called during instantiation as file paths are discovered. Use to trigger the task during startup.
**Note:** This option is passed to [chokidar][chokidar-external] but is defaulted to `true` instead of `false`. |
+| delay | number | 200 | The millisecond delay between a file change and task execution. Allows for waiting on many changes before executing a task, e.g. find-and-replace on many files. |
+| queue | boolean | true | When true and the task is already running, any file changes will queue a single task execution. Keeps long running tasks from overlapping. |
+| events | string
array | [ 'add',
'change',
'unlink' ] | The events being watched to trigger task execution. Can be `'add'`, `'addDir'`, `'change'`, `'unlink'`, `'unlinkDir'`, `'ready'`, and/or `'error'`. Additionally `'all'` is available, which represents all events other than `'ready'` and `'error'`.
_This option is passed directly to [chokidar][chokidar-external]._ |
+| persistent | boolean | true | If false, the watcher will not keep the Node process running. Disabling this option is not recommended.
_This option is passed directly to [chokidar][chokidar-external]._ |
+| ignored | array
string
RegExp
function | | Defines globs to be ignored. If a function is provided, it will be called twice per path - once with just the path, then with the path and the `fs.Stats` object of that file.
_This option is passed directly to [chokidar][chokidar-external]._ |
+| followSymlinks | boolean | true | When true, changes to both symbolic links and the linked files trigger events. If false, only changes to the symbolic links trigger events.
_This option is passed directly to [chokidar][chokidar-external]._ |
+| cwd | string | | The directory that will be combined with any relative path to form an absolute path. Is ignored for absolute paths. Use to avoid combining `globs` with `path.join()`.
_This option is passed directly to [chokidar][chokidar-external]._ |
+| disableGlobbing | boolean | false | If true, all `globs` are treated as literal path names, even if they have special characters.
_This option is passed directly to [chokidar][chokidar-external]._ |
+| usePolling | boolean | false | When false, the watcher will use `fs.watch()` (or [fsevents][fsevents-external] on Mac) for watching. If true, use `fs.watchFile()` polling instead - needed for successfully watching files over a network or other non-standard situations. Overrides the `useFsEvents` default.
_This option is passed directly to [chokidar][chokidar-external]._ |
+| interval | number | 100 | Combine with `usePolling: true`. Interval of file system polling.
_This option is passed directly to [chokidar][chokidar-external]._ |
+| binaryInterval | number | 300 | Combine with `usePolling: true`. Interval of file system polling for binary files.
_This option is passed directly to [chokidar][chokidar-external]._ |
+| useFsEvents | boolean | true | When true, uses fsevents for watching if available. If explicitly set to true, supersedes the `usePolling` option. If set to false, automatically sets `usePolling` to true.
_This option is passed directly to [chokidar][chokidar-external]._ |
+| alwaysStat | boolean | false | If true, always calls `fs.stat()` on changed files - will slow down file watcher. The `fs.Stat` object is only available if you are using the chokidar instance directly.
_This option is passed directly to [chokidar][chokidar-external]._ |
+| depth | number | | Indicates how many nested levels of directories will be watched.
_This option is passed directly to [chokidar][chokidar-external]._ |
+| awaitWriteFinish | boolean | false | Do not use this option, use `delay` instead.
_This option is passed directly to [chokidar][chokidar-external]._ |
+| ignorePermissionErrors | boolean | false | Set to true to watch files that don't have read permissions. Then, if watching fails due to EPERM or EACCES errors, they will be skipped silently.
_This option is passed directly to [chokidar][chokidar-external]._ |
+| atomic | number | 100 | Only active if `useFsEvents` and `usePolling` are false. Automatically filters out artifacts that occur from "atomic writes" by some editors. If a file is re-added within the specified milliseconds of being deleted, a change event - instead of unlink then add - will be emitted.
_This option is passed directly to [chokidar][chokidar-external]._ |
-The `fn` is passed a single argument, `callback`, which is a function that must be called when work in the `fn` is complete. Instead of calling the `callback` function, [async completion][async-completion] can be signalled by:
- * Returning a `Stream` or `EventEmitter`
- * Returning a `Child Process`
- * Returning a `Promise`
- * Returning an `Observable`
+## Chokidar instance
-Once async completion is signalled, if another run is queued, it will be executed.
+The `watch()` method returns the underlying instance of [chokidar][chokidar-external], providing fine-grained control over your watch setup. Most commonly used to register individual event handlers that provide the `path` or `stats` of the changed files.
-`gulp.watch` returns a wrapped [chokidar] FSWatcher object. Listeners can also be set directly for any of [chokidar]'s events, such as `addDir`, `unlinkDir`, and `error`. You must set listeners directly to get
-access to chokidar's callback parameters, such as `path`.
+**When using the chokidar instance directly, you will not have access to the task system integrations, including async completion, queueing, and delay.**
```js
-var watcher = gulp.watch('js/**/*.js', gulp.parallel('concat', 'uglify'));
+const { watch } = require('gulp');
+
+const watcher = watch(['input/*.js']);
+
watcher.on('change', function(path, stats) {
- console.log('File ' + path + ' was changed');
+ console.log(`File ${path} was changed`);
+});
+
+watcher.on('add', function(path, stats) {
+ console.log(`File ${path} was added`);
});
-watcher.on('unlink', function(path) {
- console.log('File ' + path + ' was removed');
+watcher.on('unlink', function(path, stats) {
+ console.log(`File ${path} was removed`);
});
+
+watcher.close();
```
-### path
-Type: `String`
-Path to the file. If `opts.cwd` is set, `path` is relative to it.
+`watcher.on(eventName, eventHandler)`
+
+Registers `eventHandler` functions to be called when the specified event occurs.
+
+| parameter | type | note |
+|:--------------:|:-----:|--------|
+| eventName | string | The events that may be watched are `'add'`, `'addDir'`, `'change'`, `'unlink'`, `'unlinkDir'`, `'ready'`, `'error'`, or `'all'`. |
+| eventHandler | function | Function to be called when the specified event occurs. Arguments detailed in the table below. |
-### stats
-Type: `Object`
+| argument | type | note |
+|:-------------:|:-----:|--------|
+| path | string | The path of the file that changed. If the `cwd` option was set, the path will be made relative by removing the `cwd`. |
+| stats | object | An [fs.Stat][fs-stats-concepts] object, but could be `undefined`. If the `alwaysStat` option was set to `true`, `stats` will always be provided. |
-[File stats][fs stats] object when available.
-Setting the `alwaysStat` option to `true` will ensure that a file stat object will be
-provided.
+`watcher.close()`
-## watcher methods
+Shuts down the file watcher. Once shut down, no more events will be emitted.
-### watcher.close()
+`watcher.add(globs)`
-Shuts down the file watcher.
+Adds additional globs to an already-running watcher instance.
-### watcher.add(glob)
+| parameter | type | note |
+|:-------------:|:-----:|--------|
+| globs | string
array | The additional globs to be watched. |
-Watch additional glob (or array of globs) with an already-running watcher instance.
+`watcher.unwatch(globs)`
-### watcher.unwatch(glob)
+Removes globs that are being watched, while the watcher continues with the remaining paths.
-Stop watching a glob (or array of globs) while leaving the watcher running and
-emitting events for the remaining paths it is watching.
+| parameter | type | note |
+|:-------------:|:-----:|--------|
+| globs | string
array | The globs to be removed. |
-[chokidar]: https://github.com/paulmillr/chokidar
-[node-glob]: https://github.com/isaacs/node-glob
-[fs stats]: https://nodejs.org/api/fs.html#fs_class_fs_stats
-[async-completion]: https://github.com/gulpjs/async-done#completion-and-error-resolution
+[chokidar-instance-section]: #chokidar-instance
+[tasks-concepts]: concepts.md#tasks
+[globs-concepts]: concepts.md#globs
+[fs-stats-concepts]: concepts.md#file-system-stats
+[chokidar-external]: https://github.com/paulmillr/chokidar
+[fsevents-external]: https://github.com/strongloop/fsevents