bdde081050
Added test to ensure that release notes are parsed properly Updated to latest dependencies to fix security vulnerability Updated GH Actions Workflow to run test before updating tag Updated README.md to reflect proper whatsnew documentation.
128 lines
3.6 KiB
Markdown
128 lines
3.6 KiB
Markdown
# exec-sh
|
|
|
|
[](https://nodei.co/npm/exec-sh/)
|
|
|
|
[](https://www.npmjs.com/package/exec-sh)
|
|
[](https://travis-ci.org/tsertkov/exec-sh)
|
|
[](https://coveralls.io/r/tsertkov/exec-sh?branch=master)
|
|
[](https://david-dm.org/tsertkov/exec-sh)
|
|
|
|
> Execute shell command forwarding all stdio streams.
|
|
|
|
## Features
|
|
|
|
exec-sh is a wrapper for [`child_process.spawn`](http://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) with some improvements:
|
|
|
|
- Cross platform command execution:
|
|
- Windows: `cmd /C COMMAND`
|
|
- others: `sh -c COMMAND`
|
|
- Fowrards all stdio streams to current terminal (by default):
|
|
- `execSh("bash")`
|
|
- `execsh("echo -n Say: && read i && echo Said:$i")`
|
|
- stdout and stderr are passed to callback when available
|
|
- `execSh("pwd", console.log)`
|
|
|
|
## Showcase
|
|
```javascript
|
|
// JavaScript
|
|
|
|
execSh("echo hello exec-sh && bash", { cwd: "/home" }, function(err){
|
|
if (err) {
|
|
console.log("Exit code: ", err.code);
|
|
}
|
|
});
|
|
```
|
|
|
|
```sh
|
|
# Terminal output: interactive bash session
|
|
|
|
hello exec-sh
|
|
bash-3.2$ pwd
|
|
/home
|
|
bash-3.2$ exit 99
|
|
exit
|
|
Exit code: 99
|
|
```
|
|
|
|
## Usage
|
|
|
|
```javascript
|
|
var execSh = require("../");
|
|
|
|
// run interactive bash shell
|
|
execSh("echo lorem && bash", { cwd: "/home" }, function(err){
|
|
if (err) {
|
|
console.log("Exit code: ", err.code);
|
|
return;
|
|
}
|
|
|
|
// collect streams output
|
|
var child = execSh(["bash -c id", "echo lorem >&2"], true,
|
|
function(err, stdout, stderr){
|
|
console.log("error: ", err);
|
|
console.log("stdout: ", stdout);
|
|
console.log("stderr: ", stderr);
|
|
});
|
|
});
|
|
```
|
|
|
|
## Promise Interface
|
|
|
|
```javascript
|
|
var execShPromise = require("exec-sh").promise;
|
|
|
|
// run interactive bash shell
|
|
const run = async () => {
|
|
let out;
|
|
|
|
try {
|
|
out = await execShPromise('pwd', true);
|
|
} catch (e) {
|
|
console.log('Error: ', e);
|
|
console.log('Stderr: ', e.stderr);
|
|
console.log('Stdout: ', e.stdout);
|
|
|
|
return e;
|
|
}
|
|
|
|
console.log('out: ', out.stdout, out.stderr);
|
|
}
|
|
|
|
run();
|
|
```
|
|
|
|
## Public API
|
|
|
|
### `execSh(command, [options], [callback])`
|
|
|
|
Execute shell command forwarding all stdio.
|
|
|
|
**Parameters:**
|
|
|
|
- `command {String|Array}` - The command to run, or array of commands
|
|
- `[options] {Object|TRUE}` - Options object passed directly to [`child_process.spawn`](http://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options), when `TRUE` then `{ stdio: null }` used
|
|
- `[callback] {Function}` - `callback(err, stdout, stderr)`
|
|
- `err {Error|NULL}` - Error object. Has `code` property containing last command exit code when available
|
|
- `stdout {String|NULL}` - aggregated stdout or `NULL` if not available
|
|
- `stderr {String|NULL}` - aggregated stderr or `NULL` if not available
|
|
|
|
**Return Values:**
|
|
|
|
Returns [ChildProcess](http://nodejs.org/api/child_process.html#child_process_class_childprocess) object.
|
|
|
|
## Private API
|
|
Complete API Documentation including private and public methods is generated from source code by JSDoc tool and is [available here](https://s3.eu-central-1.amazonaws.com/tsertkov-artifacts/exec-sh/master/jsdoc/index.html).
|
|
|
|
## Code Coverage
|
|
Code coverage report for all files is [available here](https://s3.eu-central-1.amazonaws.com/tsertkov-artifacts/exec-sh/master/coverage/index.html).
|
|
|
|
## Scripts
|
|
|
|
- `npm test` - run tests
|
|
- `npm run jsdoc` - build jsdoc
|
|
- `npm run dev` - run tests continuously
|
|
|
|
## License
|
|
|
|
The MIT License (MIT)
|