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'));

通配符参见 node-glob syntax 或者直接是一个文件路径。

glob refers to node-glob syntax or it can be a direct file path.

globs

Type: String or Array

需要读取的通配符或者一组通配符。

Glob or globs to read.

options

Type: Object

通过glob-stream 传递给 node-glob 的配置。

Options to pass to node-glob through glob-stream

glup 添加了两个新增配置项到node-glob和glob-stream所支持的配置项中。

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

options.buffer

Type: Boolean Default: true

设置为false file.contents将以stream的形式返回而不是buffer。这对操作打文件非常有帮助。注意： 插件可以不支持 streams。

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

设置这个配置为false file.contents 将会返回null，并且不会读取这个文件。

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

路径 path

类型: String

写文件的路径(目录)。

The path(folder) to write files to.

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

使用Orchestrator定义一个任务。

Define a task using Orchestrator

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

name

任务名称。如果希望在命令行运行任务，则任务名不能包含空格。

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

deps

类型：Array

一个将要执行的任务列表，并且它们在你的任务开始前结束。

An array of tasks to be executed and complete before your task will run.

gulp.task('mytask', ['array', 'of', 'task', 'names'], function() {
  // Do stuff
});

注意：你的任务将会在所有的依赖执行完成之后执行？请确保所有的依赖正确的使用了异步执行提示：输入到一个回调或者返回一个promise 或者 event stream。

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

执行任务操作的方法。一般来说，采取gulp.src().pipe(someplugin)的形式。

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

异步任务支持 Async task support

任务可以是异步的，如果fn按照下面的方法来实现：

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

接受一个回调 Accept a callback

// Run a command in a shell 
var exec = require('child_process').exec;
gulp.task('jekyll', function(cb) {
  // Build Jekyl
  exec('jekyll build', function(err) { 
    if (err) return cb(err); //return error
    cb(); // finished task
  });
});

返回一个流 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 anthoer.

例如，假设你有两个任务，"one" 和 "two" 想要按照一下顺序来执行：

For there examples, let's presume you have two tasks, "one" and "two" that you specifically want to run in this order:

1. 在任务"one"中添加一个提示告诉它任务什么时候完成。输入到回调或者或者在完成的地方调用它或者返回一个promise或者stream 引擎需要等待解决或者各自结束。

1. In task "one" you add a hint to tell it when the task is done. Either take in a callback and call it where you're done or return a promise or stream that the engine should wait to resolve or end respectively.

1. 在任务"two" 中添加一个提示告诉引擎他需要等待第一个任务的结束。

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.watch(glob[,opts], tasks) or gulp.watch(glob[,opts, cb])

监控文件并在文件发生变化时做处理。此方法返回一个EventEmitter来触发change事件。

Watch files and do something when a file changes. This always returns an EventEmitter that emits change events.

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

glob

类型：String 或者 Array

单一通配符或者一组通配符，指明监控哪些文件的变化。

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

opts

类型：Object

传递给gaze的配置

Options, that are passed to gaze.

tasks

类型：Array

当一个文件变化时运行通过 gulp.task()添加的任务名。

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...');
});

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

glob

类型：String or Array

单一通配符或者一组通配符指明那些文件需要监控变化。

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

opts

类型：Object

传递给gaze的配置

Options, that are passed to gaze.

cb(event)

类型：Function

每次文件变化所执行的回调

gulp.watch('js/**/*.js', function(event) {
  console.log('File '+event.path+' was '+event.type+', running tasks...');
});

回调将会被传递一个描述了此次变化的event对象：

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

event.type

类型：String

发生变化的类型，added, changed 或者 deleted.

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

event.path

触发事件的文件路径.

The path to the file that triggered the event.