1 | # grunt-shell [![Build Status](https://travis-ci.org/sindresorhus/grunt-shell.svg?branch=master)](https://travis-ci.org/sindresorhus/grunt-shell)
|
2 |
|
3 | > Run shell commands
|
4 |
|
5 | A good way to interact with other CLI tools. For example, get the current Git branch with `git branch`.
|
6 |
|
7 | **Use [Stack Overflow](https://stackoverflow.com/questions/tagged/gruntjs) for support questions.**
|
8 |
|
9 |
|
10 | ## Install
|
11 |
|
12 | ```
|
13 | $ npm install --save-dev grunt-shell
|
14 | ```
|
15 |
|
16 | <a href="https://www.patreon.com/sindresorhus">
|
17 | <img src="https://c5.patreon.com/external/logo/become_a_patron_button@2x.png" width="160">
|
18 | </a>
|
19 |
|
20 |
|
21 | ## Usage
|
22 |
|
23 | ```js
|
24 | require('load-grunt-tasks')(grunt);
|
25 |
|
26 | grunt.initConfig({
|
27 | shell: {
|
28 | options: {
|
29 | stderr: false
|
30 | },
|
31 | target: {
|
32 | command: 'ls'
|
33 | },
|
34 | another: 'ls ./src' // Shorthand
|
35 | }
|
36 | });
|
37 |
|
38 | grunt.registerTask('default', ['shell']);
|
39 | ```
|
40 |
|
41 |
|
42 | ## Examples
|
43 |
|
44 | ### Run command
|
45 |
|
46 | Create a folder named `test`.
|
47 |
|
48 | ```js
|
49 | grunt.initConfig({
|
50 | shell: {
|
51 | makeDir: {
|
52 | command: 'mkdir test'
|
53 | }
|
54 | }
|
55 | });
|
56 | ```
|
57 |
|
58 | The `command` property supports templates:
|
59 |
|
60 | ```js
|
61 | grunt.initConfig({
|
62 | testDir: 'test',
|
63 | shell: {
|
64 | makeDir: {
|
65 | command: 'mkdir <%= testDir %>'
|
66 | }
|
67 | }
|
68 | });
|
69 | ```
|
70 |
|
71 | You can also supply a function that returns the command:
|
72 |
|
73 | ```js
|
74 | grunt.initConfig({
|
75 | shell: {
|
76 | hello: {
|
77 | command: () => 'echo hello'
|
78 | }
|
79 | }
|
80 | });
|
81 | ```
|
82 |
|
83 | Which can also take arguments:
|
84 |
|
85 | ```js
|
86 | module.exports = grunt => {
|
87 | grunt.loadNpmTasks('grunt-shell');
|
88 | grunt.initConfig({
|
89 | shell: {
|
90 | greet: {
|
91 | command: greeting => `echo ${greeting}`
|
92 | }
|
93 | }
|
94 | });
|
95 | grunt.registerTask('default', ['shell:greet:hello']);
|
96 | }
|
97 | ```
|
98 |
|
99 | ### Run command and display the output
|
100 |
|
101 | Output a directory listing in your Terminal.
|
102 |
|
103 | ```js
|
104 | grunt.initConfig({
|
105 | shell: {
|
106 | dirListing: {
|
107 | command: 'ls'
|
108 | }
|
109 | }
|
110 | });
|
111 | ```
|
112 |
|
113 | ### Custom callback
|
114 |
|
115 | Do whatever you want with the output.
|
116 |
|
117 | ```js
|
118 | function log(error, stdout, stderr, callback) {
|
119 | if (error) {
|
120 | callback(error);
|
121 | return;
|
122 | }
|
123 |
|
124 | console.log(stdout);
|
125 | callback();
|
126 | }
|
127 |
|
128 | grunt.initConfig({
|
129 | shell: {
|
130 | dirListing: {
|
131 | command: 'ls',
|
132 | options: {
|
133 | callback: log
|
134 | }
|
135 | }
|
136 | }
|
137 | });
|
138 | ```
|
139 |
|
140 | ### Option passed to the .exec() method
|
141 |
|
142 | Run a command in another directory. In this example, we run it in a subfolder using the `cwd` (current working directory) option.
|
143 |
|
144 | ```js
|
145 | grunt.initConfig({
|
146 | shell: {
|
147 | subfolderLs: {
|
148 | command: 'ls',
|
149 | options: {
|
150 | stderr: false,
|
151 | execOptions: {
|
152 | cwd: 'tasks'
|
153 | }
|
154 | }
|
155 | }
|
156 | }
|
157 | });
|
158 | ```
|
159 |
|
160 | ### Multiple commands
|
161 |
|
162 | Run multiple commands by placing them in an array which is joined using `&&` or `;`. `&&` means run this only if the previous command succeeded. You can also use `&` to have the commands run concurrently (by executing all commands except the last one in a subshell).
|
163 |
|
164 | ```js
|
165 | grunt.initConfig({
|
166 | shell: {
|
167 | multiple: {
|
168 | command: [
|
169 | 'mkdir test',
|
170 | 'cd test',
|
171 | 'ls'
|
172 | ].join('&&')
|
173 | }
|
174 | }
|
175 | });
|
176 | ```
|
177 |
|
178 |
|
179 | ## Config
|
180 |
|
181 | ### command
|
182 |
|
183 | *Required*<br>
|
184 | Type: `string` `Function`
|
185 |
|
186 | Command to run or a function which returns the command. Supports underscore templates.
|
187 |
|
188 | *Command can be omitted by directly setting the target with the command.*
|
189 |
|
190 | ### cwd
|
191 |
|
192 | Type: `string`
|
193 |
|
194 | Shortcut. Same as `options.execOptions.cwd` (see below).
|
195 |
|
196 |
|
197 | ## Options
|
198 |
|
199 | ### stdout
|
200 |
|
201 | Type: `boolean`<br>
|
202 | Default: `true`
|
203 |
|
204 | Show stdout in the terminal.
|
205 |
|
206 | ### stderr
|
207 |
|
208 | Type: `boolean`<br>
|
209 | Default: `true`
|
210 |
|
211 | Show stderr in the terminal.
|
212 |
|
213 | ### stdin
|
214 |
|
215 | Type: `boolean`<br>
|
216 | Default: `true`
|
217 |
|
218 | Forward the terminal's stdin to the command.
|
219 |
|
220 | ### failOnError
|
221 |
|
222 | Type: `boolean`<br>
|
223 | Default: `true`
|
224 |
|
225 | Fail task if it encounters an error. Doesn't apply if you specify a `callback`.
|
226 |
|
227 | ### stdinRawMode
|
228 |
|
229 | Type: `boolean`<br>
|
230 | Default: `false`
|
231 |
|
232 | Set `stdin` to [act as a raw device](https://nodejs.org/api/tty.html#tty_readstream_setrawmode_mode).
|
233 |
|
234 | ### callback(error, stdout, stderr, callback)
|
235 |
|
236 | Type: `Function`
|
237 |
|
238 | Lets you override the default callback with your own.
|
239 |
|
240 | **Make sure to call the `callback` method when you're done.** Supply an error as the first argument to `callback` to print a warning and cause the task to fail.
|
241 |
|
242 | ### preferLocal
|
243 |
|
244 | Type: `boolean`<br>
|
245 | Default: `true`
|
246 |
|
247 | Execute local binaries by name like [`$ npm run-script`](https://www.keithcirkel.co.uk/how-to-use-npm-as-a-build-tool/).
|
248 |
|
249 | ### execOptions
|
250 |
|
251 | Type: `Object`
|
252 |
|
253 | Specify some options to be passed to the [.exec()](https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback) method:
|
254 |
|
255 | - `cwd` string *Current working directory of the child process*
|
256 | - `env` Object *Environment key-value pairs*
|
257 | - `setsid` boolean
|
258 | - `encoding` string *(Default: `'utf8'`)*
|
259 | - `timeout` number *(Default: `0`)*
|
260 | - `maxBuffer` number *(Default: `1000 * 1000 * 10` → 10 MB)*
|
261 | - `killSignal` string *(Default: `'SIGTERM'`)*
|
262 |
|
263 |
|
264 | ## License
|
265 |
|
266 | MIT © [Sindre Sorhus](https://sindresorhus.com)
|