1 | # gulp-filter
|
2 |
|
3 | > Filter files in a [`vinyl`](https://github.com/gulpjs/vinyl) stream
|
4 |
|
5 | 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.
|
6 |
|
7 | ## Install
|
8 |
|
9 | ```sh
|
10 | npm install --save-dev gulp-filter
|
11 | ```
|
12 |
|
13 | ## Usage
|
14 |
|
15 | ### Filter only
|
16 |
|
17 | You may want to just filter the stream content:
|
18 |
|
19 | ```js
|
20 | import gulp from 'gulp';
|
21 | import uglify from 'gulp-uglify';
|
22 | import filter from 'gulp-filter';
|
23 |
|
24 | export 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
|
40 | import gulp 'gulp';
|
41 | import uglify 'gulp-uglify';
|
42 | import filter 'gulp-filter';
|
43 |
|
44 | export 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 |
|
61 | By combining and restoring different filters you can process different sets of files with a single pipeline.
|
62 |
|
63 | ```js
|
64 | import gulp from 'gulp';
|
65 | import less from 'gulp-less';
|
66 | import concat from 'gulp-concat';
|
67 | import filter from 'gulp-filter';
|
68 |
|
69 | export 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 |
|
86 | 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.
|
87 |
|
88 | ```js
|
89 | import gulp 'gulp';
|
90 | import uglify 'gulp-uglify';
|
91 | import filter 'gulp-filter';
|
92 |
|
93 | export 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 |
|
114 | Returns a [transform stream](https://nodejs.org/api/stream.html#stream_class_stream_transform) with a [.restore](#optionsrestore) property.
|
115 |
|
116 | #### pattern
|
117 |
|
118 | Type: `string | string[] | Function`
|
119 |
|
120 | Accepts a string/array with globbing patterns which are run through [multimatch](https://github.com/sindresorhus/multimatch).
|
121 |
|
122 | If 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
|
125 | filter(file => /unicorns/.test(file.path));
|
126 | ```
|
127 |
|
128 | #### options
|
129 |
|
130 | Type: `object`
|
131 |
|
132 | Accepts [`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 |
|
138 | Type: `boolean`\
|
139 | Default: `false`
|
140 |
|
141 | Restore filtered files.
|
142 |
|
143 | ##### passthrough
|
144 |
|
145 | Type: `boolean`\
|
146 | Default: `true`
|
147 |
|
148 | 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`.
|
149 |
|
150 | When the stream is a `stream.Readable`, it ends by itself, but when it's `stream.PassThrough`, you are responsible of ending the stream.
|