From f3f2d9f9b624983fc4985a5ab5b45542e08bcf83 Mon Sep 17 00:00:00 2001
From: Janice Niemeir <Janice.guerrero@gmail.com>
Date: Thu, 31 May 2018 10:46:05 -0700
Subject: [PATCH] Docs: Add "Watching Files" documentation

---
 docs/getting-started/8-watching-files.md | 122 +++++++++++++++++++++++
 1 file changed, 122 insertions(+)
 create mode 100644 docs/getting-started/8-watching-files.md

diff --git a/docs/getting-started/8-watching-files.md b/docs/getting-started/8-watching-files.md
new file mode 100644
index 000000000..4ed63d2f2
--- /dev/null
+++ b/docs/getting-started/8-watching-files.md
@@ -0,0 +1,122 @@
+<!-- front-matter
+id: watching-files
+title: Watching Files
+hide_title: true
+sidebar_label: Watching Files
+-->
+
+# Watching Files
+
+The `watch()` API connects [globs][globs-docs] to [tasks][creating-tasks-docs] using a file system watcher. It watches for changes to files that match the globs and executes the task when a change occurs. If the task doesn't signal [Async Completion][async-completion-doc], it will never be run a second time.
+
+This API provides built-in delay and queueing based on most-common-use defaults.
+
+```js
+const { watch, series } = require('gulp');
+
+function clean(cb) {
+  // Body omitted
+  cb();
+}
+
+function javascript(cb) {
+  // Body omitted
+  cb();
+}
+
+function css(cb) {
+  // Body omitted
+  cb();
+}
+
+// You can use a single task
+watch('src/*.css', css);
+// Or a composed task
+watch('src/*.js', series(clean, javascript));
+```
+
+## Warning: Avoid synchronous
+
+A watcher's task cannot be synchronous, like tasks registered into the task system. If you pass a sync task, the completion can't be determined and the task won't run again - it is assumed to still be running.
+
+There is no error or warning message provided because the file watcher keeps your Node process running. Since the process doesn't exit, it cannot be determined whether the task is done or just taking a really, really long time to run.
+
+## Watched events
+
+By default, the watcher executes tasks whenever a file is created, changed, or deleted.
+If you need to use different events, you can use the `events` option when calling `watch()`. The available events are `'add'`, `'addDir'`, `'change'`, `'unlink'`, `'unlinkDir'`, `'ready'`, `'error'`. Additionally `'all'` is available, which represents all events other than `'ready'` and `'error'`.
+
+```js
+const { watch } = require('gulp');
+
+// All events will be watched
+watch('src/*.js', { events: 'all' }, function(cb) {
+  // Body omitted
+  cb();
+});
+```
+
+## Initial execution
+
+Upon calling `watch()`, the tasks won't be executed, instead they'll wait for the first file change.
+
+To execute tasks before the first file change, set the `ignoreInitial` option to `false`.
+
+```js
+const { watch } = require('gulp');
+
+// The task will be executed upon startup
+watch('src/*.js', { ignoreInitial: false }, function(cb) {
+  // Body omitted
+  cb();
+});
+```
+
+## Queueing
+
+Each `watch()` guarantees that its currently running task won't execute again concurrently. When a file change is made while a watcher task is running, another execution will queue up to run when the task finishes. Only one run can be queued up at a time.
+
+To disable queueing, set the `queue` option to `false`.
+
+```js
+const { watch } = require('gulp');
+
+// The task will be run (concurrently) for every change made
+watch('src/*.js', { queue: false }, function(cb) {
+  // Body omitted
+  cb();
+});
+```
+
+## Delay
+
+Upon file change, a watcher task won't run until a 200ms delay has elapsed. This is to avoid starting a task too early when many files are being changed at once - like find-and-replace.
+
+To adjust the delay duration, set the `delay` option to a positive integer.
+
+```js
+const { watch } = require('gulp');
+
+// The task won't be run until 500ms have elapsed since the first change
+watch('src/*.js', { delay: 500 }, function(cb) {
+  // Body omitted
+  cb();
+});
+```
+
+## Using the watcher instance
+
+You likely won't use this feature, but if you need full control over changed files - like access to paths or metadata - use the [chokidar][chokidar-module-package] instance returned from `watch()`.
+
+__Be careful:__ The returned chokidar instance doesn't have queueing, delay, or async completion features.
+
+## Optional dependency
+
+Gulp has an optional dependency called [fsevents][fsevents-package], which is a Mac-specific file watcher. If you see an installation warning for fsevents - _"npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents"_ - it is not an issue.
+If fsevents installation is skipped, a fallback watcher will be used and any errors occurring in your gulpfile aren't related to this warning.
+
+[globs-docs]: 6-explaining-globs.md
+[creating-tasks-docs]: 3-creating-tasks.md
+[async-completion-doc]: 4-async-completion.md
+[chokidar-module-package]: https://www.npmjs.com/package/chokidar
+[fsevents-package]: https://www.npmjs.com/package/fsevents