.config/coc/extensions/node_modules/coc-prettier/node_modules/os-locale/node_modules/execa/readme.md

   1 # execa [![Build Status: Linux](https://travis-ci.org/sindresorhus/execa.svg?branch=master)](https://travis-ci.org/sindresorhus/execa) [![Build status: Windows](https://ci.appveyor.com/api/projects/status/x5ajamxtjtt93cqv/branch/master?svg=true)](https://ci.appveyor.com/project/sindresorhus/execa/branch/master) [![Coverage Status](https://coveralls.io/repos/github/sindresorhus/execa/badge.svg?branch=master)](https://coveralls.io/github/sindresorhus/execa?branch=master)
   2
   3 > A better [`child_process`](https://nodejs.org/api/child_process.html)
   4
   5
   6 ## Why
   7
   8 - Promise interface.
   9 - [Strips EOF](https://github.com/sindresorhus/strip-eof) from the output so you don't have to `stdout.trim()`.
  10 - Supports [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) binaries cross-platform.
  11 - [Improved Windows support.](https://github.com/IndigoUnited/node-cross-spawn#why)
  12 - Higher max buffer. 10 MB instead of 200 KB.
  13 - [Executes locally installed binaries by name.](#preferlocal)
  14 - [Cleans up spawned processes when the parent process dies.](#cleanup)
  15
  16
  17 ## Install
  18
  19 ```
  20 $ npm install execa
  21 ```
  22
  23 <a href="https://www.patreon.com/sindresorhus">
  24         <img src="https://c5.patreon.com/external/logo/become_a_patron_button@2x.png" width="160">
  25 </a>
  26
  27
  28 ## Usage
  29
  30 ```js
  31 const execa = require('execa');
  32
  33 (async () => {
  34         const {stdout} = await execa('echo', ['unicorns']);
  35         console.log(stdout);
  36         //=> 'unicorns'
  37 })();
  38 ```
  39
  40 Additional examples:
  41
  42 ```js
  43 const execa = require('execa');
  44
  45 (async () => {
  46         // Pipe the child process stdout to the current stdout
  47         execa('echo', ['unicorns']).stdout.pipe(process.stdout);
  48
  49
  50         // Run a shell command
  51         const {stdout} = await execa.shell('echo unicorns');
  52         //=> 'unicorns'
  53
  54
  55         // Catching an error
  56         try {
  57                 await execa.shell('exit 3');
  58         } catch (error) {
  59                 console.log(error);
  60                 /*
  61                 {
  62                         message: 'Command failed: /bin/sh -c exit 3'
  63                         killed: false,
  64                         code: 3,
  65                         signal: null,
  66                         cmd: '/bin/sh -c exit 3',
  67                         stdout: '',
  68                         stderr: '',
  69                         timedOut: false
  70                 }
  71                 */
  72         }
  73 })();
  74
  75 // Catching an error with a sync method
  76 try {
  77         execa.shellSync('exit 3');
  78 } catch (error) {
  79         console.log(error);
  80         /*
  81         {
  82                 message: 'Command failed: /bin/sh -c exit 3'
  83                 code: 3,
  84                 signal: null,
  85                 cmd: '/bin/sh -c exit 3',
  86                 stdout: '',
  87                 stderr: '',
  88                 timedOut: false
  89         }
  90         */
  91 }
  92 ```
  93
  94
  95 ## API
  96
  97 ### execa(file, [arguments], [options])
  98
  99 Execute a file.
 100
 101 Think of this as a mix of `child_process.execFile` and `child_process.spawn`.
 102
 103 Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess), which is enhanced to also be a `Promise` for a result `Object` with `stdout` and `stderr` properties.
 104
 105 ### execa.stdout(file, [arguments], [options])
 106
 107 Same as `execa()`, but returns only `stdout`.
 108
 109 ### execa.stderr(file, [arguments], [options])
 110
 111 Same as `execa()`, but returns only `stderr`.
 112
 113 ### execa.shell(command, [options])
 114
 115 Execute a command through the system shell. Prefer `execa()` whenever possible, as it's both faster and safer.
 116
 117 Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess).
 118
 119 The `child_process` instance is enhanced to also be promise for a result object with `stdout` and `stderr` properties.
 120
 121 ### execa.sync(file, [arguments], [options])
 122
 123 Execute a file synchronously.
 124
 125 Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options).
 126
 127 This method throws an `Error` if the command fails.
 128
 129 ### execa.shellSync(file, [options])
 130
 131 Execute a command synchronously through the system shell.
 132
 133 Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options).
 134
 135 ### options
 136
 137 Type: `Object`
 138
 139 #### cwd
 140
 141 Type: `string`<br>
 142 Default: `process.cwd()`
 143
 144 Current working directory of the child process.
 145
 146 #### env
 147
 148 Type: `Object`<br>
 149 Default: `process.env`
 150
 151 Environment key-value pairs. Extends automatically from `process.env`. Set `extendEnv` to `false` if you don't want this.
 152
 153 #### extendEnv
 154
 155 Type: `boolean`<br>
 156 Default: `true`
 157
 158 Set to `false` if you don't want to extend the environment variables when providing the `env` property.
 159
 160 #### argv0
 161
 162 Type: `string`
 163
 164 Explicitly set the value of `argv[0]` sent to the child process. This will be set to `command` or `file` if not specified.
 165
 166 #### stdio
 167
 168 Type: `string[]` `string`<br>
 169 Default: `pipe`
 170
 171 Child's [stdio](https://nodejs.org/api/child_process.html#child_process_options_stdio) configuration.
 172
 173 #### detached
 174
 175 Type: `boolean`
 176
 177 Prepare child to run independently of its parent process. Specific behavior [depends on the platform](https://nodejs.org/api/child_process.html#child_process_options_detached).
 178
 179 #### uid
 180
 181 Type: `number`
 182
 183 Sets the user identity of the process.
 184
 185 #### gid
 186
 187 Type: `number`
 188
 189 Sets the group identity of the process.
 190
 191 #### shell
 192
 193 Type: `boolean` `string`<br>
 194 Default: `false`
 195
 196 If `true`, runs `command` inside of a shell. Uses `/bin/sh` on UNIX and `cmd.exe` on Windows. A different shell can be specified as a string. The shell should understand the `-c` switch on UNIX or `/d /s /c` on Windows.
 197
 198 #### stripEof
 199
 200 Type: `boolean`<br>
 201 Default: `true`
 202
 203 [Strip EOF](https://github.com/sindresorhus/strip-eof) (last newline) from the output.
 204
 205 #### preferLocal
 206
 207 Type: `boolean`<br>
 208 Default: `true`
 209
 210 Prefer locally installed binaries when looking for a binary to execute.<br>
 211 If you `$ npm install foo`, you can then `execa('foo')`.
 212
 213 #### localDir
 214
 215 Type: `string`<br>
 216 Default: `process.cwd()`
 217
 218 Preferred path to find locally installed binaries in (use with `preferLocal`).
 219
 220 #### input
 221
 222 Type: `string` `Buffer` `stream.Readable`
 223
 224 Write some input to the `stdin` of your binary.<br>
 225 Streams are not allowed when using the synchronous methods.
 226
 227 #### reject
 228
 229 Type: `boolean`<br>
 230 Default: `true`
 231
 232 Setting this to `false` resolves the promise with the error instead of rejecting it.
 233
 234 #### cleanup
 235
 236 Type: `boolean`<br>
 237 Default: `true`
 238
 239 Keep track of the spawned process and `kill` it when the parent process exits.
 240
 241 #### encoding
 242
 243 Type: `string`<br>
 244 Default: `utf8`
 245
 246 Specify the character encoding used to decode the `stdout` and `stderr` output.
 247
 248 #### timeout
 249
 250 Type: `number`<br>
 251 Default: `0`
 252
 253 If timeout is greater than `0`, the parent will send the signal identified by the `killSignal` property (the default is `SIGTERM`) if the child runs longer than timeout milliseconds.
 254
 255 #### buffer
 256
 257 Type: `boolean`<br>
 258 Default: `true`
 259
 260 Buffer the output from the spawned process. When buffering is disabled you must consume the output of the `stdout` and `stderr` streams because the promise will not be resolved/rejected until they have completed.
 261
 262 #### maxBuffer
 263
 264 Type: `number`<br>
 265 Default: `10000000` (10MB)
 266
 267 Largest amount of data in bytes allowed on `stdout` or `stderr`.
 268
 269 #### killSignal
 270
 271 Type: `string` `number`<br>
 272 Default: `SIGTERM`
 273
 274 Signal value to be used when the spawned process will be killed.
 275
 276 #### stdin
 277
 278 Type: `string` `number` `Stream` `undefined` `null`<br>
 279 Default: `pipe`
 280
 281 Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
 282
 283 #### stdout
 284
 285 Type: `string` `number` `Stream` `undefined` `null`<br>
 286 Default: `pipe`
 287
 288 Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
 289
 290 #### stderr
 291
 292 Type: `string` `number` `Stream` `undefined` `null`<br>
 293 Default: `pipe`
 294
 295 Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
 296
 297 #### windowsVerbatimArguments
 298
 299 Type: `boolean`<br>
 300 Default: `false`
 301
 302 If `true`, no quoting or escaping of arguments is done on Windows. Ignored on other platforms. This is set to `true` automatically when the `shell` option is `true`.
 303
 304
 305 ## Tips
 306
 307 ### Save and pipe output from a child process
 308
 309 Let's say you want to show the output of a child process in real-time while also saving it to a variable.
 310
 311 ```js
 312 const execa = require('execa');
 313 const getStream = require('get-stream');
 314
 315 const stream = execa('echo', ['foo']).stdout;
 316
 317 stream.pipe(process.stdout);
 318
 319 getStream(stream).then(value => {
 320         console.log('child output:', value);
 321 });
 322 ```
 323
 324
 325 ## License
 326
 327 MIT © [Sindre Sorhus](https://sindresorhus.com)