www.aleph1.co.uk Git - yaffs-website/blob - 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 Same options as [`child_process.execFile`](https://nodejs.org/api/child_process.html#child_process_child_process_execfile_file_args_options_callback).
  68
  69 Think of this as a mix of `child_process.execFile` and `child_process.spawn`.
  70
  71 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.
  72
  73 ### execa.stdout(file, [arguments], [options])
  74
  75 Same as `execa()`, but returns only `stdout`.
  76
  77 ### execa.stderr(file, [arguments], [options])
  78
  79 Same as `execa()`, but returns only `stderr`.
  80
  81 ### execa.shell(command, [options])
  82
  83 Execute a command through the system shell. Prefer `execa()` whenever possible, as it's both faster and safer.
  84
  85 Same options as [`child_process.exec`](https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback).
  86
  87 Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess).
  88
  89 The `child_process` instance is enhanced to also be promise for a result object with `stdout` and `stderr` properties.
  90
  91 ### execa.sync(file, [arguments], [options])
  92
  93 Execute a file synchronously.
  94
  95 Same options as [`child_process.execFileSync`](https://nodejs.org/api/child_process.html#child_process_child_process_execfilesync_file_args_options), except the default encoding is `utf8` instead of `buffer`.
  96
  97 Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options).
  98
  99 ### execa.shellSync(file, [options])
 100
 101 Execute a command synchronously through the system shell.
 102
 103 Same options as [`child_process.execSync`](https://nodejs.org/api/child_process.html#child_process_child_process_execsync_command_options), except the default encoding is `utf8` instead of `buffer`.
 104
 105 Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options).
 106
 107 ### options
 108
 109 Additional options:
 110
 111 #### stripEof
 112
 113 Type: `boolean`<br>
 114 Default: `true`
 115
 116 [Strip EOF](https://github.com/sindresorhus/strip-eof) (last newline) from the output.
 117
 118 #### preferLocal
 119
 120 Type: `boolean`<br>
 121 Default: `true`
 122
 123 Prefer locally installed binaries when looking for a binary to execute.<br>
 124 If you `$ npm install foo`, you can then `execa('foo')`.
 125
 126 #### input
 127
 128 Type: `string` `Buffer` `ReadableStream`
 129
 130 Write some input to the `stdin` of your binary.<br>
 131 Streams are not allowed when using the synchronous methods.
 132
 133 #### reject
 134
 135 Type: `boolean`<br>
 136 Default: `true`
 137
 138 Setting this to `false` resolves the promise with the error instead of rejecting it.
 139
 140 #### cleanup
 141
 142 Type: `boolean`<br>
 143 Default: `true`
 144
 145 Keep track of the spawned process and `kill` it when the parent process exits.
 146
 147
 148 ## License
 149
 150 MIT © [Sindre Sorhus](https://sindresorhus.com)