{"id":699,"url":"https://github.com/ehmicky/gulp-execa","last_synced_at":"2025-04-05T01:03:51.950Z","repository":{"id":40571993,"uuid":"174192611","full_name":"ehmicky/gulp-execa","owner":"ehmicky","description":"Gulp.js command execution for humans","archived":false,"fork":false,"pushed_at":"2025-03-28T03:59:59.000Z","size":10920,"stargazers_count":58,"open_issues_count":0,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-28T05:18:28.041Z","etag":null,"topics":["bash","child-process","cli","command-line","es6","exec","execa","gulp","gulp-plugin","gulpjs","gulpplugin","javascript","library","nodejs","security","shell","spawn","stream","terminal","typescript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ehmicky.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-06T17:47:56.000Z","updated_at":"2025-03-28T04:00:02.000Z","dependencies_parsed_at":"2024-04-05T17:48:05.068Z","dependency_job_id":"eecf66f5-3afe-4550-9881-341bca770df1","html_url":"https://github.com/ehmicky/gulp-execa","commit_stats":{"total_commits":1444,"total_committers":3,"mean_commits":481.3333333333333,"dds":0.008310249307479256,"last_synced_commit":"45d03fbea64ac7e42c772ad8adabfad227d1b1ca"},"previous_names":[],"tags_count":47,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fgulp-execa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fgulp-execa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fgulp-execa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fgulp-execa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ehmicky","download_url":"https://codeload.github.com/ehmicky/gulp-execa/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247271515,"owners_count":20911587,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","child-process","cli","command-line","es6","exec","execa","gulp","gulp-plugin","gulpjs","gulpplugin","javascript","library","nodejs","security","shell","spawn","stream","terminal","typescript"],"created_at":"2024-01-05T20:15:29.138Z","updated_at":"2025-04-05T01:03:51.926Z","avatar_url":"https://github.com/ehmicky.png","language":"JavaScript","readme":"\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/ehmicky/design/main/gulp-execa/gulp-execa_dark.svg\"/\u003e\n  \u003cimg alt=\"gulp-execa logo\" src=\"https://raw.githubusercontent.com/ehmicky/design/main/gulp-execa/gulp-execa.svg\" width=\"500\"/\u003e\n\u003c/picture\u003e\n\n[![Node](https://img.shields.io/badge/-Node.js-808080?logo=node.js\u0026colorA=404040\u0026logoColor=66cc33)](https://www.npmjs.com/package/gulp-execa)\n[![TypeScript](https://img.shields.io/badge/-Typed-808080?logo=typescript\u0026colorA=404040\u0026logoColor=0096ff)](/src/main.d.ts)\n[![Codecov](https://img.shields.io/badge/-Tested%20100%25-808080?logo=codecov\u0026colorA=404040)](https://codecov.io/gh/ehmicky/gulp-execa)\n[![Mastodon](https://img.shields.io/badge/-Mastodon-808080.svg?logo=mastodon\u0026colorA=404040\u0026logoColor=9590F9)](https://fosstodon.org/@ehmicky)\n[![Medium](https://img.shields.io/badge/-Medium-808080.svg?logo=medium\u0026colorA=404040)](https://medium.com/@ehmicky)\n\n[Gulp.js](https://gulpjs.com) command execution for humans.\n\nAs opposed to similar plugins or to\n[`child_process.exec()`](https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback),\nthis uses [Execa](https://github.com/sindresorhus/execa) which provides:\n\n- [Better Windows support](https://github.com/IndigoUnited/node-cross-spawn#why),\n  including [shebangs](\u003chttps://en.wikipedia.org/wiki/Shebang_(Unix)\u003e)\n- Faster and more secure commands, since [no shell is used by default](#command)\n- Execution of\n  [locally installed binaries](https://github.com/sindresorhus/execa#preferlocal)\n- [Interleaved](https://github.com/sindresorhus/execa#all-1) `stdout`/`stderr`\n\n`gulp-execa` adds Gulp-specific features to\n[Execa](https://github.com/sindresorhus/execa) including:\n\n- a [task shortcut syntax](#taskcommand-options)\n- configurable [verbosity](#echo)\n- [better errors](https://github.com/gulpjs/plugin-error)\n\nCommands can be executed either directly or inside a\n[files stream](https://gulpjs.com/docs/en/api/src). In\n[streaming mode](#streamfunction-options), unlike other libraries:\n\n- commands are run [in parallel](https://github.com/almost/through2-concurrent),\n  not [serially](https://github.com/rvagg/through2)\n- output can be saved [either in files or in variables](#result)\n\n# Example\n\n`gulpfile.js`:\n\n```js\nimport { pipeline } from 'node:stream/promises'\n\nimport gulp from 'gulp'\nimport { exec, stream, task } from 'gulp-execa'\n\nexport const audit = task('npm audit')\n\nexport const outdated = async () =\u003e {\n  await exec('npm outdated')\n}\n\nexport const sort = () =\u003e\n  pipeline(\n    gulp.src('*.txt'),\n    stream(({ path }) =\u003e `sort ${path}`),\n    gulp.dest('sorted'),\n  )\n```\n\n# Install\n\n```\nnpm install -D gulp-execa\n```\n\nThis plugin requires Gulp 5 and Node.js \u003e=18.18.0. It is an ES module and must\nbe loaded using\n[an `import` or `import()` statement](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c),\nnot `require()`. If TypeScript is used, it must be configured to\n[output ES modules](https://www.typescriptlang.org/docs/handbook/esm-node.html),\nnot CommonJS.\n\n# Methods\n\n## task(command, [options])\n\nReturns a Gulp task that executes `command`.\n\n```js\nimport { task } from 'gulp-execa'\n\nexport const audit = task('npm audit')\n```\n\n## exec(command, [options])\n\nExecutes `command`. The return value is both a promise and a\n[`child_process` instance](https://github.com/sindresorhus/execa#execacommand-options).\n\nThe promise will be resolved with the\n[command result](https://github.com/sindresorhus/execa#childprocessresult). If\nthe command failed, the promise will be rejected with a nice\n[error](https://github.com/sindresorhus/execa#childprocessresult). If the\n[`reject: false`](https://github.com/sindresorhus/execa#reject) option was used,\nthe promise will be resolved with that error instead.\n\n```js\nimport { exec } from 'gulp-execa'\n\nexport const outdated = async () =\u003e {\n  await exec('npm outdated')\n}\n```\n\n## stream(function, [options])\n\nReturns a stream that executes a `command` on each input file.\n\n`function` must:\n\n- take a [Vinyl file](https://gulpjs.com/docs/en/api/vinyl#instance-properties)\n  as argument. The most useful property is `file.path` but\n  [other properties](https://gulpjs.com/docs/en/api/vinyl#instance-properties)\n  are available as well.\n- return either:\n  - a `command` string\n  - an `options` object with a `command` property\n  - `undefined`\n\n```js\nimport { pipeline } from 'node:stream/promises'\n\nimport gulp from 'gulp'\nimport { stream } from 'gulp-execa'\n\nexport const sort = () =\u003e\n  pipeline(\n    gulp.src('*.txt'),\n    stream(({ path }) =\u003e `sort ${path}`),\n    gulp.dest('sorted'),\n  )\n```\n\nEach file in the stream will spawn a separate process. This can consume lots of\nresources so you should only use this method when there are no alternatives such\nas:\n\n- firing a command programmatically instead of spawning a child process\n- passing several files, a directory or a globbing pattern as arguments to the\n  command\n\nThe [`debug`](#debug),\n[`stdout`](https://github.com/sindresorhus/execa#stdout-1),\n[`stderr`](https://github.com/sindresorhus/execa#stderr-1),\n[`all`](https://github.com/sindresorhus/execa#all-2) and\n[`stdio`](https://github.com/sindresorhus/execa#stdio) options cannot be used\nwith this method.\n\n# Command\n\nBy default no shell interpreter (like Bash or `cmd.exe`) is used. This means\n`command` must be just the program and its arguments. No escaping/quoting is\nneeded, except for significant spaces (with a backslash).\n\nShell features such as globbing, variables and operators (like `\u0026\u0026` `\u003e` `;`)\nshould not be used. All of this can be done directly in Node.js instead.\n\nShell interpreters are slower, less secure and less cross-platform. However, you\ncan still opt-in to using them with the\n[`shell` option](https://github.com/sindresorhus/execa#shell).\n\n```js\nimport { writeFileStream } from 'node:fs'\n\nimport gulp from 'gulp'\nimport { task } from 'gulp-execa'\n\n// Wrong\n// export const check = task('npm audit \u0026\u0026 npm outdated')\n\n// Correct\nexport const check = gulp.series(task('npm audit'), task('npm outdated'))\n\n// Wrong\n// export const install = task('npm install \u003e log.txt')\n\n// Correct\nexport const install = task('npm install', {\n  stdout: writeFileStream('log.txt'),\n})\n```\n\n# Options\n\n`options` is an optional object.\n\n[All Execa options](https://github.com/sindresorhus/execa#options) can be used.\nPlease refer to its documentation for a list of possible options.\n\nThe following options are available as well.\n\n## echo\n\n_Type_: `boolean`\\\n_Default_: [`debug`](#debug) option's value\n\nWhether the `command` should be printed on the console.\n\n```bash\n$ gulp audit\n[13:09:39] Using gulpfile ~/code/gulpfile.js\n[13:09:39] Starting 'audit'...\n[13:09:39] [gulp-execa] npm audit\n[13:09:44] Finished 'audit' after 4.96 s\n```\n\n## debug\n\n_Type_: `boolean`\\\n_Default_: `true` for [`task()`](#taskcommand-options) and\n[`exec()`](#execcommand-options), `false` for\n[`stream()`](#streamfunction-options).\n\nWhether both the `command` and its output (`stdout`/`stderr`) should be printed\non the console instead of being returned in JavaScript.\n\n```bash\n$ gulp audit\n[13:09:39] Using gulpfile ~/code/gulpfile.js\n[13:09:39] Starting 'audit'...\n[13:09:39] [gulp-execa] npm audit\n\n                        == npm audit security report ===\n\nfound 0 vulnerabilities\n in 27282 scanned packages\n[13:09:44] Finished 'audit' after 4.96 s\n```\n\n## result\n\n_Type_: `string`\\\n_Value_: `'replace'` or `'save'`\\\n_Default_: `'replace'`\n\nWith [`stream()`](#streamfunction-options), whether the command result should:\n\n- `replace` the file's contents\n- `save`: [be pushed](https://github.com/sindresorhus/execa#childprocessresult)\n  to the `file.execa` array property\n\n\u003c!-- eslint-disable unicorn/no-null --\u003e\n\n```js\nimport { pipeline } from 'node:stream/promises'\n\nimport gulp from 'gulp'\nimport { stream } from 'gulp-execa'\nimport through from 'through2'\n\nexport const task = () =\u003e\n  pipeline(\n    gulp.src('*.js'),\n    // Prints the number of lines of each file\n    stream(({ path }) =\u003e `wc -l ${path}`, { result: 'save' }),\n    through.obj((file, encoding, func) =\u003e {\n      console.log(file.execa[0].stdout)\n      func(null, file)\n    }),\n  )\n```\n\n## from\n\n_Type_: `string`\\\n_Value_: `'stdout'`, `'stderr'` or `'all'`\\\n_Default_: `'stdout'`\n\nWhich output stream to use with [`result: 'replace'`](#result).\n\n\u003c!-- eslint-disable unicorn/no-null --\u003e\n\n```js\nimport { pipeline } from 'node:stream/promises'\n\nimport gulp from 'gulp'\nimport { stream } from 'gulp-execa'\nimport through from 'through2'\n\nexport const task = () =\u003e\n  pipeline(\n    gulp.src('*.js'),\n    // Prints the number of lines of each file, including `stderr`\n    stream(({ path }) =\u003e `wc -l ${path}`, { result: 'replace', from: 'all' }),\n    through.obj((file, encoding, func) =\u003e {\n      console.log(file.contents.toString())\n      func(null, file)\n    }),\n  )\n```\n\n## maxConcurrency\n\n_Type_: `integer`\\\n_Default_: `100`\n\nWith [`stream()`](#streamfunction-options), how many commands to run in parallel\nat once.\n\n# See also\n\n- [Execa](https://github.com/sindresorhus/execa)\n\n# Support\n\nFor any question, _don't hesitate_ to [submit an issue on GitHub](../../issues).\n\nEveryone is welcome regardless of personal background. We enforce a\n[Code of conduct](CODE_OF_CONDUCT.md) in order to promote a positive and\ninclusive environment.\n\n# Contributing\n\nThis project was made with ❤️. The simplest way to give back is by starring and\nsharing it online.\n\nIf the documentation is unclear or has a typo, please click on the page's `Edit`\nbutton (pencil icon) and suggest a correction.\n\nIf you would like to help us fix a bug or add a new feature, please check our\n[guidelines](CONTRIBUTING.md). Pull requests are welcome!\n\nThanks go to our wonderful contributors:\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START --\u003e\n\u003c!-- prettier-ignore --\u003e\n\u003ctable\u003e\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"https://fosstodon.org/@ehmicky\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/8136211?v=4\" width=\"100px;\" alt=\"ehmicky\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eehmicky\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/ehmicky/gulp-execa/commits?author=ehmicky\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"#design-ehmicky\" title=\"Design\"\u003e🎨\u003c/a\u003e \u003ca href=\"#ideas-ehmicky\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e \u003ca href=\"https://github.com/ehmicky/gulp-execa/commits?author=ehmicky\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"https://twitter.com/BarryThePenguin\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/1351912?v=4\" width=\"100px;\" alt=\"Jonathan Haines\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eJonathan Haines\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/ehmicky/gulp-execa/issues?q=author%3ABarryThePenguin\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\u003c/table\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n","funding_links":[],"categories":["Repository","JavaScript","Libraries"],"sub_categories":["Shell"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehmicky%2Fgulp-execa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fehmicky%2Fgulp-execa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehmicky%2Fgulp-execa/lists"}