1 | # gulp-changed [![Build Status](https://travis-ci.org/sindresorhus/gulp-changed.svg?branch=master)](https://travis-ci.org/sindresorhus/gulp-changed)
|
2 |
|
3 | > Only pass through changed files
|
4 |
|
5 | No more wasting precious time on processing unchanged files.
|
6 |
|
7 | By default it's only able to detect whether files in the stream changed. If you require something more advanced like knowing if imports/dependencies changed, create a custom comparator, or use [another plugin](https://github.com/gulpjs/gulp#incremental-builds).
|
8 |
|
9 |
|
10 | ## Install
|
11 |
|
12 | ```
|
13 | $ npm install --save-dev gulp-changed
|
14 | ```
|
15 |
|
16 |
|
17 | ## Usage
|
18 |
|
19 | ```js
|
20 | const gulp = require('gulp');
|
21 | const changed = require('gulp-changed');
|
22 | const ngAnnotate = require('gulp-ng-annotate'); // Just as an example
|
23 |
|
24 | const SOURCE = 'src/*.js';
|
25 | const DESTINATION = 'dist';
|
26 |
|
27 | exports.default = () => (
|
28 | gulp.src(SOURCE)
|
29 | .pipe(changed(DESTINATION))
|
30 | // `ngAnnotate` will only get the files that
|
31 | // changed since the last time it was run
|
32 | .pipe(ngAnnotate())
|
33 | .pipe(gulp.dest(DESTINATION))
|
34 | );
|
35 | ```
|
36 |
|
37 | ## API
|
38 |
|
39 | ### changed(destination, options?)
|
40 |
|
41 | #### destination
|
42 |
|
43 | Type: `string | Function`
|
44 |
|
45 | Destination directory. Same as you put into `gulp.dest()`.
|
46 |
|
47 | This is needed to be able to compare the current files with the destination files.
|
48 |
|
49 | Can also be a function returning a destination directory path.
|
50 |
|
51 | #### options
|
52 |
|
53 | Type: `object`
|
54 |
|
55 | ##### cwd
|
56 |
|
57 | Type: `string`<br>
|
58 | Default: `process.cwd()`
|
59 |
|
60 | Working directory the folder is relative to.
|
61 |
|
62 | ##### extension
|
63 |
|
64 | Type: `string`
|
65 |
|
66 | Extension of the destination files.
|
67 |
|
68 | Useful if it differs from the original, like in the example below:
|
69 |
|
70 | ```js
|
71 | exports.jade = () => (
|
72 | gulp.src('src/**/*.jade')
|
73 | .pipe(changed('app', {extension: '.html'}))
|
74 | .pipe(jade())
|
75 | .pipe(gulp.dest('app'))
|
76 | );
|
77 | ```
|
78 |
|
79 | ##### hasChanged
|
80 |
|
81 | Type: `Function`<br>
|
82 | Default: `changed.compareLastModifiedTime`
|
83 |
|
84 | Function that determines whether the source file is different from the destination file.
|
85 |
|
86 | ###### Built-in comparators
|
87 |
|
88 | - `changed.compareLastModifiedTime`
|
89 | - `changed.compareContents`
|
90 |
|
91 | ###### Example
|
92 |
|
93 | ```js
|
94 | exports.jade = () => (
|
95 | gulp.src('src/**/*.jade')
|
96 | .pipe(changed('app', {hasChanged: changed.compareContents}))
|
97 | .pipe(jade())
|
98 | .pipe(gulp.dest('app'))
|
99 | );
|
100 | ```
|
101 |
|
102 | You can also supply a custom comparator function which will receive the following arguments and should return `Promise`.
|
103 |
|
104 | - `stream` *([transform object stream](https://github.com/rvagg/through2#transformfunction))* - Should be used to queue `sourceFile` if it passes some comparison
|
105 | - `sourceFile` *([Vinyl file object](https://github.com/wearefractal/vinyl#file))*
|
106 | - `destPath` *(string)* - Destination for `sourceFile` as an absolute path
|
107 |
|
108 | ##### transformPath
|
109 |
|
110 | Type: `Function`
|
111 |
|
112 | Function to transform the path to the destination file. Should return the absolute path to the (renamed) destination file.
|
113 |
|
114 | Useful if you rename your file later on, like in the below example:
|
115 |
|
116 | ```js
|
117 | exports.marked = () => (
|
118 | gulp.src('src/content/about.md')
|
119 | .pipe(changed('dist', {transformPath: newPath => path.join(path.dirname(newPath), path.basename(newPath, '.md'), 'index.html')}))
|
120 | .pipe(marked())
|
121 | .pipe(rename(newPath => path.join(path.dirname(newPath), path.basename(newPath, '.md'), 'index.html'))))
|
122 | .pipe(gulp.dest('dist'))
|
123 | );
|
124 | ```
|
125 |
|
126 |
|
127 | ## In-place change monitoring
|
128 |
|
129 | If you're looking to process source files in-place without any build output (formatting, linting, etc), have a look at [gulp-changed-in-place](https://github.com/alexgorbatchev/gulp-changed-in-place).
|