API.md

gulp API docs

gulp.src(globs[, options])

Takes a glob and represents a file structure. Can be piped to plugins.

gulp.src('./client/templates/*.jade')
    .pipe(jade())
    .pipe(minify())
    .pipe(gulp.dest('./build/minified_templates'));

globs

Type: String or Array

Glob or globs to read.

options

Type: Object

Options to pass to node-glob through glob-stream.

gulp adds two additional options in addition to the options supported by node-glob:

options.buffer

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 may not implement support for streams.

options.read

Type: Boolean Default: true

Setting this to false will return file.contents as null and not read the file at all.

gulp.dest(path)

Can be piped to and it will write files. Re-emits all data passed to it so you can pipe to multiple folders.

gulp.src('./client/templates/*.jade')
  .pipe(jade())
  .pipe(gulp.dest('./build/templates'))
  .pipe(minify())
  .pipe(gulp.dest('./build/minified_templates'));

path

Type: String

The path (folder) to write files to.

gulp.task(name[, deps], fn)

Define a task using Orchestrator.

gulp.task('somename', function() {
  // Do stuff
});

name

The name of the task. Tasks that you want to run from the command line should not have spaces in them.

deps

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.

fn

The function that performs the task's operations. Generally this takes the form of gulp.src().pipe(someplugin()).

Async task support

Tasks can be made asynchronous if its fn does one of the following:

Accept a callback

gulp.task('somename', function(cb) {
  // Do stuff
  cb(err);
});

Return a stream

gulp.task('somename', function() {
  var stream = gulp.src('./client/**/*.js')
    .pipe(minify())
    .pipe(gulp.dest('/build'));
  return stream;
});

Return a promise

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:

1. 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.

2. 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']);
``


### gulp.run(tasks...[, cb])

#### tasks
Type: `String`

Tasks to be executed. You may pass any number of tasks as individual arguments. **Note:** Tasks are run concurrently and therefore do not run in order, see [Orchestrator] for more information.

```javascript
gulp.run('scripts', 'copyfiles', 'builddocs');

gulp.run('scripts', 'copyfiles', 'builddocs', function(err) {
  // All done or aborted due to err
});

Use gulp.run to run tasks from other tasks. Avoid this command and use task dependencies instead.

gulp.watch(glob, tasks) or gulp.watch(glob [, opts], cb)

Watch files and do something when a file changes

gulp.watch(glob, tasks)

glob

Type: String or Array

A single glob or array of globs that indicate which files to watch for changes.

tasks

Type: Array

Names of task(s) to run when a file changes, added with gulp.task()

gulp.watch('js/**/*.js', ['uglify','reload']);

gulp.watch(glob, tasks)

glob

Type: String or Array

A single glob or array of globs that indicate which files to watch for changes.

opts

Type: Object

Options, that are passed to gaze.

cb(event)

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...');
  gulp.run('scripts', 'copyfiles');
});

The callback will be passed an object, event, that describes the change:

event.type

Type: String

The type of change that occurred, either added, changed or deleted.

event.path

Type: String

The path to the file that triggered the event.

gulp.env

gulp.env is a node-optimist arguments object. For instance, if you run:

gulp test dostuff --production

Which results in the following gulp.env:

{
  _: ['test', 'dostuff'],
  production: true
}

You can use this to conditionally enable certain plugins:

gulp.task('scripts', function() {
  var stream = gulp.src(['client/js/**/*.js', '!client/js/vendor/**']);

  // Only uglify in production
  if (gulp.env.production) {
    stream = stream.pipe(uglify());
  }

  stream.pipe(gulp.dest('build/js'));
});

There is also gulp-if to make this a lot prettier.