Docs: Add gulp.tree API & examples

docs/API.md

@@ -535,6 +535,154 @@ Type: String
 
 The path to the file that triggered the event.
 
+### gulp.tree(options)
+
+Returns the tree of tasks. Inherited from [undertaker]. See the [undertaker docs for this function](https://github.com/phated/undertaker#treeoptions--object).
+
+#### options
+Type: Object
+
+Options to pass to [undertaker].
+
+##### options.deep
+Type: `Boolean`
+
+Default: `false`
+
+If set to true whole tree should be returned.
+
+#### Example gulpfile
+
+```js
+gulp.task('one', function(done) {
+ // do stuff
+ done();
+});
+
+gulp.task('two', function(done) {
+ // do stuff
+ done();
+});
+
+gulp.task('three', function(done) {
+ // do stuff
+ done();
+});
+
+gulp.task('four', gulp.series('one', 'two'));
+
+gulp.task('five',
+ gulp.series('four',
+ gulp.parallel('three', function(done) {
+ // do more stuff
+ done();
+ })
+ )
+);
+```
+
+#### Example tree output
+
+```js
+gulp.tree()
+
+// output: [ 'one', 'two', 'three', 'four', 'five' ]
+
+gulp.tree({ deep: true })
+
+/*output: [
+ {
+ "label":"one",
+ "type":"task",
+ "nodes":[]
+ },
+ {
+ "label":"two",
+ "type":"task",
+ "nodes":[]
+ },
+ {
+ "label":"three",
+ "type":"task",
+ "nodes":[]
+ },
+ {
+ "label":"four",
+ "type":"task",
+ "nodes":[
+ {
+ "label":"<series>",
+ "type":"function",
+ "nodes":[
+ {
+ "label":"one",
+ "type":"task",
+ "nodes":[]
+ },
+ {
+ "label":"two",
+ "type":"task",
+ "nodes":[]
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "label":"five",
+ "type":"task",
+ "nodes":[
+ {
+ "label":"<series>",
+ "type":"function",
+ "nodes":[
+ {
+ "label":"four",
+ "type":"task",
+ "nodes":[
+ {
+ "label":"<series>",
+ "type":"function",
+ "nodes":[
+ {
+ "label":"one",
+ "type":"task",
+ "nodes":[]
+ },
+ {
+ "label":"two",
+ "type":"task",
+ "nodes":[]
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "label":"<parallel>",
+ "type":"function",
+ "nodes":[
+ {
+ "label":"three",
+ "type":"task",
+ "nodes":[]
+ },
+ {
+ "label":"<anonymous>",
+ "type":"function",
+ "nodes":[]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+]
+*/
+```
+
+
 [Function.name]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/name
 [gaze]: https://github.com/shama/gaze
 [glob-stream]: https://github.com/gulpjs/glob-stream