Skip to content

Commit

Permalink
Docs: Add "Watching Files" documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
janiceilene authored and phated committed May 31, 2018
1 parent 233c3f9 commit f3f2d9f
Showing 1 changed file with 122 additions and 0 deletions.
122 changes: 122 additions & 0 deletions docs/getting-started/8-watching-files.md
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit f3f2d9f

Please sign in to comment.