[ { "path": ".editorconfig", "content": "# https://editorconfig.org\nroot = true\n\n[*]\nindent_style = space\nindent_size = 2\ncharset = utf-8\ntrim_trailing_whitespace = true\ninsert_final_newline = true\nend_of_line = lf\n\n[*.md]\ntrim_trailing_whitespace = false\n" }, { "path": ".eslintrc", "content": "{\n \"extends\": \"gulp\"\n}\n" }, { "path": ".gitattributes", "content": "* text eol=lf\n\n# Denote all files that are truly binary and should not be modified.\n*.png binary\n*.jpg binary\n" }, { "path": ".github/SECURITY.md", "content": "# Security Policy\n\n## Supported Versions\n\n| Version | Supported |\n| ------- | ------------------ |\n| 4.x.x | :white_check_mark: |\n| < 4.0 | :x: |\n\n## Reporting a Vulnerability\n\nTo report a security vulnerability, please use the\n[Tidelift security contact](https://tidelift.com/security).\nTidelift will coordinate the fix and disclosure.\n" }, { "path": ".github/workflows/dev.yml", "content": "name: dev\non:\n pull_request:\n push:\n branches:\n - master\n - main\nenv:\n CI: true\n\njobs:\n prettier:\n name: Format code\n runs-on: ubuntu-latest\n if: ${{ github.event_name == 'push' }}\n\n steps:\n - name: Checkout\n uses: actions/checkout@v2\n\n - name: Prettier\n uses: gulpjs/prettier_action@v3.0\n with:\n commit_message: 'chore: Run prettier'\n prettier_options: '--write .'\n\n test:\n name: Tests for Node ${{ matrix.node }} on ${{ matrix.os }}\n runs-on: ${{ matrix.os }}\n\n strategy:\n fail-fast: false\n matrix:\n node: [10, 12, 14, 16, 18, 20, 22, 24]\n os: [ubuntu-latest, windows-latest, macos-13]\n\n steps:\n - name: Clone repository\n uses: actions/checkout@v2\n\n - name: Set Node.js version\n uses: actions/setup-node@v2\n with:\n node-version: ${{ matrix.node }}\n\n - run: node --version\n - run: npm --version\n\n - name: Install npm dependencies\n run: npm install\n\n - name: Run lint\n run: npm run lint\n\n - name: Run tests\n run: npm test\n\n - name: Coveralls\n uses: coverallsapp/github-action@v1.1.2\n with:\n github-token: ${{ secrets.GITHUB_TOKEN }}\n flag-name: ${{matrix.os}}-node-${{ matrix.node }}\n parallel: true\n\n coveralls:\n needs: test\n name: Finish up\n\n runs-on: ubuntu-latest\n steps:\n - name: Coveralls Finished\n uses: coverallsapp/github-action@v1.1.2\n with:\n github-token: ${{ secrets.GITHUB_TOKEN }}\n parallel-finished: true\n" }, { "path": ".github/workflows/release.yml", "content": "name: release\non:\n push:\n branches:\n - master\n - main\n\njobs:\n release-please:\n runs-on: ubuntu-latest\n steps:\n - uses: GoogleCloudPlatform/release-please-action@v2\n with:\n token: ${{ secrets.GITHUB_TOKEN }}\n release-type: node\n package-name: release-please-action\n" }, { "path": ".gitignore", "content": "# Logs\nlogs\n*.log\n\n# Runtime data\npids\n*.pid\n*.seed\n\n# Directory for instrumented libs generated by jscoverage/JSCover\nlib-cov\n\n# Coverage directory used by tools like istanbul\ncoverage\n.nyc_output\n\n# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)\n.grunt\n\n# Compiled binary addons (https://nodejs.org/api/addons.html)\nbuild/Release\n\n# Dependency directory\n# Commenting this out is preferred by some people, see\n# https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git-\nnode_modules\n\n# Users Environment Variables\n.lock-wscript\n\n# Garbage files\n.DS_Store\n\n# Test results\ntest.xunit\n" }, { "path": ".npmrc", "content": "package-lock=false\n" }, { "path": ".prettierignore", "content": "coverage/\n.nyc_output/\nCHANGELOG.md\n" }, { "path": ".tidelift.yml", "content": "ci:\n platform:\n NPM:\n # We use an older version that doesn't use ES6+ features to support back to node 0.10\n eslint:\n tests:\n outdated: skip\n # We use an older version that doesn't use ES6+ features to support back to node 0.10\n expect:\n tests:\n outdated: skip\n # We use an older version that doesn't use ES6+ features to support back to node 0.10\n mocha:\n tests:\n outdated: skip\n" }, { "path": "CHANGELOG.md", "content": "# gulp changelog\n\n### [5.0.1](https://www.github.com/gulpjs/gulp/compare/v5.0.0...v5.0.1) (2025-06-01)\n\n\n### Bug Fixes\n\n* Avoid globbing before read stream is opened ([#2839](https://www.github.com/gulpjs/gulp/issues/2839)) ([19122f3](https://www.github.com/gulpjs/gulp/commit/19122f3d9eefccaadcf0e96313a7d3b83348348b))\n* Avoid Node.js deprecation warning for `fs.Stats` ([#2838](https://www.github.com/gulpjs/gulp/issues/2838)) ([69a5d0e](https://www.github.com/gulpjs/gulp/commit/69a5d0e904278dde61c835a0b198d7d1c5a15b95))\n* Support top-level await on Node 22.12+ ([#2836](https://www.github.com/gulpjs/gulp/issues/2836)) ([04b4a74](https://www.github.com/gulpjs/gulp/commit/04b4a74aec63302f603f0cca3826f75b1bda64ad))\n\n## [5.0.0](https://www.github.com/gulpjs/gulp/compare/v4.0.2...v5.0.0) (2024-03-29)\n\nWe've tried to provide a high-level changelog for gulp v5 below, but it\ndoesn't contain all changes from the 60+ dependencies that we maintain.\n\nPlease see [individual changelogs](#individual-changelogs) to drill down\ninto all changes that were made.\n\n### ⚠ BREAKING CHANGES\n\n* Drop support for Node.js <10.13\n* Default stream encoding to UTF-8\n* Standardized on `anymatch` library for globbing paths. All globs should work the same between `src` and `watch` now!\n* Removed support for ordered globs. This aligns with the chokidar globbing implementation. If you need your globs to be ordered, you can use `ordered-read-stream`\n* All globs and paths are normalized to unix-like filepaths\n* Only allow JS variants for `.gulp.*` config files\n* Removed support for alpha releases of v4 from `gulp-cli`\n* Removed the `--verify` flag\n* Renamed the `--require` flag to `--preload` to avoid conflicting with Node.js flags\n* Removed many legacy and deprecated loaders\n* Upgrade to chokidar v3\n* Clone `Vinyl` objects with stream contents using `teex`, but no longer wait for all streams to flow before cloned streams will receive data\n* Stop using `process.umask()` to make directories, instead falling back to Node's default mode\n* Throw on non-function, non-string option coercers\n* Drop support of Node.js snake_case flags\n* Use a Symbol for attaching the `gulplog` namespace to the store\n* Use a Symbol for attaching the `gulplog` store to the global\n* Use sha256 to hash the `v8flags` cache into a filename\n\n### Features\n\n* Streamlined the dependency tree\n* Switch all streams implementation to Streamx\n* Rewrote `glob-stream` to use a custom directory walk that relies on newer Node.js features and is more performant than old implementation\n* Implement translation support for all CLI messages and all messages passing through gulplog\n* Allow users to customize or remove the timestamp from their logs\n* Upgraded gulplog to v2. Messages logged via v1 will also display a deprecated warning. Plugins should update to v2 as the community upgrades to gulp 5\n* Added support for `gulpile.cjs` and `gulpfile.mjs`\n* Add support for `swc`, `esbuild`, `sucrase`, and `mdx` loaders\n* Provide an ESM export ([#2760](https://www.github.com/gulpjs/gulp/issues/2760)) ([b00de68](https://www.github.com/gulpjs/gulp/commit/b00de681f5ef6ade283d544f62f770f6b27a9e52))\n* Support sourcemap handling on streaming `Vinyl` contents\n* Support `extends` syntax for `.gulp.*` config file\n* Allow overriding `gulpfile` and `preloads` via `.gulp.*` config file\n\n### Bug Fixes\n\n* Resolve bugs related to symlinks on various platforms\n* Resolved some reported ReDoS CVEs and improved performance in glob-parent\n* Rework errors surfaced when encountering files or symlinks when trying to create directories\n* Ensure watch allows japanese characters in globs ([72668c6](https://www.github.com/gulpjs/gulp/commit/72668c61e445c81fad23bc6ed24967a3238a648d))\n* Ensure watch does not trigger on negated globs ([72668c6](https://www.github.com/gulpjs/gulp/commit/72668c61e445c81fad23bc6ed24967a3238a648d))\n* Improve handling of BOM at the beginning of a stream\n* Properly handle function coercer in array of option coercers\n* Fork `to-absolute-glob` to:\n - Check negative patterns before trimming\n - Ensure glob-like characters are escaped in cwd & root options\n - Resolve `../` at the beginning of globs\n\n### Miscellaneous Chores\n\n* Remove lazystream dependency\n* Updated various stream test suites to test against Node.js core `stream`, `readable-stream`, and `streamx`\n* Normalize repository, dropping node <10.13 support ([#2758](https://www.github.com/gulpjs/gulp/issues/2758)) ([72668c6](https://www.github.com/gulpjs/gulp/commit/72668c61e445c81fad23bc6ed24967a3238a648d))\n\n### Individual Changelogs\n\nWe created and maintain various projects that gulp depends upon. You can find their changelogs linked below:\n\n* [undertaker](https://github.com/gulpjs/undertaker/blob/master/CHANGELOG.md#200-2024-03-22)\n* [vinyl-fs](https://github.com/gulpjs/vinyl-fs/blob/master/CHANGELOG.md#400-2023-06-11)\n* [glob-stream](https://github.com/gulpjs/glob-stream/blob/master/CHANGELOG.md#801-2024-03-25)\n* [gulp-cli](https://github.com/gulpjs/gulp-cli/blob/master/CHANGELOG.md#300-2024-03-24)\n* [interpret](https://github.com/gulpjs/interpret/blob/master/CHANGELOG.md#311-2022-06-29)\n* [glob-parent](https://github.com/gulpjs/glob-parent/blob/main/CHANGELOG.md#602-2021-09-29)\n* [glob-watcher](https://github.com/gulpjs/glob-watcher/blob/master/CHANGELOG.md#600-2023-05-31)\n* [vinyl](https://github.com/gulpjs/vinyl/blob/master/CHANGELOG.md#300-2022-09-26)\n* [fs-mkdirp-stream](https://github.com/gulpjs/fs-mkdirp-stream/blob/master/CHANGELOG.md#201-2022-09-17)\n* [lead](https://github.com/gulpjs/lead/blob/master/CHANGELOG.md#400-2022-09-22)\n* [vinyl-sourcemap](https://github.com/gulpjs/vinyl-sourcemap/blob/master/CHANGELOG.md#200-2022-10-17)\n* [to-through](https://github.com/gulpjs/to-through/blob/master/CHANGELOG.md#300-2022-09-07)\n* [resolve-options](https://github.com/gulpjs/resolve-options/blob/master/CHANGELOG.md#200-2022-06-24)\n* [remove-bom-stream](https://github.com/gulpjs/remove-bom-stream/blob/master/CHANGELOG.md#200-2022-04-19)\n* [value-or-function](https://github.com/gulpjs/value-or-function/blob/master/CHANGELOG.md#400-2022-01-30)\n* [now-and-later](https://github.com/gulpjs/now-and-later/blob/master/CHANGELOG.md#300-2022-06-25)\n* [@gulpjs/to-absolute-glob](https://github.com/gulpjs/to-absolute-glob/blob/master/CHANGELOG.md#400-2023-01-03)\n* [fined](https://github.com/gulpjs/fined/blob/master/CHANGELOG.md#200-2021-10-31)\n* [mute-stdout](https://github.com/gulpjs/mute-stdout/blob/master/CHANGELOG.md#200-2021-11-22)\n* [semver-greatest-satisfied-range](https://github.com/gulpjs/semver-greatest-satisfied-range/blob/master/CHANGELOG.md#200-2022-01-31)\n* [flagged-respawn](https://github.com/gulpjs/flagged-respawn/blob/master/CHANGELOG.md#200-2021-11-21)\n* [rechoir](https://github.com/gulpjs/rechoir/blob/master/CHANGELOG.md#080-2021-07-24)\n* [gulplog](https://github.com/gulpjs/gulplog/blob/master/CHANGELOG.md#220-2024-03-23)\n* [glogg](https://github.com/gulpjs/glogg/blob/master/CHANGELOG.md#220-2024-03-23)\n* [@gulpjs/messages](https://github.com/gulpjs/messages/blob/master/CHANGELOG.md#110-2024-03-24)\n* [sparkles](https://github.com/gulpjs/sparkles/blob/master/CHANGELOG.md#210-2024-03-23)\n* [liftoff](https://github.com/gulpjs/liftoff/blob/main/CHANGELOG.md#500-2024-03-16)\n* [v8flags](https://github.com/gulpjs/v8flags/blob/master/CHANGELOG.md#401-2023-09-03)\n* [bach](https://github.com/gulpjs/bach/blob/master/CHANGELOG.md#201-2022-08-29)\n* [undertaker-registry](https://github.com/gulpjs/undertaker-registry/blob/master/CHANGELOG.md#200-2021-12-29)\n* [async-settle](https://github.com/gulpjs/async-settle/blob/master/CHANGELOG.md#200-2022-06-25)\n* [last-run](https://github.com/gulpjs/last-run/blob/master/CHANGELOG.md#200-2022-01-10)\n* [async-done](https://github.com/gulpjs/async-done/blob/master/CHANGELOG.md#200-2022-06-25)\n* [replace-homedir](https://github.com/gulpjs/replace-homedir/blob/master/CHANGELOG.md#200-2022-01-31)\n\n## 4.0.0\n\n### Task system changes\n\n- replaced 3.x task system (orchestrator) with new task system (bach)\n - removed gulp.reset\n - removed 3 argument syntax for `gulp.task`\n - `gulp.task` should only be used when you will call the task with the CLI\n - added `gulp.series` and `gulp.parallel` methods for composing tasks. Everything must use these now.\n - added single argument syntax for `gulp.task` which allows a named function to be used as the name of the task and task function.\n - added `gulp.tree` method for retrieving the task tree. Pass `{ deep: true }` for an `archy` compatible node list.\n - added `gulp.registry` for setting custom registries.\n\n### CLI changes\n\n- split CLI out into a module if you want to save bandwidth/disk space. you can install the gulp CLI using either `npm install gulp -g` or `npm install gulp-cli -g`, where gulp-cli is the smaller one (no module code included)\n- add `--tasks-json` flag to CLI to dump the whole tree out for other tools to consume\n- added `--verify` flag to check the dependencies in package.json against the plugin blacklist.\n\n### vinyl/vinyl-fs changes\n\n- added `gulp.symlink` which functions exactly like `gulp.dest`, but symlinks instead.\n- added `dirMode` param to `gulp.dest` and `gulp.symlink` which allows better control over the mode of the destination folder that is created.\n- globs passed to `gulp.src` will be evaluated in order, which means this is possible `gulp.src(['*.js', '!b*.js', 'bad.js'])` (exclude every JS file that starts with a b except bad.js)\n- performance for gulp.src has improved massively\n - `gulp.src(['**/*', '!b.js'])` will no longer eat CPU since negations happen during walking now\n- added `since` option to `gulp.src` which lets you only match files that have been modified since a certain date (for incremental builds)\n- fixed `gulp.src` not following symlinks\n- added `overwrite` option to `gulp.dest` which allows you to enable or disable overwriting of existing files\n\n## 3.9.1\n\n- update interpret to 1.0.0 (support for babel-register)\n- fix to include manpages in published tarball\n- documentation/recipe updates\n\n## 3.9.0\n\n- add babel support\n- add transpiler fallback support\n- add support for some renamed transpilers: livescript, etc\n- add JSCS\n- update dependencies (liftoff, interpret)\n- documentation tweaks\n\n## 3.8.11\n\n- fix node 0.12/iojs problems\n- add node 0.12 and iojs to travis\n- update dependencies (liftoff, v8flags)\n- documentation tweaks\n\n## 3.8.10\n\n- add link to spanish docs\n- update dependencies (archy, semver, mocha, etc)\n- documentation tweaks\n\n## 3.8.9\n\n- fix local version undefined output\n- add completion for fish shell\n- fix powershell completion line splitting\n- add support for arbitrary node flags (oops, should have been a minor bump)\n- add v8flags dependency\n- update dependencies (liftoff)\n- documentation tweaks\n\n## 3.8.8\n\n- update dependencies (minimist, tildify)\n- documentation tweaks\n\n## 3.8.7\n\n- handle errors a bit better\n- update dependencies (gulp-util, semver, etc)\n- documentation tweaks\n\n## 3.8.6\n\n- remove executable flag from LICENSE\n- update dependencies (chalk, minimist, liftoff, etc)\n- documentation tweaks\n\n## 3.8.5\n\n- simplify --silent and --tasks-simple\n- fix bug in autocomplete where errors would come out\n\n## 3.8.4\n\n- CLI will use exit code 1 on exit when any task fails during the lifetime of the process\n\n\n## 3.8.3\n\n- Tweak error formatting to work better with PluginErrors and strings\n\n## 3.8.2\n\n- add manpage generation\n\n## 3.8.1\n\n- the CLI now adds process.env.INIT_CWD which is the original cwd it was launched from\n\n## 3.8.0\n\n- update vinyl-fs\n - gulp.src is now a writable passthrough, this means you can use it to add files to your pipeline at any point\n - gulp.dest can now take a function to determine the folder\n\nThis is now possible!\n\n```js\ngulp.src('lib/*.js')\n .pipe(uglify())\n .pipe(gulp.src('styles/*.css'))\n .pipe(gulp.dest(function(file){\n // I don't know, you can do something cool here\n return 'build/whatever';\n }));\n```\n\n## 3.7.0\n\n- update vinyl-fs to remove BOM from UTF8 files\n- add --tasks-simple flag for plaintext task listings\n- updated autocomplete scripts to be simpler and use new --tasks-simple flag\n- added support for transpilers via liftoff 0.11 and interpret\n - just npm install your compiler (coffee-script for example) and it will work out of the box\n\n## 3.5.5\n\n- update deps\n- gulp.dest now support mode option, uses source file mode by default (file.stat.mode)\n- use chalk for colors in bin\n- update gulp.env deprecation msg to be more helpful\n\n\n## 3.5.2\n\n- add -V for version on CLI (unix standard)\n- -v is deprecated, use -V\n- add -T as an alias for --tasks\n- documentation\n\n## 3.5\n\n- added `gulp.watch(globs, tasksArray)` sugar\n- remove gulp.taskQueue\n- deprecate gulp.run\n- deprecate gulp.env\n- add engineStrict to prevent people with node < 0.9 from installing\n\n## 3.4\n\n- added `--tasks` that prints out the tree of tasks + deps\n- global cli + local install mismatch is no longer fatal\n- remove tests for fs stuff\n- switch core src, dest, and watch to vinyl-fs\n- internal cleaning\n\n## 3.3.4\n\n- `--base` is now `--cwd`\n\n## 3.3.3\n\n- support for `--base` CLI arg to change where the search for gulpfile/`--require`s starts\n- support for `--gulpfile` CLI arg to point to a gulpfile specifically\n\n## 3.3.0\n\n- file.contents streams are no longer paused coming out of src\n- dest now passes files through before they are empty to fix passing to multiple dests\n\n## 3.2.4\n\n- Bug fix - we didn't have any CLI tests\n\n## 3.2.3\n\n- Update dependencies for bug fixes\n- autocomplete stuff in the completion folder\n\n## 3.2\n\n- File object is now [vinyl](https://github.com/wearefractal/vinyl)\n- .watch() is now [glob-watcher](https://github.com/wearefractal/glob-watcher)\n- Fix CLI -v when no gulpfile found\n- gulp-util updated\n- Logging moved to CLI bin file\n - Will cause double logging if you update global CLI to 3.2 but not local\n - Will cause no logging if you update local to 3.1 but not global CLI\n- Drop support for < 0.9\n\n## 3.1.3\n\n- Move isStream and isBuffer to gulp-util\n\n## 3.1\n\n- Move file class to gulp-util\n\n## 3.0\n\n- Ability to pass multiple globs and glob negations to glob-stream\n- Breaking change to the way glob-stream works\n- File object is now a class\n- file.shortened changed to file.relative\n- file.cwd added\n- Break out getStats to avoid nesting\n- Major code reorganization\n\n## 2.7\n\n- Breaking change to the way options are passed to glob-stream\n- Introduce new File object to ease pain of computing shortened names (now a getter)\n\n## 2.4 - 2.6\n\n- Moved stuff to gulp-util\n- Quit exposing createGlobStream (just use the glob-stream module)\n- More logging\n- Prettier time durations\n- Tons of documentation changes\n- gulp.trigger(tasks...) as a through stream\n\n## 1.2-2.4 (11/12/13)\n\n- src buffer=false fixed for 0.8 and 0.9 (remember to .resume() on these versions before consuming)\n- CLI completely rewritten\n - Colorful logging\n - Uses local version of gulp to run tasks\n - Uses findup to locate gulpfile (so you can run it anywhere in your project)\n - chdir to gulpfile directory before loading it\n - Correct exit codes on errors\n- silent flag added to gulp to disable logging\n- Fixes to task orchestration (3rd party)\n- Better support for globbed directories (thanks @robrich)\n\n## 1.2 (10/28/13)\n\n- Can specify buffer=false on src streams to make file.content a stream\n- Can specify read=false on src streams to disable file.content\n\n## 1.1 (10/21/13)\n\n- Can specify run callback\n- Can specify task dependencies\n- Tasks can accept callback or return promise\n- `gulp.verbose` exposes run-time internals\n\n## 1.0 (9/26/13)\n\n- Specify dependency versions\n- Updated docs\n\n## 0.2 (8/6/13)\n\n- Rename .files() to .src() and .folder() to .dest()\n\n## 0.1 (7/18/13)\n\n- Initial Release\n" }, { "path": "CONTRIBUTING.md", "content": "# Request for contributions\n\nPlease contribute to this repository if any of the following is true:\n- You have expertise in community development, communication, or education\n- You want open source communities to be more collaborative and inclusive\n- You want to help lower the burden to first time contributors\n\n# How to contribute\n\nPrerequisites:\n\n- familiarity with [GitHub PRs](https://help.github.com/articles/using-pull-requests) (pull requests) and issues\n- knowledge of Markdown for editing `.md` documents\n\nIn particular, this community seeks the following types of contributions:\n\n- ideas: participate in an Issues thread or start your own to have your voice\nheard\n- resources: submit a PR to add to [docs README.md](/docs/README.md) with links to related content\n- outline sections: help us ensure that this repository is comprehensive. If\nthere is a topic that is overlooked, please add it, even if it is just a stub\nin the form of a header and single sentence. Initially, most things fall into\nthis category\n- write: contribute your expertise in an area by helping us expand the included\ncontent\n- copy editing: fix typos, clarify language, and generally improve the quality\nof the content\n- formatting: help keep content easy to read with consistent formatting\n- code: Fix issues or contribute new features to this or any related projects\n\n# Project structure\n\nGulp itself is tiny: index.js contains [very few lines of code](https://github.com/gulpjs/gulp/blob/master/index.js).\nIt is powered by a few other libraries which each handle a few specific tasks\neach.\n\nYou can view all issues with the \"help wanted\" label across all gulp projects\nhere: https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+user%3Agulpjs+label%3A%22help+wanted%22+\n\n## Undertaker: task management\n\nUndertaker handles task management in Gulp: the `gulp.task()`, `gulp.series()`\nand `gulp.parallel()` functions. `gulp.series()` and `gulp.parallel()` are in\nturn powered by Bach.\n\n- https://github.com/gulpjs/undertaker\n- https://github.com/gulpjs/bach\n\n## vinyl-fs: file streams\n\nvinyl-fs powers the `gulp.src()` and `gulp.dest()` functions: they take files\nand globs specified by the user, turns them into a stream of file objects,\nand then puts them back into the filesystem when `gulp.dest()` is called.\n\nThe file objects themselves are vinyl objects: that's another library (a simple\none!)\n\n- https://github.com/gulpjs/vinyl-fs\n- https://github.com/gulpjs/vinyl\n\n## chokidar: file watching\n\n`gulp.watch()` is using chokidar for file watching. It's actually wrapped in a\nsmall library on the gulp organization, glob-watcher.\n\n- https://github.com/paulmillr/chokidar\n- https://github.com/gulpjs/glob-watcher\n\n## gulp-cli: running gulp\n\nFinally, we have gulp-cli. This uses liftoff to take what people run in the\ncommand line and run the correct tasks. It works with both gulp 4 and older\nversions of gulp.\n\n- https://github.com/gulpjs/gulp-cli\n- https://github.com/js-cli/js-liftoff\n\n# Conduct\n\nWe are committed to providing a friendly, safe and welcoming environment for\nall, regardless of gender, sexual orientation, disability, ethnicity, religion,\nor similar personal characteristic.\n\nOn IRC, please avoid using overtly sexual nicknames or other nicknames that\nmight detract from a friendly, safe and welcoming environment for all.\n\nPlease be kind and courteous. There's no need to be mean or rude.\nRespect that people have differences of opinion and that every design or\nimplementation choice carries a trade-off and numerous costs. There is seldom\na right answer, merely an optimal answer given a set of values and\ncircumstances.\n\nPlease keep unstructured critique to a minimum. If you have solid ideas you\nwant to experiment with, make a fork and see how it works.\n\nWe will exclude you from interaction if you insult, demean or harass anyone.\nThat is not welcome behavior. We interpret the term \"harassment\" as\nincluding the definition in the\n[Citizen Code of Conduct](http://citizencodeofconduct.org/);\nif you have any lack of clarity about what might be included in that concept,\nplease read their definition. In particular, we don't tolerate behavior that\nexcludes people in socially marginalized groups.\n\nPrivate harassment is also unacceptable. No matter who you are, if you feel\nyou have been or are being harassed or made uncomfortable by a community\nmember, please contact one of the channel ops or any of the\n[gulpjs](https://github.com/orgs/gulpjs/people) core team\nimmediately. Whether you're a regular contributor or a newcomer, we care about\nmaking this community a safe place for you and we've got your back.\n\nLikewise any spamming, trolling, flaming, baiting or other attention-stealing\nbehavior is not welcome.\n\n\n# Communication\n\nThere is an IRC channel on irc.freenode.net, channel `#gulpjs`. You're\nwelcome to drop in and ask questions, discuss bugs and such. The channel is\nnot currently logged.\n\nGitHub issues are the primary way for communicating about specific proposed\nchanges to this project.\n\nIn both contexts, please follow the conduct guidelines above. Language issues\nare often contentious and we'd like to keep discussion brief, civil and focused\non what we're actually doing, not wandering off into too much imaginary stuff.\n\n# Frequently Asked Questions\n\nSee [the FAQ docs page](/docs/FAQ.md)\n" }, { "path": "EXPENSE_POLICY.md", "content": "# Expense Policy\n\n## Funding can be requested for significant changes made by Core Members.\n* Discuss the changes in the private gulp team forum.\n* Include a cost estimation with either a fixed price or hours + rate (suggested $50 per hour).\n* Notify the team before you exceed an estimate.\n\n## Bug bounties may be assigned at the Core Members’ discretion to issues of significant importance - usually issues outstanding for at least 6 months.\n* Issues with bug bounties will be labeled “Bug Bounty: $x”.\n* In order to claim a bug bounty, create a Pull Request that fixes an issue with a “Bug Bounty” label.\n* The Pull Request must be reviewed and merged by a Core Member. If competing submissions exist, the best solution will be chosen by a Core Member. All else equal, the first submission will be chosen.\n* Once your Pull Request is merged, you can submit an expense to our [Open Collective](https://opencollective.com/gulpjs/expenses/new) which includes the link to your submission in the description (e.g. $100 bug bounty claim for https://github.com/gulpjs/gulp/pull/2226). You will also need to provide an invoice, see the [Open Collective Expense FAQ](https://opencollective.com/faq/expenses) for more details and to get a Google Docs template that you can use.\n* Then, add a comment on your Pull Request, noting that you’ve claimed the money, with a link to your Open Collective expense. This is to ensure the same person who fixed the issue is claiming the money.\n* Your expense will be validated by a Core Member and then your payment will be dispersed by Open Collective the following Friday.\n\n## If you're doing other good things for gulp that end up costing you real money, feel free to reach out and we can discuss helping with those expenses!\n" }, { "path": "LICENSE", "content": "The MIT License (MIT)\n\nCopyright (c) 2013-2024 Blaine Bublitz and Eric Schoffstall \n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" }, { "path": "README.md", "content": "

\n \n \n \n

The streaming build system

\n

\n\n[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Build Status][ci-image]][ci-url] [![Coveralls Status][coveralls-image]][coveralls-url]\n\n## What is gulp?\n\n- **Automation** - gulp is a toolkit that helps you automate painful or time-consuming tasks in your development workflow.\n- **Platform-agnostic** - Integrations are built into all major IDEs and people are using gulp with PHP, .NET, Node.js, Java, and other platforms.\n- **Strong Ecosystem** - Use npm modules to do anything you want + over 3000 curated plugins for streaming file transformations.\n- **Simple** - By providing only a minimal API surface, gulp is easy to learn and simple to use.\n\n## Installation\n\nFollow our [Quick Start guide][quick-start].\n\n## Roadmap\n\nFind out about all our work-in-progress and outstanding issues at https://github.com/orgs/gulpjs/projects.\n\n## Documentation\n\nCheck out the [Getting Started guide][getting-started-guide] and [API docs][api-docs] on our website!\n\n__Excuse our dust! All other docs will be behind until we get everything updated. Please open an issue if something isn't working.__\n\n## Sample `gulpfile.js`\n\nThis file will give you a taste of what gulp does.\n\n```js\nvar gulp = require('gulp');\nvar less = require('gulp-less');\nvar babel = require('gulp-babel');\nvar concat = require('gulp-concat');\nvar uglify = require('gulp-uglify');\nvar rename = require('gulp-rename');\nvar cleanCSS = require('gulp-clean-css');\nvar del = require('del');\n\nvar paths = {\n styles: {\n src: 'src/styles/**/*.less',\n dest: 'assets/styles/'\n },\n scripts: {\n src: 'src/scripts/**/*.js',\n dest: 'assets/scripts/'\n }\n};\n\n/* Not all tasks need to use streams, a gulpfile is just another node program\n * and you can use all packages available on npm, but it must return either a\n * Promise, a Stream or take a callback and call it\n */\nfunction clean() {\n // You can use multiple globbing patterns as you would with `gulp.src`,\n // for example if you are using del 2.0 or above, return its promise\n return del([ 'assets' ]);\n}\n\n/*\n * Define our tasks using plain functions\n */\nfunction styles() {\n return gulp.src(paths.styles.src)\n .pipe(less())\n .pipe(cleanCSS())\n // pass in options to the stream\n .pipe(rename({\n basename: 'main',\n suffix: '.min'\n }))\n .pipe(gulp.dest(paths.styles.dest));\n}\n\nfunction scripts() {\n return gulp.src(paths.scripts.src, { sourcemaps: true })\n .pipe(babel())\n .pipe(uglify())\n .pipe(concat('main.min.js'))\n .pipe(gulp.dest(paths.scripts.dest));\n}\n\nfunction watch() {\n gulp.watch(paths.scripts.src, scripts);\n gulp.watch(paths.styles.src, styles);\n}\n\n/*\n * Specify if tasks run in series or parallel using `gulp.series` and `gulp.parallel`\n */\nvar build = gulp.series(clean, gulp.parallel(styles, scripts));\n\n/*\n * You can use CommonJS `exports` module notation to declare tasks\n */\nexports.clean = clean;\nexports.styles = styles;\nexports.scripts = scripts;\nexports.watch = watch;\nexports.build = build;\n/*\n * Define default task that can be called by just running `gulp` from cli\n */\nexports.default = build;\n```\n\n## Use latest JavaScript version in your gulpfile\n\nGulp provides a wrapper that will be loaded in your ESM code, so you can name your gulpfile as `gulpfile.mjs` or with `\"type\": \"module\"` specified in your `package.json` file.\n\nAnd here's the same sample from above written in **ESNext**.\n\n```js\nimport { src, dest, watch } from 'gulp';\nimport less from 'gulp-less';\nimport babel from 'gulp-babel';\nimport concat from 'gulp-concat';\nimport uglify from 'gulp-uglify';\nimport rename from 'gulp-rename';\nimport cleanCSS from 'gulp-clean-css';\nimport {deleteAsync} from 'del';\n\nconst paths = {\n styles: {\n src: 'src/styles/**/*.less',\n dest: 'assets/styles/'\n },\n scripts: {\n src: 'src/scripts/**/*.js',\n dest: 'assets/scripts/'\n }\n};\n\n/*\n * For small tasks you can export arrow functions\n */\nexport const clean = () => deleteAsync([ 'assets' ]);\n\n/*\n * You can also declare named functions and export them as tasks\n */\nexport function styles() {\n return src(paths.styles.src)\n .pipe(less())\n .pipe(cleanCSS())\n // pass in options to the stream\n .pipe(rename({\n basename: 'main',\n suffix: '.min'\n }))\n .pipe(dest(paths.styles.dest));\n}\n\nexport function scripts() {\n return src(paths.scripts.src, { sourcemaps: true })\n .pipe(babel())\n .pipe(uglify())\n .pipe(concat('main.min.js'))\n .pipe(dest(paths.scripts.dest));\n}\n\n /*\n * You could even use `export as` to rename exported tasks\n */\nfunction watchFiles() {\n watch(paths.scripts.src, scripts);\n watch(paths.styles.src, styles);\n}\nexport { watchFiles as watch };\n\nconst build = gulp.series(clean, gulp.parallel(styles, scripts));\n/*\n * Export a default task\n */\nexport default build;\n```\n\n## Incremental Builds\n\nYou can filter out unchanged files between runs of a task using\nthe `gulp.src` function's `since` option and `gulp.lastRun`:\n```js\nconst paths = {\n ...\n images: {\n src: 'src/images/**/*.{jpg,jpeg,png}',\n dest: 'build/img/'\n }\n}\n\nfunction images() {\n return gulp.src(paths.images.src, {since: gulp.lastRun(images)})\n .pipe(imagemin())\n .pipe(gulp.dest(paths.images.dest));\n}\n\nfunction watch() {\n gulp.watch(paths.images.src, images);\n}\n```\nTask run times are saved in memory and are lost when gulp exits. It will only\nsave time during the `watch` task when running the `images` task\nfor a second time.\n\n## Want to contribute?\n\nAnyone can help make this project better - check out our [Contributing guide](/CONTRIBUTING.md)!\n\n\n[quick-start]: https://gulpjs.com/docs/en/getting-started/quick-start\n[getting-started-guide]: https://gulpjs.com/docs/en/getting-started/quick-start\n[api-docs]: https://gulpjs.com/docs/en/api/concepts\n[esm-module]: https://github.com/standard-things/esm\n\n\n\n[downloads-image]: https://img.shields.io/npm/dm/gulp.svg?style=flat-square\n[npm-url]: https://www.npmjs.com/package/gulp\n[npm-image]: https://img.shields.io/npm/v/gulp.svg?style=flat-square\n\n[ci-url]: https://github.com/gulpjs/gulp/actions?query=workflow:dev\n[ci-image]: https://img.shields.io/github/actions/workflow/status/gulpjs/gulp/dev.yml?branch=master&style=flat-square\n\n[coveralls-url]: https://coveralls.io/r/gulpjs/gulp\n[coveralls-image]: https://img.shields.io/coveralls/gulpjs/gulp/master.svg?style=flat-square\n\n" }, { "path": "bin/gulp.js", "content": "#!/usr/bin/env node\n\nrequire('gulp-cli')();\n" }, { "path": "docs/CLI.md", "content": "## gulp CLI docs\n\n### Flags\n\ngulp has very few flags to know about. All other flags are for tasks to use if needed.\n\n- `-v` or `--version` will display the global and local gulp versions\n- `--require ` will require a module before running the gulpfile. This is useful for transpilers but also has other applications. You can use multiple `--require` flags\n- `--gulpfile ` will manually set path of gulpfile. Useful if you have multiple gulpfiles. This will set the CWD to the gulpfile directory as well\n- `--cwd ` will manually set the CWD. The search for the gulpfile, as well as the relativity of all requires will be from here\n- `-T` or `--tasks` will display the task dependency tree for the loaded gulpfile. It will include the task names and their [description](./API.md#fndescription).\n- `--tasks-simple` will display a plaintext list of tasks for the loaded gulpfile\n- `--verify` will verify plugins referenced in project's package.json against the plugins blacklist\n- `--color` will force gulp and gulp plugins to display colors even when no color support is detected\n- `--no-color` will force gulp and gulp plugins to not display colors even when color support is detected\n- `--silent` will disable all gulp logging\n\nThe CLI adds process.env.INIT_CWD which is the original cwd it was launched from.\n\n#### Task specific flags\n\nRefer to this [StackOverflow](https://stackoverflow.com/questions/23023650/is-it-possible-to-pass-a-flag-to-gulp-to-have-it-run-tasks-in-different-ways) link for how to add task specific flags\n\n### Tasks\n\nTasks can be executed by running `gulp ...`.\n\nIf more than one task is listed, Gulp will execute all of them\nconcurrently, that is, as if they had all been listed as dependencies of\na single task.\n\nGulp does not serialize tasks listed on the command line. From using\nother comparable tools users may expect to execute something like\n`gulp clean build`, with tasks named `clean` and `build`. This will not\nproduce the intended result, as the two tasks will be executed\nconcurrently.\n\nJust running `gulp` will execute the task `default`. If there is no\n`default` task, gulp will error.\n\n### Compilers\n\nYou can find a list of supported languages at [interpret](https://github.com/tkellen/node-interpret#jsvariants). If you would like to add support for a new language send pull request/open issues there.\n\n### Examples\n\n#### Example gulpfile\n\n```js\ngulp.task('one', function(done) {\n // do stuff\n done();\n});\n\ngulp.task('two', function(done) {\n // do stuff\n done();\n});\n\ngulp.task('three', three);\n\nfunction three(done) {\n done();\n}\nthree.description = \"This is the description of task three\";\n\ngulp.task('four', gulp.series('one', 'two'));\n\ngulp.task('five',\n gulp.series('four',\n gulp.parallel('three', function(done) {\n // do more stuff\n done();\n })\n )\n);\n```\n\n### `-T` or `--tasks`\n\nCommand: `gulp -T` or `gulp --tasks`\n\nOutput:\n```shell\n[20:58:55] Tasks for ~\\exampleProject\\gulpfile.js\n[20:58:55] ├── one\n[20:58:55] ├── two\n[20:58:55] ├── three This is the description of task three\n[20:58:55] ├─┬ four\n[20:58:55] │ └─┬ \n[20:58:55] │ ├── one\n[20:58:55] │ └── two\n[20:58:55] ├─┬ five\n[20:58:55] │ └─┬ \n[20:58:55] │ ├─┬ four\n[20:58:55] │ │ └─┬ \n[20:58:55] │ │ ├── one\n[20:58:55] │ │ └── two\n[20:58:55] │ └─┬ \n[20:58:55] │ ├── three\n[20:58:55] │ └── \n```\n\n### `--tasks-simple`\n\nCommand: `gulp --tasks-simple`\n\nOutput:\n```shell\none\ntwo\nthree\nfour\nfive\n```\n" }, { "path": "docs/FAQ.md", "content": "# FAQ\n\n## Why gulp? Why not ____?\n\nSee the [gulp introduction slideshow] for a rundown on how gulp came to be.\n\n## Is it \"gulp\" or \"Gulp\"?\n\ngulp is always lowercase. The only exception is in the gulp logo where gulp is capitalized.\n\n## Where can I find a list of gulp plugins?\n\ngulp plugins always include the `gulpplugin` keyword. [Search gulp plugins][search-gulp-plugins] or [view all plugins][npm plugin search].\n\n## I want to write a gulp plugin, how do I get started?\n\nSee the [Writing a gulp plugin] wiki page for guidelines and an example to get you started.\n\n## My plugin does ____, is it doing too much?\n\nProbably. Ask yourself:\n\n1. Is my plugin doing something that other plugins may need to do?\n - If so, that piece of functionality should be a separate plugin. [Check if it already exists on npm][npm plugin search].\n1. Is my plugin doing two, completely different things based on a configuration option?\n - If so, it may serve the community better to release it as two separate plugins\n - If the two tasks are different, but very closely related, it's probably OK\n\n## How should newlines be represented in plugin output?\n\nAlways use `\\n` to prevent diff issues between operating systems.\n\n## I installed gulp as a dependency from package.json file by running `npm install` but I keep getting `command not found` whenever I try running a gulp command, why doesn't it work?\n\nUpon installing gulp as a project dependency, you need to add that to your PATH environment variable so that when you run a command, the system can find it. An easy solution is to install gulp globally, so that its binaries end up in your PATH environment variable. To install gulp globally, use the command `npm install gulp-cli -g`\n\n## Where can I get updates on gulp?\n\ngulp updates can be found on the following twitters:\n\n- [@wearefractal](https://twitter.com/wearefractal)\n- [@eschoff](https://twitter.com/eschoff)\n- [@gulpjs](https://twitter.com/gulpjs)\n\n## Does gulp have an chat channel?\n\nYes, come chat with us on [Gitter](https://gitter.im/gulpjs/gulp).\n\n[Writing a gulp plugin]: writing-a-plugin/README.md\n[gulp introduction slideshow]: https://slid.es/contra/gulp\n[Freenode]: https://freenode.net/\n[search-gulp-plugins]: https://gulpjs.com/plugins/\n[npm plugin search]: https://npmjs.org/browse/keyword/gulpplugin\n" }, { "path": "docs/README.md", "content": "# gulp documentation\n\n* [Getting Started](getting-started/) - Get started with gulp\n* [API documentation](api/) - The programming interface, defined\n* [CLI documentation](CLI.md) - Learn how to call tasks and use compilers\n* [Writing a Plugin](writing-a-plugin/) - The essentials of writing a gulp plugin\n* [Why Use Pump?](why-use-pump/README.md) - Why to use the `pump` module instead of calling `.pipe` yourself\n* [Simplified Chinese documentation][SimplifiedChineseDocs] - gulp 简体中文文档\n* [Korean documentation][KoreanDocs] - gulp 한국어 참조 문서\n* [Polish documentation](/docs/locale/pl_PL/README.md) - gulp Dokumentacja\n\n\n## FAQ\n\nSee the [FAQ](FAQ.md) for the answers to commonly asked questions.\n\n\n## Recipes\n\nThe community has written [recipes](recipes#recipes) for common gulp use-cases.\n\n\n## Still got questions?\n\nPost on [StackOverflow with a #gulp tag](https://stackoverflow.com/questions/tagged/gulp) or come chat with us in [#gulpjs](https://webchat.freenode.net/?channels=gulpjs) on [Freenode](https://freenode.net/).\n\n## Videos\n* [Intro to Gulp 4](https://youtu.be/N42LQ2dLoA8) presented by @addyosmani and @gauntface\n\n## Books\n* [Developing a gulp Edge](http://shop.oreilly.com/product/9781939902146.do)\n* [Getting Started with Gulp – Second Edition](https://www.packtpub.com/application-development/getting-started-gulp-%E2%80%93-second-edition) - Travis Maynard, Packt (April 2017)\n\n\n## Articles\n* [Tagtree intro to gulp video](http://tagtree.io/gulp)\n* [Introduction to node.js streams](https://github.com/substack/stream-handbook)\n* [Video introduction to node.js streams](https://www.youtube.com/watch?v=QgEuZ52OZtU)\n* [Getting started with gulp (by @markgdyr)](https://markgoodyear.com/2014/01/getting-started-with-gulp/)\n* [A cheatsheet for gulp](https://github.com/osscafe/gulp-cheatsheet)\n* [Why you shouldn’t create a gulp plugin (or, how to stop worrying and learn to love existing node packages)](http://blog.overzealous.com/post/74121048393/why-you-shouldnt-create-a-gulp-plugin-or-how-to-stop)\n* [Inspiration (slides) about why gulp was made](http://slid.es/contra/gulp)\n* [Building With Gulp](http://www.smashingmagazine.com/2014/06/11/building-with-gulp/)\n* [Gulp - The Basics (screencast)](https://www.youtube.com/watch?v=dwSLFai8ovQ)\n* [Get started with gulp (video series)](https://www.youtube.com/playlist?list=PLRk95HPmOM6PN-G1xyKj9q6ap_dc9Yckm)\n* [Optimize your web code with gulp](http://www.linuxuser.co.uk/tutorials/optimise-your-web-code-with-gulp-js)\n* [Automate Your Tasks Easily with Gulp.js ](https://scotch.io/tutorials/automate-your-tasks-easily-with-gulp-js)\n* [How to upgrade to Gulp v4](https://www.liquidlight.co.uk/blog/article/how-do-i-update-to-gulp-4/)\n\n## Examples\n\n- [Web Starter Kit gulpfile](https://github.com/google/web-starter-kit/blob/master/gulpfile.babel.js)\n\n\n## License\n\nAll the documentation is covered by the CC0 license *(do whatever you want with it - public domain)*.\n\n[![CC0](https://i.creativecommons.org/p/zero/1.0/88x31.png)](https://creativecommons.org/publicdomain/zero/1.0/)\n\nTo the extent possible under law, [Fractal](http://wearefractal.com) has waived all copyright and related or neighboring rights to this work.\n\n[SpanishDocs]: https://github.com/bucaran/gulp-docs-es\n[SimplifiedChineseDocs]: https://github.com/lisposter/gulp-docs-zh-cn\n[KoreanDocs]: https://github.com/preco21/gulp-docs-ko\n" }, { "path": "docs/advanced/creating-custom-registries.md", "content": "\n\n# Creating Custom Registries\n\nAllows custom registries to be plugged into the task system, which can provide shared tasks or augmented functionality. Registries are registered using [`registry()`][registry-api-docs].\n\n## Structure\n\nIn order to be accepted by gulp, custom registries must follow a specific format.\n\n```js\n// as a function\nfunction TestRegistry() {}\n\nTestRegistry.prototype.init = function (gulpInst) {}\nTestRegistry.prototype.get = function (name) {}\nTestRegistry.prototype.set = function (name, fn) {}\nTestRegistry.prototype.tasks = function () {}\n\n// as a class\nclass TestRegistry {\n init(gulpInst) {}\n\n get(name) {}\n\n set(name, fn) {}\n\n tasks() {}\n}\n```\n\nIf a registry instance passed to `registry()` doesn't have all four methods, an error will be thrown.\n\n## Registration\n\nIf we want to register our example registry from above, we will need to pass an instance of it to `registry()`.\n\n```js\nconst { registry } = require('gulp');\n\n// ... TestRegistry setup code\n\n// good!\nregistry(new TestRegistry())\n\n// bad!\nregistry(TestRegistry())\n// This will trigger an error: 'Custom registries must be instantiated, but it looks like you passed a constructor'\n```\n\n## Methods\n\n### `init(gulpInst)`\n\nThe `init()` method of a registry is called at the very end of the `registry()` function. The gulp instance passed as the only argument (`gulpInst`) can be used to pre-define tasks using\n`gulpInst.task(taskName, fn)`.\n\n#### Parameters\n\n| parameter | type | note |\n|:---------:|:----:|------|\n| gulpInst | object | Instance of gulp. |\n\n### `get(name)`\n\nThe `get()` method receives a task `name` for the custom registry to resolve and return, or `undefined` if no task with that name exists.\n\n#### Parameters\n\n| parameter | type | note |\n|:---------:|:----:|------|\n| name | string | Name of the task to be retrieved. |\n\n### `set(name, fn)`\n\nThe `set()` method receives a task `name` and `fn`. This is called internally by `task()` to provide user-registered tasks to custom registries.\n\n#### Parameters\n\n| parameter | type | note |\n|:---------:|:----:|------|\n| name | string | Name of the task to be set. |\n| fn | function | Task function to be set. |\n\n### `tasks()`\n\nMust return an object listing all tasks in the registry.\n\n## Use Cases\n\n### Sharing Tasks\n\nTo share common tasks with all your projects, you can expose an `init` method on the registry and it will receive an instance of gulp as the only argument. You can then use `gulpInst.task(name, fn)` to register pre-defined tasks.\n\nFor example, you might want to share a `clean` task:\n\n```js\nconst fs = require('fs');\nconst util = require('util');\n\nconst DefaultRegistry = require('undertaker-registry');\nconst del = require('del');\n\nfunction CommonRegistry(opts){\n DefaultRegistry.call(this);\n\n opts = opts || {};\n\n this.buildDir = opts.buildDir || './build';\n}\n\nutil.inherits(CommonRegistry, DefaultRegistry);\n\nCommonRegistry.prototype.init = function(gulpInst) {\n const buildDir = this.buildDir;\n const exists = fs.existsSync(buildDir);\n\n if(exists){\n throw new Error('Cannot initialize common tasks. ' + buildDir + ' directory exists.');\n }\n\n gulpInst.task('clean', function(){\n return del([buildDir]);\n });\n}\n\nmodule.exports = CommonRegistry;\n```\n\nThen to use it in a project:\n\n```js\nconst { registry, series, task } = require('gulp');\nconst CommonRegistry = require('myorg-common-tasks');\n\nregistry(new CommonRegistry({ buildDir: '/dist' }));\n\ntask('build', series('clean', function build(cb) {\n // do things\n cb();\n}));\n```\n\n### Sharing Functionality\n\nBy controlling how tasks are added to the registry, you can decorate them.\n\nFor example, if you wanted all tasks to share some data, you can use a custom registry to bind them to that data. Be sure to return the altered task, as per the description of registry methods above:\n\n```js\nconst { registry, series, task } = require('gulp');\nconst util = require('util');\nconst DefaultRegistry = require('undertaker-registry');\n\n// Some task defined somewhere else\nconst BuildRegistry = require('./build.js');\nconst ServeRegistry = require('./serve.js');\n\nfunction ConfigRegistry(config){\n DefaultRegistry.call(this);\n this.config = config;\n}\n\nutil.inherits(ConfigRegistry, DefaultRegistry);\n\nConfigRegistry.prototype.set = function set(name, fn) {\n var bound = fn.bind(this.config);\n // Preserve internal properties and task metadata.\n var task = Object.assign(bound, fn);\n // The `DefaultRegistry` uses `this._tasks` for storage.\n this._tasks[name] = task;\n return task;\n};\n\nregistry(new BuildRegistry());\nregistry(new ServeRegistry());\n\n// `registry` will reset each task in the registry with\n// `ConfigRegistry.prototype.set` which will bind them to the config object.\nregistry(new ConfigRegistry({\n src: './src',\n build: './build',\n bindTo: '0.0.0.0:8888'\n}));\n\ntask('default', series('clean', 'build', 'serve', function(cb) {\n console.log('Server bind to ' + this.bindTo);\n console.log('Serving' + this.build);\n cb();\n}));\n```\n\n## Examples\n\n* [undertaker-registry][undertaker-registry-example]: The Gulp 4 default registry.\n* [undertaker-common-tasks][undertaker-common-tasks-example]: Proof-of-concept custom registry that pre-defines tasks.\n* [undertaker-task-metadata][undertaker-task-metadata-example]: Proof-of-concept custom registry that attaches metadata to each task.\n\n[registry-api-docs]: ../api/registry.md\n[undertaker-registry-example]: https://github.com/gulpjs/undertaker-registry\n[undertaker-common-tasks-example]: https://github.com/gulpjs/undertaker-common-tasks\n[undertaker-task-metadata-example]: https://github.com/gulpjs/undertaker-task-metadata\n" }, { "path": "docs/api/README.md", "content": "## Table of Contents\n\n* [API Concepts](concepts.md)\n* [src()](src.md)\n* [dest()](dest.md)\n* [symlink()](symlink.md)\n* [lastRun()](last-run.md)\n* [series()](series.md)\n* [parallel()](parallel.md)\n* [watch()](watch.md)\n* [task()](task.md)\n* [registry()](registry.md)\n* [tree()](tree.md)\n* [Vinyl](vinyl.md)\n* [Vinyl.isVinyl()](vinyl-isvinyl.md)\n* [Vinyl.isCustomProp()](vinyl-iscustomprop.md)\n" }, { "path": "docs/api/concepts.md", "content": "\n\n# Concepts\n\nThe following concepts are prerequisites to understanding the API docs. They will be referenced throughout, refer back to this page for detailed explanations.\n\nIf you're new here, begin with the [Getting Started Guide][quick-start-docs].\n\n## Vinyl\n\nVinyl is a metadata object that describes a file. The main properties of a Vinyl instance are `path` and `contents` - core aspects of a file on your file system. Vinyl objects can be used to describe files from many sources - on a local file system or any remote storage option.\n\n## Vinyl adapters\n\nWhile Vinyl provides a way to describe a file, a way to access these files is needed. Each file source is accessed using a Vinyl adapter.\n\nAn adapter exposes:\n* A method with the signature `src(globs, [options])` and returns a stream that produces Vinyl objects.\n* A method with the signature `dest(folder, [options])` and returns a stream that consumes Vinyl objects.\n* Any extra methods specific to their input/output medium - such as the `symlink` method `vinyl-fs` provides. They should always return streams that produce and/or consume Vinyl objects.\n\n## Tasks\n\nEach gulp task is an asynchronous JavaScript function that either accepts an error-first callback or returns a stream, promise, event emitter, child process, or observable. Due to some platform limitations, synchronous tasks aren't supported.\n\nFor a more detailed explanation, see [Creating Tasks][creating-tasks-doc].\n\n## Globs\n\nA glob is a string of literal and/or wildcard characters, like `*`, `**`, or `!`, used to match filepaths. Globbing is the act of locating files on a file system using one or more globs.\n\nIf you don't have experience with globs, see [Explaining Globs][explaining-globs-docs].\n\n## Glob base\n\nA glob base - sometimes called glob parent - is the path segment before any special characters in a glob string. As such, the glob base of `/src/js/**.js` is `/src/js/`. All paths that match the glob are guaranteed to share the glob base - that path segment can't be variable.\n\nVinyl instances generated by `src()` are constructed with the glob base set as their `base` property. When written to the file system with `dest()`, the `base` will be removed from the output path to preserve directory structures.\n\nFor more in depth information, see the [glob-parent][glob-parent-external] repository.\n\n## File system stats\n\nFile metadata is provided as an instance of Node's [`fs.Stats`][fs-stats-external]. It is available as the `stat` property on your Vinyl instances and used internally to determine if a Vinyl object represents a directory or symbolic link. When written to the file system, permissions and time values are synchronized from the Vinyl object's `stat` property.\n\n## File system modes\n\nFile system modes determine what permissions exist for a file. Most files and directories on your file system will have a fairly permissive mode, allowing gulp to read/write/update files on your behalf. By default, gulp will create files with the same permissions as the running process, but you can configure the modes through options in `src()`, `dest()`, etc. If you're experiencing permission (EPERM) issues, check the modes on your files.\n\n## Modules\n\nGulp is made up of many small modules that are pulled together to work cohesively. By utilizing [semver][semver-external] within the small modules, we can release bug fixes and features without publishing new versions of gulp. Often, when you don't see progress on the main repository, work is being done in one of these modules.\n\nIf you're having trouble, ensure your current modules are updated using the `npm update` command. If the problem persists, open an issue on the individual project repository.\n\n* [undertaker][undertaker-external] - the task registration system\n* [vinyl][vinyl-external] - the virtual file objects\n* [vinyl-fs][vinyl-fs-external] - a vinyl adapter to your local file system\n* [glob-watcher][glob-watcher-external] - the file watcher\n* [bach][bach-external] - task orchestration using `series()` and `parallel()`\n* [last-run][last-run-external] - tracks the last run time of a task\n* [vinyl-sourcemap][vinyl-sourcemap-external] - built-in sourcemap support\n* [gulp-cli][gulp-cli-external] - the command line interface for interacting with gulp\n\n\n[quick-start-docs]: ../getting-started/1-quick-start.md\n[creating-tasks-doc]: ../getting-started/3-creating-tasks.md\n[explaining-globs-docs]: ../getting-started/6-explaining-globs.md\n[undertaker-external]: https://github.com/gulpjs/undertaker\n[vinyl-external]: https://github.com/gulpjs/vinyl\n[vinyl-fs-external]: https://github.com/gulpjs/vinyl-fs\n[glob-watcher-external]: https://github.com/gulpjs/glob-watcher\n[bach-external]: https://github.com/gulpjs/bach\n[last-run-external]: https://github.com/gulpjs/last-run\n[vinyl-sourcemap-external]: https://github.com/gulpjs/vinyl-sourcemap\n[gulp-cli-external]: https://github.com/gulpjs/gulp-cli\n[semver-external]: https://semver.org\n[fs-stats-external]: https://nodejs.org/api/fs.html#fs_class_fs_stats\n[glob-parent-external]: https://github.com/es128/glob-parent\n" }, { "path": "docs/api/dest.md", "content": "\n\n# dest()\n\nCreates a stream for writing [Vinyl][vinyl-concepts] objects to the file system.\n\n## Usage\n\n```js\nconst { src, dest } = require('gulp');\n\nfunction copy() {\n return src('input/*.js')\n .pipe(dest('output/'));\n}\n\nexports.copy = copy;\n```\n\n## Signature\n\n```js\ndest(directory, [options])\n```\n\n### Parameters\n\n| parameter | type | note |\n|:--------------:|:-----:|--------|\n| directory
**(required)** | string
function | The path of the output directory where files will be written. If a function is used, the function will be called with each Vinyl object and must return a string directory path. |\n| options | object | Detailed in [Options][options-section] below. |\n\n### Returns\n\nA stream that can be used in the middle or at the end of a pipeline to create files on the file system.\nWhenever a Vinyl object is passed through the stream, it writes the contents and other details out to the file system at the given directory. If the Vinyl object has a `symlink` property, a symbolic link will be created instead of writing the contents. After the file is created, its [metadata will be updated][metadata-updates-section] to match the Vinyl object.\n\nWhenever a file is created on the file system, the Vinyl object will be modified.\n* The `cwd`, `base`, and `path` properties will be updated to match the created file.\n* The `stat` property will be updated to match the file on the file system.\n* If the `contents` property is a stream, it will be reset so it can be read again.\n\n### Errors\n\nWhen `directory` is an empty string, throws an error with the message, \"Invalid dest() folder argument. Please specify a non-empty string or a function.\"\n\nWhen `directory` is not a string or function, throws an error with the message, \"Invalid dest() folder argument. Please specify a non-empty string or a function.\"\n\nWhen `directory` is a function that returns an empty string or `undefined`, emits an error with the message, \"Invalid output folder\".\n\n### Options\n\n\n**For options that accept a function, the passed function will be called with each Vinyl object and must return a value of another listed type.**\n\n| name | type | default | note |\n|:-------:|:------:|-----------|-------|\n| cwd | string
function | `process.cwd()` | The directory that will be combined with any relative path to form an absolute path. Is ignored for absolute paths. Use to avoid combining `directory` with `path.join()`. |\n| mode | number
function | `stat.mode` of the Vinyl object | The mode used when creating files. If not set and `stat.mode` is missing, the process' mode will be used instead. |\n| dirMode | number
function | | The mode used when creating directories. If not set, the process' mode will be used. |\n| overwrite | boolean
function | true | When true, overwrites existing files with the same path. |\n| append | boolean
function | false | If true, adds contents to the end of the file, instead of replacing existing contents. |\n| sourcemaps | boolean
string
function | false | If true, writes inline sourcemaps to the output file. Specifying a `string` path will write external [sourcemaps][sourcemaps-section] at the given path. |\n| relativeSymlinks | boolean
function | false | When false, any symbolic links created will be absolute.
**Note**: Ignored if a junction is being created, as they must be absolute. |\n| useJunctions | boolean
function | true | This option is only relevant on Windows and ignored elsewhere. When true, creates directory symbolic link as a junction. Detailed in [Symbolic links on Windows][symbolic-links-section] below. |\n\n## Metadata updates\n\nWhenever the `dest()` stream creates a file, the Vinyl object's `mode`, `mtime`, and `atime` are compared to the created file. If they differ, the created file will be updated to reflect the Vinyl object's metadata. If those properties are the same, or gulp doesn't have permissions to make changes, the attempt is skipped silently.\n\nThis functionality is disabled on Windows or other operating systems that don't support Node's `process.getuid()` or `process.geteuid()` methods. This is due to Windows having unexpected results through usage of `fs.fchmod()` and `fs.futimes()`.\n\n**Note**: The `fs.futimes()` method internally converts `mtime` and `atime` timestamps to seconds. This division by 1000 may cause some loss of precision on 32-bit operating systems.\n\n## Sourcemaps\n\nSourcemap support is built directly into `src()` and `dest()`, but it is disabled by default. Enable it to produce inline or external sourcemaps.\n\nInline sourcemaps:\n```js\nconst { src, dest } = require('gulp');\nconst uglify = require('gulp-uglify');\n\nsrc('input/**/*.js', { sourcemaps: true })\n .pipe(uglify())\n .pipe(dest('output/', { sourcemaps: true }));\n```\n\nExternal sourcemaps:\n```js\nconst { src, dest } = require('gulp');\nconst uglify = require('gulp-uglify');\n\nsrc('input/**/*.js', { sourcemaps: true })\n .pipe(uglify())\n .pipe(dest('output/', { sourcemaps: '.' }));\n```\n\n## Symbolic links on Windows\n\nWhen creating symbolic links on Windows, a `type` argument is passed to Node's `fs.symlink()` method which specifies the kind of target being linked. The link type is set to:\n* `'file'` when the target is a regular file\n* `'junction'` when the target is a directory\n* `'dir'` when the target is a directory and the user disables the `useJunctions` option\n\n\nIf you try to create a dangling (pointing to a non-existent target) link, the link type can't be determined automatically. In these cases, behavior will vary depending on whether the dangling link is being created via `symlink()` or via `dest()`.\n\nFor dangling links created via `symlink()`, the incoming Vinyl object represents the target, so its stats will determine the desired link type. If `isDirectory()` returns false then a `'file'` link is created, otherwise a `'junction'` or a `'dir'` link is created depending on the value of the `useJunctions` option.\n\nFor dangling links created via `dest()`, the incoming Vinyl object represents the link - typically loaded from disk via `src(..., { resolveSymlinks: false })`. In this case, the link type can't be reasonably determined and defaults to using `'file'`. This may cause unexpected behavior if you are creating a dangling link to a directory. **Avoid this scenario.**\n\n[sourcemaps-section]: #sourcemaps\n[symbolic-links-section]: #symbolic-links-on-windows\n[options-section]: #options\n[metadata-updates-section]: #metadata-updates\n[vinyl-concepts]: ../api/concepts.md#vinyl\n" }, { "path": "docs/api/last-run.md", "content": "\n\n# lastRun()\n\nRetrieves the last time a task was successfully completed during the current running process. Most useful on subsequent task runs while a watcher is running.\n\nWhen combined with `src()`, enables incremental builds to speed up execution times by skipping files that haven't changed since the last successful task completion.\n\n## Usage\n\n```js\nconst { src, dest, lastRun, watch } = require('gulp');\nconst imagemin = require('gulp-imagemin');\n\nfunction images() {\n return src('src/images/**/*.jpg', { since: lastRun(images) })\n .pipe(imagemin())\n .pipe(dest('build/img/'));\n}\n\nexports.default = function() {\n watch('src/images/**/*.jpg', images);\n};\n```\n\n\n## Signature\n\n```js\nlastRun(task, [precision])\n```\n\n### Parameters\n\n| parameter | type | note |\n|:--------------:|:------:|-------|\n| task
**(required)** | function
string | The task function or the string alias of a registered task. |\n| precision | number | Default: `1000` on Node v0.10, `0` on Node v0.12+. Detailed in [Timestamp precision][timestamp-precision-section] section below. |\n\n### Returns\n\nA timestamp (in milliseconds), matching the last completion time of the task. If the task has not been run or has failed, returns `undefined`.\n\nTo avoid an invalid state being cached, the returned value will be `undefined` if a task errors.\n\n### Errors\n\nWhen called with a value other than a string or function, throws an error with the message, \"Only functions can check lastRun\".\n\nWhen called on a non-extensible function and Node is missing WeakMap, throws an error with the message, \"Only extensible functions can check lastRun\".\n\n## Timestamp precision\n\nWhile there are sensible defaults for the precision of timestamps, they can be rounded using the `precision` parameter. Useful if your file system or Node version has a lossy precision on file time attributes.\n\n* `lastRun(someTask)` returns 1426000001111\n* `lastRun(someTask, 100)` returns 1426000001100\n* `lastRun(someTask, 1000)` returns 1426000001000\n\nA file's [mtime stat][fs-stats-concepts] precision may vary depending on the node version and/or the file system used.\n\n\n| platform | precision |\n|:-----------:|:------------:|\n| Node v0.10 | 1000ms |\n| Node v0.12+ | 1ms |\n| FAT32 file system | 2000ms |\n| HFS+ or Ext3 file systems | 1000ms |\n| NTFS using Node v0.10 | 1s |\n| NTFS using Node 0.12+ | 100ms |\n| Ext4 using Node v0.10 | 1000ms |\n| Ext4 using Node 0.12+ | 1ms |\n\n\n[timestamp-precision-section]: #timestamp-precision\n[fs-stats-concepts]: ../api/concepts.md#file-system-stats\n" }, { "path": "docs/api/parallel.md", "content": "\n\n# parallel()\n\nCombines task functions and/or composed operations into larger operations that will be executed simultaneously. There are no imposed limits on the nesting depth of composed operations using `series()` and `parallel()`.\n\n## Usage\n\n```js\nconst { parallel } = require('gulp');\n\nfunction javascript(cb) {\n // body omitted\n cb();\n}\n\nfunction css(cb) {\n // body omitted\n cb();\n}\n\nexports.build = parallel(javascript, css);\n```\n\n## Signature\n\n```js\nparallel(...tasks)\n```\n\n### Parameters\n\n| parameter | type | note |\n|:--------------:|:------:|-------|\n| tasks
**(required)** | function
string | Any number of task functions can be passed as individual arguments. Strings can be used if you've registered tasks previously, but this is not recommended. |\n\n### Returns\n\nA composed operation to be registered as a task or nested within other `series` and/or `parallel` compositions.\n\nWhen the composed operation is executed, all tasks will be run at maximum concurrency. If an error occurs in one task, other tasks nondeterministically may or may not complete.\n\n### Errors\n\nWhen no tasks are passed, throws an error with the message, \"One or more tasks should be combined using series or parallel\".\n\nWhen invalid tasks or unregistered tasks are passed, throws an error with the message, \"Task never defined\".\n\n## Forward references\n\nA forward reference is when you compose tasks, using string references, that haven't been registered yet. This was a common practice in older versions, but this feature was removed to achieve faster task runtime and promote the use of named functions.\n\nIn newer versions, you'll get an error, with the message \"Task never defined\", if you try to use forward references. You may experience this when trying to use `exports` for task registration _and_ composing tasks by string. In this situation, use named functions instead of string references.\n\nDuring migration, you may need the [forward reference registry][undertaker-forward-reference-external]. This will add an extra closure to every task reference and dramatically slow down your build. **Don't rely on this fix for very long**.\n\n## Avoid duplicating tasks\n\nWhen a composed operation is run, each task will be executed every time it was supplied.\n\nA `clean` task referenced in two different compositions would be run twice and lead to undesired results. Instead, refactor the `clean` task to be specified in the final composition.\n\nIf you have code like this:\n```js\n// This is INCORRECT\nconst { series, parallel } = require('gulp');\n\nconst clean = function(cb) {\n // body omitted\n cb();\n};\n\nconst css = series(clean, function(cb) {\n // body omitted\n cb();\n});\n\nconst javascript = series(clean, function(cb) {\n // body omitted\n cb();\n});\n\nexports.build = parallel(css, javascript);\n```\n\nMigrate to this:\n```js\nconst { series, parallel } = require('gulp');\n\nfunction clean(cb) {\n // body omitted\n cb();\n}\n\nfunction css(cb) {\n // body omitted\n cb();\n}\n\nfunction javascript(cb) {\n // body omitted\n cb();\n}\n\nexports.build = series(clean, parallel(css, javascript));\n```\n\n[undertaker-forward-reference-external]: https://github.com/gulpjs/undertaker-forward-reference\n" }, { "path": "docs/api/registry.md", "content": "\n\n# registry()\n\nAllows custom registries to be plugged into the task system, which can provide shared tasks or augmented functionality.\n\n**Note:** Only tasks registered with `task()` will be provided to the custom registry. The task functions passed directly to `series()` or `parallel()` will not be provided - if you need to customize the registry behavior, compose tasks with string references.\n\nWhen assigning a new registry, each task from the current registry will be transferred and the current registry will be replaced with the new one. This allows for adding multiple custom registries in sequential order.\n\nSee [Creating Custom Registries][creating-custom-registries] for details.\n\n## Usage\n\n```js\nconst { registry, task, series } = require('gulp');\nconst FwdRef = require('undertaker-forward-reference');\n\nregistry(FwdRef());\n\ntask('default', series('forward-ref'));\n\ntask('forward-ref', function(cb) {\n // body omitted\n cb();\n});\n```\n\n## Signature\n\n```js\nregistry([registryInstance])\n```\n\n### Parameters\n\n| parameter | type | note |\n|:--------------:|:-----:|--------|\n| registryInstance | object | An instance - not the class - of a custom registry. |\n\n### Returns\n\nIf a `registryInstance` is passed, nothing will be returned. If no arguments are passed, returns the current registry instance.\n\n### Errors\n\n#### Incorrect parameter\n\nWhen a constructor (instead of an instance) is passed as `registryInstance`, throws an error with the message:\n\n> Custom registries must be instantiated, but it looks like you passed a constructor.\n\n#### Missing `get` method\n\nWhen a registry without a `get` method is passed as `registryInstance`, throws an error with the message:\n\n> Custom registry must have `get` function.\n\n#### Missing `set` method\n\nWhen a registry without a `set` method is passed as `registryInstance`, throws an error with the message:\n\n> Custom registry must have `set` function.\n\n#### Missing `init` method\n\nWhen a registry without an `init` method is passed as `registryInstance`, throws an error with the message:\n\n> Custom registry must have `init` function\"\n\n#### Missing `tasks` method\n\nWhen a registry without a `tasks` method is passed as `registryInstance`, throws an error with the message:\n\n> Custom registry must have `tasks` function.\n\n[creating-custom-registries]: ../advanced/creating-custom-registries.md\n" }, { "path": "docs/api/series.md", "content": "\n\n# series()\n\nCombines task functions and/or composed operations into larger operations that will be executed one after another, in sequential order. There are no imposed limits on the nesting depth of composed operations using `series()` and `parallel()`.\n\n## Usage\n\n```js\nconst { series } = require('gulp');\n\nfunction javascript(cb) {\n // body omitted\n cb();\n}\n\nfunction css(cb) {\n // body omitted\n cb();\n}\n\nexports.build = series(javascript, css);\n```\n\n## Signature\n\n```js\nseries(...tasks)\n```\n\n### Parameters\n\n| parameter | type | note |\n|:--------------:|:------:|-------|\n| tasks
**(required)** | function
string | Any number of task functions can be passed as individual arguments. Strings can be used if you've registered tasks previously, but this is not recommended. |\n\n### Returns\n\nA composed operation to be registered as a task or nested within other `series` and/or `parallel` compositions.\n\nWhen the composed operation is executed, all tasks will be run sequentially. If an error occurs in one task, no subsequent tasks will be run.\n\n### Errors\n\nWhen no tasks are passed, throws an error with the message, \"One or more tasks should be combined using series or parallel\".\n\nWhen invalid tasks or unregistered tasks are passed, throws an error with the message, \"Task never defined\".\n\n## Forward references\n\nA forward reference is when you compose tasks, using string references, that haven't been registered yet. This was a common practice in older versions, but this feature was removed to achieve faster task runtime and promote the use of named functions.\n\nIn newer versions, you'll get an error, with the message \"Task never defined\", if you try to use forward references. You may experience this when trying to use `exports` for your task registration *and* composing tasks by string. In this situation, use named functions instead of string references.\n\nDuring migration, you may need to use the [forward reference registry][undertaker-forward-reference-external]. This will add an extra closure to every task reference and dramatically slow down your build. **Don't rely on this fix for very long**.\n\n## Avoid duplicating tasks\n\nWhen a composed operation is run, each task will be executed every time it was supplied.\n\nA `clean` task referenced in two different compositions would be run twice and lead to undesired results. Instead, refactor the `clean` task to be specified in the final composition.\n\nIf you have code like this:\n```js\n// This is INCORRECT\nconst { series, parallel } = require('gulp');\n\nconst clean = function(cb) {\n // body omitted\n cb();\n};\n\nconst css = series(clean, function(cb) {\n // body omitted\n cb();\n});\n\nconst javascript = series(clean, function(cb) {\n // body omitted\n cb();\n});\n\nexports.build = parallel(css, javascript);\n```\n\nMigrate to this:\n```js\nconst { series, parallel } = require('gulp');\n\nfunction clean(cb) {\n // body omitted\n cb();\n}\n\nfunction css(cb) {\n // body omitted\n cb();\n}\n\nfunction javascript(cb) {\n // body omitted\n cb();\n}\n\nexports.build = series(clean, parallel(css, javascript));\n```\n\n[undertaker-forward-reference-external]: https://github.com/gulpjs/undertaker-forward-reference\n" }, { "path": "docs/api/src.md", "content": "\n\n# src()\n\nCreates a stream for reading [Vinyl][vinyl-concepts] objects from the file system.\n\n**Note:** BOMs (byte order marks) have no purpose in UTF-8 and will be removed from UTF-8 files read by `src()`, unless disabled using the `removeBOM` option.\n\n## Usage\n\n```javascript\nconst { src, dest } = require('gulp');\n\nfunction copy() {\n return src('input/*.js')\n .pipe(dest('output/'));\n}\n\nexports.copy = copy;\n```\n\n\n## Signature\n\n```js\nsrc(globs, [options])\n```\n\n### Parameters\n\n| parameter | type | note |\n|:--------------:|:------:|-------|\n| globs | string
array | [Globs][globs-concepts] to watch on the file system. |\n| options | object | Detailed in [Options][options-section] below. |\n\n### Returns\n\nA stream that can be used at the beginning or in the middle of a pipeline to add files based on the given globs.\n\n### Errors\n\nWhen the `globs` argument can only match one file (such as `foo/bar.js`) and no match is found, throws an error with the message, \"File not found with singular glob\". To suppress this error, set the `allowEmpty` option to `true`.\n\nWhen an invalid glob is given in `globs`, throws an error with the message, \"Invalid glob argument\".\n\n### Options\n\n**For options that accept a function, the passed function will be called with each Vinyl object and must return a value of another listed type.**\n\n\n| name | type | default | note |\n|:--------:|:------:|------------|--------|\n| encoding | string
boolean | \"utf8\" | When false, file contents are treated as binary. When a string, this is used as the text encoding. |\n| buffer | boolean
function | true | When true, file contents are buffered into memory. If false, the Vinyl object's `contents` property will be a paused stream. It may not be possible to buffer the contents of large files.
**Note:** Plugins may not implement support for streaming contents. |\n| read | boolean
function | true | If false, files will be not be read and their Vinyl objects won't be writable to disk via `.dest()`. |\n| since | date
timestamp
function | | When set, only creates Vinyl objects for files modified since the specified time. |\n| removeBOM | boolean
function | true | When true, removes the BOM from UTF-8 encoded files. If false, ignores a BOM. |\n| sourcemaps | boolean
function | false | If true, enables [sourcemaps][sourcemaps-section] support on Vinyl objects created. Loads inline sourcemaps and resolves external sourcemap links. |\n| resolveSymlinks | boolean
function | true | When true, recursively resolves symbolic links to their targets. If false, preserves the symbolic links and sets the Vinyl object's `symlink` property to the original file's path. |\n| cwd | string | `process.cwd()` | The directory that will be combined with any relative path to form an absolute path. Is ignored for absolute paths. Use to avoid combining `globs` with `path.join()`.
_This option is passed directly to [glob-stream][glob-stream-external]._ |\n| base | string | | Explicitly set the `base` property on created Vinyl objects. Detailed in [API Concepts][glob-base-concepts].
_This option is passed directly to [glob-stream][glob-stream-external]._ |\n| cwdbase | boolean | false | If true, `cwd` and `base` options should be aligned.
_This option is passed directly to [glob-stream][glob-stream-external]._ |\n| root | string | | The root path that `globs` are resolved against.
_This option is passed directly to [glob-stream][glob-stream-external]._ |\n| allowEmpty | boolean | false | When false, `globs` which can only match one file (such as `foo/bar.js`) causes an error to be thrown if they don't find a match. If true, suppresses glob failures.
_This option is passed directly to [glob-stream][glob-stream-external]._ |\n| uniqueBy | string
function | `'path'` | Remove duplicates from the stream by comparing the string property name or the result of the function.
**Note:** When using a function, the function receives the streamed data (objects containing `cwd`, `base`, `path` properties). |\n| dot | boolean | false | If true, compare globs against dot files, like `.gitignore`.
_This option is passed directly to [anymatch][anymatch-external]._ |\n| nounique | boolean | false | When false, prevents duplicate files in the result set.
_This option is passed directly to [anymatch][anymatch-external]._ |\n| debug | boolean | false | If true, debugging information will be logged to the command line.
_This option is passed directly to [anymatch][anymatch-external]._ |\n| nobrace | boolean | false | If true, avoids expanding brace sets - e.g. `{a,b}` or `{1..3}`.
_This option is passed directly to [anymatch][anymatch-external]._ |\n| noglobstar | boolean | false | If true, treats double-star glob character as single-star glob character.
_This option is passed directly to [anymatch][anymatch-external]._ |\n| noext | boolean | false | If true, avoids matching [extglob][extglob-docs] patterns - e.g. `+(ab)`.
_This option is passed directly to [anymatch][anymatch-external]._ |\n| nocase | boolean | false | If true, performs a case-insensitive match.
**Note:** On case-insensitive file systems, non-magic patterns will match by default.
_This option is passed directly to [anymatch][anymatch-external]._ |\n| matchBase | boolean | false | If true and globs don't contain any `/` characters, traverses all directories and matches that glob - e.g. `*.js` would be treated as equivalent to `**/*.js`.
_This option is passed directly to [anymatch][anymatch-external]._ |\n| ignore | string
array | | Globs to exclude from matches. This option is combined with negated `globs`.
**Note:** These globs are always matched against dot files, regardless of any other settings.
_This option is passed directly to [anymatch][anymatch-external]._ |\n\n## Sourcemaps\n\nSourcemap support is built directly into `src()` and `dest()`, but is disabled by default. Enable it to produce inline or external sourcemaps.\n\nInline sourcemaps:\n```js\nconst { src, dest } = require('gulp');\nconst uglify = require('gulp-uglify');\n\nsrc('input/**/*.js', { sourcemaps: true })\n .pipe(uglify())\n .pipe(dest('output/', { sourcemaps: true }));\n```\n\nExternal sourcemaps:\n```js\nconst { src, dest } = require('gulp');\nconst uglify = require('gulp-uglify');\n\nsrc('input/**/*.js', { sourcemaps: true })\n .pipe(uglify())\n .pipe(dest('output/', { sourcemaps: '.' }));\n```\n\n[sourcemaps-section]: #sourcemaps\n[options-section]: #options\n[vinyl-concepts]: ../api/concepts.md#vinyl\n[glob-base-concepts]: ../api/concepts.md#glob-base\n[globs-concepts]: ../api/concepts.md#globs\n[extglob-docs]: ../documentation-missing.md\n[anymatch-external]: https://github.com/micromatch/anymatch\n[glob-stream-external]: https://github.com/gulpjs/glob-stream\n" }, { "path": "docs/api/symlink.md", "content": "\n\n# symlink()\n\nCreates a stream for linking [Vinyl][vinyl-concepts] objects to the file system.\n\n## Usage\n\n```js\nconst { src, symlink } = require('gulp');\n\nfunction link() {\n return src('input/*.js')\n .pipe(symlink('output/'));\n}\n\nexports.link = link;\n```\n\n## Signature\n\n```js\nsymlink(directory, [options])\n```\n\n### Parameters\n\n| parameter | type | note |\n|:--------------:|:-----:|--------|\n| directory
**(required)** | string
function | The path of the output directory where symbolic links will be created. If a function is used, the function will be called with each Vinyl object and must return a string directory path. |\n| options | object | Detailed in [Options][options-section] below. |\n\n### Returns\n\nA stream that can be used in the middle or at the end of a pipeline to create symbolic links on the file system.\nWhenever a Vinyl object is passed through the stream, it creates a symbolic link to the original file on the file system at the given directory.\n\nWhenever a symbolic link is created on the file system, the Vinyl object will be modified.\n* The `cwd`, `base`, and `path` properties will be updated to match the created symbolic link.\n* The `stat` property will be updated to match the symbolic link on the file system.\n* The `contents` property will be set to `null`.\n* The `symlink` property will be added or replaced with original path.\n\n**Note:** On Windows, directory links are created using junctions by default. The `useJunctions` option disables this behavior.\n\n\n### Errors\n\nWhen `directory` is an empty string, throws an error with the message, \"Invalid symlink() folder argument. Please specify a non-empty string or a function.\"\n\nWhen `directory` is not a string or function, throws an error with the message, \"Invalid symlink() folder argument. Please specify a non-empty string or a function.\"\n\nWhen `directory` is a function that returns an empty string or `undefined`, emits an error with the message, \"Invalid output folder\".\n\n### Options\n\n**For options that accept a function, the passed function will be called with each Vinyl object and must return a value of another listed type.**\n\n| name | type | default | note |\n|:-------:|:------:|-----------|-------|\n| cwd | string
function | `process.cwd()` |The directory that will be combined with any relative path to form an absolute path. Is ignored for absolute paths. Use to avoid combining `directory` with `path.join()`. |\n| dirMode | number
function | | The mode used when creating directories. If not set, the process' mode will be used. |\n| overwrite | boolean
function | true | When true, overwrites existing files with the same path. |\n| relativeSymlinks | boolean
function | false | When false, any symbolic links created will be absolute.
**Note**: Ignored if a junction is being created, as they must be absolute. |\n| useJunctions | boolean
function | true | This option is only relevant on Windows and ignored elsewhere. When true, creates directory symbolic link as a junction. Detailed in [Symbolic links on Windows][symbolic-links-section] below. |\n\n## Symbolic links on Windows\n\nWhen creating symbolic links on Windows, a `type` argument is passed to Node's `fs.symlink()` method which specifies the type of target being linked. The link type is set to:\n* `'file'` when the target is a regular file\n* `'junction'` when the target is a directory\n* `'dir'` when the target is a directory and the user disables the `useJunctions` option\n\n\nIf you try to create a dangling (pointing to a non-existent target) link, the link type can't be determined automatically. In these cases, behavior will vary depending on whether the dangling link is being created via `symlink()` or via `dest()`.\n\nFor dangling links created via `symlink()`, the incoming Vinyl object represents the target, so its stats will determine the desired link type. If `isDirectory()` returns false then a `'file'` link is created, otherwise a `'junction'` or `'dir'` link is created depending on the value of the `useJunctions` option.\n\nFor dangling links created via `dest()`, the incoming Vinyl object represents the link - typically loaded from disk via `src(..., { resolveSymlinks: false })`. In this case, the link type can't be reasonably determined and defaults to using `'file'`. This may cause unexpected behavior when creating a dangling link to a directory. **Avoid this scenario.**\n\n[options-section]: #options\n[symbolic-links-section]: #symbolic-links-on-windows\n[vinyl-concepts]: ../api/concepts.md#vinyl\n" }, { "path": "docs/api/task.md", "content": "\n\n# task()\n\n**Reminder**: This API isn't the recommended pattern anymore - [export your tasks][creating-tasks-docs].\n\nDefines a task within the task system. The task can then be accessed from the command line and the `series()`, `parallel()`, and `lastRun()` APIs.\n\n## Usage\n\nRegister a named function as a task:\n```js\nconst { task } = require('gulp');\n\nfunction build(cb) {\n // body omitted\n cb();\n}\n\ntask(build);\n```\n\nRegister an anonymous function as a task:\n```js\nconst { task } = require('gulp');\n\ntask('build', function(cb) {\n // body omitted\n cb();\n});\n```\n\nRetrieve a task that has been registered previously:\n```js\nconst { task } = require('gulp');\n\ntask('build', function(cb) {\n // body omitted\n cb();\n});\n\nconst build = task('build');\n```\n\n## Signature\n\n```js\ntask([taskName], taskFunction)\n```\n\n### Parameters\n\nIf the `taskName` is not provided, the task will be referenced by the `name` property of a named function or a user-defined `displayName` property. The `taskName` parameter must be used for anonymous functions missing a `displayName` property.\n\nSince any registered task can be run from the command line, avoid using spaces in task names.\n\n| parameter | type | note |\n|:--------------:|:------:|-------|\n| taskName | string | An alias for the task function within the task system. Not needed when using named functions for `taskFunction`. |\n| taskFunction
**(required)** | function | A [task function][task-concepts] or composed task - generated by `series()` and `parallel()`. Ideally a named function. [Task metadata][task-metadata-section] can be attached to provide extra information to the command line. |\n\n### Returns\n\nWhen registering a task, nothing is returned.\n\nWhen retrieving a task, a wrapped task (not the original function) registered as `taskName` will be returned. The wrapped task has an `unwrap()` method that will return the original function.\n\n### Errors\n\nWhen registering a task where `taskName` is missing and `taskFunction` is anonymous, will throw an error with the message, \"Task name must be specified\".\n\n## Task metadata\n\n| property | type | note |\n|:--------------:|:------:|-------|\n| name | string | A special property of named functions. Used to register the task.
**Note:** [`name`][function-name-external] is not writable; it cannot be set or changed. |\n| displayName | string | When attached to a `taskFunction` creates an alias for the task. If using characters that aren't allowed in function names, use this property. |\n| description | string | When attached to a `taskFunction` provides a description to be printed by the command line when listing tasks. |\n| flags | object | When attached to a `taskFunction` provides flags to be printed by the command line when listing tasks. The keys of the object represent the flags and the values are their descriptions. |\n\n```js\nconst { task } = require('gulp');\n\nconst clean = function(cb) {\n // body omitted\n cb();\n};\nclean.displayName = 'clean:all';\n\ntask(clean);\n\nfunction build(cb) {\n // body omitted\n cb();\n}\nbuild.description = 'Build the project';\nbuild.flags = { '-e': 'An example flag' };\n\ntask(build);\n```\n\n[task-metadata-section]: #task-metadata\n[task-concepts]: ../api/concepts.md#tasks\n[creating-tasks-docs]: ../getting-started/3-creating-tasks.md\n[function-name-external]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/name\n" }, { "path": "docs/api/tree.md", "content": "\n\n# tree()\n\nFetches the current task dependency tree - in the rare case that it is needed.\n\nGenerally, `tree()` won't be used by gulp consumers, but it is exposed so the CLI can show the dependency graph of the tasks defined in a gulpfile.\n\n## Usage\n\nExample gulpfile:\n```js\n\nconst { series, parallel } = require('gulp');\n\nfunction one(cb) {\n // body omitted\n cb();\n}\n\nfunction two(cb) {\n // body omitted\n cb();\n}\n\nfunction three(cb) {\n // body omitted\n cb();\n}\n\nconst four = series(one, two);\n\nconst five = series(four,\n parallel(three, function(cb) {\n // Body omitted\n cb();\n })\n);\n\nmodule.exports = { one, two, three, four, five };\n```\n\nOutput for `tree()`:\n```js\n{\n label: 'Tasks',\n nodes: [ 'one', 'two', 'three', 'four', 'five' ]\n}\n```\n\n\nOutput for `tree({ deep: true })`:\n```js\n{\n label: \"Tasks\",\n nodes: [\n {\n label: \"one\",\n type: \"task\",\n nodes: []\n },\n {\n label: \"two\",\n type: \"task\",\n nodes: []\n },\n {\n label: \"three\",\n type: \"task\",\n nodes: []\n },\n {\n label: \"four\",\n type: \"task\",\n nodes: [\n {\n label: \"\",\n type: \"function\",\n branch: true,\n nodes: [\n {\n label: \"one\",\n type: \"function\",\n nodes: []\n },\n {\n label: \"two\",\n type: \"function\",\n nodes: []\n }\n ]\n }\n ]\n },\n {\n label: \"five\",\n type: \"task\",\n nodes: [\n {\n label: \"\",\n type: \"function\",\n branch: true,\n nodes: [\n {\n label: \"\",\n type: \"function\",\n branch: true,\n nodes: [\n {\n label: \"one\",\n type: \"function\",\n nodes: []\n },\n {\n label: \"two\",\n type: \"function\",\n nodes: []\n }\n ]\n },\n {\n label: \"\",\n type: \"function\",\n branch: true,\n nodes: [\n {\n label: \"three\",\n type: \"function\",\n nodes: []\n },\n {\n label: \"\",\n type: \"function\",\n nodes: []\n }\n ]\n }\n ]\n }\n ]\n }\n ]\n}\n```\n\n## Signature\n\n```js\ntree([options])\n```\n\n### Parameters\n\n| parameter | type | note |\n|:--------------:|------:|--------|\n| options | object | Detailed in [Options][options-section] below. |\n\n### Returns\n\nAn object detailing the tree of registered tasks - containing nested objects with `'label'` and `'nodes'` properties (which is [archy][archy-external] compatible).\n\nEach object may have a `type` property that can be used to determine if the node is a `task` or `function`.\n\nEach object may have a `branch` property that, when `true`, indicates the node was created using `series()` or `parallel()`.\n\n### Options\n\n| name | type | default | note |\n|:-------:|:-------:|------------|--------|\n| deep | boolean | false | If true, the entire tree will be returned. When false, only top level tasks will be returned. |\n\n[options-section]: #options\n[archy-external]: https://www.npmjs.com/package/archy\n" }, { "path": "docs/api/vinyl-iscustomprop.md", "content": "\n\n# Vinyl.isCustomProp()\n\nDetermines if a property is internally managed by Vinyl. Used by Vinyl when setting values inside the constructor or when copying properties in the `clone()` instance method.\n\nThis method is useful when extending the Vinyl class. Detailed in [Extending Vinyl][extending-vinyl-section] below.\n\n## Usage\n\n```js\nconst Vinyl = require('vinyl');\n\nVinyl.isCustomProp('sourceMap') === true;\nVinyl.isCustomProp('path') === false;\n```\n\n## Signature\n\n```js\nVinyl.isCustomProp(property)\n```\n\n### Parameters\n\n| parameter | type | note |\n|:--------------:|:------:|-------|\n| property | string | The property name to check. |\n\n### Returns\n\nTrue if the property is not internally managed.\n\n## Extending Vinyl\n\nWhen custom properties are managed internally, the static `isCustomProp` method must be extended and return false when one of the custom properties is queried.\n\n```js\nconst Vinyl = require('vinyl');\n\nconst builtInProps = ['foo', '_foo'];\n\nclass SuperFile extends Vinyl {\n constructor(options) {\n super(options);\n this._foo = 'example internal read-only value';\n }\n\n get foo() {\n return this._foo;\n }\n\n static isCustomProp(name) {\n return super.isCustomProp(name) && builtInProps.indexOf(name) === -1;\n }\n}\n```\n\nIn the example above, `foo` and `_foo` will not be assigned to the new object when cloning or passed in `options` to `new SuperFile(options)`.\n\nIf your custom properties or logic require special handling during cloning, override the `clone` method while extending Vinyl.\n\n[extending-vinyl-section]: #extending-vinyl\n" }, { "path": "docs/api/vinyl-isvinyl.md", "content": "\n\n# Vinyl.isVinyl()\n\nDetermines if an object is a Vinyl instance. Use this method instead of `instanceof`.\n\n**Note**: This method uses an internal property that some older versions of Vinyl didn't expose resulting in a false negative if using an outdated version.\n\n## Usage\n\n```js\nconst Vinyl = require('vinyl');\n\nconst file = new Vinyl();\nconst notAFile = {};\n\nVinyl.isVinyl(file) === true;\nVinyl.isVinyl(notAFile) === false;\n```\n\n## Signature\n\n```js\nVinyl.isVinyl(file);\n```\n\n### Parameters\n\n| parameter | type | note |\n|:--------------:|:------:|-------|\n| file | object | The object to check. |\n\n### Returns\n\nTrue if the `file` object is a Vinyl instance.\n\n" }, { "path": "docs/api/vinyl.md", "content": "\n\n# Vinyl\n\nA virtual file format. When a file is read by `src()`, a Vinyl object is generated to represent the file - including the path, contents, and other metadata.\n\nVinyl objects can have transformations applied using [plugins][using-plugins-docs]. They may also be persisted to the file system using `dest()`.\n\nWhen creating your own Vinyl objects - instead of generating with `src()` - use the external `vinyl` module, as shown in Usage below.\n\n## Usage\n\n```js\nconst Vinyl = require('vinyl');\n\nconst file = new Vinyl({\n cwd: '/',\n base: '/test/',\n path: '/test/file.js',\n contents: new Buffer('var x = 123')\n});\n\nfile.relative === 'file.js';\n\nfile.dirname === '/test';\nfile.dirname = '/specs';\nfile.path === '/specs/file.js';\n\nfile.basename === 'file.js';\nfile.basename = 'file.txt';\nfile.path === '/specs/file.txt';\n\nfile.stem === 'file';\nfile.stem = 'foo';\nfile.path === '/specs/foo.txt';\nfile.extname === '.txt';\nfile.extname = '.js';\nfile.path === '/specs/foo.js';\n```\n\n## Signature\n\n```js\nnew Vinyl([options])\n```\n\n### Parameters\n\n| parameter | type | note |\n|:--------------:|:------:|-------|\n| options | object | Detailed in [Options][options-section] below. |\n\n### Returns\n\nAn instance of the Vinyl class representing a single virtual file, detailed in [Vinyl instance][vinyl-instance-section] below.\n\n### Errors\n\nWhen any passed options don't conform to the [instance property definitions][instance-properties-section] (like if `path` is set to a number) throws as defined in the table.\n\n### Options\n\n| name | type | default | note |\n|:-------:|:------:|-----------|--------|\n| cwd | string | `process.cwd()` | The directory from which relative paths will be derived. Will be [normalized][normalization-and-concatenation-section] and have trailing separators removed. |\n| base | string | | Used to calculate the `relative` instance property. Falls back to the value of `cwd` if not set. Typically set to the [glob base][glob-base-concepts]. Will be [normalized][normalization-and-concatenation-section] and have trailing separators removed.|\n| path | string | | The full, absolute file path. Will be [normalized][normalization-and-concatenation-section] and have trailing separators removed. |\n| history | array | `[ ]` | An array of paths to pre-populate the `history` of a Vinyl instance. Usually comes from deriving a new Vinyl object from a previous Vinyl object. If `path` and `history` are both passed, `path` is appended to `history`. Each item will be [normalized][normalization-and-concatenation-section] and have trailing separators removed. |\n| stat | object | | An instance of `fs.Stats`, usually the result of calling `fs.stat()` on a file. Used to determine if a Vinyl object represents a directory or symbolic link. |\n| contents | ReadableStream
Buffer
`null` | `null` | The contents of the file. If `contents` is a ReadableStream, it is wrapped in a [cloneable-readable][cloneable-readable-external] stream. |\n\nAny other properties on `options` will be directly assigned to the Vinyl instance.\n\n```js\nconst Vinyl = require('vinyl');\n\nconst file = new Vinyl({ foo: 'bar' });\nfile.foo === 'bar';\n```\n\n## Vinyl instance\n\nEach instance of a Vinyl object will have properties and methods to access and/or modify information about the virtual file.\n\n### Instance properties\n\nAll internally managed paths - any instance property except `contents` and `stat` - are normalized and have trailing separators removed. See [Normalization and concatenation][normalization-and-concatenation-section] for more information.\n\n| property | type | description | throws |\n|:-----------:|:------:|----------------|----------|\n| contents | ReadableStream
Buffer
`null` | Gets and sets the contents of the virtual file. If set to a ReadableStream, it is wrapped in a [cloneable-readable][cloneable-readable-external] stream. | If set to any value other than a ReadableStream, a Buffer, or `null`. |\n| stat | object | Gets and sets an instance of [`fs.Stats`][fs-stats-concepts]. Used when determining if a Vinyl object represents a directory or symbolic link. | |\n| cwd | string | Gets and sets the current working directory. Used for deriving relative paths. | If set to an empty string or any non-string value. |\n| base | string | Gets and sets the base directory. Used to calculate the `relative` instance property. On a Vinyl object generated by `src()` will be set to the [glob base][glob-base-concepts]. If set to `null` or `undefined`, falls back to the value of the `cwd` instance property. | If set to an empty string or any non-string value (except `null` or `undefined`). |\n| path | string | Gets and sets the full, absolute file path. Setting to a value different from the current `path` appends the new path to the `history` instance property. | If set to any non-string value. |\n| history | array | Array of all `path` values the Vinyl object has been assigned. The first element is the original path and the last element is the current path. This property and its elements should be treated as read-only and only altered indirectly by setting the `path` instance property. | |\n| relative | string | Gets the relative path segment between the `base` and the `path` instance properties. | If set to any value. If accessed when `path` is not available. |\n| dirname | string | Gets and sets the directory of the `path` instance property. | If accessed when `path` is not available. |\n| stem | string | Gets and sets the stem (filename without extension) of the `path` instance property. | If accessed when `path` is not available. |\n| extname | string | Gets and sets the extension of the `path` instance property. | If accessed when `path` is not available. |\n| basename | string | Gets and sets the filename (`stem + extname`) of the `path` instance property. | If accessed when `path` is not available. |\n| symlink | string | Gets and sets the reference path of a symbolic link. | If set to any non-string value. |\n\n### Instance methods\n\n| method | return type | returns |\n|:----------:|:--------------:|--------|\n| `isBuffer()` | boolean | If the `contents` instance property is a Buffer, returns true. |\n| `isStream()` | boolean | If the `contents` instance property is a Stream, returns true. |\n| `isNull()` | boolean | If the `contents` instance property is `null`, returns true. |\n| `isDirectory()` | boolean | If the instance represents a directory, returns true. An instance is considered a directory when `isNull()` returns true, the `stat` instance property is an object, and `stat.isDirectory()` returns true. This assumes a Vinyl object was constructed with a valid (or properly mocked) `fs.Stats` object. |\n| `isSymbolic()` | boolean | If the instance represents a symbolic link, returns true. An instance is considered symbolic when `isNull()` returns true, the `stat` instance property is an object, and `stat.isSymbolicLink()` returns true. This assumes a Vinyl object was constructed with a valid (or properly mocked) `fs.Stats` object. |\n| `clone([options])` | object | A new Vinyl object with all properties cloned. By default custom properties are deep cloned. If the `deep` option is false, custom attributes will be shallow cloned. If the `contents` option is false and the `contents` instance property is a Buffer, the Buffer will be reused instead of cloned. |\n| `inspect()` | string | Returns a formatted interpretation of the Vinyl object. Automatically called by Node's console.log. |\n\n## Normalization and concatenation\n\nAll path properties are normalized by their setters. Concatenate paths with `/`, instead of using `path.join()`, and normalization will occur properly on all platforms. Never concatenate with `\\` - it is a valid filename character on POSIX system.\n\n```js\nconst file = new File();\nfile.path = '/' + 'test' + '/' + 'foo.bar';\n\nconsole.log(file.path);\n// posix => /test/foo.bar\n// win32 => \\\\test\\\\foo.bar\n```\n\n[options-section]: #options\n[vinyl-instance-section]: #vinyl-instance\n[instance-properties-section]: #instance-properties\n[normalization-and-concatenation-section]: #normalization-and-concatenation\n[glob-base-concepts]: ../api/concepts.md#glob-base\n[fs-stats-concepts]: ../api/concepts.md#file-system-stats\n[using-plugins-docs]: ../getting-started/7-using-plugins.md\n[cloneable-readable-external]: https://github.com/mcollina/cloneable-readable\n" }, { "path": "docs/api/watch.md", "content": "\n\n# watch()\n\nAllows watching globs and running a task when a change occurs. Tasks are handled uniformly with the rest of the task system.\n\n## Usage\n\n```js\nconst { watch } = require('gulp');\n\nwatch(['input/*.js', '!input/something.js'], function(cb) {\n // body omitted\n cb();\n});\n```\n\n## Signature\n\n```js\nwatch(globs, [options], [task])\n```\n\n### Parameters\n\n| parameter | type | note |\n|:--------------:|:-----:|--------|\n| globs
**(required)** | string
array | [Globs][globs-concepts] to watch on the file system. |\n| options | object | Detailed in [Options][options-section] below. |\n| task | function
string | A [task function][tasks-concepts] or composed task - generated by `series()` and `parallel()`. |\n\n### Returns\n\nAn instance of [chokidar][chokidar-instance-section] for fine-grained control over your watch setup.\n\n### Errors\n\nWhen a non-string or array with any non-strings is passed as `globs`, throws an error with the message, \"Non-string provided as watch path\".\n\nWhen a string or array is passed as `task`, throws an error with the message, \"watch task has to be a function (optionally generated by using gulp.parallel or gulp.series)\".\n\n### Options\n\n| name | type | default | note |\n|:-------:|:------:|-----------|--------|\n| ignoreInitial | boolean | true | If false, the task is called during instantiation as file paths are discovered. Use to trigger the task during startup.
**Note:** This option is passed to [chokidar][chokidar-external] but is defaulted to `true` instead of `false`. |\n| delay | number | 200 | The millisecond delay between a file change and task execution. Allows for waiting on many changes before executing a task, e.g. find-and-replace on many files. |\n| queue | boolean | true | When true and the task is already running, any file changes will queue a single task execution. Keeps long running tasks from overlapping. |\n| events | string
array | [ 'add',
'change',
'unlink' ] | The events being watched to trigger task execution. Can be `'add'`, `'addDir'`, `'change'`, `'unlink'`, `'unlinkDir'`, `'ready'`, and/or `'error'`. Additionally `'all'` is available, which represents all events other than `'ready'` and `'error'`.
_This option is passed directly to [chokidar][chokidar-external]._ |\n| persistent | boolean | true | If false, the watcher will not keep the Node process running. Disabling this option is not recommended.
_This option is passed directly to [chokidar][chokidar-external]._ |\n| ignored | array
string
RegExp
function | | Defines globs to be ignored. If a function is provided, it will be called twice per path - once with just the path, then with the path and the `fs.Stats` object of that file.
_This option is passed directly to [chokidar][chokidar-external]._ |\n| followSymlinks | boolean | true | When true, changes to both symbolic links and the linked files trigger events. If false, only changes to the symbolic links trigger events.
_This option is passed directly to [chokidar][chokidar-external]._ |\n| cwd | string | | The directory that will be combined with any relative path to form an absolute path. Is ignored for absolute paths. Use to avoid combining `globs` with `path.join()`.
_This option is passed directly to [chokidar][chokidar-external]._ |\n| disableGlobbing | boolean | false | If true, all `globs` are treated as literal path names, even if they have special characters.
_This option is passed directly to [chokidar][chokidar-external]._ |\n| usePolling | boolean | false | When false, the watcher will use `fs.watch()` (or [fsevents][fsevents-external] on Mac) for watching. If true, use `fs.watchFile()` polling instead - needed for successfully watching files over a network or other non-standard situations. Overrides the `useFsEvents` default.
_This option is passed directly to [chokidar][chokidar-external]._ |\n| interval | number | 100 | Combine with `usePolling: true`. Interval of file system polling.
_This option is passed directly to [chokidar][chokidar-external]._ |\n| binaryInterval | number | 300 | Combine with `usePolling: true`. Interval of file system polling for binary files.
_This option is passed directly to [chokidar][chokidar-external]._ |\n| useFsEvents | boolean | true | When true, uses fsevents for watching if available. If explicitly set to true, supersedes the `usePolling` option. If set to false, automatically sets `usePolling` to true.
_This option is passed directly to [chokidar][chokidar-external]._ |\n| alwaysStat | boolean | false | If true, always calls `fs.stat()` on changed files - will slow down file watcher. The `fs.Stat` object is only available if you are using the chokidar instance directly.
_This option is passed directly to [chokidar][chokidar-external]._ |\n| depth | number | | Indicates how many nested levels of directories will be watched.
_This option is passed directly to [chokidar][chokidar-external]._ |\n| awaitWriteFinish | boolean | false | Do not use this option, use `delay` instead.
_This option is passed directly to [chokidar][chokidar-external]._ |\n| ignorePermissionErrors | boolean | false | Set to true to watch files that don't have read permissions. Then, if watching fails due to EPERM or EACCES errors, they will be skipped silently.
_This option is passed directly to [chokidar][chokidar-external]._ |\n| atomic | number | 100 | Only active if `useFsEvents` and `usePolling` are false. Automatically filters out artifacts that occur from \"atomic writes\" by some editors. If a file is re-added within the specified milliseconds of being deleted, a change event - instead of unlink then add - will be emitted.
_This option is passed directly to [chokidar][chokidar-external]._ |\n\n## Chokidar instance\n\nThe `watch()` method returns the underlying instance of [chokidar][chokidar-external], providing fine-grained control over your watch setup. Most commonly used to register individual event handlers that provide the `path` or `stats` of the changed files.\n\n**When using the chokidar instance directly, you will not have access to the task system integrations, including async completion, queueing, and delay.**\n\n```js\nconst { watch } = require('gulp');\n\nconst watcher = watch(['input/*.js']);\n\nwatcher.on('change', function(path, stats) {\n console.log(`File ${path} was changed`);\n});\n\nwatcher.on('add', function(path, stats) {\n console.log(`File ${path} was added`);\n});\n\nwatcher.on('unlink', function(path, stats) {\n console.log(`File ${path} was removed`);\n});\n\nwatcher.close();\n```\n\n\n`watcher.on(eventName, eventHandler)`\n\nRegisters `eventHandler` functions to be called when the specified event occurs.\n\n| parameter | type | note |\n|:--------------:|:-----:|--------|\n| eventName | string | The events that may be watched are `'add'`, `'addDir'`, `'change'`, `'unlink'`, `'unlinkDir'`, `'ready'`, `'error'`, or `'all'`. |\n| eventHandler | function | Function to be called when the specified event occurs. Arguments detailed in the table below. |\n\n| argument | type | note |\n|:-------------:|:-----:|--------|\n| path | string | The path of the file that changed. If the `cwd` option was set, the path will be made relative by removing the `cwd`. |\n| stats | object | An [fs.Stat][fs-stats-concepts] object, but could be `undefined`. If the `alwaysStat` option was set to `true`, `stats` will always be provided. |\n\n`watcher.close()`\n\nShuts down the file watcher. Once shut down, no more events will be emitted.\n\n`watcher.add(globs)`\n\nAdds additional globs to an already-running watcher instance.\n\n| parameter | type | note |\n|:-------------:|:-----:|--------|\n| globs | string
array | The additional globs to be watched. |\n\n`watcher.unwatch(globs)`\n\nRemoves globs that are being watched, while the watcher continues with the remaining paths.\n\n| parameter | type | note |\n|:-------------:|:-----:|--------|\n| globs | string
array | The globs to be removed. |\n\n[chokidar-instance-section]: #chokidar-instance\n[options-section]: #options\n[tasks-concepts]: ../api/concepts.md#tasks\n[globs-concepts]: ../api/concepts.md#globs\n[fs-stats-concepts]: ../api/concepts.md#file-system-stats\n[chokidar-external]: https://github.com/paulmillr/chokidar\n[fsevents-external]: https://github.com/strongloop/fsevents\n" }, { "path": "docs/documentation-missing.md", "content": "\n\n# Excuse our dust!\n\nWe're in the process of rewriting **all** our documentation and some of the links we've added to completed docs haven't been written yet. You've likely clicked on one of those to end up here. We're sorry about that but please check back later on the topic you're interested in. If you want to help out, we'll happily accept a Pull Request for this missing documentation.\n\n-The Gulp Team\n" }, { "path": "docs/getting-started/1-quick-start.md", "content": "\n\n# Quick Start\n\nIf you've previously installed gulp globally, run `npm rm --global gulp` before following these instructions. For more information, read this [Sip][sip-article].\n\n## Check for node, npm, and npx\n```sh\nnode --version\n```\n![Output: v8.11.1][img-node-version-command]\n```sh\nnpm --version\n```\n![Output: 5.6.0][img-npm-version-command]\n```sh\nnpx --version\n```\n![Output: 9.7.1][img-npx-version-command]\n\nIf they are not installed, follow the instructions [here][node-install].\n\n## Install the gulp command line utility\n```sh\nnpm install --global gulp-cli\n```\n\n\n## Create a project directory and navigate into it\n```sh\nnpx mkdirp my-project\n```\n```sh\ncd my-project\n```\n\n## Create a package.json file in your project directory\n```sh\nnpm init\n```\n\nThis will guide you through giving your project a name, version, description, etc.\n\n## Install the gulp package in your devDependencies\n```sh\nnpm install --save-dev gulp\n```\n\n## Verify your gulp versions\n\n```sh\ngulp --version\n```\n\nEnsure the output matches the screenshot below or you might need to restart the steps in this guide.\n\n![Output: CLI version 2.0.1 & Local version 4.0.0][img-gulp-version-command]\n\n## Create a gulpfile\nUsing your text editor, create a file named gulpfile.js in your project root with these contents:\n```js\nfunction defaultTask(cb) {\n // place code for your default task here\n cb();\n}\n\nexports.default = defaultTask\n```\n\n## Test it\nRun the gulp command in your project directory:\n```sh\ngulp\n```\nTo run multiple tasks, you can use `gulp `.\n\n## Result\nThe default task will run and do nothing.\n![Output: Starting default & Finished default][img-gulp-command]\n\n[sip-article]: https://medium.com/gulpjs/gulp-sips-command-line-interface-e53411d4467\n[node-install]: https://nodejs.org/en/\n[img-node-version-command]: https://gulpjs.com/img/docs-node-version-command.png\n[img-npm-version-command]: https://gulpjs.com/img/docs-npm-version-command.png\n[img-npx-version-command]: https://gulpjs.com/img/docs-npx-version-command.png\n[img-gulp-version-command]: https://gulpjs.com/img/docs-gulp-version-command.png\n[img-gulp-command]: https://gulpjs.com/img/docs-gulp-command.png\n" }, { "path": "docs/getting-started/2-javascript-and-gulpfiles.md", "content": "\n\n# JavaScript and Gulpfiles\n\nGulp allows you to use existing JavaScript knowledge to write gulpfiles or to use your experience with gulpfiles to write plain JavaScript. Although a few utilities are provided to simplify working with the filesystem and command line, everything else you write is pure JavaScript.\n\n## Gulpfile explained\n\nA gulpfile is a file in your project directory titled `gulpfile.js` (or capitalized as `Gulpfile.js`, like Makefile), that automatically loads when you run the `gulp` command. Within this file, you'll often see gulp APIs, like `src()`, `dest()`, `series()`, or `parallel()` but any vanilla JavaScript or Node modules can be used. Any exported functions will be registered into gulp's task system.\n\n## Transpilation\n\nYou can write a gulpfile using a language that requires transpilation, like TypeScript or Babel, by changing the extension on your `gulpfile.js` to indicate the language and install the matching transpiler module.\n\n* For TypeScript, rename to `gulpfile.ts` and install the [ts-node][ts-node-module] module.\n* For Babel, rename to `gulpfile.babel.js` and install the [@babel/register][babel-register-module] module.\n\n__Most new versions of node support most features that TypeScript or Babel provide, except the `import`/`export` syntax. When only that syntax is desired, rename to `gulpfile.esm.js` and install the [esm][esm-module] module.__\n\nFor a more advanced dive into this topic and the full list of supported extensions, see our [gulpfile transpilation][gulpfile-transpilation-advanced] documentation.\n\n## Splitting a gulpfile\n\nMany users start by adding all logic to a gulpfile. If it ever grows too big, it can be refactored into separate files.\n\nEach task can be split into its own file, then imported into your gulpfile for composition. Not only does this keep things organized, but it allows you to test each task independently or vary composition based on conditions.\n\nNode's module resolution allows you to replace your `gulpfile.js` file with a directory named `gulpfile.js` that contains an `index.js` file which is treated as a `gulpfile.js`. This directory could then contain your individual modules for tasks. If you are using a transpiler, name the folder and file accordingly.\n\n[gulpfile-transpilation-advanced]: ../documentation-missing.md\n[ts-node-module]: https://www.npmjs.com/package/ts-node\n[babel-register-module]: https://www.npmjs.com/package/@babel/register\n[esm-module]: https://www.npmjs.com/package/esm\n" }, { "path": "docs/getting-started/3-creating-tasks.md", "content": "\n\n# Creating Tasks\n\nEach gulp task is an asynchronous JavaScript function - a function that accepts an error-first callback or returns a stream, promise, event emitter, child process, or observable ([more on that later][async-completion-docs]). Due to some platform limitations, synchronous tasks aren't supported, though there is a pretty nifty [alternative][using-async-await-docs].\n\n## Exporting\n\nTasks can be considered **public** or **private**.\n\n* **Public tasks** are exported from your gulpfile, which allows them to be run by the `gulp` command.\n* **Private tasks** are made to be used internally, usually used as part of `series()` or `parallel()` composition.\n\nA private task looks and acts like any other task, but an end-user can't ever execute it independently. To register a task publicly, export it from your gulpfile.\n\n```js\nconst { series } = require('gulp');\n\n// The `clean` function is not exported so it can be considered a private task.\n// It can still be used within the `series()` composition.\nfunction clean(cb) {\n // body omitted\n cb();\n}\n\n// The `build` function is exported so it is public and can be run with the `gulp` command.\n// It can also be used within the `series()` composition.\nfunction build(cb) {\n // body omitted\n cb();\n}\n\nexports.build = build;\nexports.default = series(clean, build);\n```\n\n![ALT TEXT MISSING][img-gulp-tasks-command]\n\nIn the past, `task()` was used to register your functions as tasks. While that API is still available, exporting should be the primary registration mechanism, except in edge cases where exports won't work.\n\n## Compose tasks\n\nGulp provides two powerful composition methods, `series()` and `parallel()`, allowing individual tasks to be composed into larger operations. Both methods accept any number of task functions or composed operations. `series()` and `parallel()` can be nested within themselves or each other to any depth.\n\nTo have your tasks execute in order, use the `series()` method.\n```js\nconst { series } = require('gulp');\n\nfunction transpile(cb) {\n // body omitted\n cb();\n}\n\nfunction bundle(cb) {\n // body omitted\n cb();\n}\n\nexports.build = series(transpile, bundle);\n```\n\nFor tasks to run at maximum concurrency, combine them with the `parallel()` method.\n```js\nconst { parallel } = require('gulp');\n\nfunction javascript(cb) {\n // body omitted\n cb();\n}\n\nfunction css(cb) {\n // body omitted\n cb();\n}\n\nexports.build = parallel(javascript, css);\n```\n\nTasks are composed immediately when either `series()` or `parallel()` is called. This allows variation in the composition instead of conditional behavior inside individual tasks.\n\n```js\nconst { series } = require('gulp');\n\nfunction minify(cb) {\n // body omitted\n cb();\n}\n\n\nfunction transpile(cb) {\n // body omitted\n cb();\n}\n\nfunction livereload(cb) {\n // body omitted\n cb();\n}\n\nif (process.env.NODE_ENV === 'production') {\n exports.build = series(transpile, minify);\n} else {\n exports.build = series(transpile, livereload);\n}\n```\n\n`series()` and `parallel()` can be nested to any arbitrary depth.\n\n```js\nconst { series, parallel } = require('gulp');\n\nfunction clean(cb) {\n // body omitted\n cb();\n}\n\nfunction cssTranspile(cb) {\n // body omitted\n cb();\n}\n\nfunction cssMinify(cb) {\n // body omitted\n cb();\n}\n\nfunction jsTranspile(cb) {\n // body omitted\n cb();\n}\n\nfunction jsBundle(cb) {\n // body omitted\n cb();\n}\n\nfunction jsMinify(cb) {\n // body omitted\n cb();\n}\n\nfunction publish(cb) {\n // body omitted\n cb();\n}\n\nexports.build = series(\n clean,\n parallel(\n cssTranspile,\n series(jsTranspile, jsBundle)\n ),\n parallel(cssMinify, jsMinify),\n publish\n);\n```\n\nWhen a composed operation is run, each task will be executed every time it was referenced. For example, a `clean` task referenced before two different tasks would be run twice and lead to undesired results. Instead, refactor the `clean` task to be specified in the final composition.\n\nIf you have code like this:\n\n```js\n// This is INCORRECT\nconst { series, parallel } = require('gulp');\n\nconst clean = function(cb) {\n // body omitted\n cb();\n};\n\nconst css = series(clean, function(cb) {\n // body omitted\n cb();\n});\n\nconst javascript = series(clean, function(cb) {\n // body omitted\n cb();\n});\n\nexports.build = parallel(css, javascript);\n```\n\nMigrate to this:\n\n```js\nconst { series, parallel } = require('gulp');\n\nfunction clean(cb) {\n // body omitted\n cb();\n}\n\nfunction css(cb) {\n // body omitted\n cb();\n}\n\nfunction javascript(cb) {\n // body omitted\n cb();\n}\n\nexports.build = series(clean, parallel(css, javascript));\n```\n\n[async-completion-docs]: ../getting-started/4-async-completion.md\n[using-async-await-docs]: ../getting-started/4-async-completion.md#using-async-await\n[img-gulp-tasks-command]: https://gulpjs.com/img/docs-gulp-tasks-command.png\n[async-once]: https://github.com/gulpjs/async-once\n" }, { "path": "docs/getting-started/4-async-completion.md", "content": "\n\n# Async Completion\n\nNode libraries handle asynchronicity in a variety of ways. The most common pattern is [error-first callbacks][node-api-error-first-callbacks], but you might also encounter [streams][stream-docs], [promises][promise-docs], [event emitters][event-emitter-docs], [child processes][child-process-docs], or [observables][observable-docs]. Gulp tasks normalize all these types of asynchronicity.\n\n## Signal task completion\n\nWhen a stream, promise, event emitter, child process, or observable is returned from a task, the success or error informs gulp whether to continue or end. If a task errors, gulp will end immediately and show that error.\n\nWhen composing tasks with `series()`, an error will end the composition and no further tasks will be executed. When composing tasks with `parallel()`, an error will end the composition but the other parallel tasks may or may not complete.\n\n### Returning a stream\n\n```js\nconst { src, dest } = require('gulp');\n\nfunction streamTask() {\n return src('*.js')\n .pipe(dest('output'));\n}\n\nexports.default = streamTask;\n```\n\n### Returning a promise\n\n```js\nfunction promiseTask() {\n return Promise.resolve('the value is ignored');\n}\n\nexports.default = promiseTask;\n```\n\n### Returning an event emitter\n\n```js\nconst { EventEmitter } = require('events');\n\nfunction eventEmitterTask() {\n const emitter = new EventEmitter();\n // Emit has to happen async otherwise gulp isn't listening yet\n setTimeout(() => emitter.emit('finish'), 250);\n return emitter;\n}\n\nexports.default = eventEmitterTask;\n```\n\n### Returning a child process\n\n```js\nconst { exec } = require('child_process');\n\nfunction childProcessTask() {\n return exec('date');\n}\n\nexports.default = childProcessTask;\n```\n\n### Returning an observable\n\n```js\nconst { of } = require('rxjs');\n\nfunction observableTask() {\n return of(1, 2, 3);\n}\n\nexports.default = observableTask;\n```\n\n### Using an error-first callback\n\nIf nothing is returned from your task, you must use the error-first callback to signal completion. The callback will be passed to your task as the only argument - named `cb()` in the examples below.\n\n```js\nfunction callbackTask(cb) {\n // `cb()` should be called by some async work\n cb();\n}\n\nexports.default = callbackTask;\n```\n\nTo indicate to gulp that an error occurred in a task using an error-first callback, call it with an `Error` as the only argument.\n\n```js\nfunction callbackError(cb) {\n // `cb()` should be called by some async work\n cb(new Error('kaboom'));\n}\n\nexports.default = callbackError;\n```\n\nHowever, you'll often pass this callback to another API instead of calling it yourself.\n\n```js\nconst fs = require('fs');\n\nfunction passingCallback(cb) {\n fs.access('gulpfile.js', cb);\n}\n\nexports.default = passingCallback;\n```\n\n## No synchronous tasks\n\nSynchronous tasks are no longer supported. They often led to subtle mistakes that were hard to debug, like forgetting to return your streams from a task.\n\nWhen you see the _\"Did you forget to signal async completion?\"_ warning, none of the techniques mentioned above were used. You'll need to use the error-first callback or return a stream, promise, event emitter, child process, or observable to resolve the issue.\n\n## Using async/await\n\nWhen not using any of the previous options, you can define your task as an [`async` function][async-await-docs], which wraps your task in a promise. This allows you to work with promises synchronously using `await` and use other synchronous code.\n\n```js\nconst fs = require('fs');\n\nasync function asyncAwaitTask() {\n const { version } = JSON.parse(fs.readFileSync('package.json', 'utf8'));\n console.log(version);\n await Promise.resolve('some result');\n}\n\nexports.default = asyncAwaitTask;\n```\n\n[node-api-error-first-callbacks]: https://nodejs.org/api/errors.html#errors_error_first_callbacks\n[stream-docs]: https://nodejs.org/api/stream.html#stream_stream\n[promise-docs]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises\n[event-emitter-docs]: https://nodejs.org/api/events.html#events_events\n[child-process-docs]: https://nodejs.org/api/child_process.html#child_process_child_process\n[observable-docs]: https://github.com/tc39/proposal-observable/blob/master/README.md\n[async-await-docs]: https://developers.google.com/web/fundamentals/primers/async-functions\n" }, { "path": "docs/getting-started/5-working-with-files.md", "content": "\n\n# Working with Files\n\nThe `src()` and `dest()` methods are exposed by gulp to interact with files on your computer.\n\n`src()` is given a [glob][explaining-globs-docs] to read from the file system and produces a [Node stream][node-streams-docs]. It locates all matching files and reads them into memory to pass through the stream.\n\nThe stream produced by `src()` should be returned from a task to signal async completion, as mentioned in [Creating Tasks][creating-tasks-docs].\n\n```js\nconst { src, dest } = require('gulp');\n\nexports.default = function() {\n return src('src/*.js')\n .pipe(dest('output/'));\n}\n```\n\nThe main API of a stream is the `.pipe()` method for chaining Transform or Writable streams.\n\n```js\nconst { src, dest } = require('gulp');\nconst babel = require('gulp-babel');\n\nexports.default = function() {\n return src('src/*.js')\n .pipe(babel())\n .pipe(dest('output/'));\n}\n```\n\n`dest()` is given an output directory string and also produces a [Node stream][node-streams-docs] which is generally used as a terminator stream. When it receives a file passed through the pipeline, it writes the contents and other details out to the filesystem at a given directory. The `symlink()` method is also available and operates like `dest()`, but creates links instead of files (see [`symlink()`][symlink-api-docs] for details).\n\nMost often plugins will be placed between `src()` and `dest()` using the `.pipe()` method and will transform the files within the stream.\n\n## Adding files to the stream\n\n`src()` can also be placed in the middle of a pipeline to add files to the stream based on the given globs. The additional files will only be available to transformations later in the stream. If [globs overlap][overlapping-globs-docs], the files will be added again.\n\nThis can be useful for transpiling some files before adding plain JavaScript files to the pipeline and uglifying everything.\n\n```js\nconst { src, dest } = require('gulp');\nconst babel = require('gulp-babel');\nconst uglify = require('gulp-uglify');\n\nexports.default = function() {\n return src('src/*.js')\n .pipe(babel())\n .pipe(src('vendor/*.js'))\n .pipe(uglify())\n .pipe(dest('output/'));\n}\n```\n\n## Output in phases\n\n`dest()` can be used in the middle of a pipeline to write intermediate states to the filesystem. When a file is received, the current state is written out to the filesystem, the path is updated to represent the new location of the output file, then that file continues down the pipeline.\n\nThis feature can be useful to create unminified and minified files with the same pipeline.\n\n```js\nconst { src, dest } = require('gulp');\nconst babel = require('gulp-babel');\nconst uglify = require('gulp-uglify');\nconst rename = require('gulp-rename');\n\nexports.default = function() {\n return src('src/*.js')\n .pipe(babel())\n .pipe(src('vendor/*.js'))\n .pipe(dest('output/'))\n .pipe(uglify())\n .pipe(rename({ extname: '.min.js' }))\n .pipe(dest('output/'));\n}\n```\n\n## Modes: streaming, buffered, and empty\n\n`src()` can operate in three modes: buffering, streaming, and empty. These are configured with the `buffer` and `read` [options][src-options-api-docs] on `src()`.\n\n* Buffering mode is the default and loads the file contents into memory. Plugins usually operate in buffering mode and many don't support streaming mode.\n* Streaming mode exists mainly to operate on large files that can't fit in memory, like giant images or movies. The contents are streamed from the filesystem in small chunks instead of loaded all at once. If you need to use streaming mode, look for a plugin that supports it or write your own.\n* Empty mode contains no contents and is useful when only working with file metadata.\n\n[explaining-globs-docs]: ../getting-started/6-explaining-globs.md\n[creating-tasks-docs]: ../getting-started/3-creating-tasks.md\n[overlapping-globs-docs]: ../getting-started/6-explaining-globs.md#overlapping-globs\n[node-streams-docs]: https://nodejs.org/api/stream.html\n[symlink-api-docs]: ../api/symlink.md\n[src-options-api-docs]: ../api/src.md#options\n" }, { "path": "docs/getting-started/6-explaining-globs.md", "content": "\n\n# Explaining Globs\n\nA glob is a string of literal and/or wildcard characters used to match filepaths. Globbing is the act of locating files on a filesystem using one or more globs.\n\nThe `src()` method expects a single glob string or an array of globs to determine which files your pipeline will operate on. At least one match must be found for your glob(s) otherwise `src()` will error. When an array of globs is used, any negative globs will remove matches from any positive glob.\n\n## Segments and separators\n\nA segment is everything between separators. The separator in a glob is always the `/` character - regardless of the operating system - even in Windows where the path separator is `\\\\`. In a glob, `\\\\` is reserved as the escape character.\n\nHere, the * is escaped, so it is treated as a literal instead of a wildcard character.\n```js\n'glob_with_uncommon_\\\\*_character.js'\n```\n\nAvoid using Node's `path` methods, like `path.join`, to create globs. On Windows, it produces an invalid glob because Node uses `\\\\` as the separator. Also avoid the `__dirname` global, `__filename` global, or `process.cwd()` for the same reasons.\n\n```js\nconst invalidGlob = path.join(__dirname, 'src/*.js');\n```\n\n## Special character: * (single-star)\n\nMatches any amount - including none - of characters within a single segment. Useful for globbing files within one directory.\n\nThis glob will match files like `index.js`, but not files like `scripts/index.js` or `scripts/nested/index.js`\n```js\n'*.js'\n```\n\n## Special character: ** (double-star)\n\nMatches any amount - including none - of characters across segments. Useful for globbing files in nested directories. Make sure to appropriately restrict your double-star globs, to avoid matching large directories unnecessarily.\n\nHere, the glob is appropriately restricted to the `scripts/` directory. It will match files like `scripts/index.js`, `scripts/nested/index.js`, and `scripts/nested/twice/index.js`.\n\n```js\n'scripts/**/*.js'\n```\n\nIn the previous example, if `scripts/` wasn't prefixed, all dependencies in `node_modules` or other directories would also be matched.\n\n## Special character: ! (negative)\n\nGlobs prefixed with the `!` character will \"negate\" the glob, excluding the match completely. All negative globs are applied to every positive glob, which is a departure from gulp versions before v5.\n\nHere, the `scripts/` directory will be traversed for all files ending in `.js`, but all files from the `scripts/vendor/` directory will be excluded.\n\n```js\n['scripts/**/*.js', '!scripts/vendor/**']\n```\n\nNegative globs can be used as an alternative for restricting double-star globs.\n\n```js\n['**/*.js', '!node_modules/**']\n```\n\n## Ordered globs\n\nVersions of gulp before v5 allowed \"ordered globs\"; however, that has been removed to align with most globbing libraries in the ecosystem.\n\nIf you need the \"ordered glob\" functionality, you can use the [ordered-read-streams][ordered-read-streams-docs] library to combine streams:\n\n```js\nconst order = require(\"ordered-read-streams\");\n\nexports.default = function () {\n return order([\n gulp.src(\"input/jquery/dist/jquery.js\"),\n gulp.src(\"input/detect_swipe/jquery.detect_swipe.js\"),\n ]).pipe(gulp.dest('output/'));\n}\n```\n\n## Overlapping globs\n\nTwo or more globs that (un)intentionally match the same file are considered overlapping. When overlapping globs are used within a single `src()`, gulp does its best to remove the duplicates, but doesn't attempt to deduplicate across separate `src()` calls.\n\n## Advanced resources\n\nMost of what you'll need to work with globs in gulp is covered here. If you'd like to get more in depth, here are a few resources.\n\n* [Micromatch Documentation][micromatch-docs]\n* [node-glob's Glob Primer][glob-primer-docs]\n* [Begin's Globbing Documentation][begin-globbing-docs]\n* [Wikipedia's Glob Page][wikipedia-glob]\n\n[micromatch-docs]: https://github.com/micromatch/micromatch\n[glob-primer-docs]: https://github.com/isaacs/node-glob#glob-primer\n[begin-globbing-docs]: https://github.com/begin/globbing#what-is-globbing\n[wikipedia-glob]: https://en.wikipedia.org/wiki/Glob_(programming)\n[ordered-read-streams-docs]: https://github.com/gulpjs/ordered-read-streams#orderedstreams-options\n" }, { "path": "docs/getting-started/7-using-plugins.md", "content": "\n\n# Using Plugins\n\nGulp plugins are [Node Transform Streams][through2-docs] that encapsulate common behavior to transform files in a pipeline - often placed between `src()` and `dest()` using the `.pipe()` method. They can change the filename, metadata, or contents of every file that passes through the stream.\n\nPlugins from npm - using the \"gulpplugin\" and \"gulpfriendly\" keywords - can be browsed and searched on the [plugin search page][gulp-plugin-site].\n\nEach plugin should only do a small amount of work, so you can connect them like building blocks. You may need to combine a bunch of them to get the desired result.\n\n```js\nconst { src, dest } = require('gulp');\nconst uglify = require('gulp-uglify');\nconst rename = require('gulp-rename');\n\nexports.default = function() {\n return src('src/*.js')\n // The gulp-uglify plugin won't update the filename\n .pipe(uglify())\n // So use gulp-rename to change the extension\n .pipe(rename({ extname: '.min.js' }))\n .pipe(dest('output/'));\n}\n```\n\n## Do you need a plugin?\n\nNot everything in gulp should use plugins. They are a quick way to get started, but many operations are improved by using a module or library instead.\n\n```js\nconst { rollup } = require('rollup');\n\n// Rollup's promise API works great in an `async` task\nexports.default = async function() {\n const bundle = await rollup({\n input: 'src/index.js'\n });\n\n return bundle.write({\n file: 'output/bundle.js',\n format: 'iife'\n });\n}\n```\n\nPlugins should always transform files. Use a (non-plugin) Node module or library for any other operations.\n\n```js\nconst del = require('delete');\n\nexports.default = function(cb) {\n // Use the `delete` module directly, instead of using gulp-rimraf\n del(['output/*.js'], cb);\n}\n```\n\n## Conditional plugins\n\nSince plugin operations shouldn't be file-type-aware, you may need a plugin like [gulp-if][gulp-if-package] to transform subsets of files.\n\n```js\nconst { src, dest } = require('gulp');\nconst gulpif = require('gulp-if');\nconst uglify = require('gulp-uglify');\n\nfunction isJavaScript(file) {\n // Check if file extension is '.js'\n return file.extname === '.js';\n}\n\nexports.default = function() {\n // Include JavaScript and CSS files in a single pipeline\n return src(['src/*.js', 'src/*.css'])\n // Only apply gulp-uglify plugin to JavaScript files\n .pipe(gulpif(isJavaScript, uglify()))\n .pipe(dest('output/'));\n}\n```\n\n## Inline plugins\n\nInline plugins are one-off Transform Streams you define inside your gulpfile by writing the desired behavior.\n\nThere are two situations where creating an inline plugin is helpful:\n* Instead of creating and maintaining your own plugin.\n* Instead of forking a plugin that exists to add a feature you want.\n\n```js\nconst { src, dest } = require('gulp');\nconst uglify = require('uglify-js');\nconst through2 = require('through2');\n\nexports.default = function() {\n return src('src/*.js')\n // Instead of using gulp-uglify, you can create an inline plugin\n .pipe(through2.obj(function(file, _, cb) {\n if (file.isBuffer()) {\n const code = uglify.minify(file.contents.toString())\n file.contents = Buffer.from(code.code)\n }\n cb(null, file);\n }))\n .pipe(dest('output/'));\n}\n```\n\n[gulp-plugin-site]: https://gulpjs.com/plugins/\n[through2-docs]: https://github.com/rvagg/through2\n[gulp-if-package]: https://www.npmjs.com/package/gulp-if\n" }, { "path": "docs/getting-started/8-watching-files.md", "content": "\n\n# Watching Files\n\nThe `watch()` API connects [globs][globs-docs] to [tasks][creating-tasks-docs] using a file system watcher. It watches for changes to files that match the globs and executes the task when a change occurs. If the task doesn't signal [Async Completion][async-completion-doc], it will never be run a second time.\n\nThis API provides built-in delay and queueing based on most-common-use defaults.\n\n```js\nconst { watch, series } = require('gulp');\n\nfunction clean(cb) {\n // body omitted\n cb();\n}\n\nfunction javascript(cb) {\n // body omitted\n cb();\n}\n\nfunction css(cb) {\n // body omitted\n cb();\n}\n\nexports.default = function() {\n // You can use a single task\n watch('src/*.css', css);\n // Or a composed task\n watch('src/*.js', series(clean, javascript));\n};\n```\n\n## Warning: avoid synchronous\n\nA watcher's task cannot be synchronous, like tasks registered into the task system. If you pass a sync task, the completion can't be determined and the task won't run again - it is assumed to still be running.\n\nThere is no error or warning message provided because the file watcher keeps your Node process running. Since the process doesn't exit, it cannot be determined whether the task is done or just taking a really, really long time to run.\n\n## Watched events\n\nBy default, the watcher executes tasks whenever a file is created, changed, or deleted.\nIf you need to use different events, you can use the `events` option when calling `watch()`. The available events are `'add'`, `'addDir'`, `'change'`, `'unlink'`, `'unlinkDir'`, `'ready'`, `'error'`. Additionally `'all'` is available, which represents all events other than `'ready'` and `'error'`.\n\n```js\nconst { watch } = require('gulp');\n\nexports.default = function() {\n // All events will be watched\n watch('src/*.js', { events: 'all' }, function(cb) {\n // body omitted\n cb();\n });\n};\n```\n\n## Initial execution\n\nUpon calling `watch()`, the tasks won't be executed, instead they'll wait for the first file change.\n\nTo execute tasks before the first file change, set the `ignoreInitial` option to `false`.\n\n```js\nconst { watch } = require('gulp');\n\nexports.default = function() {\n // The task will be executed upon startup\n watch('src/*.js', { ignoreInitial: false }, function(cb) {\n // body omitted\n cb();\n });\n};\n```\n\n## Queueing\n\nEach `watch()` guarantees that its currently running task won't execute again concurrently. When a file change is made while a watcher task is running, another execution will queue up to run when the task finishes. Only one run can be queued up at a time.\n\nTo disable queueing, set the `queue` option to `false`.\n\n```js\nconst { watch } = require('gulp');\n\nexports.default = function() {\n // The task will be run (concurrently) for every change made\n watch('src/*.js', { queue: false }, function(cb) {\n // body omitted\n cb();\n });\n};\n```\n\n## Delay\n\nUpon file change, a watcher task won't run until a 200ms delay has elapsed. This is to avoid starting a task too early when many files are being changed at once - like find-and-replace.\n\nTo adjust the delay duration, set the `delay` option to a positive integer.\n\n```js\nconst { watch } = require('gulp');\n\nexports.default = function() {\n // The task won't be run until 500ms have elapsed since the first change\n watch('src/*.js', { delay: 500 }, function(cb) {\n // body omitted\n cb();\n });\n};\n```\n\n## Using the watcher instance\n\nYou likely won't use this feature, but if you need full control over changed files - like access to paths or metadata - use the [chokidar][chokidar-module-package] instance returned from `watch()`.\n\n__Be careful:__ The returned chokidar instance doesn't have queueing, delay, or async completion features.\n\n## Optional dependency\n\nGulp has an optional dependency called [fsevents][fsevents-package], which is a Mac-specific file watcher. If you see an installation warning for fsevents - _\"npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents\"_ - it is not an issue.\nIf fsevents installation is skipped, a fallback watcher will be used and any errors occurring in your gulpfile aren't related to this warning.\n\n[globs-docs]: ../getting-started/6-explaining-globs.md\n[creating-tasks-docs]: ../getting-started/3-creating-tasks.md\n[async-completion-doc]: ../getting-started/4-async-completion.md\n[chokidar-module-package]: https://www.npmjs.com/package/chokidar\n[fsevents-package]: https://www.npmjs.com/package/fsevents\n" }, { "path": "docs/getting-started/README.md", "content": "# Getting Started\n\n1. [Quick Start](1-quick-start.md)\n2. [JavaScript and Gulpfiles](2-javascript-and-gulpfiles.md)\n3. [Creating Tasks](3-creating-tasks.md)\n4. [Async Completion](4-async-completion.md)\n5. [Working with Files](5-working-with-files.md)\n6. [Explaining Globs](6-explaining-globs.md)\n7. [Using Plugins](7-using-plugins.md)\n8. [Watching Files](8-watching-files.md)\n" }, { "path": "docs/getting-started.md", "content": "## This documentation has moved!\n\nYou can find the new documentation in our [Quick Start](getting-started/1-quick-start.md) guide.\n\nWhile you are there, check out our expanded [Getting Started](getting-started/) documentation.\n" }, { "path": "docs/recipes/README.md", "content": "# Recipes\n\n* [Automate release workflow](automate-releases.md)\n* [Combining streams to handle errors](combining-streams-to-handle-errors.md)\n* [Delete files and folders](delete-files-folder.md)\n* [Fast browserify builds with watchify](fast-browserify-builds-with-watchify.md)\n* [Incremental rebuilding, including operating on full file sets](incremental-builds-with-concatenate.md)\n* [Make stream from buffer (memory contents)](make-stream-from-buffer.md)\n* [Mocha test-runner with gulp](mocha-test-runner-with-gulp.md)\n* [Pass parameters from the command line](pass-arguments-from-cli.md)\n* [Generating a file per folder](running-task-steps-per-folder.md)\n* [Server with live-reloading and CSS injection](server-with-livereload-and-css-injection.md)\n* [Sharing streams with stream factories](sharing-streams-with-stream-factories.md)\n* [Using multiple sources in one task](using-multiple-sources-in-one-task.md)\n* [Browserify + Uglify with sourcemaps](browserify-uglify-sourcemap.md)\n* [Browserify + Globs](browserify-with-globs.md)\n* [Browserify + Globs (multiple destination)](browserify-multiple-destination.md)\n* [Output both a minified and non-minified version](minified-and-non-minified.md)\n* [Templating with Swig and YAML front-matter](templating-with-swig-and-yaml-front-matter.md)\n* [Run Grunt Tasks from Gulp](run-grunt-tasks-from-gulp.md)\n* [Rollup with rollup-stream](rollup-with-rollup-stream.md)\n* [Run gulp task via cron job](cron-task.md)\n" }, { "path": "docs/recipes/automate-releases.md", "content": "\n\n# Automate Releases\n\nIf your project follows a semantic versioning, it may be a good idea to automatize the steps needed to do a release.\nThe recipe below bumps the project version, commits the changes to git and creates a new GitHub release.\n\nFor publishing a GitHub release you'll need to [create a personal access token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) and add it to your project. However, we don't want to commit it, so we'll use [`dotenv`](https://www.npmjs.com/package/dotenv) to load it from a git-ignored `.env` file:\n\n```\nGH_TOKEN=ff34885...\n```\n\nDon't forget to add `.env` to your `.gitignore`.\n\nNext, install all the necessary dependencies for this recipe:\n\n```sh\nnpm install --save-dev conventional-recommended-bump conventional-changelog-cli conventional-github-releaser dotenv execa\n```\n\nBased on your environment, setup and preferences, your release workflow might look something like this:\n\n``` js\nconst gulp = require('gulp');\nconst conventionalRecommendedBump = require('conventional-recommended-bump');\nconst conventionalGithubReleaser = require('conventional-github-releaser');\nconst execa = require('execa');\nconst fs = require('fs');\nconst { promisify } = require('util');\nconst dotenv = require('dotenv');\n\n// load environment variables\nconst result = dotenv.config();\n\nif (result.error) {\n throw result.error;\n}\n\n// Conventional Changelog preset\nconst preset = 'angular';\n// print output of commands into the terminal\nconst stdio = 'inherit';\n\nasync function bumpVersion() {\n // get recommended version bump based on commits\n const { releaseType } = await promisify(conventionalRecommendedBump)({ preset });\n // bump version without committing and tagging\n await execa('npm', ['version', releaseType, '--no-git-tag-version'], {\n stdio,\n });\n}\n\nasync function changelog() {\n await execa(\n 'npx',\n [\n 'conventional-changelog',\n '--preset',\n preset,\n '--infile',\n 'CHANGELOG.md',\n '--same-file',\n ],\n { stdio }\n );\n}\n\nasync function commitTagPush() {\n // even though we could get away with \"require\" in this case, we're taking the safe route\n // because \"require\" caches the value, so if we happen to use \"require\" again somewhere else\n // we wouldn't get the current value, but the value of the last time we called \"require\"\n const { version } = JSON.parse(await promisify(fs.readFile)('package.json'));\n const commitMsg = `chore: release ${version}`;\n await execa('git', ['add', '.'], { stdio });\n await execa('git', ['commit', '--message', commitMsg], { stdio });\n await execa('git', ['tag', `v${version}`], { stdio });\n await execa('git', ['push', '--follow-tags'], { stdio });\n}\n\nfunction githubRelease(done) {\n conventionalGithubReleaser(\n { type: 'oauth', token: process.env.GH_TOKEN },\n { preset },\n done\n );\n}\n\nexports.release = gulp.series(\n bumpVersion,\n changelog,\n commitTagPush,\n githubRelease\n);\n```\n" }, { "path": "docs/recipes/browserify-multiple-destination.md", "content": "# Browserify + Globs (multiple destination)\n\nThis example shows how to set up a task of bundling multiple entry points into multiple destinations using browserify.\n\nThe below `js` task bundles all the `.js` files under `src/` as entry points and writes the results under `dest/`.\n\n\n```js\nvar gulp = require('gulp');\nvar browserify = require('browserify');\nvar log = require('gulplog');\nvar tap = require('gulp-tap');\nvar buffer = require('gulp-buffer');\nvar sourcemaps = require('gulp-sourcemaps');\nvar uglify = require('gulp-uglify');\n\ngulp.task('js', function () {\n\n return gulp.src('src/**/*.js', {read: false}) // no need of reading file because browserify does.\n\n // transform file objects using gulp-tap plugin\n .pipe(tap(function (file) {\n\n log.info('bundling ' + file.path);\n\n // replace file contents with browserify's bundle stream\n file.contents = browserify(file.path, {debug: true}).bundle();\n\n }))\n\n // transform streaming contents into buffer contents (because gulp-sourcemaps does not support streaming contents)\n .pipe(buffer())\n\n // load and init sourcemaps\n .pipe(sourcemaps.init({loadMaps: true}))\n\n .pipe(uglify())\n\n // write sourcemaps\n .pipe(sourcemaps.write('./'))\n\n .pipe(gulp.dest('dest'));\n\n});\n```\n" }, { "path": "docs/recipes/browserify-transforms.md", "content": "# Browserify + Transforms\n\n[Browserify](https://github.com/browserify/browserify) has become an important and indispensable\ntool but requires being wrapped before working well with gulp. Below is a simple recipe for using\nBrowserify with transforms.\n\nSee also: the [Combining Streams to Handle Errors](https://github.com/gulpjs/gulp/blob/master/docs/recipes/combining-streams-to-handle-errors.md) recipe for handling errors with browserify or uglify in your stream.\n\n``` javascript\n'use strict';\n\nvar browserify = require('browserify');\nvar gulp = require('gulp');\nvar source = require('vinyl-source-stream');\nvar buffer = require('vinyl-buffer');\nvar log = require('gulplog');\nvar uglify = require('gulp-uglify');\nvar reactify = require('reactify');\n\ngulp.task('javascript', function () {\n // set up the browserify instance on a task basis\n var b = browserify({\n entries: './entry.js',\n debug: true,\n // defining transforms here will avoid crashing your stream\n transform: [reactify]\n });\n\n return b.bundle()\n .pipe(source('app.js', { sourcemaps: true }))\n .pipe(buffer())\n // Add transformation tasks to the pipeline here.\n .pipe(uglify())\n .on('error', log.error)\n .pipe(gulp.dest('./dist/js/', { sourcemaps: '../sourcemaps/' }));\n});\n```\n" }, { "path": "docs/recipes/browserify-uglify-sourcemap.md", "content": "# Browserify + Uglify2 with sourcemaps\n\n[Browserify](https://github.com/browserify/browserify) has become an important and indispensable\ntool but requires being wrapped before working well with gulp. Below is a simple recipe for using\nBrowserify with full sourcemaps that resolve to the original individual files.\n\nSee also: the [Combining Streams to Handle Errors](https://github.com/gulpjs/gulp/blob/master/docs/recipes/combining-streams-to-handle-errors.md) recipe for handling errors with browserify or uglify in your stream.\n\nA simple `gulpfile.js` file for Browserify + Uglify2 with sourcemaps:\n\n``` javascript\n'use strict';\n\nvar browserify = require('browserify');\nvar gulp = require('gulp');\nvar source = require('vinyl-source-stream');\nvar buffer = require('vinyl-buffer');\nvar uglify = require('gulp-uglify');\nvar sourcemaps = require('gulp-sourcemaps');\nvar log = require('gulplog');\n\ngulp.task('javascript', function () {\n // set up the browserify instance on a task basis\n var b = browserify({\n entries: './entry.js',\n debug: true\n });\n\n return b.bundle()\n .pipe(source('app.js'))\n .pipe(buffer())\n .pipe(sourcemaps.init({loadMaps: true}))\n // Add transformation tasks to the pipeline here.\n .pipe(uglify())\n .on('error', log.error)\n .pipe(sourcemaps.write('./'))\n .pipe(gulp.dest('./dist/js/'));\n});\n```\n" }, { "path": "docs/recipes/browserify-with-globs.md", "content": "# Browserify + Globs\n\n[Browserify + Uglify2](https://github.com/gulpjs/gulp/blob/master/docs/recipes/browserify-uglify-sourcemap.md) shows how to setup a basic gulp task to bundle a JavaScript file with its dependencies, and minify the bundle with UglifyJS while preserving source maps.\nIt does not, however, show how one may use gulp and Browserify with multiple entry files.\n\nSee also: the [Combining Streams to Handle Errors](https://github.com/gulpjs/gulp/blob/master/docs/recipes/combining-streams-to-handle-errors.md) recipe for handling errors with Browserify or UglifyJS in your stream.\n\n``` javascript\n'use strict';\n\nvar browserify = require('browserify');\nvar gulp = require('gulp');\nvar source = require('vinyl-source-stream');\nvar buffer = require('vinyl-buffer');\nvar globby = require('globby');\nvar through = require('through2');\nvar log = require('gulplog');\nvar uglify = require('gulp-uglify');\nvar sourcemaps = require('gulp-sourcemaps');\nvar reactify = require('reactify');\n\ngulp.task('javascript', function () {\n // gulp expects tasks to return a stream, so we create one here.\n var bundledStream = through();\n\n bundledStream\n // turns the output bundle stream into a stream containing\n // the normal attributes gulp plugins expect.\n .pipe(source('app.js'))\n // the rest of the gulp task, as you would normally write it.\n // here we're copying from the Browserify + Uglify2 recipe.\n .pipe(buffer())\n .pipe(sourcemaps.init({loadMaps: true}))\n // Add gulp plugins to the pipeline here.\n .pipe(uglify())\n .on('error', log.error)\n .pipe(sourcemaps.write('./'))\n .pipe(gulp.dest('./dist/js/'));\n\n // \"globby\" replaces the normal \"gulp.src\" as Browserify\n // creates it's own readable stream.\n globby(['./entries/*.js']).then(function(entries) {\n // create the Browserify instance.\n var b = browserify({\n entries: entries,\n debug: true,\n transform: [reactify]\n });\n\n // pipe the Browserify stream into the stream we created earlier\n // this starts our gulp pipeline.\n b.bundle().pipe(bundledStream);\n }).catch(function(err) {\n // ensure any errors from globby are handled\n bundledStream.emit('error', err);\n });\n\n // finally, we return the stream, so gulp knows when this task is done.\n return bundledStream;\n});\n```\n" }, { "path": "docs/recipes/combining-streams-to-handle-errors.md", "content": "# Combining streams to handle errors\n\nBy default, emitting an error on a stream will cause it to be thrown unless it already has a listener attached to the `error` event. This gets a bit tricky when you're working with longer pipelines of streams.\n\nBy using [stream-combiner2](https://github.com/substack/stream-combiner2) you can turn a series of streams into a single stream, meaning you only need to listen to the `error` event in one place in your code.\n\nHere's an example of using it in a gulpfile:\n\n```js\nvar combiner = require('stream-combiner2');\nvar uglify = require('gulp-uglify');\nvar gulp = require('gulp');\n\ngulp.task('test', function() {\n return combiner.obj([\n gulp.src('bootstrap/js/*.js'),\n uglify(),\n gulp.dest('public/bootstrap')\n ])\n // any errors in the above streams will get caught\n // by this listener, instead of being thrown:\n .on('error', console.error.bind(console));\n});\n```\n" }, { "path": "docs/recipes/cron-task.md", "content": "# Run gulp task via cron job\n\nWhile logged in via a user that has privileges to run `gulp`, run the following:\n\n crontab -e\n\nto edit your current \"[crontab](https://en.wikipedia.org/wiki/Cron)\" file.\n\nTypically, within a cron job, you want to run any binary using absolute paths,\nso an initial approach to running `gulp build` every minute might look like:\n\n * * * * * cd /your/dir/to/run/in && /usr/local/bin/gulp build\n\nHowever, you might see in the cron logs that you get this error:\n\n> `/usr/bin/env: node: No such file or directory`\n\nTo fix this, we need to add a [symbolic link](https://en.wikipedia.org/wiki/Ln_\\(Unix\\))\nwithin `/usr/bin` to point to the actual path of our node binary.\n\nBe sure you are logged in as a **sudo** user, and paste in the following command to your terminal:\n\n sudo ln -s $(which node) /usr/bin/node\n\nOnce this link is established, your cron task should run successfully.\n" }, { "path": "docs/recipes/delete-files-folder.md", "content": "# Delete files and folders\n\nYou might want to delete some files before running your build. Since deleting files doesn't work on the file contents, there's no reason to use a gulp plugin. An excellent opportunity to use a vanilla node module.\n\nLet's use the [`del`](https://github.com/sindresorhus/del) module for this example as it supports multiple files and [globbing](https://github.com/sindresorhus/multimatch#globbing-patterns):\n\n```sh\n$ npm install --save-dev gulp del\n```\n\nImagine the following file structure:\n\n```\n.\n├── dist\n│   ├── report.csv\n│   ├── desktop\n│   └── mobile\n│   ├── app.js\n│   ├── deploy.json\n│   └── index.html\n└── src\n```\n\nIn the gulpfile we want to clean out the contents of the `mobile` folder before running our build:\n\n```js\nvar gulp = require('gulp');\nvar del = require('del');\n\ngulp.task('clean:mobile', function () {\n return del([\n 'dist/report.csv',\n // here we use a globbing pattern to match everything inside the `mobile` folder\n 'dist/mobile/**/*',\n // we don't want to clean this file though so we negate the pattern\n '!dist/mobile/deploy.json'\n ]);\n});\n\ngulp.task('default', gulp.series('clean:mobile'));\n```\n\n\n## Delete files in a pipeline\n\nYou might want to delete some files after processing them in a pipeline.\n\nWe'll use [vinyl-paths](https://github.com/sindresorhus/vinyl-paths) to easily get the file path of files in the stream and pass it to the `del` method.\n\n```sh\n$ npm install --save-dev gulp del vinyl-paths\n```\n\nImagine the following file structure:\n\n```\n.\n├── tmp\n│   ├── rainbow.js\n│   └── unicorn.js\n└── dist\n```\n\n```js\nvar gulp = require('gulp');\nvar stripDebug = require('gulp-strip-debug'); // only as an example\nvar del = require('del');\nvar vinylPaths = require('vinyl-paths');\n\ngulp.task('clean:tmp', function () {\n return gulp.src('tmp/*')\n .pipe(vinylPaths(del))\n .pipe(stripDebug())\n .pipe(gulp.dest('dist'));\n});\n\ngulp.task('default', gulp.series('clean:tmp'));\n```\n\nThis will only delete the tmp dir.\n\n\nOnly do this if you're already using other plugins in the pipeline, otherwise just use the module directly as `gulp.src` is costly.\n" }, { "path": "docs/recipes/fast-browserify-builds-with-watchify.md", "content": "# Fast browserify builds with watchify\n\nAs a [browserify](https://github.com/browserify/browserify) project begins to expand, the time to bundle it slowly gets longer and longer. While it might start at 1 second, it's possible to be waiting 30 seconds for your project to build on particularly large projects.\n\nThat's why [substack](https://github.com/substack) wrote [watchify](https://github.com/browserify/watchify), a persistent browserify bundler that watches files for changes and *only rebuilds what it needs to*. This way, that first build might still take 30 seconds, but subsequent builds can still run in under 100ms – which is a huge improvement.\n\nWatchify doesn't have a gulp plugin, and it doesn't need one: you can use [vinyl-source-stream](https://github.com/hughsk/vinyl-source-stream) to pipe the bundle stream into your gulp pipeline.\n\n``` javascript\n'use strict';\n\nvar watchify = require('watchify');\nvar browserify = require('browserify');\nvar gulp = require('gulp');\nvar source = require('vinyl-source-stream');\nvar buffer = require('vinyl-buffer');\nvar log = require('gulplog');\nvar sourcemaps = require('gulp-sourcemaps');\nvar assign = require('lodash.assign');\n\n// add custom browserify options here\nvar customOpts = {\n entries: ['./src/index.js'],\n debug: true\n};\nvar opts = assign({}, watchify.args, customOpts);\nvar b = watchify(browserify(opts));\n\n// add transformations here\n// i.e. b.transform(coffeeify);\n\ngulp.task('js', bundle); // so you can run `gulp js` to build the file\nb.on('update', bundle); // on any dep update, runs the bundler\nb.on('log', log.info); // output build logs to terminal\n\nfunction bundle() {\n return b.bundle()\n // log errors if they happen\n .on('error', log.error.bind(log, 'Browserify Error'))\n .pipe(source('bundle.js'))\n // optional, remove if you don't need to buffer file contents\n .pipe(buffer())\n // optional, remove if you dont want sourcemaps\n .pipe(sourcemaps.init({loadMaps: true})) // loads map from browserify file\n // Add transformation tasks to the pipeline here.\n .pipe(sourcemaps.write('./')) // writes .map file\n .pipe(gulp.dest('./dist'));\n}\n```\n" }, { "path": "docs/recipes/handling-the-delete-event-on-watch.md", "content": "# Handling the Delete Event on Watch\n\nYou can listen for `'unlink'` events to fire on the watcher returned from `gulp.watch`.\nThis gets fired when files are removed, so you can delete the file from your destination\ndirectory, using something like:\n\n```js\n'use strict';\n\nvar del = require('del');\nvar path = require('path');\nvar gulp = require('gulp');\nvar header = require('gulp-header');\nvar footer = require('gulp-footer');\n\ngulp.task('scripts', function() {\n return gulp.src('src/**/*.js', {base: 'src'})\n .pipe(header('(function () {\\r\\n\\t\\'use strict\\'\\r\\n'))\n .pipe(footer('\\r\\n})();'))\n .pipe(gulp.dest('build'));\n});\n\ngulp.task('watch', function () {\n var watcher = gulp.watch('src/**/*.js', ['scripts']);\n\n watcher.on('unlink', function (filepath) {\n var filePathFromSrc = path.relative(path.resolve('src'), filepath);\n // Concatenating the 'build' absolute path used by gulp.dest in the scripts task\n var destFilePath = path.resolve('build', filePathFromSrc);\n del.sync(destFilePath);\n });\n});\n```\n" }, { "path": "docs/recipes/incremental-builds-with-concatenate.md", "content": "# Incremental rebuilding, including operating on full file sets\n\nThe trouble with incremental rebuilds is you often want to operate on _all_ processed files, not just single files. For example, you may want to lint and module-wrap just the file(s) that have changed, then concatenate it with all other linted and module-wrapped files. This is difficult without the use of temp files.\n\nUse [gulp-cached](https://github.com/wearefractal/gulp-cached) and [gulp-remember](https://github.com/ahaurw01/gulp-remember) to achieve this.\n\n```js\nvar gulp = require('gulp');\nvar header = require('gulp-header');\nvar footer = require('gulp-footer');\nvar concat = require('gulp-concat');\nvar jshint = require('gulp-jshint');\nvar cached = require('gulp-cached');\nvar remember = require('gulp-remember');\n\nvar scriptsGlob = 'src/**/*.js';\n\ngulp.task('scripts', function() {\n return gulp.src(scriptsGlob)\n .pipe(cached('scripts')) // only pass through changed files\n .pipe(jshint()) // do special things to the changed files...\n .pipe(header('(function () {')) // e.g. jshinting ^^^\n .pipe(footer('})();')) // and some kind of module wrapping\n .pipe(remember('scripts')) // add back all files to the stream\n .pipe(concat('app.js')) // do things that require all files\n .pipe(gulp.dest('public/'));\n});\n\ngulp.task('watch', function () {\n var watcher = gulp.watch(scriptsGlob, gulp.series('scripts')); // watch the same files in our scripts task\n watcher.on('change', function (event) {\n if (event.type === 'deleted') { // if a file is deleted, forget about it\n delete cached.caches.scripts[event.path]; // gulp-cached remove api\n remember.forget('scripts', event.path); // gulp-remember remove api\n }\n });\n});\n```\n" }, { "path": "docs/recipes/maintain-directory-structure-while-globbing.md", "content": "# Maintain Directory Structure while Globbing\n\nIf you are planning to read a few files/folders from a directory and maintain their relative path, you need to pass `{base: '.'}` as the second argument to `gulp.src()`.\n\n\nFor example, if you have a directory structure like\n\n![Dev setup](https://cloud.githubusercontent.com/assets/2562992/3178498/bedf75b4-ec1a-11e3-8a71-a150ad94b450.png)\n\nand want to read only a few files say\n\n```js\n[ 'index.html',\n 'css/**',\n 'js/**',\n 'lib/**',\n 'images/**',\n 'plugin/**'\n ]\n```\n\nIn this case, Gulp will read all the sub-folders of (_say_) `css` folder and arrange them relative to your root folder and they will no longer be the sub-folder of `css`. The output after globbing would look like\n\n![Zipped-Unzipped](https://cloud.githubusercontent.com/assets/2562992/3178614/27208c52-ec1c-11e3-852e-8bbb8e420c7f.png)\n\nIf you want to maintain the structure, you need to pass `{base: '.'}` to `gulp.src()`. Like\n\n```js\ngulp.task('task', function () {\n return gulp.src(['index.html',\n 'css/**',\n 'js/**',\n 'lib/**',\n 'images/**',\n 'plugin/**'\n ], {base: '.'})\n .pipe(operation1())\n .pipe(operation2());\n});\n```\nAnd the input to your `operation1()` will be a folder structure like\n\n![with-base](https://cloud.githubusercontent.com/assets/2562992/3178607/053d6722-ec1c-11e3-9ba8-7ce39e1a480e.png)\n" }, { "path": "docs/recipes/make-stream-from-buffer.md", "content": "# Make stream from buffer (memory contents)\n\nSometimes you may need to start a stream with files that their contents are in a variable and not in a physical file. In other words, how to start a 'gulp' stream without using `gulp.src()`.\n\nLet's say for example that we have a directory with js lib files and another directory with versions of some module. The target of the build would be to create one js file for each version, containing all the libs and the version of the module concatenated.\n\nLogically we would break it down like this:\n\n* load the lib files\n* concatenate the lib file contents\n* load the versions files\n* for each version file, concatenate the libs' contents and the version file contents\n* for each version file, output the result in a file\n\nImagine this file structure:\n\n```sh\n├── libs\n│   ├── lib1.js\n│   └── lib2.js\n└── versions\n ├── version.1.js\n └── version.2.js\n```\n\nYou should get:\n\n```sh\n└── output\n ├── version.1.complete.js # lib1.js + lib2.js + version.1.js\n └── version.2.complete.js # lib1.js + lib2.js + version.2.js\n```\n\nA simple and modular way to do this would be the following:\n\n```js\nvar gulp = require('gulp');\nvar source = require('vinyl-source-stream');\nvar vinylBuffer = require('vinyl-buffer');\nvar tap = require('gulp-tap');\nvar concat = require('gulp-concat');\nvar size = require('gulp-size');\nvar path = require('path');\nvar es = require('event-stream');\n\nvar memory = {}; // we'll keep our assets in memory\n\n// task of loading the files' contents in memory\ngulp.task('load-lib-files', function() {\n // read the lib files from the disk\n return gulp.src('src/libs/*.js')\n // concatenate all lib files into one\n .pipe(concat('libs.concat.js'))\n // tap into the stream to get each file's data\n .pipe(tap(function(file) {\n // save the file contents in memory\n memory[path.basename(file.path)] = file.contents.toString();\n }));\n});\n\ngulp.task('load-versions', function() {\n memory.versions = {};\n // read the version files from the disk\n return gulp.src('src/versions/version.*.js')\n // tap into the stream to get each file's data\n .pipe( tap(function(file) {\n // save the file contents in the assets\n memory.versions[path.basename(file.path)] = file.contents.toString();\n }));\n});\n\ngulp.task('write-versions', function() {\n // we store all the different version file names in an array\n var availableVersions = Object.keys(memory.versions);\n // we make an array to store all the stream promises\n var streams = [];\n\n availableVersions.forEach(function(v) {\n // make a new stream with fake file name\n var stream = source('final.' + v);\n\n var streamEnd = stream;\n\n // we load the data from the concatenated libs\n var fileContents = memory['libs.concat.js'] +\n // we add the version's data\n '\\n' + memory.versions[v];\n\n // write the file contents to the stream\n stream.write(fileContents);\n\n process.nextTick(function() {\n // in the next process cycle, end the stream\n stream.end();\n });\n\n streamEnd = streamEnd\n // transform the raw data into the stream, into a vinyl object/file\n .pipe(vinylBuffer())\n //.pipe(tap(function(file) { /* do something with the file contents here */ }))\n .pipe(gulp.dest('output'));\n\n // add the end of the stream, otherwise the task would finish before all the processing\n // is done\n streams.push(streamEnd);\n\n });\n\n return es.merge.apply(this, streams);\n});\n\n//============================================ our main task\ngulp.task('default', gulp.series(\n // load the files in parallel\n gulp.parallel('load-lib-files', 'load-versions'),\n // ready to write once all resources are in memory\n 'write-versions'\n )\n);\n\n//============================================ our watcher task\n// only watch after having run 'default' once so that all resources\n// are already in memory\ngulp.task('watch', gulp.series(\n 'default',\n function() {\n gulp.watch('./src/libs/*.js', gulp.series(\n 'load-lib-files',\n 'write-versions'\n ));\n\n gulp.watch('./src/versions/*.js', gulp.series(\n 'load-lib-files',\n 'write-versions'\n ));\n }\n));\n```\n" }, { "path": "docs/recipes/minified-and-non-minified.md", "content": "# Output both a minified and non-minified version\n\nOutputting both a minified and non-minified version of your combined JavaScript files can be achieved by using `gulp-rename` and piping to `dest` twice (once before minifying and once after minifying):\n\n```js\n'use strict';\n\nvar gulp = require('gulp');\nvar rename = require('gulp-rename');\nvar uglify = require('gulp-uglify');\n\nvar DEST = 'build/';\n\ngulp.task('default', function() {\n return gulp.src('foo.js')\n // This will output the non-minified version\n .pipe(gulp.dest(DEST))\n // This will minify and rename to foo.min.js\n .pipe(uglify())\n .pipe(rename({ extname: '.min.js' }))\n .pipe(gulp.dest(DEST));\n});\n\n```\n" }, { "path": "docs/recipes/minimal-browsersync-setup-with-gulp4.md", "content": "# Minimal BrowserSync setup with Gulp 4\n\n[BrowserSync](https://www.browsersync.io/) is a great tool to streamline\nthe development process with the ability to reflect code changes instantaneously\nin the browser through live-reloading. Setting up a live-reloading\nBrowserSync server with Gulp 4 is very clean and easy.\n\n## Step 1: Install the dependencies\n\n```\nnpm install --save-dev browser-sync\n```\n\n## Step 2: Setup the project structure\n\n```\nsrc/\n scripts/\n |__ index.js\ndist/\n scripts/\nindex.html\ngulpfile.babel.js\n```\n\nThe goal here is to be able to:\n- Build the source script file in `src/scripts/`, e.g. compiling with babel, minifying, etc.\n- Put the compiled version in `dist/scripts` for use in `index.html`\n- Watch for changes in the source file and rebuild the `dist` package\n- With each rebuild of the `dist` package, reload the browser to immediately reflect the changes\n\n## Step 3: Write the gulpfile\n\nThe gulpfile could be broken in 3 parts.\n\n### 1. Write the task to prepare the dist package as usual\n\nRefer to the main [README](https://github.com/gulpjs/gulp/blob/master/docs/README.md)\nfor more information.\n\n```javascript\nimport babel from 'gulp-babel';\nimport concat from 'gulp-concat';\nimport del from 'del';\nimport gulp from 'gulp';\nimport uglify from 'gulp-uglify';\n\nconst paths = {\n scripts: {\n src: 'src/scripts/*.js',\n dest: 'dist/scripts/'\n }\n};\n\nconst clean = () => del(['dist']);\n\nfunction scripts() {\n return gulp.src(paths.scripts.src, { sourcemaps: true })\n .pipe(babel())\n .pipe(uglify())\n .pipe(concat('index.min.js'))\n .pipe(gulp.dest(paths.scripts.dest));\n}\n```\n\n### 2. Setup the BrowserSync server\n\nAnd write the tasks to serve and reload the server accordingly.\n\n```javascript\nimport browserSync from 'browser-sync';\nconst server = browserSync.create();\n\nfunction reload(done) {\n server.reload();\n done();\n}\n\nfunction serve(done) {\n server.init({\n server: {\n baseDir: './'\n }\n });\n done();\n}\n```\n\n### 3. Watch for source change, rebuild the scripts and reload the server\n\nThis is trivially accomplished with `gulp.series`\n\n```javascript\nconst watch = () => gulp.watch(paths.scripts.src, gulp.series(scripts, reload));\n```\n\n## Step 4: Bring it all together\n\nThe last step is to expose the default task\n\n```javascript\nconst dev = gulp.series(clean, scripts, serve, watch);\nexport default dev;\n```\n\nAnd profit\n\n```bash\n$ gulp\n```\n\nNow if you go to [http://localhost:3000](http://localhost:3000), which is the default address of the\nBrowserSync server, you will see that the end result in the browser is updated everytime you change\nthe content of the source file. Here is the whole gulpfile:\n\n```javascript\nimport babel from 'gulp-babel';\nimport concat from 'gulp-concat';\nimport del from 'del';\nimport gulp from 'gulp';\nimport uglify from 'gulp-uglify';\nimport browserSync from 'browser-sync';\n\nconst server = browserSync.create();\n\nconst paths = {\n scripts: {\n src: 'src/scripts/*.js',\n dest: 'dist/scripts/'\n }\n};\n\nconst clean = () => del(['dist']);\n\nfunction scripts() {\n return gulp.src(paths.scripts.src, { sourcemaps: true })\n .pipe(babel())\n .pipe(uglify())\n .pipe(concat('index.min.js'))\n .pipe(gulp.dest(paths.scripts.dest));\n}\n\nfunction reload(done) {\n server.reload();\n done();\n}\n\nfunction serve(done) {\n server.init({\n server: {\n baseDir: './'\n }\n });\n done();\n}\n\nconst watch = () => gulp.watch(paths.scripts.src, gulp.series(scripts, reload));\n\nconst dev = gulp.series(clean, scripts, serve, watch);\nexport default dev;\n```\n" }, { "path": "docs/recipes/mocha-test-runner-with-gulp.md", "content": "# Mocha test-runner with gulp\n\n### Passing shared module in all tests\n\n```js\n// npm install gulp gulp-mocha\n\nvar gulp = require('gulp');\nvar mocha = require('gulp-mocha');\n\ngulp.task('default', function() {\n return gulp.src(['test/test-*.js'], { read: false })\n .pipe(mocha({\n reporter: 'spec',\n globals: {\n should: require('should')\n }\n }));\n});\n```\n\n### Running mocha tests when files change\n\n```js\n// npm install gulp gulp-mocha gulplog\n\nvar gulp = require('gulp');\nvar mocha = require('gulp-mocha');\nvar log = require('gulplog');\n\ngulp.task('mocha', function() {\n return gulp.src(['test/*.js'], { read: false })\n .pipe(mocha({ reporter: 'list' }))\n .on('error', log.error);\n});\n\ngulp.task('watch-mocha', function() {\n gulp.watch(['lib/**', 'test/**'], gulp.series('mocha'));\n});\n```\n" }, { "path": "docs/recipes/pass-arguments-from-cli.md", "content": "# Pass arguments from the command line\n\n```js\n// npm install --save-dev gulp gulp-if gulp-uglify minimist\n\nvar gulp = require('gulp');\nvar gulpif = require('gulp-if');\nvar uglify = require('gulp-uglify');\n\nvar minimist = require('minimist');\n\nvar knownOptions = {\n string: 'env',\n default: { env: process.env.NODE_ENV || 'production' }\n};\n\nvar options = minimist(process.argv.slice(2), knownOptions);\n\ngulp.task('scripts', function() {\n return gulp.src('**/*.js')\n .pipe(gulpif(options.env === 'production', uglify())) // only minify in production\n .pipe(gulp.dest('dist'));\n});\n```\n\nThen run gulp with:\n\n```sh\n$ gulp scripts --env development\n```\n" }, { "path": "docs/recipes/rollup-with-rollup-stream.md", "content": "# Rollup with rollup-stream\n\nLike Browserify, [Rollup](https://rollupjs.org/) is a bundler and thus only fits naturally into gulp if it's at the start of the pipeline. Unlike Browserify, Rollup doesn't natively produce a stream as output and needs to be wrapped before it can take this position. [rollup-stream](https://github.com/Permutatrix/rollup-stream) does this for you, producing output just like that of Browserify's `bundle()` method—as a result, most of the Browserify recipes here will also work with rollup-stream.\n\n## Basic usage\n```js\n// npm install --save-dev gulp @rollup/stream@1 vinyl-source-stream\nvar gulp = require('gulp');\nvar rollup = require('rollup-stream');\nvar source = require('vinyl-source-stream');\n\ngulp.task('rollup', function() {\n return rollup({\n input: './src/main.js'\n })\n\n // give the file the name you want to output with\n .pipe(source('app.js'))\n\n // and output to ./dist/app.js as normal.\n .pipe(gulp.dest('./dist'));\n});\n```\n\n## Usage with sourcemaps\n```js\n// npm install --save-dev gulp @rollup/stream@1 gulp-sourcemaps vinyl-source-stream vinyl-buffer\n// optional: npm install --save-dev gulp-rename\nvar gulp = require('gulp');\nvar rollup = require('rollup-stream');\nvar sourcemaps = require('gulp-sourcemaps');\n//var rename = require('gulp-rename');\nvar source = require('vinyl-source-stream');\nvar buffer = require('vinyl-buffer');\n\ngulp.task('rollup', function() {\n return rollup({\n input: './src/main.js',\n sourcemap: true,\n format: 'umd'\n })\n\n // point to the entry file.\n .pipe(source('main.js', './src'))\n\n // buffer the output. most gulp plugins, including gulp-sourcemaps, don't support streams.\n .pipe(buffer())\n\n // tell gulp-sourcemaps to load the inline sourcemap produced by rollup-stream.\n .pipe(sourcemaps.init({loadMaps: true}))\n\n // transform the code further here.\n\n // if you want to output with a different name from the input file, use gulp-rename here.\n //.pipe(rename('index.js'))\n\n // write the sourcemap alongside the output file.\n .pipe(sourcemaps.write('.'))\n\n // and output to ./dist/main.js as normal.\n .pipe(gulp.dest('./dist'));\n});\n```\n" }, { "path": "docs/recipes/run-grunt-tasks-from-gulp.md", "content": "# Run Grunt Tasks from Gulp\n\nIt is possible to run Grunt tasks / Grunt plugins from within Gulp. This can be useful during a gradual migration from Grunt to Gulp or if there's a specific plugin that you need. With the described approach no Grunt CLI and no Gruntfile is required.\n\n**This approach requires Grunt >=1.0.0**\n\nvery simple example `gulpfile.js`:\n\n```js\n// npm install gulp grunt grunt-contrib-copy --save-dev\n\nvar gulp = require('gulp');\nvar grunt = require('grunt');\n\ngrunt.initConfig({\n copy: {\n main: {\n src: 'src/*',\n dest: 'dest/'\n }\n }\n});\ngrunt.loadNpmTasks('grunt-contrib-copy');\n\ngulp.task('copy', function (done) {\n grunt.tasks(\n ['copy:main'], //you can add more grunt tasks in this array\n {gruntfile: false}, //don't look for a Gruntfile - there is none. :-)\n function () {done();}\n );\n});\n\n```\n\nNow start the task with:\n`gulp copy`\n\nWith the aforementioned approach the grunt tasks get registered within gulp's task system. **Keep in mind grunt tasks are usually blocking (unlike gulp), therefore no other task (not even a gulp task) can run until a grunt task is completed.**\n\n\n### A few words on alternatives\n\nThere's a *gulpfriendly* node module `gulp-grunt` [available](https://www.npmjs.org/package/gulp-grunt) which takes a different approach. It spawns child processes and within them the grunt tasks are executed. The way it works implies some limitations though:\n\n* It is at the moment not possible to pass options / cli args etc. to the grunt tasks via `gulp-grunt`\n* All grunt tasks have to be defined in a separate Gruntfile\n* You need to have the Grunt CLI installed\n* The output of some grunt tasks gets malformatted (.i.e. color coding).\n" }, { "path": "docs/recipes/running-task-steps-per-folder.md", "content": "# Generating a file per folder\n\nIf you have a set of folders, and wish to perform a set of tasks on each, for instance...\n\n```\n/scripts\n/scripts/jquery/*.js\n/scripts/angularjs/*.js\n```\n\n...and want to end up with...\n\n```\n/scripts\n/scripts/jquery.min.js\n/scripts/angularjs.min.js\n```\n\n...you'll need to do something like the following...\n\n``` javascript\nvar fs = require('fs');\nvar path = require('path');\nvar merge = require('merge-stream');\nvar gulp = require('gulp');\nvar concat = require('gulp-concat');\nvar rename = require('gulp-rename');\nvar uglify = require('gulp-uglify');\n\nvar scriptsPath = 'src/scripts';\n\nfunction getFolders(dir) {\n return fs.readdirSync(dir)\n .filter(function(file) {\n return fs.statSync(path.join(dir, file)).isDirectory();\n });\n}\n\ngulp.task('scripts', function(done) {\n var folders = getFolders(scriptsPath);\n if (folders.length === 0) return done(); // nothing to do!\n var tasks = folders.map(function(folder) {\n return gulp.src(path.join(scriptsPath, folder, '/**/*.js'))\n // concat into foldername.js\n .pipe(concat(folder + '.js'))\n // write to output\n .pipe(gulp.dest(scriptsPath))\n // minify\n .pipe(uglify())\n // rename to folder.min.js\n .pipe(rename(folder + '.min.js'))\n // write to output again\n .pipe(gulp.dest(scriptsPath));\n });\n\n // process all remaining files in scriptsPath root into main.js and main.min.js files\n var root = gulp.src(path.join(scriptsPath, '/*.js'))\n .pipe(concat('main.js'))\n .pipe(gulp.dest(scriptsPath))\n .pipe(uglify())\n .pipe(rename('main.min.js'))\n .pipe(gulp.dest(scriptsPath));\n\n return merge(tasks, root);\n});\n```\n\nA few notes:\n\n- `folders.map` - executes the function once per folder, and returns the async stream\n- `merge` - combines the streams and ends only when all streams emitted end\n" }, { "path": "docs/recipes/server-with-livereload-and-css-injection.md", "content": "# Server with live-reloading and CSS injection\n\nWith [BrowserSync](https://browsersync.io) and gulp, you can easily create a development server that is accessible to any device on the same WiFi network. BrowserSync also has live-reload built in, so there's nothing else to configure.\n\nFirst install the modules:\n\n```sh\n$ npm install --save-dev gulp browser-sync\n```\n\nThen, considering the following file structure...\n\n```\ngulpfile.js\napp/\n styles/\n main.css\n scripts/\n main.js\n index.html\n```\n\n... you can easily serve files from the `app` directory and have all browsers reload when any of them change with the following in `gulpfile.js`:\n\n```js\nvar gulp = require('gulp');\nvar browserSync = require('browser-sync');\nvar reload = browserSync.reload;\n\n// watch files for changes and reload\ngulp.task('serve', function() {\n browserSync({\n server: {\n baseDir: 'app'\n }\n });\n\n gulp.watch(['*.html', 'styles/**/*.css', 'scripts/**/*.js'], {cwd: 'app'}, reload);\n});\n\n```\n\nand including the CSS in `index.html`:\n\n```html\n\n \n ...\n \n ...\n\n```\n\nto serve your files and launch a browser window pointing to the default URL (http://localhost:3000) run:\n\n```bash\ngulp serve\n```\n\n\n## + CSS pre-processors\n\nA common use-case is to reload CSS files after they've been pre-processed. Using Sass as an example, this is how you can instruct browsers to reload the CSS without doing a full-page refresh.\n\nConsidering this updated file structure...\n\n```\ngulpfile.js\napp/\n scss/\n main.scss\n scripts/\n main.js\n index.html\n```\n... you can easily watch Sass files from the `scss` directory and have all browsers reload when any of them change with the following in `gulpfile.js`:\n\n```js\nvar gulp = require('gulp');\nvar sass = require('gulp-ruby-sass');\nvar browserSync = require('browser-sync');\nvar reload = browserSync.reload;\n\ngulp.task('sass', function() {\n return sass('scss/styles.scss')\n .pipe(gulp.dest('app/css'))\n .pipe(reload({ stream:true }));\n});\n\n// watch Sass files for changes, run the Sass preprocessor with the 'sass' task and reload\ngulp.task('serve', gulp.series('sass', function() {\n browserSync({\n server: {\n baseDir: 'app'\n }\n });\n\n gulp.watch('scss/*.scss', gulp.series('sass'));\n}));\n```\n\nand including the pre-processed CSS in `index.html`:\n\n```html\n\n \n ...\n \n ...\n\n```\n\nto serve your files and launch a browser window pointing to the default URL (http://localhost:3000) run:\n\n```bash\ngulp serve\n```\n\n## Extras\n\n- Live reload, CSS injection and scroll/form syncing works seamlessly inside of [BrowserStack](https://www.browserstack.com/) virtual machines.\n- Set `tunnel: true` to view your local site at a public URL (complete with all BrowserSync features).\n" }, { "path": "docs/recipes/sharing-streams-with-stream-factories.md", "content": "# Sharing streams with stream factories\n\nIf you use the same plugins in multiple tasks you might find yourself getting that itch to DRY things up. This method will allow you to create factories to split out your commonly used stream chains.\n\nWe'll use [lazypipe](https://github.com/OverZealous/lazypipe) to get the job done.\n\nThis is our sample file:\n\n```js\nvar gulp = require('gulp');\nvar uglify = require('gulp-uglify');\nvar coffee = require('gulp-coffee');\nvar jshint = require('gulp-jshint');\nvar stylish = require('jshint-stylish');\n\ngulp.task('bootstrap', function() {\n return gulp.src('bootstrap/js/*.js')\n .pipe(jshint())\n .pipe(jshint.reporter(stylish))\n .pipe(uglify())\n .pipe(gulp.dest('public/bootstrap'));\n});\n\ngulp.task('coffee', function() {\n return gulp.src('lib/js/*.coffee')\n .pipe(coffee())\n .pipe(jshint())\n .pipe(jshint.reporter(stylish))\n .pipe(uglify())\n .pipe(gulp.dest('public/js'));\n});\n```\n\nand our file after using lazypipe looks like this:\n\n```js\nvar gulp = require('gulp');\nvar uglify = require('gulp-uglify');\nvar coffee = require('gulp-coffee');\nvar jshint = require('gulp-jshint');\nvar stylish = require('jshint-stylish');\nvar lazypipe = require('lazypipe');\n\n// give lazypipe\nvar jsTransform = lazypipe()\n .pipe(jshint)\n .pipe(jshint.reporter, stylish)\n .pipe(uglify);\n\ngulp.task('bootstrap', function() {\n return gulp.src('bootstrap/js/*.js')\n .pipe(jsTransform())\n .pipe(gulp.dest('public/bootstrap'));\n});\n\ngulp.task('coffee', function() {\n return gulp.src('lib/js/*.coffee')\n .pipe(coffee())\n .pipe(jsTransform())\n .pipe(gulp.dest('public/js'));\n});\n```\n\nYou can see we split out our JavaScript pipeline (JSHint + Uglify) that was being reused in multiple tasks into a factory. These factories can be reused in as many tasks as you want. You can also nest factories and you can chain factories together for great effect. Splitting out each shared pipeline also gives you one central location to modify if you decide to change up your workflow.\n" }, { "path": "docs/recipes/templating-with-swig-and-yaml-front-matter.md", "content": "# Templating with Swig and YAML front-matter\nTemplating can be setup using `gulp-swig` and `gulp-front-matter`:\n\n##### `page.html`\n\n```html\n---\ntitle: Things to do\ntodos:\n - First todo\n - Another todo item\n - A third todo item\n---\n\n \n {{ title }}\n \n \n

{{ title }}

\n
    {% for todo in todos %}\n
  • {{ todo }}
    • \n {% endfor %}
\n \n\n```\n\n##### `gulpfile.js`\n\n```js\nvar gulp = require('gulp');\nvar swig = require('gulp-swig');\nvar frontMatter = require('gulp-front-matter');\n\ngulp.task('compile-page', function() {\n gulp.src('page.html')\n .pipe(frontMatter({ property: 'data' }))\n .pipe(swig())\n .pipe(gulp.dest('build'));\n});\n\ngulp.task('default', ['compile-page']);\n```\n" }, { "path": "docs/recipes/using-multiple-sources-in-one-task.md", "content": "# Using multiple sources in one task\n\n```js\n// npm install --save-dev gulp merge-stream\n\nvar gulp = require('gulp');\nvar merge = require('merge-stream');\n\ngulp.task('test', function() {\n var bootstrap = gulp.src('bootstrap/js/*.js')\n .pipe(gulp.dest('public/bootstrap'));\n\n var jquery = gulp.src('jquery.cookie/jquery.cookie.js')\n .pipe(gulp.dest('public/jquery'));\n\n return merge(bootstrap, jquery);\n});\n```\n\n`gulp.src` will emit files in the order they were added:\n\n```js\n// npm install gulp gulp-concat\n\nvar gulp = require('gulp');\nvar concat = require('gulp-concat');\n\ngulp.task('default', function() {\n return gulp.src(['foo/*', 'bar/*'])\n .pipe(concat('result.txt'))\n .pipe(gulp.dest('build'));\n});\n" }, { "path": "docs/support/for-enterprise.md", "content": "\n\n# Gulp for enterprise\n\nAvailable as part of the Tidelift Subscription.\n\nTidelift is working with the maintainers of Gulp and thousands of other\nopen source projects to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use.\n\nLearn more\n\nRequest a demo\n\n## Enterprise-ready open source software—managed for you\n\nThe Tidelift Subscription is a managed open source subscription for application dependencies covering millions of open source projects across JavaScript, Python, Java, PHP, Ruby, .NET, and more.\n\nYour subscription includes:\n\n* **Security updates**\n\n Tidelift’s security response team coordinates patches for new breaking security vulnerabilities and alerts immediately through a private channel, so your software supply chain is always secure.\n\n* **Licensing verification and indemnification**\n\n Tidelift verifies license information to enable easy policy enforcement and adds intellectual property indemnification to cover creators and users in case something goes wrong. You always have a 100% up-to-date bill of materials for your dependencies to share with your legal team, customers, or partners.\n\n* **Maintenance and code improvement**\n\n Tidelift ensures the software you rely on keeps working as long as you need it to work. Your managed dependencies are actively maintained and we recruit additional maintainers where required.\n\n* **Package selection and version guidance**\n\n We help you choose the best open source packages from the start—and then guide you through updates to stay on the best releases as new issues arise.\n\n* **Roadmap input**\n\n Take a seat at the table with the creators behind the software you use. Tidelift’s participating maintainers earn more income as their software is used by more subscribers, so they’re interested in knowing what you need.\n\n* **Tooling and cloud integration**\n\n Tidelift works with GitHub, GitLab, BitBucket, and more. We support every cloud platform (and other deployment targets, too).\n\nThe end result? All of the capabilities you expect from commercial-grade software, for the full breadth of open source you use. That means less time grappling with esoteric open source trivia, and more time building your own applications—and your business.\n\nLearn more\n\nRequest a demo\n" }, { "path": "docs/why-use-pump/README.md", "content": "# Why Use Pump?\n\nWhen using `pipe` from the Node.js streams, errors are not propagated forward\nthrough the piped streams, and source streams aren’t closed if a destination\nstream closed. The [`pump`][pump] module normalizes these problems and passes\nyou the errors in a callback.\n\n## A common gulpfile example\n\nA common pattern in gulp files is to simply return a Node.js stream, and expect\nthe gulp tool to handle errors.\n\n```javascript\n// example of a common gulpfile\nvar gulp = require('gulp');\nvar uglify = require('gulp-uglify');\n\ngulp.task('compress', function () {\n // returns a Node.js stream, but no handling of error messages\n return gulp.src('lib/*.js')\n .pipe(uglify())\n .pipe(gulp.dest('dist'));\n});\n```\n\n![pipe error](pipe-error.png)\n\nThere’s an error in one of the JavaScript files, but that error message is the\nopposite of helpful. You want to know what file and line contains the error. So\nwhat is this mess?\n\nWhen there’s an error in a stream, the Node.js stream fire the 'error' event,\nbut if there’s no handler for this event, it instead goes to the defined\n[uncaught exception][uncaughtException] handler. The default behavior of the\nuncaught exception handler is documented:\n\n> By default, Node.js handles such exceptions by printing the stack trace to\n> stderr and exiting.\n\n## Handling the Errors\n\nSince allowing the errors to make it to the uncaught exception handler isn’t\nuseful, we should handle the exceptions properly. Let’s give that a quick shot.\n\n```javascript\nvar gulp = require('gulp');\nvar uglify = require('gulp-uglify');\n\ngulp.task('compress', function () {\n return gulp.src('lib/*.js')\n .pipe(uglify())\n .pipe(gulp.dest('dist'))\n .on('error', function(err) {\n console.error('Error in compress task', err.toString());\n });\n});\n```\n\nUnfortunately, Node.js stream’s `pipe` function doesn’t forward errors through\nthe chain, so this error handler only handles the errors given by\n`gulp.dest`. Instead we need to handle errors for each stream.\n\n```javascript\nvar gulp = require('gulp');\nvar uglify = require('gulp-uglify');\n\ngulp.task('compress', function () {\n function createErrorHandler(name) {\n return function (err) {\n console.error('Error from ' + name + ' in compress task', err.toString());\n };\n }\n\n return gulp.src('lib/*.js')\n .on('error', createErrorHandler('gulp.src'))\n .pipe(uglify())\n .on('error', createErrorHandler('uglify'))\n .pipe(gulp.dest('dist'))\n .on('error', createErrorHandler('gulp.dest'));\n});\n```\n\nThis is a lot of complexity to add in each of your gulp tasks, and it’s easy to\nforget to do it. In addition, it’s still not perfect, as it doesn’t properly\nsignal to gulp’s task system that the task has failed. We can fix this, and we\ncan handle the other pesky issues with error propogations with streams, but it’s\neven more work!\n\n## Using pump\n\nThe [`pump`][pump] module is a cheat code of sorts. It’s a wrapper around the\n`pipe` functionality that handles these cases for you, so you can stop hacking\non your gulpfiles, and get back to hacking new features into your app.\n\n```javascript\nvar gulp = require('gulp');\nvar uglify = require('gulp-uglify');\nvar pump = require('pump');\n\ngulp.task('compress', function (cb) {\n pump([\n gulp.src('lib/*.js'),\n uglify(),\n gulp.dest('dist')\n ],\n cb\n );\n});\n```\n\nThe gulp task system provides a gulp task with a callback, which can signal\nsuccessful task completion (being called with no arguments), or a task failure\n(being called with an Error argument). Fortunately, this is the exact same\nformat `pump` uses!\n\n![pump error](pump-error.png)\n\nNow it’s very clear what plugin the error was from, what the error actually was,\nand from what file and line number.\n\n[pump]: https://github.com/mafintosh/pump\n[uncaughtException]: https://nodejs.org/api/process.html#process_event_uncaughtexception\n" }, { "path": "docs/writing-a-plugin/README.md", "content": "# Writing a plugin\n\nIf you plan to create your own Gulp plugin, you will save time by reading the full documentation.\n\n* [Guidelines](guidelines.md) (a MUST read)\n* [Using buffers](using-buffers.md)\n* [Dealing with streams](dealing-with-streams.md)\n* [Testing](testing.md)\n\n## What it does\n\n### Streaming file objects\n\nA gulp plugin always returns a stream in [object mode](https://nodejs.org/api/stream.html#stream_object_mode) that does the following:\n\n1. Takes in [vinyl File objects](https://github.com/gulpjs/vinyl)\n2. Outputs [vinyl File objects](https://github.com/gulpjs/vinyl) (via `transform.push()` and/or the plugin's callback function)\n\nThese are known as [transform streams](https://nodejs.org/api/stream.html#stream_class_stream_transform_1)\n(also sometimes called through streams).\nTransform streams are streams that are readable and writable; they manipulate objects as they're being passed through.\n\nAll gulp plugins essentially boil down to this:\n```js\nvar Transform = require('stream').Transform;\n\nmodule.exports = function() {\n // Monkey patch Transform or create your own subclass,\n // implementing `_transform()` and optionally `_flush()`\n var transformStream = new Transform({objectMode: true});\n /**\n * @param {Buffer|string} file\n * @param {string=} encoding - ignored if file contains a Buffer\n * @param {function(Error, object)} callback - Call this function (optionally with an\n * error argument and data) when you are done processing the supplied chunk.\n */\n transformStream._transform = function(file, encoding, callback) {\n var error = null,\n output = doSomethingWithTheFile(file);\n callback(error, output);\n };\n\n return transformStream;\n};\n```\n\nAlternatively you could pass your transform and flush functions to the `Transform` constructor or even extend `Transform` with ES6 classes, as described by the [Node.js docs](https://nodejs.org/docs/latest/api/stream.html#stream_implementing_a_transform_stream). However, many plugins prefer to use the [through2](https://github.com/rvagg/through2/) module to simplify their code:\n\n```js\nvar through = require('through2'); // npm install --save through2\n\nmodule.exports = function() {\n return through.obj(function(file, encoding, callback) {\n callback(null, doSomethingWithTheFile(file));\n });\n};\n```\n\nThe stream returned from `through()` (and `this` within your transform function) is an instance of the [Transform](https://github.com/iojs/readable-stream/blob/master/lib/_stream_transform.js)\nclass, which extends [Duplex](https://github.com/iojs/readable-stream/blob/master/lib/_stream_duplex.js),\n[Readable](https://github.com/iojs/readable-stream/blob/master/lib/_stream_readable.js)\n(and parasitically from Writable) and ultimately [Stream](https://nodejs.org/api/stream.html).\nIf you need to parse additional options, you can call the `through()` function directly:\n\n```js\n return through({objectMode: true /* other options... */}, function(file, encoding, callback) { ...\n```\n\nSupported options include:\n\n* highWaterMark (defaults to 16)\n* defaultEncoding (defaults to 'utf8')\n* encoding - 'utf8', 'base64', 'utf16le', 'ucs2' etc.\n If specified, a [StringDecoder](https://github.com/rvagg/string_decoder/blob/master/index.js) `decoder` will be attached to the stream.\n* readable {boolean}\n* writable {boolean}\n* allowHalfOpen {boolean} If set to false, then the stream will automatically end the readable side when the writable side ends and vice versa.\n\n### Modifying file content\n\nThe function parameter that you pass to `through.obj()` is a [_transform](https://nodejs.org/api/stream.html#stream_transform_transform_chunk_encoding_callback)\nfunction which will operate on the input `file`. You may also provide an optional [_flush](https://nodejs.org/api/stream.html#stream_transform_flush_callback)\nfunction if you need to emit a bit more data at the end of the stream.\n\nFrom within your transform function call `this.push(file)` 0 or more times to pass along transformed/cloned files.\nYou don't need to call `this.push(file)` if you provide all output to the `callback()` function.\n\nCall the `callback` function only when the current file (stream/buffer) is completely consumed.\nIf an error is encountered, pass it as the first argument to the callback, otherwise set it to null.\nIf you have passed all output data to `this.push()` you can omit the second argument to the callback.\n\nGenerally, a gulp plugin would update `file.contents` and then choose to either:\n\n - call `callback(null, file)`\n _or_\n - make one call to `this.push(file)`\n\nIf a plugin creates multiple files from a single input file, it would make multiple calls to `this.push()` - eg:\n\n```js\nmodule.exports = function() {\n /**\n * @this {Transform}\n */\n var transform = function(file, encoding, callback) {\n var files = splitFile(file);\n this.push(files[0]);\n this.push(files[1]);\n callback();\n };\n\n return through.obj(transform);\n};\n```\n\nThe [gulp-unzip](https://github.com/suisho/gulp-unzip/blob/master/index.js) plugin provides a good example of making\nmultiple calls to `push()`. It also uses a chunk transform stream with a `_flush()` function _within_ the Vinyl transform function.\n\nVinyl files can have 3 possible forms for the contents attribute:\n\n- [Streams](dealing-with-streams.md)\n- [Buffers](using-buffers.md)\n- Empty (null) - Useful for things like rimraf, clean, where contents is not needed.\n\nA simple example showing how to detect & handle each form is provided below, for a more detailed explanation of each\napproach follow the links above.\n\n```js\nvar PluginError = require('plugin-error');\n\n// consts\nvar PLUGIN_NAME = 'gulp-example';\n\nmodule.exports = function() {\n return through.obj(function(file, encoding, callback) {\n if (file.isNull()) {\n // nothing to do\n return callback(null, file);\n }\n\n if (file.isStream()) {\n // file.contents is a Stream - https://nodejs.org/api/stream.html\n this.emit('error', new PluginError(PLUGIN_NAME, 'Streams not supported!'));\n\n // or, if you can handle Streams:\n //file.contents = file.contents.pipe(...\n //return callback(null, file);\n } else if (file.isBuffer()) {\n // file.contents is a Buffer - https://nodejs.org/api/buffer.html\n this.emit('error', new PluginError(PLUGIN_NAME, 'Buffers not supported!'));\n\n // or, if you can handle Buffers:\n //file.contents = ...\n //return callback(null, file);\n }\n });\n};\n```\n\nNote: When looking through the code of other gulp plugins (and the example above), you may notice that the transform functions will return the result of the callback:\n\n```js\nreturn callback(null, file);\n```\n\n...don't be confused - gulp ignores any return value of your transform function. The code above is simply a short-hand form of:\n\n```js\nif (someCondition) {\n callback(null, file);\n return;\n}\n// further execution...\n```\n\n\n## Useful resources\n\n* [File object](https://github.com/gulpjs/vinyl)\n* [PluginError](https://github.com/gulpjs/plugin-error)\n* [through2](https://www.npmjs.com/package/through2)\n* [bufferstreams](https://www.npmjs.com/package/bufferstreams)\n\n\n## Sample plugins\n\n* [sindresorhus' gulp plugins](https://github.com/search?q=%40sindresorhus+gulp-)\n* [contra's gulp plugins](https://github.com/search?q=%40contra+gulp-)\n* [gulp-replace](https://github.com/lazd/gulp-replace)\n\n\n## About streams\n\nIf you're unfamiliar with streams, you will need to read up on them:\n\n* https://www.freecodecamp.org/news/node-js-streams-everything-you-need-to-know-c9141306be93/\n* https://nodejs.org/api/stream.html\n\nOther libraries that are not file manipulating through streams but are made for use with gulp are tagged with the [gulpfriendly](https://npmjs.org/browse/keyword/gulpfriendly) keyword on npm.\n" }, { "path": "docs/writing-a-plugin/dealing-with-streams.md", "content": "# Dealing with streams\n\n> It is highly recommended to write plugins supporting streams. Here is some information on creating a gulp plugin that supports streams.\n\n> Make sure to follow the best practices regarding error handling and add a line that makes the gulp plugin re-emit the first error caught during the transformation of the content.\n\n[Writing a Plugin](README.md) > Writing stream based plugins\n\n## Dealing with streams\n\nLet's implement a plugin prepending some text to files. This plugin supports all possible forms of `file.contents`.\n\n```js\nvar through = require('through2');\nvar PluginError = require('plugin-error');\n\n// consts\nconst PLUGIN_NAME = 'gulp-prefixer';\n\nfunction prefixStream(prefixText) {\n var stream = through();\n stream.write(prefixText);\n return stream;\n}\n\n// plugin level function (dealing with files)\nfunction gulpPrefixer(prefixText) {\n if (!prefixText) {\n throw new PluginError(PLUGIN_NAME, 'Missing prefix text!');\n }\n\n prefixText = new Buffer(prefixText); // allocate ahead of time\n\n // creating a stream through which each file will pass\n var stream = through.obj(function(file, enc, cb) {\n if (file.isBuffer()) {\n this.emit('error', new PluginError(PLUGIN_NAME, 'Buffers not supported!'));\n return cb();\n }\n\n if (file.isStream()) {\n // define the streamer that will transform the content\n var streamer = prefixStream(prefixText);\n // catch errors from the streamer and emit a gulp plugin error\n streamer.on('error', this.emit.bind(this, 'error'));\n // start the transformation\n file.contents = file.contents.pipe(streamer);\n }\n\n // make sure the file goes through the next gulp plugin\n this.push(file);\n // tell the stream engine that we are done with this file\n cb();\n });\n\n // returning the file stream\n return stream;\n}\n\n// exporting the plugin main function\nmodule.exports = gulpPrefixer;\n```\n\nThe above plugin can be used like this:\n\n```js\nvar gulp = require('gulp');\nvar gulpPrefixer = require('gulp-prefixer');\n\ngulp.src('files/**/*.js', { buffer: false })\n .pipe(gulpPrefixer('prepended string'))\n .pipe(gulp.dest('modified-files'));\n```\n\n## Some plugins using streams\n\n* [gulp-svgicons2svgfont](https://github.com/nfroidure/gulp-svgiconstosvgfont)\n" }, { "path": "docs/writing-a-plugin/guidelines.md", "content": "# Guidelines\n\n> While these guidelines are totally optional, we **HIGHLY** recommend that everyone follows them. Nobody wants to use a bad plugin. These guidelines will actually help make your life easier by giving you assurance that your plugin fits well within gulp.\n\n[Writing a Plugin](README.md) > Guidelines\n\n1. Your plugin should not do something that can be done easily with an existing node module\n - For example: deleting a folder does not need to be a gulp plugin. Use a module like [del](https://github.com/sindresorhus/del) within a task instead.\n - Wrapping every possible thing just for the sake of wrapping it will pollute the ecosystem with low quality plugins that don't make sense within the gulp paradigm.\n - gulp plugins are for file-based operations! If you find yourself shoehorning a complex process into streams just make a normal node module instead.\n - A good example of a gulp plugin would be something like gulp-coffee. The coffee-script module does not work with Vinyl out of the box, so we wrap it to add this functionality and abstract away pain points to make it work well within gulp.\n1. Your plugin should only do **one thing**, and do it well.\n - Avoid config options that make your plugin do completely different tasks\n - For example: A JS minification plugin should not have an option that adds a header as well\n1. Your plugin shouldn't do things that other plugins are responsible for\n - It should not concat, [gulp-concat](https://github.com/contra/gulp-concat) does that\n - It should not add headers, [gulp-header](https://www.npmjs.com/package/gulp-header) does that\n - It should not add footers, [gulp-footer](https://www.npmjs.com/package/gulp-footer) does that\n - If it's a common but optional use case, document that your plugin is often used with another plugin\n - Make use of other plugins within your plugin! This reduces the amount of code you have to write and ensures a stable ecosystem.\n1. Your plugin **must be tested**\n - Testing a gulp plugin is easy, you don't even need gulp to test it\n - Look at other plugins for examples\n1. Add `gulpplugin` as a keyword in your `package.json` so you show up on our search\n1. Your plugin API should be a function that returns a stream\n - If you need to store state somewhere, do it internally\n - If you need to pass state/options between plugins, tack it on the file object\n1. Do not throw errors inside a stream\n - Instead, you should emit it as an **error** event.\n - If you encounter an error **outside** the stream, such as invalid configuration while creating the stream, you may throw it.\n1. Prefix any errors with the name of your plugin\n - For example: `gulp-replace: Cannot do regexp replace on a stream`\n - Use [PluginError](https://github.com/gulpjs/plugin-error) module to make this easy\n1. Name your plugin appropriately: it should begin with \"gulp-\" if it is a gulp plugin\n - If it is not a gulp plugin, it should not begin with \"gulp-\"\n1. The type of `file.contents` should always be the same going out as it was when it came in\n - If file.contents is null (non-read) just ignore the file and pass it along\n - If file.contents is a Stream and you don't support that just emit an error\n - Do not buffer a stream to shoehorn your plugin to work with streams. This will cause horrible things to happen.\n1. Do not pass the `file` object downstream until you are done with it\n1. Use [`file.clone()`](https://github.com/gulpjs/vinyl#clone) when cloning a file or creating a new one based on a file.\n1. Use modules from our [recommended modules page](recommended-modules.md) to make your life easier\n1. Do NOT require `gulp` as a dependency or peerDependency in your plugin\n - Using gulp to test or automate your plugin workflow is totally cool, just make sure you put it as a devDependency\n - Requiring gulp as a dependency of your plugin means that anyone who installs your plugin is also installing a new gulp and its entire dependency tree.\n - There is no reason you should be using gulp within your actual plugin code. If you find yourself doing this open an issue so we can help you out.\n\n## Why are these guidelines so strict?\n\ngulp aims to be simple for users. By providing strict guidelines we are able to provide a consistent and high-quality ecosystem for everyone. While this does add a little more work and thought for plugin authors, it removes a lot of problems later down the road.\n\n### What happens if I don't follow them?\n\nnpm is open for everyone, and you are free to make whatever you want but these guidelines were prescribed for a reason. There are acceptance tests coming soon that will be integrated into the plugin search. If you fail to adhere to the plugin guidelines it will be publicly visible/sortable via a scoring system. People will always prefer to use plugins that match \"the gulp way\".\n\n### What does a good plugin look like?\n\n```js\n// through2 is a thin wrapper around node transform streams\nvar through = require('through2');\nvar PluginError = require('plugin-error');\n\n// Consts\nconst PLUGIN_NAME = 'gulp-prefixer';\n\nfunction prefixStream(prefixText) {\n var stream = through();\n stream.write(prefixText);\n return stream;\n}\n\n// Plugin level function(dealing with files)\nfunction gulpPrefixer(prefixText) {\n\n if (!prefixText) {\n throw new PluginError(PLUGIN_NAME, 'Missing prefix text!');\n }\n prefixText = new Buffer(prefixText); // allocate ahead of time\n\n // Creating a stream through which each file will pass\n return through.obj(function(file, enc, cb) {\n if (file.isNull()) {\n // return empty file\n return cb(null, file);\n }\n if (file.isBuffer()) {\n file.contents = Buffer.concat([prefixText, file.contents]);\n }\n if (file.isStream()) {\n file.contents = file.contents.pipe(prefixStream(prefixText));\n }\n\n cb(null, file);\n\n });\n\n}\n\n// Exporting the plugin main function\nmodule.exports = gulpPrefixer;\n```\n" }, { "path": "docs/writing-a-plugin/recommended-modules.md", "content": "# Recommended Modules\n\n> Sticking to this curated list of recommended modules will make sure you don't violate the plugin guidelines and ensure consistency across plugins.\n\n[Writing a Plugin](README.md) > Recommended Modules\n\n#### Replacing a file extension\n\nUse [replace-ext](https://github.com/wearefractal/replace-ext)\n\n#### Errors\n\nUse [plugin-error](https://github.com/gulpjs/plugin-error)\n\n#### String colors\n\nUse [chalk](https://github.com/sindresorhus/chalk)\n\n#### Date formatting\n\nUse [dateformat](https://github.com/felixge/node-dateformat)\n\nDisplay as `HH:MM:ss`\n" }, { "path": "docs/writing-a-plugin/testing.md", "content": "# Testing\n\n> Testing your plugin is the only way to ensure quality. It brings confidence to your users and makes your life easier.\n\n[Writing a Plugin](README.md) > Testing\n\n\n## Tooling\n\nMost plugins use [mocha](https://github.com/mochajs/mocha), [should](https://github.com/shouldjs/should.js) and [event-stream](https://github.com/dominictarr/event-stream) to help them test. The following examples will use these tools.\n\n\n## Testing plugins for streaming mode\n\n```js\nvar assert = require('assert');\nvar es = require('event-stream');\nvar File = require('vinyl');\nvar prefixer = require('../');\n\ndescribe('gulp-prefixer', function() {\n describe('in streaming mode', function() {\n\n it('should prepend text', function(done) {\n\n // create the fake file\n var fakeFile = new File({\n contents: es.readArray(['stream', 'with', 'those', 'contents'])\n });\n\n // Create a prefixer plugin stream\n var myPrefixer = prefixer('prependthis');\n\n // write the fake file to it\n myPrefixer.write(fakeFile);\n\n // wait for the file to come back out\n myPrefixer.once('data', function(file) {\n // make sure it came out the same way it went in\n assert(file.isStream());\n\n // buffer the contents to make sure it got prepended to\n file.contents.pipe(es.wait(function(err, data) {\n // check the contents\n assert.equal(data, 'prependthisstreamwiththosecontents');\n done();\n }));\n });\n\n });\n\n });\n});\n```\n\n\n## Testing plugins for buffer mode\n\n```js\nvar assert = require('assert');\nvar es = require('event-stream');\nvar File = require('vinyl');\nvar prefixer = require('../');\n\ndescribe('gulp-prefixer', function() {\n describe('in buffer mode', function() {\n\n it('should prepend text', function(done) {\n\n // create the fake file\n var fakeFile = new File({\n contents: new Buffer('abufferwiththiscontent')\n });\n\n // Create a prefixer plugin stream\n var myPrefixer = prefixer('prependthis');\n\n // write the fake file to it\n myPrefixer.write(fakeFile);\n\n // wait for the file to come back out\n myPrefixer.once('data', function(file) {\n // make sure it came out the same way it went in\n assert(file.isBuffer());\n\n // check the contents\n assert.equal(file.contents.toString('utf8'), 'prependthisabufferwiththiscontent');\n done();\n });\n\n });\n\n });\n});\n```\n\n\n## Some plugins with high-quality Testing\n\n* [gulp-cat](https://github.com/ben-eb/gulp-cat/blob/master/test.js)\n* [gulp-concat](https://github.com/contra/gulp-concat/blob/master/test/main.js)\n" }, { "path": "docs/writing-a-plugin/using-buffers.md", "content": "# Using buffers\n\n> Here is some information on creating gulp plugin that manipulates buffers.\n\n[Writing a Plugin](README.md) > Using buffers\n\n## Using buffers\nIf your plugin is relying on a buffer based library, you will probably choose to base your plugin around file.contents as a buffer. Let's implement a plugin prepending some text to files:\n\n```js\nvar through = require('through2');\nvar PluginError = require('plugin-error');\n\n// consts\nconst PLUGIN_NAME = 'gulp-prefixer';\n\n// plugin level function (dealing with files)\nfunction gulpPrefixer(prefixText) {\n if (!prefixText) {\n throw new PluginError(PLUGIN_NAME, 'Missing prefix text!');\n }\n\n prefixText = new Buffer(prefixText); // allocate ahead of time\n\n // creating a stream through which each file will pass\n var stream = through.obj(function(file, enc, cb) {\n if (file.isStream()) {\n this.emit('error', new PluginError(PLUGIN_NAME, 'Streams are not supported!'));\n return cb();\n }\n\n if (file.isBuffer()) {\n file.contents = Buffer.concat([prefixText, file.contents]);\n }\n\n // make sure the file goes through the next gulp plugin\n this.push(file);\n\n // tell the stream engine that we are done with this file\n cb();\n });\n\n // returning the file stream\n return stream;\n};\n\n// exporting the plugin main function\nmodule.exports = gulpPrefixer;\n```\n\nThe above plugin can be used like this:\n\n```js\nvar gulp = require('gulp');\nvar gulpPrefixer = require('gulp-prefixer');\n\ngulp.src('files/**/*.js')\n .pipe(gulpPrefixer('prepended string'))\n .pipe(gulp.dest('modified-files'));\n```\n\n## Handling streams\n\nUnfortunately, the above plugin will error when using gulp.src in non-buffered (streaming) mode. You should support streams too if possible. See [Dealing with streams](dealing-with-streams.md) for more information.\n\n## Some plugins based on buffers\n\n* [gulp-coffee](https://github.com/contra/gulp-coffee)\n* [gulp-svgmin](https://github.com/ben-eb/gulp-svgmin)\n* [gulp-marked](https://github.com/lmtm/gulp-marked)\n* [gulp-svg2ttf](https://github.com/nfroidure/gulp-svg2ttf)\n" }, { "path": "index.js", "content": "'use strict';\n\nvar util = require('util');\nvar Undertaker = require('undertaker');\nvar vfs = require('vinyl-fs');\nvar watch = require('glob-watcher');\n\nfunction Gulp() {\n Undertaker.call(this);\n\n // Bind the functions for destructuring\n this.watch = this.watch.bind(this);\n this.task = this.task.bind(this);\n this.series = this.series.bind(this);\n this.parallel = this.parallel.bind(this);\n this.registry = this.registry.bind(this);\n this.tree = this.tree.bind(this);\n this.lastRun = this.lastRun.bind(this);\n this.src = this.src.bind(this);\n this.dest = this.dest.bind(this);\n this.symlink = this.symlink.bind(this);\n}\nutil.inherits(Gulp, Undertaker);\n\nGulp.prototype.src = vfs.src;\nGulp.prototype.dest = vfs.dest;\nGulp.prototype.symlink = vfs.symlink;\nGulp.prototype.watch = function(glob, opt, task) {\n if (typeof opt === 'string' || typeof task === 'string' ||\n Array.isArray(opt) || Array.isArray(task)) {\n throw new Error('watching ' + glob + ': watch task has to be ' +\n 'a function (optionally generated by using gulp.parallel ' +\n 'or gulp.series)');\n }\n\n if (typeof opt === 'function') {\n task = opt;\n opt = {};\n }\n\n opt = opt || {};\n\n var fn;\n if (typeof task === 'function') {\n fn = this.parallel(task);\n }\n\n return watch(glob, opt, fn);\n};\n\n// Let people use this class from our instance\nGulp.prototype.Gulp = Gulp;\n\nvar inst = new Gulp();\nmodule.exports = inst;\n" }, { "path": "index.mjs", "content": "import gulp from \"./index.js\";\n\n// These are bound to the gulp instance in our CommonJS file\n// so it is okay to reassign them to export\nexport const watch = gulp.watch;\nexport const task = gulp.task;\nexport const series = gulp.series;\nexport const parallel = gulp.parallel;\nexport const registry = gulp.registry;\nexport const tree = gulp.tree;\nexport const lastRun = gulp.lastRun;\nexport const src = gulp.src;\nexport const dest = gulp.dest;\nexport const symlink = gulp.symlink;\n\nexport default gulp;\n" }, { "path": "package.json", "content": "{\n \"name\": \"gulp\",\n \"version\": \"5.0.1\",\n \"description\": \"The streaming build system.\",\n \"homepage\": \"https://gulpjs.com\",\n \"author\": \"Gulp Team (https://gulpjs.com/)\",\n \"contributors\": [\n \"Eric Schoffstall \",\n \"Blaine Bublitz \"\n ],\n \"repository\": \"gulpjs/gulp\",\n \"license\": \"MIT\",\n \"engines\": {\n \"node\": \">=10.13.0\"\n },\n \"main\": \"index.js\",\n \"exports\": {\n \".\": {\n \"import\": \"./index.mjs\",\n \"require\": \"./index.js\"\n }\n },\n \"files\": [\n \"LICENSE\",\n \"index.js\",\n \"index.mjs\",\n \"bin\"\n ],\n \"bin\": {\n \"gulp\": \"./bin/gulp.js\"\n },\n \"scripts\": {\n \"lint\": \"eslint .\",\n \"pretest\": \"npm run lint\",\n \"test\": \"nyc mocha --async-only\"\n },\n \"dependencies\": {\n \"glob-watcher\": \"^6.0.0\",\n \"gulp-cli\": \"^3.1.0\",\n \"undertaker\": \"^2.0.0\",\n \"vinyl-fs\": \"^4.0.2\"\n },\n \"devDependencies\": {\n \"eslint\": \"^7.0.0\",\n \"eslint-config-gulp\": \"^5.0.0\",\n \"eslint-plugin-node\": \"^11.1.0\",\n \"expect\": \"^27.0.0\",\n \"mkdirp\": \"^3.0.1\",\n \"mocha\": \"^8.0.0\",\n \"nyc\": \"^15.0.0\",\n \"rimraf\": \"^3.0.0\"\n },\n \"nyc\": {\n \"reporter\": [\n \"lcov\",\n \"text-summary\"\n ]\n },\n \"prettier\": {\n \"singleQuote\": true\n },\n \"keywords\": [\n \"build\",\n \"stream\",\n \"system\",\n \"make\",\n \"tool\",\n \"asset\",\n \"pipeline\",\n \"series\",\n \"parallel\",\n \"streaming\"\n ]\n}\n" }, { "path": "test/.gitkeep", "content": "" }, { "path": "test/dest.js", "content": "'use strict';\n\nvar fs = require('fs');\nvar path = require('path');\n\nvar expect = require('expect');\nvar rimraf = require('rimraf');\n\nvar gulp = require('../');\n\nvar outpath = path.join(__dirname, './out-fixtures');\n\ndescribe('gulp.dest()', function() {\n before(function () {\n if (process.versions.node.startsWith(\"10.\")) {\n this.skip();\n return;\n }\n });\n\n beforeEach(rimraf.bind(null, outpath));\n afterEach(rimraf.bind(null, outpath));\n\n it('should return a stream', function(done) {\n var stream = gulp.dest(path.join(__dirname, './fixtures/'));\n expect(stream).toBeDefined();\n expect(stream.on).toBeDefined();\n done();\n });\n\n it('should return a output stream that writes files', function(done) {\n var instream = gulp.src('./fixtures/**/*.txt', { cwd: __dirname });\n var outstream = gulp.dest(outpath);\n instream.pipe(outstream);\n\n var expectedContents = Buffer.from('this is a test');\n\n outstream.on('error', done);\n outstream.on('data', function(file) {\n // Data should be re-emitted right\n expect(file).toBeDefined();\n expect(file.path).toBeDefined();\n expect(file.contents).toBeDefined();\n expect(file.path).toEqual(path.join(outpath, './copy/example.txt'));\n expect(file.contents).toEqual(expectedContents);\n });\n outstream.on('end', function() {\n fs.readFile(path.join(outpath, 'copy', 'example.txt'), function(err, contents) {\n expect(err).toBeNull();\n expect(contents).toBeDefined();\n expect(contents).toEqual(expectedContents);\n done();\n });\n });\n });\n\n it('should return a output stream that does not write non-read files', function(done) {\n var instream = gulp.src('./fixtures/**/*.txt', { read: false, cwd: __dirname });\n var outstream = gulp.dest(outpath);\n instream.pipe(outstream);\n\n outstream.on('error', done);\n outstream.on('data', function(file) {\n // Data should be re-emitted right\n expect(file).toBeDefined();\n expect(file.path).toBeDefined();\n expect(file.contents).toBeNull();\n expect(file.path).toEqual(path.join(outpath, './copy/example.txt'));\n });\n outstream.on('end', function() {\n fs.readFile(path.join(outpath, 'copy', 'example.txt'), function(err, contents) {\n expect(err).toBeDefined();\n expect(contents).toBeUndefined();\n done();\n });\n });\n });\n\n it('should return a output stream that writes streaming files', function(done) {\n var instream = gulp.src('./fixtures/**/*.txt', { buffer: false, cwd: __dirname });\n var outstream = instream.pipe(gulp.dest(outpath));\n\n outstream.on('error', done);\n outstream.on('data', function(file) {\n // Data should be re-emitted right\n expect(file).toBeDefined();\n expect(file.path).toBeDefined();\n expect(file.contents).toBeDefined();\n expect(file.path).toEqual(path.join(outpath, './copy/example.txt'));\n });\n outstream.on('end', function() {\n fs.readFile(path.join(outpath, 'copy', 'example.txt'), function(err, contents) {\n expect(err).toBeNull();\n expect(contents).toBeDefined();\n expect(contents).toEqual(Buffer.from('this is a test'));\n done();\n });\n });\n });\n\n it('should return a output stream that writes streaming files into new directories', function(done) {\n testWriteDir({ cwd: __dirname }, done);\n });\n\n it('should return a output stream that writes streaming files into new directories (buffer: false)', function(done) {\n testWriteDir({ buffer: false, cwd: __dirname }, done);\n });\n\n it('should return a output stream that writes streaming files into new directories (read: false)', function(done) {\n testWriteDir({ read: false, cwd: __dirname }, done);\n });\n\n it('should return a output stream that writes streaming files into new directories (read: false, buffer: false)', function(done) {\n testWriteDir({ buffer: false, read: false, cwd: __dirname }, done);\n });\n\n function testWriteDir(srcOptions, done) {\n var instream = gulp.src('./fixtures/stuff', srcOptions);\n var outstream = instream.pipe(gulp.dest(outpath));\n\n outstream.on('error', done);\n outstream.on('data', function(file) {\n // Data should be re-emitted right\n expect(file).toBeDefined();\n expect(file.path).toBeDefined();\n expect(file.path).toEqual(path.join(outpath, './stuff'));\n });\n outstream.on('end', function() {\n fs.exists(path.join(outpath, 'stuff'), function(exists) {\n expect(exists).toBeDefined();\n done();\n });\n });\n }\n\n});\n" }, { "path": "test/fixtures/copy/example.txt", "content": "this is a test" }, { "path": "test/fixtures/gulpfiles/cjs/gulpfile.cjs", "content": "exports.default = function (done) {\n done()\n}\n" }, { "path": "test/fixtures/gulpfiles/mjs/gulpfile.mjs", "content": "import assert from \"assert\";\nimport EventEmitter from \"events\";\n\nimport gulp, {\n watch,\n task,\n series,\n parallel,\n registry,\n tree,\n lastRun,\n src,\n dest,\n symlink,\n} from 'gulp';\n\nexport default function (done) {\n assert(typeof watch === 'function');\n assert(typeof task === 'function');\n assert(typeof series === 'function');\n assert(typeof parallel === 'function');\n assert(typeof registry === 'function');\n assert(typeof tree === 'function');\n assert(typeof lastRun === 'function');\n assert(typeof src === 'function');\n assert(typeof dest === 'function');\n assert(typeof symlink === 'function');\n assert(gulp instanceof EventEmitter);\n done();\n}\n" }, { "path": "test/fixtures/stuff/run.dmc", "content": "" }, { "path": "test/fixtures/stuff/test.dmc", "content": "" }, { "path": "test/fixtures/test/run.jade", "content": "test template" }, { "path": "test/fixtures/test.coffee", "content": "this is a test" }, { "path": "test/index.test.js", "content": "'use strict';\n\nvar cp = require('child_process');\nvar path = require('path');\n\nvar expect = require('expect');\n\nvar gulp = require('../');\n\ndescribe('gulp', function() {\n\n describe('hasOwnProperty', function() {\n it('src', function(done) {\n expect(Object.prototype.hasOwnProperty.call(gulp, 'src')).toEqual(true);\n done();\n });\n\n it('dest', function(done) {\n expect(Object.prototype.hasOwnProperty.call(gulp, 'dest')).toEqual(true);\n done();\n });\n\n it('symlink', function(done) {\n expect(Object.prototype.hasOwnProperty.call(gulp, 'symlink')).toEqual(true);\n done();\n });\n\n it('watch', function(done) {\n expect(Object.prototype.hasOwnProperty.call(gulp, 'watch')).toEqual(true);\n done();\n });\n\n it('task', function(done) {\n expect(Object.prototype.hasOwnProperty.call(gulp, 'task')).toEqual(true);\n done();\n });\n\n it('series', function(done) {\n expect(Object.prototype.hasOwnProperty.call(gulp, 'series')).toEqual(true);\n done();\n });\n\n it('parallel', function(done) {\n expect(Object.prototype.hasOwnProperty.call(gulp, 'parallel')).toEqual(true);\n done();\n });\n\n it('tree', function(done) {\n expect(Object.prototype.hasOwnProperty.call(gulp, 'tree')).toEqual(true);\n done();\n });\n\n it('lastRun', function(done) {\n expect(Object.prototype.hasOwnProperty.call(gulp, 'lastRun')).toEqual(true);\n done();\n });\n\n it('registry', function(done) {\n expect(Object.prototype.hasOwnProperty.call(gulp, 'registry')).toEqual(true);\n done();\n });\n });\n\n it('can run against gulpfile.cjs', function (done) {\n this.timeout(5000);\n\n var cli = path.join(__dirname, '../bin/gulp.js');\n var opts = { cwd: path.join(__dirname, 'fixtures/gulpfiles/cjs' ) };\n cp.exec('node ' + cli, opts, function (err, stdout, stderr) {\n expect(err).toBeNull();\n expect(stdout).toMatch('gulpfile.cjs');\n expect(stderr).toEqual('');\n done();\n });\n });\n\n it('can run against gulpfile.mjs', function (done) {\n // Node v10 didn't support `exports` in package.json\n if (process.version.startsWith('v10.')) {\n this.skip();\n }\n\n this.timeout(5000);\n\n var cli = path.join(__dirname, '../bin/gulp.js');\n var opts = { cwd: path.join(__dirname, 'fixtures/gulpfiles/mjs' ) };\n cp.exec('node ' + cli, opts, function (err, stdout, stderr) {\n expect(err).toBeNull();\n expect(stdout).toMatch('gulpfile.mjs');\n expect(stderr).toEqual('');\n done();\n });\n });\n});\n" }, { "path": "test/src.js", "content": "'use strict';\n\nvar path = require('path');\n\nvar expect = require('expect');\n\nvar gulp = require('../');\n\ndescribe('gulp.src()', function() {\n before(function () {\n if (process.versions.node.startsWith(\"10.\")) {\n this.skip();\n return;\n }\n });\n\n it('should return a stream', function(done) {\n var stream = gulp.src('./fixtures/*.coffee', { cwd: __dirname });\n expect(stream).toBeDefined();\n expect(stream.on).toBeDefined();\n done();\n });\n\n it('should return a input stream from a flat glob', function(done) {\n var stream = gulp.src('./fixtures/*.coffee', { cwd: __dirname });\n stream.on('error', done);\n stream.on('data', function(file) {\n expect(file).toBeDefined();\n expect(file.path).toBeDefined();\n expect(file.contents).toBeDefined();\n expect(file.path).toEqual(path.join(__dirname, './fixtures/test.coffee'));\n expect(file.contents).toEqual(Buffer.from('this is a test'));\n });\n stream.on('end', function() {\n done();\n });\n });\n\n it('should return a input stream for multiple globs', function(done) {\n var globArray = [\n './fixtures/stuff/run.dmc',\n './fixtures/stuff/test.dmc',\n ];\n var stream = gulp.src(globArray, { cwd: __dirname });\n\n var files = [];\n stream.on('error', done);\n stream.on('data', function(file) {\n expect(file).toBeDefined();\n expect(file.path).toBeDefined();\n files.push(file);\n });\n stream.on('end', function() {\n expect(files.length).toEqual(2);\n expect(files[0].path).toEqual(path.join(__dirname, globArray[0]));\n expect(files[1].path).toEqual(path.join(__dirname, globArray[1]));\n done();\n });\n });\n\n it('should return a input stream for multiple globs, with negation', function(done) {\n var expectedPath = path.join(__dirname, './fixtures/stuff/run.dmc');\n var globArray = [\n './fixtures/stuff/*.dmc',\n '!fixtures/stuff/test.dmc',\n ];\n var stream = gulp.src(globArray, { cwd: __dirname });\n\n var files = [];\n stream.on('error', done);\n stream.on('data', function(file) {\n expect(file).toBeDefined();\n expect(file.path).toBeDefined();\n files.push(file);\n });\n stream.on('end', function() {\n expect(files.length).toEqual(1);\n expect(files[0].path).toEqual(expectedPath);\n done();\n });\n });\n\n it('should return a input stream with no contents when read is false', function(done) {\n var stream = gulp.src('./fixtures/*.coffee', { read: false, cwd: __dirname });\n stream.on('error', done);\n stream.on('data', function(file) {\n expect(file).toBeDefined();\n expect(file.path).toBeDefined();\n expect(file.contents).toBeNull();\n expect(file.path).toEqual(path.join(__dirname, './fixtures/test.coffee'));\n });\n stream.on('end', function() {\n done();\n });\n });\n\n it('should return a input stream with contents as stream when buffer is false', function(done) {\n var stream = gulp.src('./fixtures/*.coffee', { buffer: false, cwd: __dirname });\n stream.on('error', done);\n stream.on('data', function(file) {\n expect(file).toBeDefined();\n expect(file.path).toBeDefined();\n expect(file.contents).toBeDefined();\n var buf = '';\n file.contents.on('data', function(d) {\n buf += d;\n });\n file.contents.on('end', function() {\n expect(buf).toEqual('this is a test');\n done();\n });\n expect(file.path).toEqual(path.join(__dirname, './fixtures/test.coffee'));\n });\n });\n\n it('should return a input stream from a deep glob', function(done) {\n var stream = gulp.src('./fixtures/**/*.jade', { cwd: __dirname });\n stream.on('error', done);\n stream.on('data', function(file) {\n expect(file).toBeDefined();\n expect(file.path).toBeDefined();\n expect(file.contents).toBeDefined();\n expect(file.path).toEqual(path.join(__dirname, './fixtures/test/run.jade'));\n expect(file.contents).toEqual(Buffer.from('test template'));\n });\n stream.on('end', function() {\n done();\n });\n });\n\n it('should return a input stream from a deeper glob', function(done) {\n var stream = gulp.src('./fixtures/**/*.dmc', { cwd: __dirname });\n var a = 0;\n stream.on('error', done);\n stream.on('data', function() {\n ++a;\n });\n stream.on('end', function() {\n expect(a).toEqual(2);\n done();\n });\n });\n\n it('should return a file stream from a flat path', function(done) {\n var a = 0;\n var stream = gulp.src(path.join(__dirname, './fixtures/test.coffee'));\n stream.on('error', done);\n stream.on('data', function(file) {\n ++a;\n expect(file).toBeDefined();\n expect(file.path).toBeDefined();\n expect(file.contents).toBeDefined();\n expect(file.path).toEqual(path.join(__dirname, './fixtures/test.coffee'));\n expect(file.contents).toEqual(Buffer.from('this is a test'));\n });\n stream.on('end', function() {\n expect(a).toEqual(1);\n done();\n });\n });\n});\n" }, { "path": "test/watch.js", "content": "'use strict';\n\n/* eslint-disable no-use-before-define */\n\nvar fs = require('fs');\nvar path = require('path');\n\nvar expect = require('expect');\nvar rimraf = require('rimraf');\nvar mkdirp = require('mkdirp').mkdirp;\n\nvar gulp = require('../');\n\nvar outpath = path.join(__dirname, './out-fixtures');\n\nvar tempFileContent = 'A test generated this file and it is safe to delete';\n\nfunction createTempFile(path) {\n fs.writeFileSync(path, tempFileContent);\n}\n\nfunction updateTempFile(path) {\n setTimeout(function() {\n fs.appendFileSync(path, ' changed');\n }, 125);\n}\n\nfunction removeTempFile(path) {\n setTimeout(function() {\n fs.unlinkSync(path);\n }, 125);\n}\n\ndescribe('gulp.watch()', function() {\n beforeEach(function (done) {\n rimraf(outpath, done);\n });\n beforeEach(function () {\n return mkdirp(outpath);\n });\n afterEach(function (done) {\n rimraf(outpath, done);\n });\n\n it('should call the function when file changes: no options', function(done) {\n var tempFile = path.join(outpath, 'watch-func.txt');\n\n createTempFile(tempFile);\n\n var watcher = gulp.watch('watch-func.txt', { cwd: outpath }, function(cb) {\n watcher.close();\n cb();\n done();\n });\n\n updateTempFile(tempFile);\n });\n\n it('should execute the gulp.parallel tasks', function(done) {\n var tempFile = path.join(outpath, 'watch-func.txt');\n\n createTempFile(tempFile);\n\n gulp.task('test', function(cb) {\n watcher.close();\n cb();\n done();\n });\n\n var watcher = gulp.watch('watch-func.txt', { cwd: outpath }, gulp.parallel('test'));\n\n updateTempFile(tempFile);\n });\n\n it('should work with destructuring', function(done) {\n var tempFile = path.join(outpath, 'watch-func.txt');\n var watch = gulp.watch;\n var parallel = gulp.parallel;\n var task = gulp.task;\n createTempFile(tempFile);\n\n task('test', function(cb) {\n watcher.close();\n cb();\n done();\n });\n\n var watcher = watch('watch-func.txt', { cwd: outpath }, parallel('test'));\n\n updateTempFile(tempFile);\n });\n\n it('should not call the function when no file changes: no options', function(done) {\n var tempFile = path.join(outpath, 'watch-func.txt');\n\n createTempFile(tempFile);\n\n setTimeout(function() {\n // Chokidar seems to pick up the file we just created, so we wait briefly before setup\n // I wonder if node hasn't fully flushed the file or something...\n var watcher = gulp.watch('watch-func.txt', { cwd: outpath }, function() {\n done(new Error('should not each here!'));\n });\n\n setTimeout(function () {\n watcher.close();\n done();\n }, 1000);\n }, 250);\n });\n\n it('should call the function when file changes: w/ options', function(done) {\n var tempFile = path.join(outpath, 'watch-func-options.txt');\n\n createTempFile(tempFile);\n\n var watcher = gulp.watch('watch-func-options.txt', { cwd: outpath }, function(cb) {\n watcher.close();\n cb();\n done();\n });\n\n updateTempFile(tempFile);\n });\n\n it('should call the function when file changes at a path with japanese characters', function(done) {\n var japaneseDir = path.join(outpath, 'フォルダ');\n\n fs.mkdirSync(japaneseDir);\n\n var tempFile = path.join(japaneseDir, 'foobar.txt');\n\n createTempFile(tempFile);\n\n var watcher = gulp.watch('フォルダ/*', { cwd: outpath }, function(cb) {\n watcher.close();\n cb();\n done();\n });\n\n updateTempFile(tempFile);\n });\n\n it('should not call the function when ignored file changes', function(done) {\n var tempFile = path.join(outpath, 'ignored.txt');\n\n createTempFile(tempFile);\n\n var watcher = gulp.watch(['*', '!ignored.txt'], { cwd: outpath }, function() {\n done(new Error('should not each here!'));\n });\n\n removeTempFile(tempFile);\n setTimeout(function () {\n watcher.close();\n done();\n }, 1000);\n });\n\n it('should not drop options when no callback specified', function(done) {\n var tempFile = path.join(outpath, 'watch-func-nodrop-options.txt');\n // By passing a cwd option, ensure options are not lost to gaze\n var relFile = '../watch-func-nodrop-options.txt';\n var cwd = path.join(outpath, '/subdir');\n\n createTempFile(tempFile);\n\n var watcher = gulp.watch(relFile, { cwd: cwd })\n .on('change', function(filepath) {\n expect(filepath).toBeDefined();\n expect(path.resolve(cwd, filepath)).toEqual(path.resolve(tempFile));\n watcher.close();\n done();\n });\n\n updateTempFile(tempFile);\n });\n\n it('should work without options or callback', function(done) {\n var watcher = gulp.watch('x');\n watcher.close();\n done();\n });\n\n it('should run many tasks: w/ options', function(done) {\n var tempFile = path.join(outpath, 'watch-task-options.txt');\n var a = 0;\n\n createTempFile(tempFile);\n\n gulp.task('task1', function(cb) {\n a++;\n cb();\n });\n gulp.task('task2', function(cb) {\n a += 10;\n expect(a).toEqual(11);\n watcher.close();\n cb();\n done();\n });\n\n var watcher = gulp.watch('watch-task-options.txt', { cwd: outpath }, gulp.series('task1', 'task2'));\n\n updateTempFile(tempFile);\n });\n\n it('should run many tasks: no options', function(done) {\n var tempFile = path.join(outpath, 'watch-many-tasks-no-options.txt');\n var a = 0;\n\n createTempFile(tempFile);\n\n gulp.task('task1', function(cb) {\n a++;\n cb();\n });\n gulp.task('task2', function(cb) {\n a += 10;\n expect(a).toEqual(11);\n watcher.close();\n cb();\n done();\n });\n\n var watcher = gulp.watch('./test/out-fixtures/watch-many-tasks-no-options.txt', gulp.series('task1', 'task2'));\n\n updateTempFile(tempFile);\n });\n\n it('should throw an error: passed parameter (string) is not a function', function(done) {\n var filename = 'empty.txt';\n var tempFile = path.join(outpath, filename);\n\n createTempFile(tempFile);\n try {\n gulp.watch(filename, { cwd: outpath }, 'task1');\n } catch (err) {\n expect(err.message).toEqual('watching ' + filename + ': watch task has to be a function (optionally generated by using gulp.parallel or gulp.series)');\n done();\n }\n });\n\n it('should throw an error: passed parameter (array) is not a function', function(done) {\n var filename = 'empty.txt';\n var tempFile = path.join(outpath, filename);\n\n createTempFile(tempFile);\n try {\n gulp.watch(filename, { cwd: outpath }, ['task1']);\n } catch (err) {\n expect(err.message).toEqual('watching ' + filename + ': watch task has to be a function (optionally generated by using gulp.parallel or gulp.series)');\n done();\n }\n });\n\n});\n" } ]