New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve documentation of the usage section #541
Changes from 1 commit
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -34,6 +34,8 @@ npm install execa | |
|
||
## Usage | ||
|
||
### Promise interface | ||
|
||
```js | ||
import {execa} from 'execa'; | ||
|
||
|
@@ -44,68 +46,38 @@ console.log(stdout); | |
|
||
### Scripts interface | ||
|
||
For more information, please see [this page](docs/scripts.md). | ||
For more information about Execa scripts, please see [this page](docs/scripts.md). | ||
|
||
#### Basic | ||
|
||
```js | ||
import {$} from 'execa'; | ||
|
||
const {stdout} = await $`echo unicorns`; | ||
// const {stdout} = await $`echo ${'unicorns'}`; | ||
// const {stdout} = await $`echo ${['unicorns', 'rainbows']}`; | ||
const unicorns = await $`echo unicorns`; | ||
const {stdout} = await $`echo ${unicorns}${'!'}}`; | ||
console.log(stdout); | ||
//=> 'unicorns!' | ||
|
||
const {stdout} = await $`echo ${['unicorns', 'rainbows']}`; | ||
console.log(stdout); | ||
//=> 'unicorns' | ||
//=> 'unicorns rainbows' | ||
``` | ||
|
||
#### With options | ||
|
||
```js | ||
import {$} from 'execa'; | ||
|
||
await $({stdio: 'inherit'})`echo unicorns`; | ||
//=> 'unicorns' | ||
``` | ||
|
||
#### With pre-defined options | ||
|
||
```js | ||
import {$} from 'execa'; | ||
|
||
const $$ = $({stdio: 'inherit'}); | ||
|
||
await $$`echo unicorns`; | ||
//=> 'unicorns' | ||
await $$({shell: true})`echo unicorns && echo rainbows`; | ||
//=> 'unicorns' | ||
//=> 'rainbows' | ||
``` | ||
|
||
#### Synchronous | ||
|
||
```js | ||
import {$} from 'execa'; | ||
|
||
const {stdout} = $.sync`echo unicorns`; | ||
console.log(stdout); | ||
await $$({shell: true})`echo unicorns && echo rainbows`; | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This consolidation is nice, but removes the basic example of using the imported There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. That's a good point, let's keep them split. Done 👍 |
||
//=> 'unicorns' | ||
|
||
$({stdio: 'inherit'}).sync`echo rainbows`; | ||
//=> 'rainbows' | ||
``` | ||
|
||
#### With results from `$` or `$.sync` | ||
|
||
```js | ||
import {$} from 'execa'; | ||
|
||
const unicorns = await $`echo unicorns`; | ||
|
||
$({stdio: 'inherit'}).sync`echo ${unicorns} rainbows`; | ||
//=> 'unicorns rainbows' | ||
``` | ||
|
||
#### Verbose mode | ||
|
||
```sh | ||
|
@@ -120,7 +92,9 @@ unicorns | |
rainbows | ||
``` | ||
|
||
### Redirect output to a file | ||
### Input/output | ||
|
||
#### Redirect output to a file | ||
|
||
```js | ||
import {execa} from 'execa'; | ||
|
@@ -135,7 +109,7 @@ await execa('echo', ['unicorns']).pipeStderr('stderr.txt'); | |
await execa('echo', ['unicorns'], {all:true}).pipeAll('all.txt'); | ||
``` | ||
|
||
### Redirect input from a file | ||
#### Redirect input from a file | ||
|
||
```js | ||
import {execa} from 'execa'; | ||
|
@@ -146,7 +120,7 @@ console.log(stdout); | |
//=> 'unicorns' | ||
``` | ||
|
||
### Save and pipe output from a child process | ||
#### Save and pipe output from a child process | ||
|
||
```js | ||
import {execa} from 'execa'; | ||
|
@@ -157,7 +131,7 @@ console.log(stdout); | |
// Also returns 'unicorns' | ||
``` | ||
|
||
### Pipe multiple processes | ||
#### Pipe multiple processes | ||
|
||
```js | ||
import {execa} from 'execa'; | ||
|
@@ -202,60 +176,7 @@ try { | |
} | ||
``` | ||
|
||
### Cancelling a spawned process | ||
|
||
```js | ||
import {execa} from 'execa'; | ||
|
||
const abortController = new AbortController(); | ||
const subprocess = execa('node', [], {signal: abortController.signal}); | ||
|
||
setTimeout(() => { | ||
abortController.abort(); | ||
}, 1000); | ||
|
||
try { | ||
await subprocess; | ||
} catch (error) { | ||
console.log(subprocess.killed); // true | ||
console.log(error.isCanceled); // true | ||
} | ||
``` | ||
|
||
### Catching an error with the sync method | ||
|
||
```js | ||
import {execaSync} from 'execa'; | ||
|
||
try { | ||
execaSync('unknown', ['command']); | ||
} catch (error) { | ||
console.log(error); | ||
/* | ||
{ | ||
message: 'Command failed with ENOENT: unknown command spawnSync unknown ENOENT', | ||
errno: -2, | ||
code: 'ENOENT', | ||
syscall: 'spawnSync unknown', | ||
path: 'unknown', | ||
spawnargs: ['command'], | ||
originalMessage: 'spawnSync unknown ENOENT', | ||
shortMessage: 'Command failed with ENOENT: unknown command spawnSync unknown ENOENT', | ||
command: 'unknown command', | ||
escapedCommand: 'unknown command', | ||
stdout: '', | ||
stderr: '', | ||
all: '', | ||
failed: true, | ||
timedOut: false, | ||
isCanceled: false, | ||
killed: false | ||
} | ||
*/ | ||
} | ||
``` | ||
|
||
### Kill a process | ||
### Graceful termination | ||
|
||
Using SIGTERM, and after 2 seconds, kill it with SIGKILL. | ||
|
||
|
@@ -776,13 +697,33 @@ const run = async () => { | |
console.log(await pRetry(run, {retries: 5})); | ||
``` | ||
|
||
### Cancelling a spawned process | ||
|
||
```js | ||
import {execa} from 'execa'; | ||
|
||
const abortController = new AbortController(); | ||
const subprocess = execa('node', [], {signal: abortController.signal}); | ||
|
||
setTimeout(() => { | ||
abortController.abort(); | ||
}, 1000); | ||
|
||
try { | ||
await subprocess; | ||
} catch (error) { | ||
console.log(subprocess.killed); // true | ||
console.log(error.isCanceled); // true | ||
} | ||
``` | ||
|
||
### Execute the current package's binary | ||
|
||
```js | ||
import {getBinPathSync} from 'get-bin-path'; | ||
import {getBinPath} from 'get-bin-path'; | ||
|
||
const binPath = getBinPathSync(); | ||
const subprocess = execa(binPath); | ||
const binPath = await getBinPath(); | ||
await execa(binPath); | ||
``` | ||
|
||
`execa` can be combined with [`get-bin-path`](https://github.com/ehmicky/get-bin-path) to test the current package's binary. As opposed to hard-coding the path to the binary, this validates that the `package.json` `bin` field is correctly set up. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This example errors on reassignment of the block-scoped var
stdout
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Right! Fixed.