Skip to content
Gulp.js command execution for humans
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Add .github/ May 19, 2019
docs
examples Fix linting May 20, 2019
src Use default value `true` for `preferLocal` Jun 25, 2019
test Fix tests Jul 9, 2019
.all-contributorsrc docs: update .all-contributorsrc Jun 21, 2019
.editorconfig First commit Mar 6, 2019
.eslintrc.yml
.gitattributes Add .gitattributes Apr 17, 2019
.gitignore
.prettierrc.yml
.travis.yml
CHANGELOG.md Fix linting Jun 18, 2019
CODE_OF_CONDUCT.md Add code of conduct May 19, 2019
CONTRIBUTING.md Add CONTRIBUTING May 19, 2019
LICENSE First commit Mar 6, 2019
README.md Update README Jul 10, 2019
ava.config.js Simplify ava.config.js Apr 16, 2019
gulpfile.js First commit Mar 6, 2019
package-lock.json Upgrade gulp-shared-tasks 0.30.25 -> 0.30.26 Jul 19, 2019
package.json

README.md

Codecov Travis Node Gitter Twitter Medium

Gulp.js command execution for humans.

As opposed to similar plugins or to child_process.exec(), this uses execa which provides:

gulp-execa adds Gulp-specific features to execa including:

Commands can be executed either directly or inside a files stream. In streaming mode, unlike other libraries:

Example

gulpfile.js:

const { src, dest } = require('gulp')
const { task, exec, stream } = require('gulp-execa')

module.exports.audit = task('npm audit')

module.exports.outdated = async () => {
  await exec('npm outdated')
}

module.exports.sort = () =>
  src('*.txt')
    .pipe(stream(({ path }) => `sort ${path}`))
    .pipe(dest('sorted'))

Demo

You can try this library:

Install

npm install -D gulp-execa

This plugin requires Gulp 4.

Methods

task(command, [options])

Returns a Gulp task that executes command.
Full documentation.

exec(command, [options])

Executes command. The return value is both a promise and a child_process instance.
Full documentation.

stream(function, [options])

Returns a stream that executes a command on each input file. function must take a file as argument and return a command.

Each file in the stream will spawn a separate process. This can consume lots of resources so you should only use this method when there are no alternatives.

Full documentation.

Command

By default no shell interpreter (like Bash or cmd.exe) is used. This means command must be just the program and its arguments. No escaping/quoting is needed, except for significant spaces (with a backslash).

Shell features such as globbing, variables and operators (like && > ;) should not be used. All of this can be done directly in Node.js instead.

Shell interpreters are slower, less secure and less cross-platform. However, you can still opt-in to using them with the shell option.

const { writeFileStream } = require('fs')

const { series } = require('gulp')

// Wrong
module.exports.check = task('npm audit && npm outdated')

// Correct
module.exports.check = series(task('npm audit'), task('npm outdated'))

// Wrong
module.exports.install = task('npm install > log.txt')

// Correct
module.exports.install = task('npm install', {
  stdout: writeFileStream('log.txt'),
})

Options

options is an optional object.

All options from both child_process.spawn() and child_process.exec() are available: cwd, env, argv0, stdio, detached, uid, gid, shell, encoding, timeout, maxBuffer, killSignal, windowsVerbatimArguments, windowsHide.

All execa options can also be used: cleanup, preferLocal, localDir, buffer, input, stdin, stdout, stderr, reject, stripFinalNewline, extendEnv.

The following options are available as well.

echo

Type: boolean
Default: true for task() and exec(), false for stream().

Whether the command should be printed on the console.
Full documentation.

verbose

Type: boolean
Default: true for task() and exec(), false for stream().

Whether both the command and its output (stdout/stderr) should be printed on the console instead of being returned in JavaScript.
Full documentation.

result

Type: string
Value: 'replace' or 'save'
Default: 'replace'

With stream(), whether the command result should:

  • replace the file's contents
  • save: be pushed to the file.execa array property

Full documentation.

from

Type: string
Value: 'stdout', 'stderr' or 'all'
Default: 'stdout'

Which output stream to use with result: 'replace'.
Full documentation.

maxConcurrency

Type: integer
Default: 100

With stream(), how many commands to run in parallel at once.

See also

Support

If you found a bug or would like a new feature, don't hesitate to submit an issue on GitHub.

For other questions, feel free to chat with us on Gitter.

Everyone is welcome regardless of personal background. We enforce a Code of conduct in order to promote a positive and inclusive environment.

Contributing

This project was made with ❤️. The simplest way to give back is by starring and sharing it online.

If the documentation is unclear or has a typo, please click on the page's Edit button (pencil icon) and suggest a correction.

If you would like to help us fix a bug or add a new feature, please check our guidelines. Pull requests are welcome!

Thanks go to our wonderful contributors:

ehmicky
ehmicky

💻 🎨 🤔 📖
Jonathan Haines
Jonathan Haines

🐛
You can’t perform that action at this time.