gulp-filter

What is gulp-filter?

The gulp-filter package is a plugin for Gulp, a streaming build system. It allows you to filter files in a vinyl stream based on a given criteria, enabling you to include or exclude files from further processing in your Gulp tasks.

What are gulp-filter's main functionalities?

Filtering files by glob patterns

This feature allows you to filter files in a stream using glob patterns. In this example, only JavaScript files are passed through the filter and then written to the 'dist/js' directory.

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

const jsFilter = filter('**/*.js', { restore: true });

gulp.task('scripts', function() {
  return gulp.src('src/**/*')
    .pipe(jsFilter)
    .pipe(gulp.dest('dist/js'))
    .pipe(jsFilter.restore);
});

Restoring filtered files

This feature allows you to restore the filtered files back into the stream after processing. In this example, after processing JavaScript files, the rest of the files are written to the 'dist/others' directory.

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

const jsFilter = filter('**/*.js', { restore: true });

gulp.task('scripts', function() {
  return gulp.src('src/**/*')
    .pipe(jsFilter)
    .pipe(gulp.dest('dist/js'))
    .pipe(jsFilter.restore)
    .pipe(gulp.dest('dist/others'));
});

Filtering files by custom function

This feature allows you to filter files using a custom function. In this example, only JavaScript files containing the string 'use strict' are passed through the filter and then written to the 'dist/strict' directory.

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

const customFilter = filter(function(file) {
  return file.contents.toString().indexOf('use strict') !== -1;
});

gulp.task('strict', function() {
  return gulp.src('src/**/*.js')
    .pipe(customFilter)
    .pipe(gulp.dest('dist/strict'));
});

Other packages similar to gulp-filter

gulp-if

The gulp-if package allows you to conditionally run a Gulp plugin based on a condition. It is similar to gulp-filter in that it can be used to include or exclude files from further processing, but it does so based on a condition rather than a filter.

gulp-match

The gulp-match package is used to match files in a Gulp stream based on a condition. It is similar to gulp-filter in that it can be used to include or exclude files from further processing, but it is more lightweight and only provides matching functionality.

gulp-ignore

The gulp-ignore package allows you to ignore files in a Gulp stream based on a condition. It is similar to gulp-filter in that it can be used to exclude files from further processing, but it does not provide the ability to restore filtered files back into the stream.

README

gulp-filter

Filter files in a vinyl stream

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 call the restore method.

Install

$ npm install --save-dev gulp-filter

Usage

Simple

var gulp = require('gulp');
var jscs = require('gulp-jscs');
var gulpFilter = require('gulp-filter');

gulp.task('default', function () {
	// create filter instance inside task function
	var filter = gulpFilter('!src/vendor');

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

Multiple filters

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

var gulp = require('gulp');
var less = require('gulp-less');
var concat = require('gulp-concat');
var gulpFilter = require('gulp-filter');

gulp.task('default', function () {
	var jsFilter = gulpFilter('**/*.js');
	var lessFilter = gulpFilter('**/*.less');

	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 may also want to restore filtered files in a different place and use it as a standalone source of files. The end option allow you to do so.

var gulp = require('gulp');
var jscs = require('gulp-jscs');
var gulpFilter = require('gulp-filter');

gulp.task('default', function () {
	var filter = gulpFilter('!src/vendor');

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

	// use filtered files as a gulp file source
	filter.restore({end: true})
  		.pipe(gulp.dest('vendor-dist'));
});

API

filter(pattern, options)

Returns a transform stream with a .restore() method.

pattern

Type: String|Array|Function

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

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(function (file) {
	return /unicorns/.test(file.path);
});

options

Type: Object

Accepts minimatch options.

Note: Set dot: true if you need to match files prefixed with a dot (eg. .gitignore).

stream.restore(options)

Brings back the previously filtered out files.

options.end

Type: boolean
Default: false

Set to true if you want restore streams to end when their source stream ends.

License

MIT © Sindre Sorhus