gulp-micromatch-filter

Filter files in a vinyl stream using micromatch

Enables you to work on a subset of the original files by filtering them using globbing. When you're done and want all the original files back you just use the restore stream.

This is a fork of gulp-filter using micromatch instead of multimatch. In essence, it is a thin combination of streamfilter and micromatch.

It also matches on relativePath by default but allows you to specify your own options.fileToPath function (e.g., use module.exports.relativeToCwd for the default behaviour of gulp-filter).

Install

$ npm install --save-dev gulp-micromatch-filter

Usage

Filter only

You may want to just filter the stream content:

const gulp = require('gulp');
const uglify = require('gulp-uglify');
const filter = require('gulp-micromatch-filter');

gulp.task('default', () => {
	// create filter instance inside task function
	const f = filter(['**', '!*src/vendor']);

	return gulp.src('src/**/*.js')
		// filter a subset of the files
		.pipe(f)
		// run them through a plugin
		.pipe(uglify())
		.pipe(gulp.dest('dist'));
});

Restoring filtered files

const gulp = require('gulp');
const uglify = require('gulp-uglify');
const filter = require('gulp-micromatch-filter');

gulp.task('default', () => {
	// create filter instance inside task function
	const f = filter(['**', '!*src/vendor'], {restore: true});

	return gulp.src('src/**/*.js')
		// filter a subset of the files
		.pipe(f)
		// run them through a plugin
		.pipe(uglify())
		// bring back the previously filtered out files (optional)
		.pipe(f.restore)
		.pipe(gulp.dest('dist'));
});

Multiple filters

By combining and restoring different filters you can process different sets of files with a single pipeline.

const gulp = require('gulp');
const less = require('gulp-less');
const concat = require('gulp-concat');
const filter = require('gulp-micromatch-filter');

gulp.task('default', () => {
	const jsFilter = filter('**/*.js', {restore: true});
	const lessFilter = filter('**/*.less', {restore: true});

	return gulp.src('assets/**')
		.pipe(jsFilter)
		.pipe(concat('bundle.js'))
		.pipe(jsFilter.restore)
		.pipe(lessFilter)
		.pipe(less())
		.pipe(lessFilter.restore)
		.pipe(gulp.dest('out/'));
});

Restore as a file source

You can restore filtered files in a different place and use it as a standalone source of files (ReadableStream). Setting the passthrough option to false allows you to do so.

const gulp = require('gulp');
const uglify = require('gulp-uglify');
const filter = require('gulp-micromatch-filter');

gulp.task('default', () => {
	const f = filter(['**', '!*src/vendor'], {restore: true, passthrough: false});

	const stream = gulp.src('src/**/*.js')
		// filter a subset of the files
		.pipe(f)
		// run them through a plugin
		.pipe(uglify())
		.pipe(gulp.dest('dist'));

	// use filtered files as a gulp file source
	f.restore.pipe(gulp.dest('vendor-dist'));

	return stream;
});

API

filter(pattern, [options])

Returns a transform stream with a .restore object.

pattern

Type: string, array, function

Accepts a string/array with globbing patterns which are run through micromatch .

If you supply a function you'll get a vinyl file object as the first argument and you're expected to return true/false whether to include the file:

filter(file => /unicorns/.test(file.path));

options

Type: object

Accepts micromatch options .

options.restore

Type: boolean
Default: false

Restore filtered files.

options.passthrough

Type: boolean
Default: true

When set to true filtered files are restored with a PassThrough stream, otherwise, when set to false, filtered files are restored as a Readable stream.

When the stream is Readable it ends by itself, but when PassThrough, you are responsible of ending the stream.