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