Docs: Add gulp.tree API & examples

Author: SyntaxRules

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