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. E.g. compiling Compass `compass compile` or get the current git branch `git branch`.
|
6 |
|
7 | **Use [StackOverflow](http://stackoverflow.com/questions/tagged/gruntjs) for support questions.**
|
8 |
|
9 |
|
10 | ## Getting Started
|
11 |
|
12 | If you haven't used [grunt][] before, be sure to check out the [Getting Started][] guide, as it explains how to create a [gruntfile][Getting Started] as well as install and use grunt plugins. Once you're familiar with that process, install this plugin with this command:
|
13 |
|
14 | ```sh
|
15 | $ npm install --save-dev grunt-shell
|
16 | ```
|
17 |
|
18 | Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
|
19 |
|
20 | ```js
|
21 | grunt.loadNpmTasks('grunt-shell');
|
22 | ```
|
23 |
|
24 | *Tip: the [load-grunt-tasks](https://github.com/sindresorhus/load-grunt-tasks) module makes it easier to load multiple grunt tasks.*
|
25 |
|
26 | [grunt]: http://gruntjs.com
|
27 | [Getting Started]: https://github.com/gruntjs/grunt/wiki/Getting-started
|
28 |
|
29 |
|
30 | ## Documentation
|
31 |
|
32 |
|
33 | ### Example config
|
34 |
|
35 | ```js
|
36 | grunt.initConfig({
|
37 | shell: { // Task
|
38 | listFolders: { // Target
|
39 | options: { // Options
|
40 | stderr: false
|
41 | },
|
42 | command: 'ls'
|
43 | }
|
44 | }
|
45 | });
|
46 |
|
47 | grunt.loadNpmTasks('grunt-shell');
|
48 | grunt.registerTask('default', ['shell']);
|
49 | ```
|
50 |
|
51 |
|
52 | ### Example usage
|
53 |
|
54 |
|
55 | #### Run command
|
56 |
|
57 | Create a folder named `test`.
|
58 |
|
59 | ```js
|
60 | grunt.initConfig({
|
61 | shell: {
|
62 | makeDir: {
|
63 | command: 'mkdir test'
|
64 | }
|
65 | }
|
66 | });
|
67 | ```
|
68 |
|
69 | The `command` property supports templates:
|
70 |
|
71 | ```js
|
72 | grunt.initConfig({
|
73 | testDir: 'test',
|
74 | shell: {
|
75 | makeDir: {
|
76 | command: 'mkdir <%= testDir %>'
|
77 | }
|
78 | }
|
79 | });
|
80 | ```
|
81 |
|
82 | You can also supply a function that returns the command:
|
83 |
|
84 | ```js
|
85 | grunt.initConfig({
|
86 | shell: {
|
87 | hello: {
|
88 | command: function () {
|
89 | return 'echo hello';
|
90 | }
|
91 | }
|
92 | }
|
93 | });
|
94 | ```
|
95 | Which can also take arguments:
|
96 |
|
97 | ```js
|
98 | module.exports = function(grunt) {
|
99 | grunt.loadNpmTasks('grunt-shell');
|
100 | grunt.initConfig({
|
101 | shell: {
|
102 | greet: {
|
103 | command: function (greeting) {
|
104 | return 'echo ' + greeting;
|
105 | }
|
106 | }
|
107 | }
|
108 | });
|
109 | grunt.registerTask('default', ['shell:greet:hello']);
|
110 | }
|
111 | ```
|
112 |
|
113 |
|
114 | #### Run command and display the output
|
115 |
|
116 | Output a directory listing in your Terminal.
|
117 |
|
118 | ```js
|
119 | grunt.initConfig({
|
120 | shell: {
|
121 | dirListing: {
|
122 | command: 'ls'
|
123 | }
|
124 | }
|
125 | });
|
126 | ```
|
127 |
|
128 |
|
129 | #### Custom callback
|
130 |
|
131 | Do whatever you want with the output.
|
132 |
|
133 | ```js
|
134 | function log(err, stdout, stderr, cb) {
|
135 | console.log(stdout);
|
136 | cb();
|
137 | }
|
138 |
|
139 | grunt.initConfig({
|
140 | shell: {
|
141 | dirListing: {
|
142 | command: 'ls',
|
143 | options: {
|
144 | callback: log
|
145 | }
|
146 | }
|
147 | }
|
148 | });
|
149 | ```
|
150 |
|
151 |
|
152 | #### Option passed to the .exec() method
|
153 |
|
154 | Run a command in another directory. In this example we run it in a subfolder using the `cwd` (current working directory) option.
|
155 |
|
156 | ```js
|
157 | grunt.initConfig({
|
158 | shell: {
|
159 | subfolderLs: {
|
160 | command: 'ls',
|
161 | options: {
|
162 | stderr: false,
|
163 | execOptions: {
|
164 | cwd: 'tasks'
|
165 | }
|
166 | }
|
167 | }
|
168 | }
|
169 | });
|
170 | ```
|
171 |
|
172 |
|
173 | #### Multiple commands
|
174 |
|
175 | 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).
|
176 |
|
177 | ```js
|
178 | grunt.initConfig({
|
179 | shell: {
|
180 | multiple: {
|
181 | command: [
|
182 | 'mkdir test',
|
183 | 'cd test',
|
184 | 'ls'
|
185 | ].join('&&')
|
186 | }
|
187 | }
|
188 | });
|
189 | ```
|
190 |
|
191 |
|
192 | ### Config
|
193 |
|
194 |
|
195 | #### command
|
196 |
|
197 | **Required**
|
198 | Type: `string`, `function`
|
199 |
|
200 | The command you want to run or a function which returns it. Supports underscore templates.
|
201 |
|
202 |
|
203 | ### Options
|
204 |
|
205 |
|
206 | #### stdout
|
207 |
|
208 | Type: `boolean`
|
209 | Default: `true`
|
210 |
|
211 | Show stdout in the Terminal.
|
212 |
|
213 |
|
214 | #### stderr
|
215 |
|
216 | Type: `boolean`
|
217 | Default: `true`
|
218 |
|
219 | Show stderr in the Terminal.
|
220 |
|
221 |
|
222 | #### stdin
|
223 |
|
224 | Type: `boolean`
|
225 | Default: `true`
|
226 |
|
227 | Forward the terminal's stdin to the command.
|
228 |
|
229 |
|
230 | #### failOnError
|
231 |
|
232 | Type: `boolean`
|
233 | Default: `true`
|
234 |
|
235 | Fail task if it encounters an error. Does not apply if you specify a `callback`.
|
236 |
|
237 |
|
238 | #### callback(err, stdout, stderr, cb)
|
239 |
|
240 | Type: `function`
|
241 | Default: `function () {}`
|
242 |
|
243 | Lets you override the default callback with your own.
|
244 |
|
245 | **Make sure to call the `cb` method when you're done.**
|
246 |
|
247 |
|
248 | #### execOptions
|
249 |
|
250 | Type: `object`
|
251 |
|
252 | Specify some options to be passed to the [.exec()](http://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback) method:
|
253 |
|
254 | - `cwd` String *Current working directory of the child process*
|
255 | - `env` Object *Environment key-value pairs*
|
256 | - `setsid` Boolean
|
257 | - `encoding` String *(Default: 'utf8')*
|
258 | - `timeout` Number *(Default: 0)*
|
259 | - `maxBuffer` Number *(Default: 200\*1024)*
|
260 | - `killSignal` String *(Default: 'SIGTERM')*
|
261 |
|
262 |
|
263 | ## License
|
264 |
|
265 | MIT © [Sindre Sorhus](http://sindresorhus.com)
|