Docs: Improve incremental build example & add gulp.lastRun API

README.md

@@ -80,12 +80,56 @@ gulp.task('default', gulp.series('clean', 'all'));
 
 ## Incremental Builds
 
-We recommend these plugins:
+You can filter out unchanged files between runs of a task using
+the `gulp.src` function's `since` option and `gulp.lastRun`:
+```js
+gulp.task('images', function() {
+  return gulp.src(paths.images, {since: gulp.lastRun('images')})
+    .pipe(imagemin({optimizationLevel: 5}))
+    .pipe(gulp.dest('build/img'));
+});
+
+gulp.task('watch', function() {
+  gulp.watch(paths.images, 'images');
+});
+```
+Task run times are saved in memory and are lost when gulp exits. It will only
+save time during the `watch` task when running the `images` task
+for a second time.
 
-- [gulp-changed](https://github.com/sindresorhus/gulp-changed) - only pass through changed files
-- [gulp-cached](https://github.com/contra/gulp-cached) - in-memory file cache, not for operation on sets of files
-- [gulp-remember](https://github.com/ahaurw01/gulp-remember) - pairs nicely with gulp-cached
-- [gulp-newer](https://github.com/tschaub/gulp-newer) - pass through newer source files only, supports many:1 source:dest
+If you want to compare modification time between files instead, we recommend these plugins:
+- [gulp-changed];
+- or [gulp-newer] - supports many:1 source:dest.
+
+[gulp-newer] example:
+```js
+gulp.task('images', function() {
+  var dest = 'build/img';
+  return gulp.src(paths.images)
+    .pipe(newer(dest))  // pass through newer images only
+    .pipe(imagemin({optimizationLevel: 5}))
+    .pipe(gulp.dest(dest));
+});
+```
+
+If you can't simply filter out unchanged files, but need them in a later phase
+of the stream, we recommend these plugins:
+- [gulp-cached] - in-memory file cache, not for operation on sets of files
+- [gulp-remember] - pairs nicely with gulp-cached
+
+[gulp-remember] example:
+```js
+gulp.task('scripts', function () {
+  return gulp.src(scriptsGlob)
+    .pipe(cache('scripts'))    // only pass through changed files
+    .pipe(header('(function () {')) // do special things to the changed files...
+    .pipe(footer('})();'))     // for example,
+                               // add a simple module wrap to each file
+    .pipe(remember('scripts')) // add back all files to the stream
+    .pipe(concat('app.js'))    // do things that require all files
+    .pipe(gulp.dest('public/'))
+});
+```
 
 ## Want to test the latest and greatest?
 
@@ -135,3 +179,8 @@ Become a sponsor to get your logo on our README on Github.
 
 [backers-image]: https://opencollective.com/gulpjs/backers.svg
 [sponsors-image]: https://opencollective.com/gulpjs/sponsors.svg
+
+[gulp-cached]: https://github.com/contra/gulp-cached
+[gulp-remember]: https://github.com/ahaurw01/gulp-remember
+[gulp-changed]: https://github.com/sindresorhus/gulp-changed
+[gulp-newer]: https://github.com/tschaub/gulp-newer

docs/API.md

@@ -350,6 +350,38 @@ gulp.task('sometask', function() {
 });
 ```
 
+### lastRun(taskName, [timeResolution])
+
+Returns the timestamp of the last time the task ran successfully. The time
+will be the time the task started. Returns `undefined` if the task has
+not run yet.
+
+#### taskName
+
+Type: `String`
+
+The name of the registered task or of a function.
+
+#### timeResolution
+
+Type: `Number`.
+
+Default: `1000` on node v0.10, `0` on node v0.12 (and iojs v1.5).
+
+Set the time resolution of the returned timestamps. Assuming
+the task named "someTask" ran at `1426000004321`:
+- `gulp.lastRun('someTask', 1000)` would return `1426000004000`.
+- `gulp.lastRun('someTask', 100)` would return `1426000004300`.
+
+`timeResolution` allows you to compare a run time to a file [mtime stat][fs stats]
+attribute. This attribute time resolution may vary depending of the node version
+and the file system used:
+- on node v0.10, a file [mtime stat][fs stats] time resolution of any files will be 1s at best;
+- on node v0.12 and iojs v1.5, 1ms at best;
+- for files on FAT32, the mtime time resolution is 2s;
+- on HFS+ and Ext3, 1s;
+- on NTFS, 1s on node v0.10, 100ms on node 0.12;
+- on Ext4, 1s on node v0.10, 1ms on node 0.12.
 
 ### gulp.parallel(...tasks)
 
@@ -482,3 +514,4 @@ The path to the file that triggered the event.
 [Undertaker]: https://github.com/phated/undertaker
 [vinyl File instance]: https://github.com/gulpjs/vinyl
 [Vinyl files]: https://github.com/gulpjs/vinyl-fs
+[fs stats]: https://nodejs.org/api/fs.html#fs_class_fs_stats