UNPKG

3.79 kBMarkdownView Raw
1# gulp-filter
2
3> Filter files in a [`vinyl`](https://github.com/gulpjs/vinyl) stream
4
5Enables 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.
6
7## Install
8
9```sh
10npm install --save-dev gulp-filter
11```
12
13## Usage
14
15### Filter only
16
17You may want to just filter the stream content:
18
19```js
20import gulp from 'gulp';
21import uglify from 'gulp-uglify';
22import filter from 'gulp-filter';
23
24export default () => {
25 // Create filter instance inside task function
26 const f = filter(['**', '!*src/vendor']);
27
28 return gulp.src('src/**/*.js')
29 // Filter a subset of the files
30 .pipe(f)
31 // Run them through a plugin
32 .pipe(uglify())
33 .pipe(gulp.dest('dist'));
34};
35```
36
37### Restoring filtered files
38
39```js
40import gulp 'gulp';
41import uglify 'gulp-uglify';
42import filter 'gulp-filter';
43
44export default () => {
45 // Create filter instance inside task function
46 const f = filter(['**', '!*src/vendor'], {restore: true});
47
48 return gulp.src('src/**/*.js')
49 // Filter a subset of the files
50 .pipe(f)
51 // Run them through a plugin
52 .pipe(uglify())
53 // Bring back the previously filtered out files (optional)
54 .pipe(f.restore)
55 .pipe(gulp.dest('dist'));
56};
57```
58
59### Multiple filters
60
61By combining and restoring different filters you can process different sets of files with a single pipeline.
62
63```js
64import gulp from 'gulp';
65import less from 'gulp-less';
66import concat from 'gulp-concat';
67import filter from 'gulp-filter';
68
69export default () => {
70 const jsFilter = filter('**/*.js', {restore: true});
71 const lessFilter = filter('**/*.less', {restore: true});
72
73 return gulp.src('assets/**')
74 .pipe(jsFilter)
75 .pipe(concat('bundle.js'))
76 .pipe(jsFilter.restore)
77 .pipe(lessFilter)
78 .pipe(less())
79 .pipe(lessFilter.restore)
80 .pipe(gulp.dest('out/'));
81};
82```
83
84### Restore as a file source
85
86You 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.
87
88```js
89import gulp 'gulp';
90import uglify 'gulp-uglify';
91import filter 'gulp-filter';
92
93export default () => {
94 const f = filter(['**', '!*src/vendor'], {restore: true, passthrough: false});
95
96 const stream = gulp.src('src/**/*.js')
97 // Filter a subset of the files
98 .pipe(f)
99 // Run them through a plugin
100 .pipe(uglify())
101 .pipe(gulp.dest('dist'));
102
103 // Use filtered files as a gulp file source
104 f.restore.pipe(gulp.dest('vendor-dist'));
105
106 return stream;
107};
108```
109
110## API
111
112### filter(pattern, options?)
113
114Returns a [transform stream](https://nodejs.org/api/stream.html#stream_class_stream_transform) with a [.restore](#optionsrestore) property.
115
116#### pattern
117
118Type: `string | string[] | Function`
119
120Accepts a string/array with globbing patterns which are run through [multimatch](https://github.com/sindresorhus/multimatch).
121
122If you supply a function, you'll get a [`vinyl` file object](https://github.com/wearefractal/vinyl#file) as the first argument and you're expected to return a boolean of whether to include the file:
123
124```js
125filter(file => /unicorns/.test(file.path));
126```
127
128#### options
129
130Type: `object`
131
132Accepts [`minimatch` options](https://github.com/isaacs/minimatch#options).
133
134*Note:* Set `dot: true` if you need to match files prefixed with a dot, for example, `.gitignore`.
135
136##### restore
137
138Type: `boolean`\
139Default: `false`
140
141Restore filtered files.
142
143##### passthrough
144
145Type: `boolean`\
146Default: `true`
147
148When set to `true`, filtered files are restored with a `stream.PassThrough`, otherwise, when set to `false`, filtered files are restored as a `stram.Readable`.
149
150When the stream is a `stream.Readable`, it ends by itself, but when it's `stream.PassThrough`, you are responsible of ending the stream.