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 glob patterns. When you're done and want all the original files back, you just use the restore stream.

Install

npm install --save-dev gulp-filter

Usage

Filter only

You may want to just filter the stream content:

import gulp from 'gulp';
import uglify from 'gulp-uglify';
import filter from 'gulp-filter';

export 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

import gulp 'gulp';
import uglify 'gulp-uglify';
import filter 'gulp-filter';

export 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.

import gulp from 'gulp';
import less from 'gulp-less';
import concat from 'gulp-concat';
import filter from 'gulp-filter';

export 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.

import gulp 'gulp';
import uglify 'gulp-uglify';
import filter 'gulp-filter';

export 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 property.

pattern

Type: string | string[] | 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 a boolean of whether to include the file:

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

options

Type: object

Accepts minimatch options.

Note: Set dot: true if you need to match files prefixed with a dot, for example, .gitignore.

restore

Type: boolean
Default: false

Restore filtered files.

passthrough

Type: boolean
Default: true

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

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