gulp-watch

Watch, that actually is an endless stream

This is an reimplementation of bundled gulp.watch with an endless-stream approach. If gulp.watch is working for you, stick with it; otherwise, you can try this gulp-watch plugin.

The main reason for gulp-watch's existence is that it can easily achieve per-file rebuilding on file change:

Installation

Run npm install gulp-watch.

Usage

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

gulp.task('default', function () {
    gulp.src('css/**/*.css')
        .pipe(watch('css/**/*.css', function(files) {
            return files.pipe(gulp.dest('./one/'));
        }))
        .pipe(gulp.dest('./two/'));
    // `one` and `two` will contain same files
});

Protip: until gulpjs 4.0 is released, you can use gulp-plumber to prevent stops on errors.

More examples can be found in docs/readme.md.

API

watch(glob, [options, callback])

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

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

Callback function(events, done)

This function is called, when some group of events (that grouped with gulp-batch) is happens on file-system. All incoming files that piped in will be grouped and passed to events stream as is.

• events — is Stream of incoming events. Events will be grouped by timeout to prevent multiple tasks to be executed repeatedly by commands like git pull.
• done — is callback for your function signal to batch once you are done. This allows you to run your callback as soon as the previous end. done can be omitter iff callback returning Stream or Promise, otherwise it will block next events.

Options

This object is passed to gaze options directly (refer to gaze documentation). For batched mode, we are using gulp-batch, so options from there are also available. And of course options for gulp.src are used too. If you do not want content from watch, then add read: false to the options object.

options.base

Type: String
Default: undefined

Use explicit base path for files from glob.

options.name

Type: String
Default: undefined

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

options.verbose

Type: Boolean / undefined
Default: undefined

This options will enable more verbose output (on true) or disable it completly (on false).

Methods

Returned Stream from constructor have some useful methods:

• close() — calling gaze.close and emitting end, after gaze.close is done.

Also it has _gaze property to access Gaze instance.

Events

• end — all files are stop being watched.
• ready — just re-emitted event from gaze.
• error — when something happened inside callback, you will get notified.

2.0.0 Changes

Before 2.0.0 version there was a bug in gulp-batch - it does not prevent tasks to execute in same time. In 2.0.0 version of gulp-batch was bumped.

This can cause your watch tasks to hang, if you do not calling done in callback or returning Stream/Promise from it.

Migration to 1.0.0

• watch is not emmiting files at start - read «Starting tasks on events» and «Incremental build» for workarounds.
• watch is now pass through stream - which means that streaming files into watch will not add them to gaze. It is very hard to maintain, because watch is not aware about glob, from which this files come from and can not re-create vinyl object properly without maintaining cache of the base properties of incoming files (yuck).
• array of tasks is not accepted as callback - this was not working anyway, but rationale behind it - requiring gulp and calling internal method start is bad. This feature will become more clear, when gulp 4.0.0 will be released with new task system. Read «Starting tasks on events» for right way to do it.

License

MIT (c) 2014 Vsevolod Strukchinsky ([email protected])