-
-
Notifications
You must be signed in to change notification settings - Fork 4.2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Docs: Split API docs into separate markdown files
- Loading branch information
Showing
13 changed files
with
904 additions
and
846 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
<!-- front-matter | ||
id: api-toc | ||
title: API Table of Contents | ||
hide_title: true | ||
sidebar_label: api-toc | ||
--> | ||
|
||
## gulp API docs | ||
|
||
* [gulp.src](src.md) - Emit files matching one or more globs | ||
* [gulp.dest](dest.md) - Write files to directories | ||
* [gulp.symlink](symlink.md) - Write files to symlinks | ||
* [gulp.task](task.md) - Define tasks | ||
* [gulp.lastRun](lastRun.md) - Get timestamp of last successful run | ||
* [gulp.parallel](parallel.md) - Run tasks in parallel | ||
* [gulp.series](series.md) - Run tasks in series | ||
* [gulp.watch](watch.md) - Do something when a file changes | ||
* [gulp.tree](tree.md) - Get the tree of tasks | ||
* [gulp.registry](registry.md) - Get or set the task registry |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,66 @@ | ||
<!-- front-matter | ||
id: api-dest | ||
title: dest() | ||
hide_title: true | ||
sidebar_label: dest() | ||
--> | ||
|
||
# `gulp.dest(path[, options])` | ||
|
||
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 | ||
gulp.src('./client/templates/*.pug') | ||
.pipe(pug()) | ||
.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. | ||
|
||
## path | ||
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]. | ||
|
||
## options | ||
Type: `Object` | ||
|
||
### options.cwd | ||
Type: `String` | ||
|
||
Default: `process.cwd()` | ||
|
||
`cwd` for the output folder, only has an effect if provided output folder is | ||
relative. | ||
|
||
### options.mode | ||
Type: `String` or `Number` | ||
|
||
Default: the mode of the input file (file.stat.mode) or the process mode | ||
if the input file has no mode property. | ||
|
||
Octal permission specifying the mode the files should be created with: e.g. | ||
`"0744"`, `0744` or `484` (`0744` in base 10). | ||
|
||
### options.dirMode | ||
Type: `String` or `Number` | ||
|
||
Default: Default is the process mode. | ||
|
||
Octal permission specifying the mode the directory should be created with: e.g. | ||
`"0755"`, `0755` or `493` (`0755` in base 10). | ||
|
||
### options.overwrite | ||
Type: `Boolean` | ||
|
||
Default: `true` | ||
|
||
Specify if existing files with the same path should be overwritten or not. | ||
|
||
[vinyl File instance]: https://github.com/gulpjs/vinyl |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,43 @@ | ||
<!-- front-matter | ||
id: api-lastRun | ||
title: lastRun() | ||
hide_title: true | ||
sidebar_label: lastRun() | ||
--> | ||
|
||
# `gulp.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. | ||
|
||
[fs stats]: https://nodejs.org/api/fs.html#fs_class_fs_stats |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,40 @@ | ||
<!-- front-matter | ||
id: api-parallel | ||
title: parallel() | ||
hide_title: true | ||
sidebar_label: parallel() | ||
--> | ||
|
||
# `gulp.parallel(...tasks)` | ||
|
||
Takes a number of task names or functions and returns a function of the composed | ||
tasks or functions. | ||
|
||
When using task names, the task should already be registered. | ||
|
||
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. | ||
|
||
```js | ||
gulp.task('one', function(done) { | ||
// do stuff | ||
done(); | ||
}); | ||
|
||
gulp.task('two', function(done) { | ||
// do stuff | ||
done(); | ||
}); | ||
|
||
gulp.task('default', gulp.parallel('one', 'two', function(done) { | ||
// do more stuff | ||
done(); | ||
})); | ||
``` | ||
|
||
## tasks | ||
Type: `Array`, `String` or `Function` | ||
|
||
A task name, a function or an array of either. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,64 @@ | ||
<!-- front-matter | ||
id: api-registry | ||
title: registry() | ||
hide_title: true | ||
sidebar_label: registry() | ||
--> | ||
|
||
# `gulp.registry([registry])` | ||
|
||
Get or set the underlying task registry. Inherited from [undertaker]; see the undertaker documention on [registries](https://github.com/phated/undertaker#registryregistryinstance). Using this, you can change registries that enhance gulp in different ways. Utilizing a custom registry has at least three use cases: | ||
|
||
- [Sharing tasks](https://github.com/phated/undertaker#sharing-tasks) | ||
- [Sharing functionality](https://github.com/phated/undertaker#sharing-functionalities) (e.g. you could override the task prototype to add some additional logging, bind task metadata or include some config settings.) | ||
- Handling other behavior that hooks into the registry lifecycle (see [gulp-hub](https://github.com/frankwallis/gulp-hub) for an example) | ||
|
||
To build your own custom registry see the [undertaker documentation on custom registries](https://github.com/phated/undertaker#custom-registries). | ||
|
||
## registry | ||
|
||
A registry instance. When passed in, the tasks from the current registry will be transferred to the new registry and then current registry will be replaced with the new registry. | ||
|
||
## Example | ||
|
||
This example shows how to create and use a simple custom registry to add tasks. | ||
|
||
```js | ||
//gulpfile.js | ||
var gulp = require('gulp'); | ||
|
||
var companyTasks = require('./myCompanyTasksRegistry.js'); | ||
|
||
gulp.registry(companyTasks); | ||
|
||
gulp.task('one', gulp.parallel('someCompanyTask', function(done) { | ||
console.log('in task one'); | ||
done(); | ||
})); | ||
``` | ||
|
||
```js | ||
//myCompanyTasksRegistry.js | ||
var util = require('util'); | ||
|
||
var DefaultRegistry = require('undertaker-registry'); | ||
|
||
function MyCompanyTasksRegistry() { | ||
DefaultRegistry.call(this); | ||
} | ||
util.inherits(MyCompanyTasksRegistry, DefaultRegistry); | ||
|
||
MyCompanyTasksRegistry.prototype.init = function(gulp) { | ||
gulp.task('clean', function(done) { | ||
done(); | ||
}); | ||
gulp.task('someCompanyTask', function(done) { | ||
console.log('performing some company task.'); | ||
done(); | ||
}); | ||
}; | ||
|
||
module.exports = new MyCompanyTasksRegistry(); | ||
``` | ||
|
||
[undertaker]: https://github.com/gulpjs/undertaker |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,39 @@ | ||
<!-- front-matter | ||
id: api-series | ||
title: series() | ||
hide_title: true | ||
sidebar_label: series() | ||
--> | ||
|
||
# `gulp.series(...tasks)` | ||
|
||
Takes a number of task names or functions and returns a function of the composed | ||
tasks or functions. | ||
|
||
When using task names, the task should already be registered. | ||
|
||
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. | ||
|
||
```js | ||
gulp.task('one', function(done) { | ||
// do stuff | ||
done(); | ||
}); | ||
|
||
gulp.task('two', function(done) { | ||
// do stuff | ||
done(); | ||
}); | ||
|
||
gulp.task('default', gulp.series('one', 'two', function(done) { | ||
// do more stuff | ||
done(); | ||
})); | ||
``` | ||
|
||
## tasks | ||
Type: `Array`, `String` or `Function` | ||
|
||
A task name, a function or an array of either. |
Oops, something went wrong.