## gulp-shell

A handy command line interface for gulp

### Installation

npm install --save-dev gulp-shell


### Usage

var gulp  = require('gulp')
var shell = require('gulp-shell')

.pipe(shell([
'echo <%= f(file.path) %>',
'ls -l <%= file.path %>'
], {
templateData: {
f: function (s) {
return s.replace(/\$/, '.bak')
}
}
}))
})


If you just want to execute a series of commands only once, starting the stream with gulp.src('') should do the trick. However, this is an anti-pattern, and it won't work in gulp 4.0 .

Or you can use this shorthand:

gulp.task('shorthand', shell.task([
'echo hello',
'echo world'
]))


You can find more examples in the gulpfile of this project.

### API

#### shell(commands, options) or shell.task(commands, options)

##### commands

type: Array or String

A command can be a template which can be interpolated by some file info (e.g. file.path).

##### options.verbose

type: Boolean

default: false

Set to true to print the command(s) to stdout as they are executed

##### options.errorMessage

type: String

default: Command <%= command %> failed with exit code <%= error.code %>

You can add a custom error message for when the command fails. This can be a template which can be interpolated with the current command, some file info (e.g. file.path) and some error info (e.g. error.code).

##### options.ignoreErrors

type: Boolean

default: false

By default, it will emit an error event when the command finishes unsuccessfully.

##### options.quiet

type: Boolean

default: false

By default, it will print the command output.

##### options.interactive

type: Boolean

default: false

Turn it on only if you need to run some interactive commands.

##### options.cwd

type: String

default: process.cwd()

Sets the current working directory for the command. This can be a template which can be interpolated by some file info (e.g. file.path).

##### options.templateData

type: Object

The data that can be accessed in template.

##### options.maxBuffer

type: Number

default: 16MB(16 1024 1024)

You won't need to set this option unless you encounter a "stdout maxBuffer exceeded" error.

For example, setting it to 16 * 1024 * 1024 will result in 16MB.

##### options.timeout

type: Number

default: undefined (no timeout)

The maximum amount of time in milliseconds the process is allowed to run.

##### options.env

type: Object

By default, all the commands will be executed in an environment with all the variables in process.env and PATH prepended by ./node_modules/.bin (allowing you to run executables in your Node's dependencies).

You can override any environment variables with this option.

For example, setting it to {PATH: process.env.PATH} will reset the PATH if the default one brings your some troubles.