garagesocial / gulp-watch

Watch, that actually is an endless stream

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.

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
Default: false

This options will enable more verbose output (useful for debugging).

Methods

Returned Stream from constructor have some useful methods:

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

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.

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])