1 | <p align="center">
|
2 | <a href="http://gulpjs.com">
|
3 | <img height="257" width="114" src="https://raw.githubusercontent.com/gulpjs/artwork/master/gulp-2x.png">
|
4 | </a>
|
5 | </p>
|
6 |
|
7 | # gulp-cli
|
8 |
|
9 | [![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Build Status][travis-image]][travis-url] [![AppVeyor Build Status][appveyor-image]][appveyor-url] [![Coveralls Status][coveralls-image]][coveralls-url] [![Gitter chat][gitter-image]][gitter-url]
|
10 |
|
11 | Command Line Utility for Gulp
|
12 |
|
13 | ## Usage
|
14 |
|
15 | ```bash
|
16 | > gulp [flags] <task> <task>...
|
17 | ```
|
18 |
|
19 | ## Custom Metadata
|
20 |
|
21 | When listing tasks with the `gulp -T` command, gulp-cli displays some custom metadata as defined upon task functions. Currently supported properties:
|
22 |
|
23 | * `task.description` - String of the description to display.
|
24 |
|
25 | ```js
|
26 | function clean() { ... }
|
27 | clean.description = 'Cleans up generated files.';
|
28 | ```
|
29 |
|
30 | * `task.flags` - Object with key/value pairs being flag/description to display.
|
31 |
|
32 | ```js
|
33 | function build() { ... }
|
34 | build.flags = {
|
35 | '--prod': 'Builds in production mode.'
|
36 | };
|
37 | ```
|
38 |
|
39 | Example Usage:
|
40 |
|
41 | ```js
|
42 | function build() { ... }
|
43 | build.description = 'Build entire project.';
|
44 | build.flags = {
|
45 | '--prod': 'Builds in production mode (minification, etc).'
|
46 | };
|
47 | // gulp 3.x
|
48 | gulp.task('build', build);
|
49 | // gulp 4.x
|
50 | gulp.task(build);
|
51 | ```
|
52 |
|
53 | ## Tasks
|
54 |
|
55 | The task(s) listed on the command line will be executed.
|
56 | If more than one task is listed, Gulp will execute all of them
|
57 | concurrently, that is, as if they had all been listed as dependencies of
|
58 | a single task.
|
59 |
|
60 | Gulp does not serialize tasks listed on the command line. From using
|
61 | other comparable tools users may expect to execute something like
|
62 | `gulp clean build`, with tasks named `clean` and `build`. This will not
|
63 | produce the intended result, as the two tasks will be executed
|
64 | concurrently.
|
65 |
|
66 | Just running `gulp` will execute the task `default`. If there is no
|
67 | `default` task, gulp will error.
|
68 |
|
69 | ## Completion
|
70 | > Thanks to the grunt team, specifically Tyler Kellen
|
71 |
|
72 | To enable tasks auto-completion in shell you should add `eval "$(gulp --completion=shell)"` in your `.shellrc` file.
|
73 |
|
74 | ###### Bash:
|
75 |
|
76 | Add `eval "$(gulp --completion=bash)"` to `~/.bashrc`.
|
77 |
|
78 | ###### Zsh:
|
79 |
|
80 | Add `eval "$(gulp --completion=zsh)"` to `~/.zshrc`.
|
81 |
|
82 | ###### Powershell:
|
83 |
|
84 | Add `Invoke-Expression ((gulp --completion=powershell) -join [System.Environment]::NewLine)` to `$PROFILE`.
|
85 |
|
86 | ###### Fish:
|
87 |
|
88 | Add `gulp --completion=fish | source` to `~/.config/fish/config.fish`.
|
89 |
|
90 | ## Compilers
|
91 |
|
92 | You can find a list of supported languages at https://github.com/js-cli/js-interpret. If you would like to add support for a new language, send pull requests/open issues on that project.
|
93 |
|
94 | ## Environment
|
95 |
|
96 | The CLI adds process.env.INIT_CWD which is the original cwd it was launched from.
|
97 |
|
98 | ## Configuration
|
99 |
|
100 | Configuration is supported through the use of a `.gulp.*` file (e.g. `.gulp.json`, `.gulp.yml`). You can find a list of supported languages at https://github.com/js-cli/js-interpret.
|
101 |
|
102 | Configuration from the home directory (`~`) and current working directory (`cwd`) are merged with `cwd` taking precedence.
|
103 |
|
104 | Supported configurations properties:
|
105 |
|
106 | | Property | Description |
|
107 | |--------------------|-------------|
|
108 | | description | Top-level description of the project/gulpfile (Replaces "Tasks for ~/path/of/gulpfile.js") |
|
109 | | flags.continue | Continue execution of tasks upon failure by default. |
|
110 | | flags.compactTasks | Reduce the output of task dependency tree by default. |
|
111 | | flags.tasksDepth | Set default depth of task dependency tree. |
|
112 | | flags.gulpfile | Set a default gulpfile |
|
113 | | flags.silent | Silence logging by default |
|
114 |
|
115 | ## Flags
|
116 |
|
117 | gulp has very few flags to know about. All other flags are for tasks to use if needed.
|
118 |
|
119 | __Some flags only work with gulp 4 and will be ignored when invoked against gulp 3.__
|
120 |
|
121 | <table>
|
122 | <thead>
|
123 | <tr>
|
124 | <th width="25%">Flag</th>
|
125 | <th width="15%">Short Flag</th>
|
126 | <th>Description</th>
|
127 | </tr>
|
128 | </thead>
|
129 | <tbody>
|
130 | <tr>
|
131 | <td>--help</td>
|
132 | <td>-h</td>
|
133 | <td>Show this help.</td>
|
134 | </tr>
|
135 | <tr>
|
136 | <td>--version</td>
|
137 | <td>-v</td>
|
138 | <td>Print the global and local gulp versions.</td>
|
139 | </tr>
|
140 | <tr>
|
141 | <td>--require [path]</td>
|
142 | <td></td>
|
143 | <td>Will require a module before running the gulpfile. This is useful for transpilers but also has other applications.</td>
|
144 | </tr>
|
145 | <tr>
|
146 | <td>--gulpfile [path]</td>
|
147 | <td></td>
|
148 | <td>Manually set path of gulpfile. Useful if you have multiple gulpfiles. This will set the CWD to the gulpfile directory as well.</td>
|
149 | </tr>
|
150 | <tr>
|
151 | <td>--cwd [path]</td>
|
152 | <td></td>
|
153 | <td>Manually set the CWD. The search for the gulpfile, as well as the relativity of all requires will be from here.</td>
|
154 | </tr>
|
155 | <tr>
|
156 | <td>--verify [path (optional)]</td>
|
157 | <td></td>
|
158 | <td>Will verify plugins referenced in project's package.json against the plugins blacklist.</td>
|
159 | </tr>
|
160 | <tr>
|
161 | <td>--tasks</td>
|
162 | <td>-T</td>
|
163 | <td>Print the task dependency tree for the loaded gulpfile.</td>
|
164 | </tr>
|
165 | <tr>
|
166 | <td>--tasks-simple</td>
|
167 | <td></td>
|
168 | <td>Print a plaintext list of tasks for the loaded gulpfile.</td>
|
169 | </tr>
|
170 | <tr>
|
171 | <td>--tasks-json [path]</td>
|
172 | <td></td>
|
173 | <td>Print the task dependency tree, in JSON format, for the loaded gulpfile. The [path] argument is optional, and if given writes the JSON to the path.</td>
|
174 | </tr>
|
175 | <tr>
|
176 | <td>--tasks-depth [number]</td>
|
177 | <td></td>
|
178 | <td>Specify the depth of the task dependency tree to print. This flag can be used with --tasks or --tasks-json. (This flag was named --depth before but is deprecated.)</td>
|
179 | </tr>
|
180 | <tr>
|
181 | <td>--compact-tasks</td>
|
182 | <td></td>
|
183 | <td>Reduce the output of task dependency tree by printing only top tasks and their child tasks. This flag can be used with --tasks or --tasks-json.</td>
|
184 | </tr>
|
185 | <tr>
|
186 | <td>--sort-tasks</td>
|
187 | <td></td>
|
188 | <td>Will sort top tasks of task dependency tree. This flag can be used with --tasks.</td>
|
189 | </tr>
|
190 | <tr>
|
191 | <td>--color</td>
|
192 | <td></td>
|
193 | <td>Will force gulp and gulp plugins to display colors, even when no color support is detected.</td>
|
194 | </tr>
|
195 | <tr>
|
196 | <td>--no-color</td>
|
197 | <td></td>
|
198 | <td>Will force gulp and gulp plugins to not display colors, even when color support is detected.</td>
|
199 | </tr>
|
200 | <tr>
|
201 | <td>--silent</td>
|
202 | <td>-S</td>
|
203 | <td>Suppress all gulp logging.</td>
|
204 | </tr>
|
205 | <tr>
|
206 | <td>--continue</td>
|
207 | <td></td>
|
208 | <td>Continue execution of tasks upon failure.</td>
|
209 | </tr>
|
210 | <tr>
|
211 | <td>--log-level</td>
|
212 | <td>-L</td>
|
213 | <td>Set the loglevel. -L for least verbose and -LLLL for most verbose. -LLL is default.</td>
|
214 | </tr>
|
215 | </tbody>
|
216 | </table>
|
217 |
|
218 | ## License
|
219 |
|
220 | MIT
|
221 |
|
222 | [gittip-url]: https://www.gittip.com/WeAreFractal/
|
223 | [gittip-image]: http://img.shields.io/gittip/WeAreFractal.svg
|
224 |
|
225 | [downloads-image]: http://img.shields.io/npm/dm/gulp-cli.svg
|
226 | [npm-url]: https://npmjs.org/package/gulp-cli
|
227 | [npm-image]: http://img.shields.io/npm/v/gulp-cli.svg
|
228 |
|
229 | [travis-url]: https://travis-ci.org/gulpjs/gulp-cli
|
230 | [travis-image]: http://img.shields.io/travis/gulpjs/gulp-cli.svg?label=travis-ci
|
231 |
|
232 | [appveyor-url]: https://ci.appveyor.com/project/gulpjs/gulp-cli
|
233 | [appveyor-image]: https://img.shields.io/appveyor/ci/gulpjs/gulp-cli.svg?label=appveyor
|
234 |
|
235 | [coveralls-url]: https://coveralls.io/r/gulpjs/gulp-cli
|
236 | [coveralls-image]: http://img.shields.io/coveralls/gulpjs/gulp-cli/master.svg
|
237 |
|
238 | [gitter-url]: https://gitter.im/gulpjs/gulp
|
239 | [gitter-image]: https://badges.gitter.im/gulpjs/gulp.png
|