Skip to content

Commit

Permalink
Merge 7c7ce0b into 0391f66
Browse files Browse the repository at this point in the history
  • Loading branch information
@dinoboff
dinoboff committed Mar 1, 2015
2 parents 0391f66 + 7c7ce0b commit 8aac2e3
Show file tree
Hide file tree
Showing 6 changed files with 204 additions and 160 deletions.
228 changes: 140 additions & 88 deletions docs/API.md
View file
Expand Up @@ -7,7 +7,7 @@ Returns a [stream](http://nodejs.org/api/stream.html) of [Vinyl files](https://g
that can be [piped](http://nodejs.org/api/stream.html#stream_readable_pipe_destination_options)
to plugins.

```javascript
```js
gulp.src('client/templates/*.jade')
.pipe(jade())
.pipe(minify())
Expand Down Expand Up @@ -60,7 +60,7 @@ gulp.src('client/js/**/*.js', { base: 'client' })

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.

```javascript
```js
gulp.src('./client/templates/*.jade')
.pipe(jade())
.pipe(gulp.dest('./build/templates'))
Expand Down Expand Up @@ -92,9 +92,10 @@ Default: `0777`

Octal permission string specifying mode for any folders that need to be created for output folder.

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

Define a task using [Orchestrator].
### gulp.task([name,] fn)

Define a task using [Undertaker].

```js
gulp.task('somename', function() {
Expand All @@ -104,132 +105,175 @@ gulp.task('somename', function() {

#### name

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

#### deps
Type: `Array`
If the name is not provided, the task will be name after the function `name` attribute.

An array of tasks to be executed and completed before your task will run.
`Function.name` is not writable; it cannot be set or edited.
It will be empty for anonymous function:

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

// bar.name === ''
var bar = function() {};

// bar.name === ''
bar.name = 'bar'
```

**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.
You should either provide the task name or avoid anonymous functions.

#### fn

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

#### Async task support
Gulp assumes each task is asynchronous and call them with a callback parameter.
A Task should either call the callback parameter to signal when operations
have ended, or return a stream, promise, child process or RxJS observable.

Tasks can be made asynchronous if its `fn` does one of the following:
#### Async support

##### Accept a callback

```javascript
// 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
});
```js
var del = require('del');

gulp.task('clean', function(done) {
del(['.build/'], done);
});
```

The callback accept an optional `Error` object. If it receives an error,
the task will fail.

##### Return a stream

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

##### Return a promise

```javascript
var Q = require('q');
```js
var Promise = require('promise');
var del = require('del');

gulp.task('clean', function() {
return new Promise(function (resolve, reject) {
del(['.build/'], function(err) {
if (err) {
reject(err);
} else {
resolve();
}
});
});
});
```

gulp.task('somename', function() {
var deferred = Q.defer();
or:
```js
var promisedDel = require('promised-del');

gulp.task('clean', function() {
return promisedDel(['.build/']);
});
```

// do async stuff
setTimeout(function() {
deferred.resolve();
}, 1);
##### Return a child process

return deferred.promise;
```js
gulp.task('clean', function() {
return spawn('rm', ['-rf', path.join(__dirname, 'build')]);
});

```

**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:
##### Return a RxJS observable

- 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.
```js
var Observable = require('rx').Observable;

For these examples, let's presume you have two tasks, "one" and "two" that you specifically want to run in this order:
gulp.task('sometask', function() {
return Observable.return(42);
});
```

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.
### gulp.parallel(tasks, ...)

So this example would look like this:
Takes a variable amount of task names or function and returns
a function of the composed tasks or functions. When using task names,
the task should already registered.

```js
var gulp = require('gulp');
When the returned function is executed, the tasks or functions will be executed in parallel,
all being executed at the same time. If an error occurs, all execution will complete.

// 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
```js
gulp.task('one', function(done) {
// do stuff
done();
});

// identifies a dependent task must be complete before this one begins
gulp.task('two', ['one'], function() {
// task 'one' is done now
gulp.task('two', function(done) {
// do stuff
done();
});

gulp.task('default', ['one', 'two']);
gulp.task('default', gulp.parallel('one', 'two', function(done) {
// do more stuff
done();
}));
```

#### tasks
Type: `Array`, `String` or `Function`

### gulp.watch(glob [, opts], tasks) or gulp.watch(glob [, opts, cb])
A task name, a function or an array of either.

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

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

#### glob
Type: `String` or `Array`
Takes a variable amount of task names or function and returns
a function of the composed tasks or functions. When using task names,
the tasks should already registered.

A single glob or array of globs that indicate which files to watch for changes.
When the returned function is executed, the tasks or functions will be executed
in series, each waiting for the prior to finish. If an error occurs,
execution will stop.

#### opts
Type: `Object`
```js
gulp.task('one', function(done) {
// do stuff
done();
});

Options, that are passed to [`gaze`](https://github.com/shama/gaze).
gulp.task('two', function(done) {
// do stuff
done();
});

gulp.task('default', gulp.series('one', 'two', function(done) {
// do more stuff
done();
}));
```

#### tasks
Type: `Array`
Type: `Array`, `String` or `Function`

Names of task(s) to run when a file changes, added with `gulp.task()`
A task name, a function or an array of either.

```js
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])
### gulp.watch(glob[, opts], tasks)

#### glob
Type: `String` or `Array`
Expand All @@ -241,33 +285,41 @@ Type: `Object`

Options, that are passed to [`gaze`](https://github.com/shama/gaze).

#### cb(event)
Type: `Function`
#### tasks
Type: `Array`, `Function` or `String`

A task name, a function or an array of either to run when a file changes.

When `tasks` is an array, the tasks will be run in parallel:
```
gulp.watch('*.js', [one, two]);
// is equivalent to
gulp.watch('*.js', gulp.parallel(one, two));
```

Callback to be called on each change.
```js
gulp.watch('js/**/*.js', ['uglify', 'reload', function(done) {
// do something
done();
}]);
```

If you need access to the event, `gulp.watch` returns an `EventEmitter` object
and you can listen to the `change` event:
```js
gulp.watch('js/**/*.js', function(event) {
var watcher = gulp.watch('js/**/*.js', ['uglify', 'reload', function(done) {
// do something
done();
}]);
watcher.on('change', function(event) {
console.log('File ' + event.path + ' was ' + event.type + ', running tasks...');
});
```

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.


[node-glob documentation]: https://github.com/isaacs/node-glob#options
[node-glob]: https://github.com/isaacs/node-glob
[glob-stream]: https://github.com/wearefractal/glob-stream
[gulp-if]: https://github.com/robrich/gulp-if
[Orchestrator]: https://github.com/robrich/orchestrator
[Undertaker]: https://github.com/phated/undertaker
[glob2base]: https://github.com/wearefractal/glob2base
8 changes: 4 additions & 4 deletions docs/recipes/delete-files-folder.md
View file
Expand Up @@ -29,17 +29,17 @@ In the gulpfile we want to clean out the contents of the `mobile` folder before
var gulp = require('gulp');
var del = require('del');

gulp.task('clean:mobile', function (cb) {
gulp.task('clean:mobile', function (done) {
del([
'dist/report.csv',
// here we use a globbing pattern to match everything inside the `mobile` folder
'dist/mobile/**',
// we don't want to clean this file though so we negate the pattern
'!dist/mobile/deploy.json'
], cb);
], done);
});

gulp.task('default', ['clean:mobile']);
gulp.task('default', gulp.series('clean:mobile'));
```


Expand Down Expand Up @@ -76,7 +76,7 @@ gulp.task('clean:tmp', function () {
.pipe(vinylPaths(del));
});

gulp.task('default', ['clean:tmp']);
gulp.task('default', gulp.series('clean:tmp'));
```

Only do this if you're already using other plugins in the pipeline, otherwise just use the module directly as `gulp.src` is costly.
2 changes: 1 addition & 1 deletion docs/recipes/maintain-directory-structure-while-globbing.md
View file
Expand Up @@ -27,7 +27,7 @@ If you want to maintain the structure, you need to pass `{base: '.'}` to `gulp.s

```js
gulp.task('task', function () {
gulp.src(['index.html',
return gulp.src(['index.html',
'css/**',
'js/**',
'lib/**',
Expand Down

0 comments on commit 8aac2e3

Please sign in to comment.