# gulp-watch

> Watch, that actually is an endless stream

Latest version **5.0.1** (published 2018-07-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install gulp-watch
pnpm add gulp-watch
yarn add gulp-watch
bun add gulp-watch
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.0.1 |
| Published | 2018-07-23 |
| First published | 2014-01-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/gulp-watch) |
| Module format | CommonJS |
| Dependencies | 12 |
| Unpacked size | 11.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 637 |
| Author | Vsevolod Strukchinsky |
| Maintainers | floatdrop, ult_combo |
| Keywords | gulp, watch, gulpplugin |

## Links

- npm: https://www.npmjs.com/package/gulp-watch
- Repository: https://github.com/floatdrop/gulp-watch
- Homepage: https://github.com/floatdrop/gulp-watch#readme
- Issues: https://github.com/floatdrop/gulp-watch/issues
- npm.io page: https://npm.io/package/gulp-watch

## Dependencies (12)

- [slash](https://npm.io/package/slash.md) ^1.0.0
- [vinyl](https://npm.io/package/vinyl.md) ^2.1.0
- [anymatch](https://npm.io/package/anymatch.md) ^1.3.0
- [chokidar](https://npm.io/package/chokidar.md) ^2.0.0
- [fancy-log](https://npm.io/package/fancy-log.md) 1.3.2
- [vinyl-file](https://npm.io/package/vinyl-file.md) ^2.0.0
- [ansi-colors](https://npm.io/package/ansi-colors.md) 1.1.0
- [glob-parent](https://npm.io/package/glob-parent.md) ^3.0.1
- [plugin-error](https://npm.io/package/plugin-error.md) 1.0.1
- [object-assign](https://npm.io/package/object-assign.md) ^4.1.0
- [readable-stream](https://npm.io/package/readable-stream.md) ^2.2.2
- [path-is-absolute](https://npm.io/package/path-is-absolute.md) ^1.0.1

## Recent versions

- 5.0.1 (latest) — 2018-07-23
- 4.2.5 (beta) — 2015-07-13
- 0.7.0-alpha3 (0.7.0-alpha3) — 2014-06-26
- 0.7.0-alpha2 (0.7.0-alpha2) — 2014-06-17
- 5.0.0 — 2018-01-07
- 4.3.11 — 2016-11-19
- 4.3.10 — 2016-09-27
- 4.3.9 — 2016-07-25
- 4.3.8 — 2016-06-19
- 4.3.7 — 2016-06-19
- 4.3.6 — 2016-05-23
- 4.3.5 — 2015-08-19
- 4.3.4 — 2015-07-26
- 4.3.3 — 2015-07-16
- 4.3.2 — 2015-07-15
- … 69 more at https://npm.io/package/gulp-watch/versions

## README

# [gulp](https://github.com/gulpjs/gulp)-watch [![Build Status: Linux][travis-image]][travis-url] [![Build Status: Windows][appveyor-image]][appveyor-url] [![Dependency Status][depstat-image]][depstat-url]

File watcher that uses super-fast [chokidar](https://github.com/paulmillr/chokidar) and emits vinyl objects.

## Installation

```
npm install --save-dev gulp-watch
```

## Usage

```js
var gulp = require('gulp'),
    watch = require('gulp-watch');

gulp.task('stream', function () {
	// Endless stream mode
    return watch('css/**/*.css', { ignoreInitial: false })
        .pipe(gulp.dest('build'));
});

gulp.task('callback', function () {
	// Callback mode, useful if any plugin in the pipeline depends on the `end`/`flush` event
    return watch('css/**/*.css', function () {
        gulp.src('css/**/*.css')
            .pipe(gulp.dest('build'));
    });
});
```

> __Protip:__ until gulpjs 4.0 is released, you can use [gulp-plumber](https://github.com/floatdrop/gulp-plumber) to prevent stops on errors.

More examples can be found in [`docs/readme.md`](/docs/readme.md).

## API

### watch(glob, [options, callback])

Creates a watcher that will spy on files that are matched by `glob` which can be a
glob string or array of glob strings.

Returns a pass through stream that will emit vinyl files
(with additional `event` property) that corresponds to event on file-system.

#### Callback `function(vinyl)`

This function is called when events happen on the file-system.
All incoming files that are piped in are grouped and passed to the `events` stream as is.

 * `vinyl` — is [vinyl](https://github.com/wearefractal/vinyl) object that corresponds to the file that caused the event. Additional `event` field is added to determine what caused changes.

Possible events:

 * `add` - file was added to watch or created
 * `change` - file was changed
 * `unlink` - file was deleted

#### Options

This object is passed to the [`chokidar` options](https://github.com/paulmillr/chokidar#api) directly. Options for [`gulp.src`](https://github.com/gulpjs/gulp/blob/master/docs/API.md#options) are also available. If you do not want content from `watch`, then add `read: false` to the `options` object.

#### options.[ignoreInitial](https://github.com/paulmillr/chokidar#path-filtering)
Type: `Boolean`  
Default: `true`

> Indicates whether chokidar should ignore the initial add events or not.

#### options.events
Type: `Array`  
Default: `['add', 'change', 'unlink']`

List of events, that should be watched by gulp-watch. Contains [event names from chokidar](https://github.com/paulmillr/chokidar#events).

#### options.base
Type: `String`  
Default: `undefined`

Use explicit base path for files from `glob`. Read more about `base` and `cwd` in [gulpjs docs](https://github.com/gulpjs/gulp/blob/master/docs/API.md#options).

#### options.name
Type: `String`  
Default: `undefined`

Name of the watcher. If it is present in options, you will get more readable output.

#### options.verbose
Type: `Boolean`  
Default: `false`

This option will enable verbose output.

#### options.readDelay
Type: `Number`  
Default: `10`

Wait for `readDelay` milliseconds before reading the file.

#### options.read
Type: `Boolean`  
Default: `true`

Setting this to `false` will return `file.contents` as null and not read the file at all. Most useful as an optimization if your plugins pipeline doesn't make use of the file contents (e.g. `gulp-clean`), or to avoid reading the file twice if you use `gulp.src()` inside the callback instead of the file object that is passed as argument.

### Methods

Returned `Stream` from constructor has some useful methods:

 * `add(path / paths)`
 * `unwatch(path / paths)`
 * `close()`

### Events

All events from [chokidar](http://npmjs.com/chokidar):

 * `add`, `change`, `unlink`, `addDir`, `unlinkDir`, `error`, `ready`, `raw`


### [Changelog](https://github.com/floatdrop/gulp-watch/releases)

## License

MIT (c) 2014 Vsevolod Strukchinsky (floatdrop@gmail.com)

[npm-url]: https://npmjs.org/package/gulp-watch
[npm-image]: http://img.shields.io/npm/v/gulp-watch.svg?style=flat

[travis-url]: https://travis-ci.org/floatdrop/gulp-watch
[travis-image]: http://img.shields.io/travis/floatdrop/gulp-watch.svg?style=flat

[appveyor-url]: https://ci.appveyor.com/project/floatdrop/gulp-watch/branch/master
[appveyor-image]: https://ci.appveyor.com/api/projects/status/gmjwsqmxht1m131s/branch/master?svg=true

[depstat-url]: https://david-dm.org/floatdrop/gulp-watch
[depstat-image]: http://img.shields.io/david/floatdrop/gulp-watch.svg?style=flat

---
_Source: https://npm.io/package/gulp-watch · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._