Jump to: gulp.src | gulp.dest | gulp.task | gulp.watch
Emits files matching provided glob or an array of globs. Returns a stream of Vinyl files that can be piped to plugins.
gulp.src('client/templates/*.jade')
.pipe(jade())
.pipe(minify())
.pipe(gulp.dest('build/minified_templates'));
glob
refers to node-glob syntax or it can be a direct file path.
Type: String
or Array
Glob or array of globs to read.
Type: Object
Options to pass to node-glob through glob-stream.
gulp adds some additional options in addition to the options supported by node-glob and glob-stream:
Type: Boolean
Default: true
Setting this to false
will return file.contents
as a stream and not buffer files. This is useful when working with large files. Note: Plugins might not implement support for streams.
Type: Boolean
Default: true
Setting this to false
will return file.contents
as null and not read the file at all.
Type: String
Default: everything before a glob starts (see glob2base)
E.g., consider somefile.js
in client/js/somedir
:
gulp.src('client/js/**/*.js') // Matches 'client/js/somedir/somefile.js' and resolves `base` to `client/js/`
.pipe(minify())
.pipe(gulp.dest('build')); // Writes 'build/somedir/somefile.js'
gulp.src('client/js/**/*.js', { base: 'client' })
.pipe(minify())
.pipe(gulp.dest('build')); // Writes 'build/js/somedir/somefile.js'
Can be piped to and it will write files. Re-emits all data passed to it so you can pipe to multiple folders. Folders that don't exist will be created.
gulp.src('./client/templates/*.jade')
.pipe(jade())
.pipe(gulp.dest('./build/templates'))
.pipe(minify())
.pipe(gulp.dest('./build/minified_templates'));
The write path is calculated by appending the file relative path to the given
destination directory. In turn, relative paths are calculated against the file base.
See gulp.src
above for more info.
Type: String
or Function
The path (output folder) to write files to. Or a function that returns it, the function will be provided a vinyl File instance.
Type: Object
Type: String
Default: process.cwd()
cwd
for the output folder, only has an effect if provided output folder is relative.
Type: String
Default: 0777
Octal permission string specifying mode for any folders that need to be created for output folder.
Define a task using Orchestrator.
gulp.task('somename', function() {
// Do stuff
});
The name of the task. Tasks that you want to run from the command line should not have spaces in them.
Type: Array
An array of tasks to be executed and completed before your task will run.
gulp.task('mytask', ['array', 'of', 'task', 'names'], function() {
// Do stuff
});
Note: Are your tasks running before the dependencies are complete? Make sure your dependency tasks are correctly using the async run hints: take in a callback or return a promise or event stream.
The function that performs the task's operations. Generally this takes the form of gulp.src().pipe(someplugin())
.
Tasks can be made asynchronous if its fn
does one of the following:
// run a command in a shell
var exec = require('child_process').exec;
gulp.task('jekyll', function(cb) {
// build Jekyll
exec('jekyll build', function(err) {
if (err) return cb(err); // return error
cb(); // finished task
});
});
gulp.task('somename', function() {
var stream = gulp.src('client/**/*.js')
.pipe(minify())
.pipe(gulp.dest('build'));
return stream;
});
var Q = require('q');
gulp.task('somename', function() {
var deferred = Q.defer();
// do async stuff
setTimeout(function() {
deferred.resolve();
}, 1);
return deferred.promise;
});
Note: By default, tasks run with maximum concurrency -- e.g. it launches all the tasks at once and waits for nothing. If you want to create a series where tasks run in a particular order, you need to do two things:
- give it a hint to tell it when the task is done,
- and give it a hint that a task depends on completion of another.
For these examples, let's presume you have two tasks, "one" and "two" that you specifically want to run in this order:
-
In task "one" you add a hint to tell it when the task is done. Either take in a callback and call it when you're done or return a promise or stream that the engine should wait to resolve or end respectively.
-
In task "two" you add a hint telling the engine that it depends on completion of the first task.
So this example would look like this:
var gulp = require('gulp');
// takes in a callback so the engine knows when it'll be done
gulp.task('one', function(cb) {
// do stuff -- async or otherwise
cb(err); // if err is not null and not undefined, the run will stop, and note that it failed
});
// identifies a dependent task must be complete before this one begins
gulp.task('two', ['one'], function() {
// task 'one' is done now
});
gulp.task('default', ['one', 'two']);
Watch files and do something when a file changes. This always returns an EventEmitter that emits change
events.
Type: String
or Array
A single glob or array of globs that indicate which files to watch for changes.
Type: Object
Options, that are passed to gaze
.
Type: Array
Names of task(s) to run when a file changes, added with gulp.task()
var watcher = gulp.watch('js/**/*.js', ['uglify','reload']);
watcher.on('change', function(event) {
console.log('File ' + event.path + ' was ' + event.type + ', running tasks...');
});
Type: String
or Array
A single glob or array of globs that indicate which files to watch for changes.
Type: Object
Options, that are passed to gaze
.
Type: Function
Callback to be called on each change.
gulp.watch('js/**/*.js', function(event) {
console.log('File ' + event.path + ' was ' + event.type + ', running tasks...');
});
The callback will be passed an object, event
, that describes the change:
Type: String
The type of change that occurred, either added
, changed
or deleted
.
Type: String
The path to the file that triggered the event.