Skip to content

Commit ebb9818

Browse files
janiceilenephated
janiceilene
authored and
phated
committed
Docs: Update tree() documentation
1 parent b636a9c commit ebb9818

File tree

1 file changed

+154
-131
lines changed

1 file changed

+154
-131
lines changed

‎docs/api/tree.md

Lines changed: 154 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -5,151 +5,174 @@ hide_title: true
55
sidebar_label: tree()
66
-->
77

8-
# `gulp.tree(options)`
8+
# tree()
99

10-
Returns the tree of tasks. Inherited from [undertaker]. See the [undertaker docs for this function](https://github.com/phated/undertaker#treeoptions--object).
10+
Fetches the current task dependency tree - in the rare case that it is needed.
1111

12-
## options
13-
Type: `Object`
12+
Generally, `tree()` won't be used by gulp consumers, but it is exposed so the CLI can show the dependency graph of the tasks defined in a gulpfile.
1413

15-
Options to pass to [undertaker].
14+
## Usage
1615

17-
### options.deep
18-
Type: `Boolean`
16+
Example gulpfile:
17+
```js
1918

20-
Default: `false`
19+
const { series, parallel } = require('gulp');
2120

22-
If set to `true` whole tree should be returned.
21+
function one(cb) {
22+
// body omitted
23+
cb();
24+
}
2325

24-
## Example gulpfile
26+
function two(cb) {
27+
// body omitted
28+
cb();
29+
}
2530

26-
```js
27-
gulp.task('one', function(done) {
28-
// do stuff
29-
done();
30-
});
31-
32-
gulp.task('two', function(done) {
33-
// do stuff
34-
done();
35-
});
36-
37-
gulp.task('three', function(done) {
38-
// do stuff
39-
done();
40-
});
41-
42-
gulp.task('four', gulp.series('one', 'two'));
43-
44-
gulp.task('five',
45-
gulp.series('four',
46-
gulp.parallel('three', function(done) {
47-
// do more stuff
48-
done();
49-
})
50-
)
31+
function three(cb) {
32+
// body omitted
33+
cb();
34+
}
35+
36+
const four = series(one, two);
37+
38+
const five = series(four,
39+
parallel(three, function(cb) {
40+
// Body omitted
41+
cb();
42+
})
5143
);
44+
45+
module.exports = { one, two, three, four, five };
46+
```
47+
48+
Output for `tree()`:
49+
```js
50+
{
51+
label: 'Tasks',
52+
nodes: [ 'one', 'two', 'three', 'four', 'five' ]
53+
}
5254
```
5355

54-
## Example tree output
5556

57+
Output for `tree({ deep: true })`:
5658
```js
57-
gulp.tree()
58-
59-
// output: [ 'one', 'two', 'three', 'four', 'five' ]
60-
61-
gulp.tree({ deep: true })
62-
63-
/*output: [
64-
{
65-
"label":"one",
66-
"type":"task",
67-
"nodes":[]
68-
},
69-
{
70-
"label":"two",
71-
"type":"task",
72-
"nodes":[]
73-
},
74-
{
75-
"label":"three",
76-
"type":"task",
77-
"nodes":[]
78-
},
79-
{
80-
"label":"four",
81-
"type":"task",
82-
"nodes":[
83-
{
84-
"label":"<series>",
85-
"type":"function",
86-
"nodes":[
87-
{
88-
"label":"one",
89-
"type":"task",
90-
"nodes":[]
91-
},
92-
{
93-
"label":"two",
94-
"type":"task",
95-
"nodes":[]
96-
}
97-
]
98-
}
59+
{
60+
label: "Tasks",
61+
nodes: [
62+
{
63+
label: "one",
64+
type: "task",
65+
nodes: []
66+
},
67+
{
68+
label: "two",
69+
type: "task",
70+
nodes: []
71+
},
72+
{
73+
label: "three",
74+
type: "task",
75+
nodes: []
76+
},
77+
{
78+
label: "four",
79+
type: "task",
80+
nodes: [
81+
{
82+
label: "<series>",
83+
type: "function",
84+
branch: true,
85+
nodes: [
86+
{
87+
label: "one",
88+
type: "function",
89+
nodes: []
90+
},
91+
{
92+
label: "two",
93+
type: "function",
94+
nodes: []
95+
}
96+
]
97+
}
9998
]
100-
},
101-
{
102-
"label":"five",
103-
"type":"task",
104-
"nodes":[
105-
{
106-
"label":"<series>",
107-
"type":"function",
108-
"nodes":[
109-
{
110-
"label":"four",
111-
"type":"task",
112-
"nodes":[
113-
{
114-
"label":"<series>",
115-
"type":"function",
116-
"nodes":[
117-
{
118-
"label":"one",
119-
"type":"task",
120-
"nodes":[]
121-
},
122-
{
123-
"label":"two",
124-
"type":"task",
125-
"nodes":[]
126-
}
127-
]
128-
}
129-
]
130-
},
131-
{
132-
"label":"<parallel>",
133-
"type":"function",
134-
"nodes":[
135-
{
136-
"label":"three",
137-
"type":"task",
138-
"nodes":[]
139-
},
140-
{
141-
"label":"<anonymous>",
142-
"type":"function",
143-
"nodes":[]
144-
}
145-
]
146-
}
147-
]
148-
}
99+
},
100+
{
101+
label: "five",
102+
type: "task",
103+
nodes: [
104+
{
105+
label: "<series>",
106+
type: "function",
107+
branch: true,
108+
nodes: [
109+
{
110+
label: "<series>",
111+
type: "function",
112+
branch: true,
113+
nodes: [
114+
{
115+
label: "one",
116+
type: "function",
117+
nodes: []
118+
},
119+
{
120+
label: "two",
121+
type: "function",
122+
nodes: []
123+
}
124+
]
125+
},
126+
{
127+
label: "<parallel>",
128+
type: "function",
129+
branch: true,
130+
nodes: [
131+
{
132+
label: "three",
133+
type: "function",
134+
nodes: []
135+
},
136+
{
137+
label: "<anonymous>",
138+
type: "function",
139+
nodes: []
140+
}
141+
]
142+
}
143+
]
144+
}
149145
]
150-
}
151-
]
152-
*/
146+
}
147+
]
148+
}
149+
```
150+
151+
## Signature
152+
153+
```js
154+
tree([options])
153155
```
154156

155-
[undertaker]: https://github.com/gulpjs/undertaker
157+
### Parameters
158+
159+
| parameter | type | note |
160+
|:--------------:|------:|--------|
161+
| options | object | Detailed in [Options][options-section] below. |
162+
163+
### Returns
164+
165+
An object detailing the tree of registered tasks - containing nested objects with `'label'` and `'nodes'` properties (which is [archy][archy-external] compatible).
166+
167+
Each object may have a `type` property that can be used to determine if the node is a `task` or `function`.
168+
169+
Each object may have a `branch` property that - when `true` - indicates the node was created using `series()` or `parallel()`.
170+
171+
### Options
172+
173+
| name | type | default | note |
174+
|:-------:|:-------:|------------|--------|
175+
| deep | boolean | false | If true, the entire tree will be returned. When false, only top level tasks will be returned. |
176+
177+
[options-section]: #options
178+
[archy-external]: https://www.npmjs.com/package/archy

0 commit comments

Comments
 (0)