.config/coc/extensions/node_modules/coc-prettier/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 --save execa
  21 ```
  22
  23
  24 ## Usage
  25
  26 ```js
  27 const execa = require('execa');
  28
  29 execa('echo', ['unicorns']).then(result => {
  30         console.log(result.stdout);
  31         //=> 'unicorns'
  32 });
  33
  34 // pipe the child process stdout to the current stdout
  35 execa('echo', ['unicorns']).stdout.pipe(process.stdout);
  36
  37 execa.shell('echo unicorns').then(result => {
  38         console.log(result.stdout);
  39         //=> 'unicorns'
  40 });
  41
  42 // example of catching an error
  43 execa.shell('exit 3').catch(error => {
  44         console.log(error);
  45         /*
  46         {
  47                 message: 'Command failed: /bin/sh -c exit 3'
  48                 killed: false,
  49                 code: 3,
  50                 signal: null,
  51                 cmd: '/bin/sh -c exit 3',
  52                 stdout: '',
  53                 stderr: '',
  54                 timedOut: false
  55         }
  56         */
  57 });
  58 ```
  59
  60
  61 ## API
  62
  63 ### execa(file, [arguments], [options])
  64
  65 Execute a file.
  66
  67 Think of this as a mix of `child_process.execFile` and `child_process.spawn`.
  68
  69 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.
  70
  71 ### execa.stdout(file, [arguments], [options])
  72
  73 Same as `execa()`, but returns only `stdout`.
  74
  75 ### execa.stderr(file, [arguments], [options])
  76
  77 Same as `execa()`, but returns only `stderr`.
  78
  79 ### execa.shell(command, [options])
  80
  81 Execute a command through the system shell. Prefer `execa()` whenever possible, as it's both faster and safer.
  82
  83 Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess).
  84
  85 The `child_process` instance is enhanced to also be promise for a result object with `stdout` and `stderr` properties.
  86
  87 ### execa.sync(file, [arguments], [options])
  88
  89 Execute a file synchronously.
  90
  91 Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options).
  92
  93 This method throws an `Error` if the command fails.
  94
  95 ### execa.shellSync(file, [options])
  96
  97 Execute a command synchronously through the system shell.
  98
  99 Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options).
 100
 101 ### options
 102
 103 Type: `Object`
 104
 105 #### cwd
 106
 107 Type: `string`<br>
 108 Default: `process.cwd()`
 109
 110 Current working directory of the child process.
 111
 112 #### env
 113
 114 Type: `Object`<br>
 115 Default: `process.env`
 116
 117 Environment key-value pairs. Extends automatically from `process.env`. Set `extendEnv` to `false` if you don't want this.
 118
 119 #### extendEnv
 120
 121 Type: `boolean`<br>
 122 Default: `true`
 123
 124 Set to `false` if you don't want to extend the environment variables when providing the `env` property.
 125
 126 #### argv0
 127
 128 Type: `string`
 129
 130 Explicitly set the value of `argv[0]` sent to the child process. This will be set to `command` or `file` if not specified.
 131
 132 #### stdio
 133
 134 Type: `Array` `string`<br>
 135 Default: `pipe`
 136
 137 Child's [stdio](https://nodejs.org/api/child_process.html#child_process_options_stdio) configuration.
 138
 139 #### detached
 140
 141 Type: `boolean`
 142
 143 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).
 144
 145 #### uid
 146
 147 Type: `number`
 148
 149 Sets the user identity of the process.
 150
 151 #### gid
 152
 153 Type: `number`
 154
 155 Sets the group identity of the process.
 156
 157 #### shell
 158
 159 Type: `boolean` `string`<br>
 160 Default: `false`
 161
 162 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.
 163
 164 #### stripEof
 165
 166 Type: `boolean`<br>
 167 Default: `true`
 168
 169 [Strip EOF](https://github.com/sindresorhus/strip-eof) (last newline) from the output.
 170
 171 #### preferLocal
 172
 173 Type: `boolean`<br>
 174 Default: `true`
 175
 176 Prefer locally installed binaries when looking for a binary to execute.<br>
 177 If you `$ npm install foo`, you can then `execa('foo')`.
 178
 179 #### localDir
 180
 181 Type: `string`<br>
 182 Default: `process.cwd()`
 183
 184 Preferred path to find locally installed binaries in (use with `preferLocal`).
 185
 186 #### input
 187
 188 Type: `string` `Buffer` `stream.Readable`
 189
 190 Write some input to the `stdin` of your binary.<br>
 191 Streams are not allowed when using the synchronous methods.
 192
 193 #### reject
 194
 195 Type: `boolean`<br>
 196 Default: `true`
 197
 198 Setting this to `false` resolves the promise with the error instead of rejecting it.
 199
 200 #### cleanup
 201
 202 Type: `boolean`<br>
 203 Default: `true`
 204
 205 Keep track of the spawned process and `kill` it when the parent process exits.
 206
 207 #### encoding
 208
 209 Type: `string`<br>
 210 Default: `utf8`
 211
 212 Specify the character encoding used to decode the `stdout` and `stderr` output.
 213
 214 #### timeout
 215
 216 Type: `number`<br>
 217 Default: `0`
 218
 219 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.
 220
 221 #### maxBuffer
 222
 223 Type: `number`<br>
 224 Default: `10000000` (10MB)
 225
 226 Largest amount of data in bytes allowed on `stdout` or `stderr`.
 227
 228 #### killSignal
 229
 230 Type: `string` `number`<br>
 231 Default: `SIGTERM`
 232
 233 Signal value to be used when the spawned process will be killed.
 234
 235 #### stdin
 236
 237 Type: `string` `number` `Stream` `undefined` `null`<br>
 238 Default: `pipe`
 239
 240 Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
 241
 242 #### stdout
 243
 244 Type: `string` `number` `Stream` `undefined` `null`<br>
 245 Default: `pipe`
 246
 247 Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
 248
 249 #### stderr
 250
 251 Type: `string` `number` `Stream` `undefined` `null`<br>
 252 Default: `pipe`
 253
 254 Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
 255
 256
 257 ## Tips
 258
 259 ### Save and pipe output from a child process
 260
 261 Let's say you want to show the output of a child process in real-time while also saving it to a variable.
 262
 263 ```js
 264 const execa = require('execa');
 265 const getStream = require('get-stream');
 266
 267 const stream = execa('echo', ['foo']).stdout;
 268
 269 stream.pipe(process.stdout);
 270
 271 getStream(stream).then(value => {
 272         console.log('child output:', value);
 273 });
 274 ```
 275
 276
 277 ## License
 278
 279 MIT © [Sindre Sorhus](https://sindresorhus.com)