Showing preview only (254K chars total). Download the full file or copy to clipboard to get everything.
Repository: gulpjs/gulp
Branch: master
Commit: 61f22dc11bb1
Files: 94
Total size: 232.5 KB
Directory structure:
gitextract_5sxvhu_w/
├── .editorconfig
├── .eslintrc
├── .gitattributes
├── .github/
│ ├── SECURITY.md
│ └── workflows/
│ ├── dev.yml
│ └── release.yml
├── .gitignore
├── .npmrc
├── .prettierignore
├── .tidelift.yml
├── CHANGELOG.md
├── CONTRIBUTING.md
├── EXPENSE_POLICY.md
├── LICENSE
├── README.md
├── bin/
│ └── gulp.js
├── docs/
│ ├── CLI.md
│ ├── FAQ.md
│ ├── README.md
│ ├── advanced/
│ │ └── creating-custom-registries.md
│ ├── api/
│ │ ├── README.md
│ │ ├── concepts.md
│ │ ├── dest.md
│ │ ├── last-run.md
│ │ ├── parallel.md
│ │ ├── registry.md
│ │ ├── series.md
│ │ ├── src.md
│ │ ├── symlink.md
│ │ ├── task.md
│ │ ├── tree.md
│ │ ├── vinyl-iscustomprop.md
│ │ ├── vinyl-isvinyl.md
│ │ ├── vinyl.md
│ │ └── watch.md
│ ├── documentation-missing.md
│ ├── getting-started/
│ │ ├── 1-quick-start.md
│ │ ├── 2-javascript-and-gulpfiles.md
│ │ ├── 3-creating-tasks.md
│ │ ├── 4-async-completion.md
│ │ ├── 5-working-with-files.md
│ │ ├── 6-explaining-globs.md
│ │ ├── 7-using-plugins.md
│ │ ├── 8-watching-files.md
│ │ └── README.md
│ ├── getting-started.md
│ ├── recipes/
│ │ ├── README.md
│ │ ├── automate-releases.md
│ │ ├── browserify-multiple-destination.md
│ │ ├── browserify-transforms.md
│ │ ├── browserify-uglify-sourcemap.md
│ │ ├── browserify-with-globs.md
│ │ ├── combining-streams-to-handle-errors.md
│ │ ├── cron-task.md
│ │ ├── delete-files-folder.md
│ │ ├── fast-browserify-builds-with-watchify.md
│ │ ├── handling-the-delete-event-on-watch.md
│ │ ├── incremental-builds-with-concatenate.md
│ │ ├── maintain-directory-structure-while-globbing.md
│ │ ├── make-stream-from-buffer.md
│ │ ├── minified-and-non-minified.md
│ │ ├── minimal-browsersync-setup-with-gulp4.md
│ │ ├── mocha-test-runner-with-gulp.md
│ │ ├── pass-arguments-from-cli.md
│ │ ├── rollup-with-rollup-stream.md
│ │ ├── run-grunt-tasks-from-gulp.md
│ │ ├── running-task-steps-per-folder.md
│ │ ├── server-with-livereload-and-css-injection.md
│ │ ├── sharing-streams-with-stream-factories.md
│ │ ├── templating-with-swig-and-yaml-front-matter.md
│ │ └── using-multiple-sources-in-one-task.md
│ ├── support/
│ │ └── for-enterprise.md
│ ├── why-use-pump/
│ │ └── README.md
│ └── writing-a-plugin/
│ ├── README.md
│ ├── dealing-with-streams.md
│ ├── guidelines.md
│ ├── recommended-modules.md
│ ├── testing.md
│ └── using-buffers.md
├── index.js
├── index.mjs
├── package.json
└── test/
├── .gitkeep
├── dest.js
├── fixtures/
│ ├── copy/
│ │ └── example.txt
│ ├── gulpfiles/
│ │ ├── cjs/
│ │ │ └── gulpfile.cjs
│ │ └── mjs/
│ │ └── gulpfile.mjs
│ ├── stuff/
│ │ ├── run.dmc
│ │ └── test.dmc
│ ├── test/
│ │ └── run.jade
│ └── test.coffee
├── index.test.js
├── src.js
└── watch.js
================================================
FILE CONTENTS
================================================
================================================
FILE: .editorconfig
================================================
# https://editorconfig.org
root = true
[*]
indent_style = space
indent_size = 2
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true
end_of_line = lf
[*.md]
trim_trailing_whitespace = false
================================================
FILE: .eslintrc
================================================
{
"extends": "gulp"
}
================================================
FILE: .gitattributes
================================================
* text eol=lf
# Denote all files that are truly binary and should not be modified.
*.png binary
*.jpg binary
================================================
FILE: .github/SECURITY.md
================================================
# Security Policy
## Supported Versions
| Version | Supported |
| ------- | ------------------ |
| 4.x.x | :white_check_mark: |
| < 4.0 | :x: |
## Reporting a Vulnerability
To report a security vulnerability, please use the
[Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure.
================================================
FILE: .github/workflows/dev.yml
================================================
name: dev
on:
pull_request:
push:
branches:
- master
- main
env:
CI: true
jobs:
prettier:
name: Format code
runs-on: ubuntu-latest
if: ${{ github.event_name == 'push' }}
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Prettier
uses: gulpjs/prettier_action@v3.0
with:
commit_message: 'chore: Run prettier'
prettier_options: '--write .'
test:
name: Tests for Node ${{ matrix.node }} on ${{ matrix.os }}
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
node: [10, 12, 14, 16, 18, 20, 22, 24]
os: [ubuntu-latest, windows-latest, macos-13]
steps:
- name: Clone repository
uses: actions/checkout@v2
- name: Set Node.js version
uses: actions/setup-node@v2
with:
node-version: ${{ matrix.node }}
- run: node --version
- run: npm --version
- name: Install npm dependencies
run: npm install
- name: Run lint
run: npm run lint
- name: Run tests
run: npm test
- name: Coveralls
uses: coverallsapp/github-action@v1.1.2
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
flag-name: ${{matrix.os}}-node-${{ matrix.node }}
parallel: true
coveralls:
needs: test
name: Finish up
runs-on: ubuntu-latest
steps:
- name: Coveralls Finished
uses: coverallsapp/github-action@v1.1.2
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
parallel-finished: true
================================================
FILE: .github/workflows/release.yml
================================================
name: release
on:
push:
branches:
- master
- main
jobs:
release-please:
runs-on: ubuntu-latest
steps:
- uses: GoogleCloudPlatform/release-please-action@v2
with:
token: ${{ secrets.GITHUB_TOKEN }}
release-type: node
package-name: release-please-action
================================================
FILE: .gitignore
================================================
# Logs
logs
*.log
# Runtime data
pids
*.pid
*.seed
# Directory for instrumented libs generated by jscoverage/JSCover
lib-cov
# Coverage directory used by tools like istanbul
coverage
.nyc_output
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
.grunt
# Compiled binary addons (https://nodejs.org/api/addons.html)
build/Release
# Dependency directory
# Commenting this out is preferred by some people, see
# https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git-
node_modules
# Users Environment Variables
.lock-wscript
# Garbage files
.DS_Store
# Test results
test.xunit
================================================
FILE: .npmrc
================================================
package-lock=false
================================================
FILE: .prettierignore
================================================
coverage/
.nyc_output/
CHANGELOG.md
================================================
FILE: .tidelift.yml
================================================
ci:
platform:
NPM:
# We use an older version that doesn't use ES6+ features to support back to node 0.10
eslint:
tests:
outdated: skip
# We use an older version that doesn't use ES6+ features to support back to node 0.10
expect:
tests:
outdated: skip
# We use an older version that doesn't use ES6+ features to support back to node 0.10
mocha:
tests:
outdated: skip
================================================
FILE: CHANGELOG.md
================================================
# gulp changelog
### [5.0.1](https://www.github.com/gulpjs/gulp/compare/v5.0.0...v5.0.1) (2025-06-01)
### Bug Fixes
* 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))
* 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))
* 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))
## [5.0.0](https://www.github.com/gulpjs/gulp/compare/v4.0.2...v5.0.0) (2024-03-29)
We've tried to provide a high-level changelog for gulp v5 below, but it
doesn't contain all changes from the 60+ dependencies that we maintain.
Please see [individual changelogs](#individual-changelogs) to drill down
into all changes that were made.
### ⚠ BREAKING CHANGES
* Drop support for Node.js <10.13
* Default stream encoding to UTF-8
* Standardized on `anymatch` library for globbing paths. All globs should work the same between `src` and `watch` now!
* 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`
* All globs and paths are normalized to unix-like filepaths
* Only allow JS variants for `.gulp.*` config files
* Removed support for alpha releases of v4 from `gulp-cli`
* Removed the `--verify` flag
* Renamed the `--require` flag to `--preload` to avoid conflicting with Node.js flags
* Removed many legacy and deprecated loaders
* Upgrade to chokidar v3
* Clone `Vinyl` objects with stream contents using `teex`, but no longer wait for all streams to flow before cloned streams will receive data
* Stop using `process.umask()` to make directories, instead falling back to Node's default mode
* Throw on non-function, non-string option coercers
* Drop support of Node.js snake_case flags
* Use a Symbol for attaching the `gulplog` namespace to the store
* Use a Symbol for attaching the `gulplog` store to the global
* Use sha256 to hash the `v8flags` cache into a filename
### Features
* Streamlined the dependency tree
* Switch all streams implementation to Streamx
* Rewrote `glob-stream` to use a custom directory walk that relies on newer Node.js features and is more performant than old implementation
* Implement translation support for all CLI messages and all messages passing through gulplog
* Allow users to customize or remove the timestamp from their logs
* 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
* Added support for `gulpile.cjs` and `gulpfile.mjs`
* Add support for `swc`, `esbuild`, `sucrase`, and `mdx` loaders
* Provide an ESM export ([#2760](https://www.github.com/gulpjs/gulp/issues/2760)) ([b00de68](https://www.github.com/gulpjs/gulp/commit/b00de681f5ef6ade283d544f62f770f6b27a9e52))
* Support sourcemap handling on streaming `Vinyl` contents
* Support `extends` syntax for `.gulp.*` config file
* Allow overriding `gulpfile` and `preloads` via `.gulp.*` config file
### Bug Fixes
* Resolve bugs related to symlinks on various platforms
* Resolved some reported ReDoS CVEs and improved performance in glob-parent
* Rework errors surfaced when encountering files or symlinks when trying to create directories
* Ensure watch allows japanese characters in globs ([72668c6](https://www.github.com/gulpjs/gulp/commit/72668c61e445c81fad23bc6ed24967a3238a648d))
* Ensure watch does not trigger on negated globs ([72668c6](https://www.github.com/gulpjs/gulp/commit/72668c61e445c81fad23bc6ed24967a3238a648d))
* Improve handling of BOM at the beginning of a stream
* Properly handle function coercer in array of option coercers
* Fork `to-absolute-glob` to:
- Check negative patterns before trimming
- Ensure glob-like characters are escaped in cwd & root options
- Resolve `../` at the beginning of globs
### Miscellaneous Chores
* Remove lazystream dependency
* Updated various stream test suites to test against Node.js core `stream`, `readable-stream`, and `streamx`
* 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))
### Individual Changelogs
We created and maintain various projects that gulp depends upon. You can find their changelogs linked below:
* [undertaker](https://github.com/gulpjs/undertaker/blob/master/CHANGELOG.md#200-2024-03-22)
* [vinyl-fs](https://github.com/gulpjs/vinyl-fs/blob/master/CHANGELOG.md#400-2023-06-11)
* [glob-stream](https://github.com/gulpjs/glob-stream/blob/master/CHANGELOG.md#801-2024-03-25)
* [gulp-cli](https://github.com/gulpjs/gulp-cli/blob/master/CHANGELOG.md#300-2024-03-24)
* [interpret](https://github.com/gulpjs/interpret/blob/master/CHANGELOG.md#311-2022-06-29)
* [glob-parent](https://github.com/gulpjs/glob-parent/blob/main/CHANGELOG.md#602-2021-09-29)
* [glob-watcher](https://github.com/gulpjs/glob-watcher/blob/master/CHANGELOG.md#600-2023-05-31)
* [vinyl](https://github.com/gulpjs/vinyl/blob/master/CHANGELOG.md#300-2022-09-26)
* [fs-mkdirp-stream](https://github.com/gulpjs/fs-mkdirp-stream/blob/master/CHANGELOG.md#201-2022-09-17)
* [lead](https://github.com/gulpjs/lead/blob/master/CHANGELOG.md#400-2022-09-22)
* [vinyl-sourcemap](https://github.com/gulpjs/vinyl-sourcemap/blob/master/CHANGELOG.md#200-2022-10-17)
* [to-through](https://github.com/gulpjs/to-through/blob/master/CHANGELOG.md#300-2022-09-07)
* [resolve-options](https://github.com/gulpjs/resolve-options/blob/master/CHANGELOG.md#200-2022-06-24)
* [remove-bom-stream](https://github.com/gulpjs/remove-bom-stream/blob/master/CHANGELOG.md#200-2022-04-19)
* [value-or-function](https://github.com/gulpjs/value-or-function/blob/master/CHANGELOG.md#400-2022-01-30)
* [now-and-later](https://github.com/gulpjs/now-and-later/blob/master/CHANGELOG.md#300-2022-06-25)
* [@gulpjs/to-absolute-glob](https://github.com/gulpjs/to-absolute-glob/blob/master/CHANGELOG.md#400-2023-01-03)
* [fined](https://github.com/gulpjs/fined/blob/master/CHANGELOG.md#200-2021-10-31)
* [mute-stdout](https://github.com/gulpjs/mute-stdout/blob/master/CHANGELOG.md#200-2021-11-22)
* [semver-greatest-satisfied-range](https://github.com/gulpjs/semver-greatest-satisfied-range/blob/master/CHANGELOG.md#200-2022-01-31)
* [flagged-respawn](https://github.com/gulpjs/flagged-respawn/blob/master/CHANGELOG.md#200-2021-11-21)
* [rechoir](https://github.com/gulpjs/rechoir/blob/master/CHANGELOG.md#080-2021-07-24)
* [gulplog](https://github.com/gulpjs/gulplog/blob/master/CHANGELOG.md#220-2024-03-23)
* [glogg](https://github.com/gulpjs/glogg/blob/master/CHANGELOG.md#220-2024-03-23)
* [@gulpjs/messages](https://github.com/gulpjs/messages/blob/master/CHANGELOG.md#110-2024-03-24)
* [sparkles](https://github.com/gulpjs/sparkles/blob/master/CHANGELOG.md#210-2024-03-23)
* [liftoff](https://github.com/gulpjs/liftoff/blob/main/CHANGELOG.md#500-2024-03-16)
* [v8flags](https://github.com/gulpjs/v8flags/blob/master/CHANGELOG.md#401-2023-09-03)
* [bach](https://github.com/gulpjs/bach/blob/master/CHANGELOG.md#201-2022-08-29)
* [undertaker-registry](https://github.com/gulpjs/undertaker-registry/blob/master/CHANGELOG.md#200-2021-12-29)
* [async-settle](https://github.com/gulpjs/async-settle/blob/master/CHANGELOG.md#200-2022-06-25)
* [last-run](https://github.com/gulpjs/last-run/blob/master/CHANGELOG.md#200-2022-01-10)
* [async-done](https://github.com/gulpjs/async-done/blob/master/CHANGELOG.md#200-2022-06-25)
* [replace-homedir](https://github.com/gulpjs/replace-homedir/blob/master/CHANGELOG.md#200-2022-01-31)
## 4.0.0
### Task system changes
- replaced 3.x task system (orchestrator) with new task system (bach)
- removed gulp.reset
- removed 3 argument syntax for `gulp.task`
- `gulp.task` should only be used when you will call the task with the CLI
- added `gulp.series` and `gulp.parallel` methods for composing tasks. Everything must use these now.
- added single argument syntax for `gulp.task` which allows a named function to be used as the name of the task and task function.
- added `gulp.tree` method for retrieving the task tree. Pass `{ deep: true }` for an `archy` compatible node list.
- added `gulp.registry` for setting custom registries.
### CLI changes
- 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)
- add `--tasks-json` flag to CLI to dump the whole tree out for other tools to consume
- added `--verify` flag to check the dependencies in package.json against the plugin blacklist.
### vinyl/vinyl-fs changes
- added `gulp.symlink` which functions exactly like `gulp.dest`, but symlinks instead.
- added `dirMode` param to `gulp.dest` and `gulp.symlink` which allows better control over the mode of the destination folder that is created.
- 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)
- performance for gulp.src has improved massively
- `gulp.src(['**/*', '!b.js'])` will no longer eat CPU since negations happen during walking now
- added `since` option to `gulp.src` which lets you only match files that have been modified since a certain date (for incremental builds)
- fixed `gulp.src` not following symlinks
- added `overwrite` option to `gulp.dest` which allows you to enable or disable overwriting of existing files
## 3.9.1
- update interpret to 1.0.0 (support for babel-register)
- fix to include manpages in published tarball
- documentation/recipe updates
## 3.9.0
- add babel support
- add transpiler fallback support
- add support for some renamed transpilers: livescript, etc
- add JSCS
- update dependencies (liftoff, interpret)
- documentation tweaks
## 3.8.11
- fix node 0.12/iojs problems
- add node 0.12 and iojs to travis
- update dependencies (liftoff, v8flags)
- documentation tweaks
## 3.8.10
- add link to spanish docs
- update dependencies (archy, semver, mocha, etc)
- documentation tweaks
## 3.8.9
- fix local version undefined output
- add completion for fish shell
- fix powershell completion line splitting
- add support for arbitrary node flags (oops, should have been a minor bump)
- add v8flags dependency
- update dependencies (liftoff)
- documentation tweaks
## 3.8.8
- update dependencies (minimist, tildify)
- documentation tweaks
## 3.8.7
- handle errors a bit better
- update dependencies (gulp-util, semver, etc)
- documentation tweaks
## 3.8.6
- remove executable flag from LICENSE
- update dependencies (chalk, minimist, liftoff, etc)
- documentation tweaks
## 3.8.5
- simplify --silent and --tasks-simple
- fix bug in autocomplete where errors would come out
## 3.8.4
- CLI will use exit code 1 on exit when any task fails during the lifetime of the process
## 3.8.3
- Tweak error formatting to work better with PluginErrors and strings
## 3.8.2
- add manpage generation
## 3.8.1
- the CLI now adds process.env.INIT_CWD which is the original cwd it was launched from
## 3.8.0
- update vinyl-fs
- gulp.src is now a writable passthrough, this means you can use it to add files to your pipeline at any point
- gulp.dest can now take a function to determine the folder
This is now possible!
```js
gulp.src('lib/*.js')
.pipe(uglify())
.pipe(gulp.src('styles/*.css'))
.pipe(gulp.dest(function(file){
// I don't know, you can do something cool here
return 'build/whatever';
}));
```
## 3.7.0
- update vinyl-fs to remove BOM from UTF8 files
- add --tasks-simple flag for plaintext task listings
- updated autocomplete scripts to be simpler and use new --tasks-simple flag
- added support for transpilers via liftoff 0.11 and interpret
- just npm install your compiler (coffee-script for example) and it will work out of the box
## 3.5.5
- update deps
- gulp.dest now support mode option, uses source file mode by default (file.stat.mode)
- use chalk for colors in bin
- update gulp.env deprecation msg to be more helpful
## 3.5.2
- add -V for version on CLI (unix standard)
- -v is deprecated, use -V
- add -T as an alias for --tasks
- documentation
## 3.5
- added `gulp.watch(globs, tasksArray)` sugar
- remove gulp.taskQueue
- deprecate gulp.run
- deprecate gulp.env
- add engineStrict to prevent people with node < 0.9 from installing
## 3.4
- added `--tasks` that prints out the tree of tasks + deps
- global cli + local install mismatch is no longer fatal
- remove tests for fs stuff
- switch core src, dest, and watch to vinyl-fs
- internal cleaning
## 3.3.4
- `--base` is now `--cwd`
## 3.3.3
- support for `--base` CLI arg to change where the search for gulpfile/`--require`s starts
- support for `--gulpfile` CLI arg to point to a gulpfile specifically
## 3.3.0
- file.contents streams are no longer paused coming out of src
- dest now passes files through before they are empty to fix passing to multiple dests
## 3.2.4
- Bug fix - we didn't have any CLI tests
## 3.2.3
- Update dependencies for bug fixes
- autocomplete stuff in the completion folder
## 3.2
- File object is now [vinyl](https://github.com/wearefractal/vinyl)
- .watch() is now [glob-watcher](https://github.com/wearefractal/glob-watcher)
- Fix CLI -v when no gulpfile found
- gulp-util updated
- Logging moved to CLI bin file
- Will cause double logging if you update global CLI to 3.2 but not local
- Will cause no logging if you update local to 3.1 but not global CLI
- Drop support for < 0.9
## 3.1.3
- Move isStream and isBuffer to gulp-util
## 3.1
- Move file class to gulp-util
## 3.0
- Ability to pass multiple globs and glob negations to glob-stream
- Breaking change to the way glob-stream works
- File object is now a class
- file.shortened changed to file.relative
- file.cwd added
- Break out getStats to avoid nesting
- Major code reorganization
## 2.7
- Breaking change to the way options are passed to glob-stream
- Introduce new File object to ease pain of computing shortened names (now a getter)
## 2.4 - 2.6
- Moved stuff to gulp-util
- Quit exposing createGlobStream (just use the glob-stream module)
- More logging
- Prettier time durations
- Tons of documentation changes
- gulp.trigger(tasks...) as a through stream
## 1.2-2.4 (11/12/13)
- src buffer=false fixed for 0.8 and 0.9 (remember to .resume() on these versions before consuming)
- CLI completely rewritten
- Colorful logging
- Uses local version of gulp to run tasks
- Uses findup to locate gulpfile (so you can run it anywhere in your project)
- chdir to gulpfile directory before loading it
- Correct exit codes on errors
- silent flag added to gulp to disable logging
- Fixes to task orchestration (3rd party)
- Better support for globbed directories (thanks @robrich)
## 1.2 (10/28/13)
- Can specify buffer=false on src streams to make file.content a stream
- Can specify read=false on src streams to disable file.content
## 1.1 (10/21/13)
- Can specify run callback
- Can specify task dependencies
- Tasks can accept callback or return promise
- `gulp.verbose` exposes run-time internals
## 1.0 (9/26/13)
- Specify dependency versions
- Updated docs
## 0.2 (8/6/13)
- Rename .files() to .src() and .folder() to .dest()
## 0.1 (7/18/13)
- Initial Release
================================================
FILE: CONTRIBUTING.md
================================================
# Request for contributions
Please contribute to this repository if any of the following is true:
- You have expertise in community development, communication, or education
- You want open source communities to be more collaborative and inclusive
- You want to help lower the burden to first time contributors
# How to contribute
Prerequisites:
- familiarity with [GitHub PRs](https://help.github.com/articles/using-pull-requests) (pull requests) and issues
- knowledge of Markdown for editing `.md` documents
In particular, this community seeks the following types of contributions:
- ideas: participate in an Issues thread or start your own to have your voice
heard
- resources: submit a PR to add to [docs README.md](/docs/README.md) with links to related content
- outline sections: help us ensure that this repository is comprehensive. If
there is a topic that is overlooked, please add it, even if it is just a stub
in the form of a header and single sentence. Initially, most things fall into
this category
- write: contribute your expertise in an area by helping us expand the included
content
- copy editing: fix typos, clarify language, and generally improve the quality
of the content
- formatting: help keep content easy to read with consistent formatting
- code: Fix issues or contribute new features to this or any related projects
# Project structure
Gulp itself is tiny: index.js contains [very few lines of code](https://github.com/gulpjs/gulp/blob/master/index.js).
It is powered by a few other libraries which each handle a few specific tasks
each.
You can view all issues with the "help wanted" label across all gulp projects
here: https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+user%3Agulpjs+label%3A%22help+wanted%22+
## Undertaker: task management
Undertaker handles task management in Gulp: the `gulp.task()`, `gulp.series()`
and `gulp.parallel()` functions. `gulp.series()` and `gulp.parallel()` are in
turn powered by Bach.
- https://github.com/gulpjs/undertaker
- https://github.com/gulpjs/bach
## vinyl-fs: file streams
vinyl-fs powers the `gulp.src()` and `gulp.dest()` functions: they take files
and globs specified by the user, turns them into a stream of file objects,
and then puts them back into the filesystem when `gulp.dest()` is called.
The file objects themselves are vinyl objects: that's another library (a simple
one!)
- https://github.com/gulpjs/vinyl-fs
- https://github.com/gulpjs/vinyl
## chokidar: file watching
`gulp.watch()` is using chokidar for file watching. It's actually wrapped in a
small library on the gulp organization, glob-watcher.
- https://github.com/paulmillr/chokidar
- https://github.com/gulpjs/glob-watcher
## gulp-cli: running gulp
Finally, we have gulp-cli. This uses liftoff to take what people run in the
command line and run the correct tasks. It works with both gulp 4 and older
versions of gulp.
- https://github.com/gulpjs/gulp-cli
- https://github.com/js-cli/js-liftoff
# Conduct
We are committed to providing a friendly, safe and welcoming environment for
all, regardless of gender, sexual orientation, disability, ethnicity, religion,
or similar personal characteristic.
On IRC, please avoid using overtly sexual nicknames or other nicknames that
might detract from a friendly, safe and welcoming environment for all.
Please be kind and courteous. There's no need to be mean or rude.
Respect that people have differences of opinion and that every design or
implementation choice carries a trade-off and numerous costs. There is seldom
a right answer, merely an optimal answer given a set of values and
circumstances.
Please keep unstructured critique to a minimum. If you have solid ideas you
want to experiment with, make a fork and see how it works.
We will exclude you from interaction if you insult, demean or harass anyone.
That is not welcome behavior. We interpret the term "harassment" as
including the definition in the
[Citizen Code of Conduct](http://citizencodeofconduct.org/);
if you have any lack of clarity about what might be included in that concept,
please read their definition. In particular, we don't tolerate behavior that
excludes people in socially marginalized groups.
Private harassment is also unacceptable. No matter who you are, if you feel
you have been or are being harassed or made uncomfortable by a community
member, please contact one of the channel ops or any of the
[gulpjs](https://github.com/orgs/gulpjs/people) core team
immediately. Whether you're a regular contributor or a newcomer, we care about
making this community a safe place for you and we've got your back.
Likewise any spamming, trolling, flaming, baiting or other attention-stealing
behavior is not welcome.
# Communication
There is an IRC channel on irc.freenode.net, channel `#gulpjs`. You're
welcome to drop in and ask questions, discuss bugs and such. The channel is
not currently logged.
GitHub issues are the primary way for communicating about specific proposed
changes to this project.
In both contexts, please follow the conduct guidelines above. Language issues
are often contentious and we'd like to keep discussion brief, civil and focused
on what we're actually doing, not wandering off into too much imaginary stuff.
# Frequently Asked Questions
See [the FAQ docs page](/docs/FAQ.md)
================================================
FILE: EXPENSE_POLICY.md
================================================
# Expense Policy
## Funding can be requested for significant changes made by Core Members.
* Discuss the changes in the private gulp team forum.
* Include a cost estimation with either a fixed price or hours + rate (suggested $50 per hour).
* Notify the team before you exceed an estimate.
## Bug bounties may be assigned at the Core Members’ discretion to issues of significant importance - usually issues outstanding for at least 6 months.
* Issues with bug bounties will be labeled “Bug Bounty: $x”.
* In order to claim a bug bounty, create a Pull Request that fixes an issue with a “Bug Bounty” label.
* 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.
* 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.
* 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.
* Your expense will be validated by a Core Member and then your payment will be dispersed by Open Collective the following Friday.
## 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!
================================================
FILE: LICENSE
================================================
The MIT License (MIT)
Copyright (c) 2013-2024 Blaine Bublitz <blaine.bublitz@gmail.com> and Eric Schoffstall <yo@contra.io>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
================================================
FILE: README.md
================================================
<p align="center">
<a href="https://gulpjs.com">
<img height="257" width="114" src="https://raw.githubusercontent.com/gulpjs/artwork/master/gulp-2x.png">
</a>
<p align="center">The streaming build system</p>
</p>
[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Build Status][ci-image]][ci-url] [![Coveralls Status][coveralls-image]][coveralls-url]
## What is gulp?
- **Automation** - gulp is a toolkit that helps you automate painful or time-consuming tasks in your development workflow.
- **Platform-agnostic** - Integrations are built into all major IDEs and people are using gulp with PHP, .NET, Node.js, Java, and other platforms.
- **Strong Ecosystem** - Use npm modules to do anything you want + over 3000 curated plugins for streaming file transformations.
- **Simple** - By providing only a minimal API surface, gulp is easy to learn and simple to use.
## Installation
Follow our [Quick Start guide][quick-start].
## Roadmap
Find out about all our work-in-progress and outstanding issues at https://github.com/orgs/gulpjs/projects.
## Documentation
Check out the [Getting Started guide][getting-started-guide] and [API docs][api-docs] on our website!
__Excuse our dust! All other docs will be behind until we get everything updated. Please open an issue if something isn't working.__
## Sample `gulpfile.js`
This file will give you a taste of what gulp does.
```js
var gulp = require('gulp');
var less = require('gulp-less');
var babel = require('gulp-babel');
var concat = require('gulp-concat');
var uglify = require('gulp-uglify');
var rename = require('gulp-rename');
var cleanCSS = require('gulp-clean-css');
var del = require('del');
var paths = {
styles: {
src: 'src/styles/**/*.less',
dest: 'assets/styles/'
},
scripts: {
src: 'src/scripts/**/*.js',
dest: 'assets/scripts/'
}
};
/* Not all tasks need to use streams, a gulpfile is just another node program
* and you can use all packages available on npm, but it must return either a
* Promise, a Stream or take a callback and call it
*/
function clean() {
// You can use multiple globbing patterns as you would with `gulp.src`,
// for example if you are using del 2.0 or above, return its promise
return del([ 'assets' ]);
}
/*
* Define our tasks using plain functions
*/
function styles() {
return gulp.src(paths.styles.src)
.pipe(less())
.pipe(cleanCSS())
// pass in options to the stream
.pipe(rename({
basename: 'main',
suffix: '.min'
}))
.pipe(gulp.dest(paths.styles.dest));
}
function scripts() {
return gulp.src(paths.scripts.src, { sourcemaps: true })
.pipe(babel())
.pipe(uglify())
.pipe(concat('main.min.js'))
.pipe(gulp.dest(paths.scripts.dest));
}
function watch() {
gulp.watch(paths.scripts.src, scripts);
gulp.watch(paths.styles.src, styles);
}
/*
* Specify if tasks run in series or parallel using `gulp.series` and `gulp.parallel`
*/
var build = gulp.series(clean, gulp.parallel(styles, scripts));
/*
* You can use CommonJS `exports` module notation to declare tasks
*/
exports.clean = clean;
exports.styles = styles;
exports.scripts = scripts;
exports.watch = watch;
exports.build = build;
/*
* Define default task that can be called by just running `gulp` from cli
*/
exports.default = build;
```
## Use latest JavaScript version in your gulpfile
Gulp 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.
And here's the same sample from above written in **ESNext**.
```js
import { src, dest, watch } from 'gulp';
import less from 'gulp-less';
import babel from 'gulp-babel';
import concat from 'gulp-concat';
import uglify from 'gulp-uglify';
import rename from 'gulp-rename';
import cleanCSS from 'gulp-clean-css';
import {deleteAsync} from 'del';
const paths = {
styles: {
src: 'src/styles/**/*.less',
dest: 'assets/styles/'
},
scripts: {
src: 'src/scripts/**/*.js',
dest: 'assets/scripts/'
}
};
/*
* For small tasks you can export arrow functions
*/
export const clean = () => deleteAsync([ 'assets' ]);
/*
* You can also declare named functions and export them as tasks
*/
export function styles() {
return src(paths.styles.src)
.pipe(less())
.pipe(cleanCSS())
// pass in options to the stream
.pipe(rename({
basename: 'main',
suffix: '.min'
}))
.pipe(dest(paths.styles.dest));
}
export function scripts() {
return src(paths.scripts.src, { sourcemaps: true })
.pipe(babel())
.pipe(uglify())
.pipe(concat('main.min.js'))
.pipe(dest(paths.scripts.dest));
}
/*
* You could even use `export as` to rename exported tasks
*/
function watchFiles() {
watch(paths.scripts.src, scripts);
watch(paths.styles.src, styles);
}
export { watchFiles as watch };
const build = gulp.series(clean, gulp.parallel(styles, scripts));
/*
* Export a default task
*/
export default build;
```
## Incremental Builds
You can filter out unchanged files between runs of a task using
the `gulp.src` function's `since` option and `gulp.lastRun`:
```js
const paths = {
...
images: {
src: 'src/images/**/*.{jpg,jpeg,png}',
dest: 'build/img/'
}
}
function images() {
return gulp.src(paths.images.src, {since: gulp.lastRun(images)})
.pipe(imagemin())
.pipe(gulp.dest(paths.images.dest));
}
function watch() {
gulp.watch(paths.images.src, images);
}
```
Task run times are saved in memory and are lost when gulp exits. It will only
save time during the `watch` task when running the `images` task
for a second time.
## Want to contribute?
Anyone can help make this project better - check out our [Contributing guide](/CONTRIBUTING.md)!
<!-- prettier-ignore-start -->
[quick-start]: https://gulpjs.com/docs/en/getting-started/quick-start
[getting-started-guide]: https://gulpjs.com/docs/en/getting-started/quick-start
[api-docs]: https://gulpjs.com/docs/en/api/concepts
[esm-module]: https://github.com/standard-things/esm
<!-- prettier-ignore-end -->
<!-- prettier-ignore-start -->
[downloads-image]: https://img.shields.io/npm/dm/gulp.svg?style=flat-square
[npm-url]: https://www.npmjs.com/package/gulp
[npm-image]: https://img.shields.io/npm/v/gulp.svg?style=flat-square
[ci-url]: https://github.com/gulpjs/gulp/actions?query=workflow:dev
[ci-image]: https://img.shields.io/github/actions/workflow/status/gulpjs/gulp/dev.yml?branch=master&style=flat-square
[coveralls-url]: https://coveralls.io/r/gulpjs/gulp
[coveralls-image]: https://img.shields.io/coveralls/gulpjs/gulp/master.svg?style=flat-square
<!-- prettier-ignore-end -->
================================================
FILE: bin/gulp.js
================================================
#!/usr/bin/env node
require('gulp-cli')();
================================================
FILE: docs/CLI.md
================================================
## gulp CLI docs
### Flags
gulp has very few flags to know about. All other flags are for tasks to use if needed.
- `-v` or `--version` will display the global and local gulp versions
- `--require <module path>` will require a module before running the gulpfile. This is useful for transpilers but also has other applications. You can use multiple `--require` flags
- `--gulpfile <gulpfile path>` will manually set path of gulpfile. Useful if you have multiple gulpfiles. This will set the CWD to the gulpfile directory as well
- `--cwd <dir path>` will manually set the CWD. The search for the gulpfile, as well as the relativity of all requires will be from here
- `-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).
- `--tasks-simple` will display a plaintext list of tasks for the loaded gulpfile
- `--verify` will verify plugins referenced in project's package.json against the plugins blacklist
- `--color` will force gulp and gulp plugins to display colors even when no color support is detected
- `--no-color` will force gulp and gulp plugins to not display colors even when color support is detected
- `--silent` will disable all gulp logging
The CLI adds process.env.INIT_CWD which is the original cwd it was launched from.
#### Task specific flags
Refer 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
### Tasks
Tasks can be executed by running `gulp <task> <task>...`.
If more than one task is listed, Gulp will execute all of them
concurrently, that is, as if they had all been listed as dependencies of
a single task.
Gulp does not serialize tasks listed on the command line. From using
other comparable tools users may expect to execute something like
`gulp clean build`, with tasks named `clean` and `build`. This will not
produce the intended result, as the two tasks will be executed
concurrently.
Just running `gulp` will execute the task `default`. If there is no
`default` task, gulp will error.
### Compilers
You 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.
### Examples
#### Example gulpfile
```js
gulp.task('one', function(done) {
// do stuff
done();
});
gulp.task('two', function(done) {
// do stuff
done();
});
gulp.task('three', three);
function three(done) {
done();
}
three.description = "This is the description of task three";
gulp.task('four', gulp.series('one', 'two'));
gulp.task('five',
gulp.series('four',
gulp.parallel('three', function(done) {
// do more stuff
done();
})
)
);
```
### `-T` or `--tasks`
Command: `gulp -T` or `gulp --tasks`
Output:
```shell
[20:58:55] Tasks for ~\exampleProject\gulpfile.js
[20:58:55] ├── one
[20:58:55] ├── two
[20:58:55] ├── three This is the description of task three
[20:58:55] ├─┬ four
[20:58:55] │ └─┬ <series>
[20:58:55] │ ├── one
[20:58:55] │ └── two
[20:58:55] ├─┬ five
[20:58:55] │ └─┬ <series>
[20:58:55] │ ├─┬ four
[20:58:55] │ │ └─┬ <series>
[20:58:55] │ │ ├── one
[20:58:55] │ │ └── two
[20:58:55] │ └─┬ <parallel>
[20:58:55] │ ├── three
[20:58:55] │ └── <anonymous>
```
### `--tasks-simple`
Command: `gulp --tasks-simple`
Output:
```shell
one
two
three
four
five
```
================================================
FILE: docs/FAQ.md
================================================
# FAQ
## Why gulp? Why not ____?
See the [gulp introduction slideshow] for a rundown on how gulp came to be.
## Is it "gulp" or "Gulp"?
gulp is always lowercase. The only exception is in the gulp logo where gulp is capitalized.
## Where can I find a list of gulp plugins?
gulp plugins always include the `gulpplugin` keyword. [Search gulp plugins][search-gulp-plugins] or [view all plugins][npm plugin search].
## I want to write a gulp plugin, how do I get started?
See the [Writing a gulp plugin] wiki page for guidelines and an example to get you started.
## My plugin does ____, is it doing too much?
Probably. Ask yourself:
1. Is my plugin doing something that other plugins may need to do?
- If so, that piece of functionality should be a separate plugin. [Check if it already exists on npm][npm plugin search].
1. Is my plugin doing two, completely different things based on a configuration option?
- If so, it may serve the community better to release it as two separate plugins
- If the two tasks are different, but very closely related, it's probably OK
## How should newlines be represented in plugin output?
Always use `\n` to prevent diff issues between operating systems.
## 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?
Upon 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`
## Where can I get updates on gulp?
gulp updates can be found on the following twitters:
- [@wearefractal](https://twitter.com/wearefractal)
- [@eschoff](https://twitter.com/eschoff)
- [@gulpjs](https://twitter.com/gulpjs)
## Does gulp have an chat channel?
Yes, come chat with us on [Gitter](https://gitter.im/gulpjs/gulp).
[Writing a gulp plugin]: writing-a-plugin/README.md
[gulp introduction slideshow]: https://slid.es/contra/gulp
[Freenode]: https://freenode.net/
[search-gulp-plugins]: https://gulpjs.com/plugins/
[npm plugin search]: https://npmjs.org/browse/keyword/gulpplugin
================================================
FILE: docs/README.md
================================================
# gulp documentation
* [Getting Started](getting-started/) - Get started with gulp
* [API documentation](api/) - The programming interface, defined
* [CLI documentation](CLI.md) - Learn how to call tasks and use compilers
* [Writing a Plugin](writing-a-plugin/) - The essentials of writing a gulp plugin
* [Why Use Pump?](why-use-pump/README.md) - Why to use the `pump` module instead of calling `.pipe` yourself
* [Simplified Chinese documentation][SimplifiedChineseDocs] - gulp 简体中文文档
* [Korean documentation][KoreanDocs] - gulp 한국어 참조 문서
* [Polish documentation](/docs/locale/pl_PL/README.md) - gulp Dokumentacja
## FAQ
See the [FAQ](FAQ.md) for the answers to commonly asked questions.
## Recipes
The community has written [recipes](recipes#recipes) for common gulp use-cases.
## Still got questions?
Post 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/).
## Videos
* [Intro to Gulp 4](https://youtu.be/N42LQ2dLoA8) presented by @addyosmani and @gauntface
## Books
* [Developing a gulp Edge](http://shop.oreilly.com/product/9781939902146.do)
* [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)
## Articles
* [Tagtree intro to gulp video](http://tagtree.io/gulp)
* [Introduction to node.js streams](https://github.com/substack/stream-handbook)
* [Video introduction to node.js streams](https://www.youtube.com/watch?v=QgEuZ52OZtU)
* [Getting started with gulp (by @markgdyr)](https://markgoodyear.com/2014/01/getting-started-with-gulp/)
* [A cheatsheet for gulp](https://github.com/osscafe/gulp-cheatsheet)
* [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)
* [Inspiration (slides) about why gulp was made](http://slid.es/contra/gulp)
* [Building With Gulp](http://www.smashingmagazine.com/2014/06/11/building-with-gulp/)
* [Gulp - The Basics (screencast)](https://www.youtube.com/watch?v=dwSLFai8ovQ)
* [Get started with gulp (video series)](https://www.youtube.com/playlist?list=PLRk95HPmOM6PN-G1xyKj9q6ap_dc9Yckm)
* [Optimize your web code with gulp](http://www.linuxuser.co.uk/tutorials/optimise-your-web-code-with-gulp-js)
* [Automate Your Tasks Easily with Gulp.js ](https://scotch.io/tutorials/automate-your-tasks-easily-with-gulp-js)
* [How to upgrade to Gulp v4](https://www.liquidlight.co.uk/blog/article/how-do-i-update-to-gulp-4/)
## Examples
- [Web Starter Kit gulpfile](https://github.com/google/web-starter-kit/blob/master/gulpfile.babel.js)
## License
All the documentation is covered by the CC0 license *(do whatever you want with it - public domain)*.
[](https://creativecommons.org/publicdomain/zero/1.0/)
To the extent possible under law, [Fractal](http://wearefractal.com) has waived all copyright and related or neighboring rights to this work.
[SpanishDocs]: https://github.com/bucaran/gulp-docs-es
[SimplifiedChineseDocs]: https://github.com/lisposter/gulp-docs-zh-cn
[KoreanDocs]: https://github.com/preco21/gulp-docs-ko
================================================
FILE: docs/advanced/creating-custom-registries.md
================================================
<!-- front-matter
id: creating-custom-registries
title: Creating Custom Registries
hide_title: true
sidebar_label: Creating Custom Registries
-->
# Creating Custom Registries
Allows 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].
## Structure
In order to be accepted by gulp, custom registries must follow a specific format.
```js
// as a function
function TestRegistry() {}
TestRegistry.prototype.init = function (gulpInst) {}
TestRegistry.prototype.get = function (name) {}
TestRegistry.prototype.set = function (name, fn) {}
TestRegistry.prototype.tasks = function () {}
// as a class
class TestRegistry {
init(gulpInst) {}
get(name) {}
set(name, fn) {}
tasks() {}
}
```
If a registry instance passed to `registry()` doesn't have all four methods, an error will be thrown.
## Registration
If we want to register our example registry from above, we will need to pass an instance of it to `registry()`.
```js
const { registry } = require('gulp');
// ... TestRegistry setup code
// good!
registry(new TestRegistry())
// bad!
registry(TestRegistry())
// This will trigger an error: 'Custom registries must be instantiated, but it looks like you passed a constructor'
```
## Methods
### `init(gulpInst)`
The `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
`gulpInst.task(taskName, fn)`.
#### Parameters
| parameter | type | note |
|:---------:|:----:|------|
| gulpInst | object | Instance of gulp. |
### `get(name)`
The `get()` method receives a task `name` for the custom registry to resolve and return, or `undefined` if no task with that name exists.
#### Parameters
| parameter | type | note |
|:---------:|:----:|------|
| name | string | Name of the task to be retrieved. |
### `set(name, fn)`
The `set()` method receives a task `name` and `fn`. This is called internally by `task()` to provide user-registered tasks to custom registries.
#### Parameters
| parameter | type | note |
|:---------:|:----:|------|
| name | string | Name of the task to be set. |
| fn | function | Task function to be set. |
### `tasks()`
Must return an object listing all tasks in the registry.
## Use Cases
### Sharing Tasks
To 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.
For example, you might want to share a `clean` task:
```js
const fs = require('fs');
const util = require('util');
const DefaultRegistry = require('undertaker-registry');
const del = require('del');
function CommonRegistry(opts){
DefaultRegistry.call(this);
opts = opts || {};
this.buildDir = opts.buildDir || './build';
}
util.inherits(CommonRegistry, DefaultRegistry);
CommonRegistry.prototype.init = function(gulpInst) {
const buildDir = this.buildDir;
const exists = fs.existsSync(buildDir);
if(exists){
throw new Error('Cannot initialize common tasks. ' + buildDir + ' directory exists.');
}
gulpInst.task('clean', function(){
return del([buildDir]);
});
}
module.exports = CommonRegistry;
```
Then to use it in a project:
```js
const { registry, series, task } = require('gulp');
const CommonRegistry = require('myorg-common-tasks');
registry(new CommonRegistry({ buildDir: '/dist' }));
task('build', series('clean', function build(cb) {
// do things
cb();
}));
```
### Sharing Functionality
By controlling how tasks are added to the registry, you can decorate them.
For 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:
```js
const { registry, series, task } = require('gulp');
const util = require('util');
const DefaultRegistry = require('undertaker-registry');
// Some task defined somewhere else
const BuildRegistry = require('./build.js');
const ServeRegistry = require('./serve.js');
function ConfigRegistry(config){
DefaultRegistry.call(this);
this.config = config;
}
util.inherits(ConfigRegistry, DefaultRegistry);
ConfigRegistry.prototype.set = function set(name, fn) {
var bound = fn.bind(this.config);
// Preserve internal properties and task metadata.
var task = Object.assign(bound, fn);
// The `DefaultRegistry` uses `this._tasks` for storage.
this._tasks[name] = task;
return task;
};
registry(new BuildRegistry());
registry(new ServeRegistry());
// `registry` will reset each task in the registry with
// `ConfigRegistry.prototype.set` which will bind them to the config object.
registry(new ConfigRegistry({
src: './src',
build: './build',
bindTo: '0.0.0.0:8888'
}));
task('default', series('clean', 'build', 'serve', function(cb) {
console.log('Server bind to ' + this.bindTo);
console.log('Serving' + this.build);
cb();
}));
```
## Examples
* [undertaker-registry][undertaker-registry-example]: The Gulp 4 default registry.
* [undertaker-common-tasks][undertaker-common-tasks-example]: Proof-of-concept custom registry that pre-defines tasks.
* [undertaker-task-metadata][undertaker-task-metadata-example]: Proof-of-concept custom registry that attaches metadata to each task.
[registry-api-docs]: ../api/registry.md
[undertaker-registry-example]: https://github.com/gulpjs/undertaker-registry
[undertaker-common-tasks-example]: https://github.com/gulpjs/undertaker-common-tasks
[undertaker-task-metadata-example]: https://github.com/gulpjs/undertaker-task-metadata
================================================
FILE: docs/api/README.md
================================================
## Table of Contents
* [API Concepts](concepts.md)
* [src()](src.md)
* [dest()](dest.md)
* [symlink()](symlink.md)
* [lastRun()](last-run.md)
* [series()](series.md)
* [parallel()](parallel.md)
* [watch()](watch.md)
* [task()](task.md)
* [registry()](registry.md)
* [tree()](tree.md)
* [Vinyl](vinyl.md)
* [Vinyl.isVinyl()](vinyl-isvinyl.md)
* [Vinyl.isCustomProp()](vinyl-iscustomprop.md)
================================================
FILE: docs/api/concepts.md
================================================
<!-- front-matter
id: concepts
title: API Concepts
hide_title: true
sidebar_label: Concepts
-->
# Concepts
The following concepts are prerequisites to understanding the API docs. They will be referenced throughout, refer back to this page for detailed explanations.
If you're new here, begin with the [Getting Started Guide][quick-start-docs].
## Vinyl
Vinyl 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.
## Vinyl adapters
While 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.
An adapter exposes:
* A method with the signature `src(globs, [options])` and returns a stream that produces Vinyl objects.
* A method with the signature `dest(folder, [options])` and returns a stream that consumes Vinyl objects.
* 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.
## Tasks
Each 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.
For a more detailed explanation, see [Creating Tasks][creating-tasks-doc].
## Globs
A 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.
If you don't have experience with globs, see [Explaining Globs][explaining-globs-docs].
## Glob base
A 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.
Vinyl 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.
For more in depth information, see the [glob-parent][glob-parent-external] repository.
## File system stats
File 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.
## File system modes
File 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.
## Modules
Gulp 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.
If 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.
* [undertaker][undertaker-external] - the task registration system
* [vinyl][vinyl-external] - the virtual file objects
* [vinyl-fs][vinyl-fs-external] - a vinyl adapter to your local file system
* [glob-watcher][glob-watcher-external] - the file watcher
* [bach][bach-external] - task orchestration using `series()` and `parallel()`
* [last-run][last-run-external] - tracks the last run time of a task
* [vinyl-sourcemap][vinyl-sourcemap-external] - built-in sourcemap support
* [gulp-cli][gulp-cli-external] - the command line interface for interacting with gulp
[quick-start-docs]: ../getting-started/1-quick-start.md
[creating-tasks-doc]: ../getting-started/3-creating-tasks.md
[explaining-globs-docs]: ../getting-started/6-explaining-globs.md
[undertaker-external]: https://github.com/gulpjs/undertaker
[vinyl-external]: https://github.com/gulpjs/vinyl
[vinyl-fs-external]: https://github.com/gulpjs/vinyl-fs
[glob-watcher-external]: https://github.com/gulpjs/glob-watcher
[bach-external]: https://github.com/gulpjs/bach
[last-run-external]: https://github.com/gulpjs/last-run
[vinyl-sourcemap-external]: https://github.com/gulpjs/vinyl-sourcemap
[gulp-cli-external]: https://github.com/gulpjs/gulp-cli
[semver-external]: https://semver.org
[fs-stats-external]: https://nodejs.org/api/fs.html#fs_class_fs_stats
[glob-parent-external]: https://github.com/es128/glob-parent
================================================
FILE: docs/api/dest.md
================================================
<!-- front-matter
id: dest
title: dest()
hide_title: true
sidebar_label: dest()
-->
# dest()
Creates a stream for writing [Vinyl][vinyl-concepts] objects to the file system.
## Usage
```js
const { src, dest } = require('gulp');
function copy() {
return src('input/*.js')
.pipe(dest('output/'));
}
exports.copy = copy;
```
## Signature
```js
dest(directory, [options])
```
### Parameters
| parameter | type | note |
|:--------------:|:-----:|--------|
| directory<br />**(required)** | string<br />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. |
| options | object | Detailed in [Options][options-section] below. |
### Returns
A stream that can be used in the middle or at the end of a pipeline to create files on the file system.
Whenever 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.
Whenever a file is created on the file system, the Vinyl object will be modified.
* The `cwd`, `base`, and `path` properties will be updated to match the created file.
* The `stat` property will be updated to match the file on the file system.
* If the `contents` property is a stream, it will be reset so it can be read again.
### Errors
When `directory` is an empty string, throws an error with the message, "Invalid dest() folder argument. Please specify a non-empty string or a function."
When `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."
When `directory` is a function that returns an empty string or `undefined`, emits an error with the message, "Invalid output folder".
### Options
**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.**
| name | type | default | note |
|:-------:|:------:|-----------|-------|
| cwd | string<br />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()`. |
| mode | number<br />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. |
| dirMode | number<br />function | | The mode used when creating directories. If not set, the process' mode will be used. |
| overwrite | boolean<br />function | true | When true, overwrites existing files with the same path. |
| append | boolean<br />function | false | If true, adds contents to the end of the file, instead of replacing existing contents. |
| sourcemaps | boolean<br />string<br />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. |
| relativeSymlinks | boolean<br />function | false | When false, any symbolic links created will be absolute.<br />**Note**: Ignored if a junction is being created, as they must be absolute. |
| useJunctions | boolean<br />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. |
## Metadata updates
Whenever 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.
This 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()`.
**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.
## Sourcemaps
Sourcemap support is built directly into `src()` and `dest()`, but it is disabled by default. Enable it to produce inline or external sourcemaps.
Inline sourcemaps:
```js
const { src, dest } = require('gulp');
const uglify = require('gulp-uglify');
src('input/**/*.js', { sourcemaps: true })
.pipe(uglify())
.pipe(dest('output/', { sourcemaps: true }));
```
External sourcemaps:
```js
const { src, dest } = require('gulp');
const uglify = require('gulp-uglify');
src('input/**/*.js', { sourcemaps: true })
.pipe(uglify())
.pipe(dest('output/', { sourcemaps: '.' }));
```
## Symbolic links on Windows
When 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:
* `'file'` when the target is a regular file
* `'junction'` when the target is a directory
* `'dir'` when the target is a directory and the user disables the `useJunctions` option
If 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()`.
For 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.
For 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.**
[sourcemaps-section]: #sourcemaps
[symbolic-links-section]: #symbolic-links-on-windows
[options-section]: #options
[metadata-updates-section]: #metadata-updates
[vinyl-concepts]: ../api/concepts.md#vinyl
================================================
FILE: docs/api/last-run.md
================================================
<!-- front-matter
id: lastrun
title: lastRun()
hide_title: true
sidebar_label: lastRun()
-->
# lastRun()
Retrieves the last time a task was successfully completed during the current running process. Most useful on subsequent task runs while a watcher is running.
When combined with `src()`, enables incremental builds to speed up execution times by skipping files that haven't changed since the last successful task completion.
## Usage
```js
const { src, dest, lastRun, watch } = require('gulp');
const imagemin = require('gulp-imagemin');
function images() {
return src('src/images/**/*.jpg', { since: lastRun(images) })
.pipe(imagemin())
.pipe(dest('build/img/'));
}
exports.default = function() {
watch('src/images/**/*.jpg', images);
};
```
## Signature
```js
lastRun(task, [precision])
```
### Parameters
| parameter | type | note |
|:--------------:|:------:|-------|
| task<br />**(required)** | function<br />string | The task function or the string alias of a registered task. |
| precision | number | Default: `1000` on Node v0.10, `0` on Node v0.12+. Detailed in [Timestamp precision][timestamp-precision-section] section below. |
### Returns
A timestamp (in milliseconds), matching the last completion time of the task. If the task has not been run or has failed, returns `undefined`.
To avoid an invalid state being cached, the returned value will be `undefined` if a task errors.
### Errors
When called with a value other than a string or function, throws an error with the message, "Only functions can check lastRun".
When called on a non-extensible function and Node is missing WeakMap, throws an error with the message, "Only extensible functions can check lastRun".
## Timestamp precision
While 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.
* `lastRun(someTask)` returns 1426000001111
* `lastRun(someTask, 100)` returns 1426000001100
* `lastRun(someTask, 1000)` returns 1426000001000
A file's [mtime stat][fs-stats-concepts] precision may vary depending on the node version and/or the file system used.
| platform | precision |
|:-----------:|:------------:|
| Node v0.10 | 1000ms |
| Node v0.12+ | 1ms |
| FAT32 file system | 2000ms |
| HFS+ or Ext3 file systems | 1000ms |
| NTFS using Node v0.10 | 1s |
| NTFS using Node 0.12+ | 100ms |
| Ext4 using Node v0.10 | 1000ms |
| Ext4 using Node 0.12+ | 1ms |
[timestamp-precision-section]: #timestamp-precision
[fs-stats-concepts]: ../api/concepts.md#file-system-stats
================================================
FILE: docs/api/parallel.md
================================================
<!-- front-matter
id: parallel
title: parallel()
hide_title: true
sidebar_label: parallel()
-->
# parallel()
Combines 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()`.
## Usage
```js
const { parallel } = require('gulp');
function javascript(cb) {
// body omitted
cb();
}
function css(cb) {
// body omitted
cb();
}
exports.build = parallel(javascript, css);
```
## Signature
```js
parallel(...tasks)
```
### Parameters
| parameter | type | note |
|:--------------:|:------:|-------|
| tasks<br />**(required)** | function<br />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. |
### Returns
A composed operation to be registered as a task or nested within other `series` and/or `parallel` compositions.
When 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.
### Errors
When no tasks are passed, throws an error with the message, "One or more tasks should be combined using series or parallel".
When invalid tasks or unregistered tasks are passed, throws an error with the message, "Task never defined".
## Forward references
A 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.
In 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.
During 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**.
## Avoid duplicating tasks
When a composed operation is run, each task will be executed every time it was supplied.
A `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.
If you have code like this:
```js
// This is INCORRECT
const { series, parallel } = require('gulp');
const clean = function(cb) {
// body omitted
cb();
};
const css = series(clean, function(cb) {
// body omitted
cb();
});
const javascript = series(clean, function(cb) {
// body omitted
cb();
});
exports.build = parallel(css, javascript);
```
Migrate to this:
```js
const { series, parallel } = require('gulp');
function clean(cb) {
// body omitted
cb();
}
function css(cb) {
// body omitted
cb();
}
function javascript(cb) {
// body omitted
cb();
}
exports.build = series(clean, parallel(css, javascript));
```
[undertaker-forward-reference-external]: https://github.com/gulpjs/undertaker-forward-reference
================================================
FILE: docs/api/registry.md
================================================
<!-- front-matter
id: registry
title: registry()
hide_title: true
sidebar_label: registry()
-->
# registry()
Allows custom registries to be plugged into the task system, which can provide shared tasks or augmented functionality.
**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.
When 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.
See [Creating Custom Registries][creating-custom-registries] for details.
## Usage
```js
const { registry, task, series } = require('gulp');
const FwdRef = require('undertaker-forward-reference');
registry(FwdRef());
task('default', series('forward-ref'));
task('forward-ref', function(cb) {
// body omitted
cb();
});
```
## Signature
```js
registry([registryInstance])
```
### Parameters
| parameter | type | note |
|:--------------:|:-----:|--------|
| registryInstance | object | An instance - not the class - of a custom registry. |
### Returns
If a `registryInstance` is passed, nothing will be returned. If no arguments are passed, returns the current registry instance.
### Errors
#### Incorrect parameter
When a constructor (instead of an instance) is passed as `registryInstance`, throws an error with the message:
> Custom registries must be instantiated, but it looks like you passed a constructor.
#### Missing `get` method
When a registry without a `get` method is passed as `registryInstance`, throws an error with the message:
> Custom registry must have `get` function.
#### Missing `set` method
When a registry without a `set` method is passed as `registryInstance`, throws an error with the message:
> Custom registry must have `set` function.
#### Missing `init` method
When a registry without an `init` method is passed as `registryInstance`, throws an error with the message:
> Custom registry must have `init` function"
#### Missing `tasks` method
When a registry without a `tasks` method is passed as `registryInstance`, throws an error with the message:
> Custom registry must have `tasks` function.
[creating-custom-registries]: ../advanced/creating-custom-registries.md
================================================
FILE: docs/api/series.md
================================================
<!-- front-matter
id: series
title: series()
hide_title: true
sidebar_label: series()
-->
# series()
Combines 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()`.
## Usage
```js
const { series } = require('gulp');
function javascript(cb) {
// body omitted
cb();
}
function css(cb) {
// body omitted
cb();
}
exports.build = series(javascript, css);
```
## Signature
```js
series(...tasks)
```
### Parameters
| parameter | type | note |
|:--------------:|:------:|-------|
| tasks<br />**(required)** | function<br />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. |
### Returns
A composed operation to be registered as a task or nested within other `series` and/or `parallel` compositions.
When the composed operation is executed, all tasks will be run sequentially. If an error occurs in one task, no subsequent tasks will be run.
### Errors
When no tasks are passed, throws an error with the message, "One or more tasks should be combined using series or parallel".
When invalid tasks or unregistered tasks are passed, throws an error with the message, "Task never defined".
## Forward references
A 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.
In 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.
During 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**.
## Avoid duplicating tasks
When a composed operation is run, each task will be executed every time it was supplied.
A `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.
If you have code like this:
```js
// This is INCORRECT
const { series, parallel } = require('gulp');
const clean = function(cb) {
// body omitted
cb();
};
const css = series(clean, function(cb) {
// body omitted
cb();
});
const javascript = series(clean, function(cb) {
// body omitted
cb();
});
exports.build = parallel(css, javascript);
```
Migrate to this:
```js
const { series, parallel } = require('gulp');
function clean(cb) {
// body omitted
cb();
}
function css(cb) {
// body omitted
cb();
}
function javascript(cb) {
// body omitted
cb();
}
exports.build = series(clean, parallel(css, javascript));
```
[undertaker-forward-reference-external]: https://github.com/gulpjs/undertaker-forward-reference
================================================
FILE: docs/api/src.md
================================================
<!-- front-matter
id: src
title: src()
hide_title: true
sidebar_label: src()
-->
# src()
Creates a stream for reading [Vinyl][vinyl-concepts] objects from the file system.
**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.
## Usage
```javascript
const { src, dest } = require('gulp');
function copy() {
return src('input/*.js')
.pipe(dest('output/'));
}
exports.copy = copy;
```
## Signature
```js
src(globs, [options])
```
### Parameters
| parameter | type | note |
|:--------------:|:------:|-------|
| globs | string<br />array | [Globs][globs-concepts] to watch on the file system. |
| options | object | Detailed in [Options][options-section] below. |
### Returns
A stream that can be used at the beginning or in the middle of a pipeline to add files based on the given globs.
### Errors
When 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`.
When an invalid glob is given in `globs`, throws an error with the message, "Invalid glob argument".
### Options
**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.**
| name | type | default | note |
|:--------:|:------:|------------|--------|
| encoding | string<br />boolean | "utf8" | When false, file contents are treated as binary. When a string, this is used as the text encoding. |
| buffer | boolean<br />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.<br />**Note:** Plugins may not implement support for streaming contents. |
| read | boolean<br />function | true | If false, files will be not be read and their Vinyl objects won't be writable to disk via `.dest()`. |
| since | date<br />timestamp<br />function | | When set, only creates Vinyl objects for files modified since the specified time. |
| removeBOM | boolean<br />function | true | When true, removes the BOM from UTF-8 encoded files. If false, ignores a BOM. |
| sourcemaps | boolean<br />function | false | If true, enables [sourcemaps][sourcemaps-section] support on Vinyl objects created. Loads inline sourcemaps and resolves external sourcemap links. |
| resolveSymlinks | boolean<br />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. |
| 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()`.<br />_This option is passed directly to [glob-stream][glob-stream-external]._ |
| base | string | | Explicitly set the `base` property on created Vinyl objects. Detailed in [API Concepts][glob-base-concepts].<br />_This option is passed directly to [glob-stream][glob-stream-external]._ |
| cwdbase | boolean | false | If true, `cwd` and `base` options should be aligned.<br />_This option is passed directly to [glob-stream][glob-stream-external]._ |
| root | string | | The root path that `globs` are resolved against.<br />_This option is passed directly to [glob-stream][glob-stream-external]._ |
| 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.<br />_This option is passed directly to [glob-stream][glob-stream-external]._ |
| uniqueBy | string<br />function | `'path'` | Remove duplicates from the stream by comparing the string property name or the result of the function.<br />**Note:** When using a function, the function receives the streamed data (objects containing `cwd`, `base`, `path` properties). |
| dot | boolean | false | If true, compare globs against dot files, like `.gitignore`.<br />_This option is passed directly to [anymatch][anymatch-external]._ |
| nounique | boolean | false | When false, prevents duplicate files in the result set.<br />_This option is passed directly to [anymatch][anymatch-external]._ |
| debug | boolean | false | If true, debugging information will be logged to the command line.<br />_This option is passed directly to [anymatch][anymatch-external]._ |
| nobrace | boolean | false | If true, avoids expanding brace sets - e.g. `{a,b}` or `{1..3}`.<br />_This option is passed directly to [anymatch][anymatch-external]._ |
| noglobstar | boolean | false | If true, treats double-star glob character as single-star glob character.<br />_This option is passed directly to [anymatch][anymatch-external]._ |
| noext | boolean | false | If true, avoids matching [extglob][extglob-docs] patterns - e.g. `+(ab)`.<br />_This option is passed directly to [anymatch][anymatch-external]._ |
| nocase | boolean | false | If true, performs a case-insensitive match.<br />**Note:** On case-insensitive file systems, non-magic patterns will match by default.<br />_This option is passed directly to [anymatch][anymatch-external]._ |
| 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`.<br />_This option is passed directly to [anymatch][anymatch-external]._ |
| ignore | string<br />array | | Globs to exclude from matches. This option is combined with negated `globs`.<br />**Note:** These globs are always matched against dot files, regardless of any other settings.<br />_This option is passed directly to [anymatch][anymatch-external]._ |
## Sourcemaps
Sourcemap support is built directly into `src()` and `dest()`, but is disabled by default. Enable it to produce inline or external sourcemaps.
Inline sourcemaps:
```js
const { src, dest } = require('gulp');
const uglify = require('gulp-uglify');
src('input/**/*.js', { sourcemaps: true })
.pipe(uglify())
.pipe(dest('output/', { sourcemaps: true }));
```
External sourcemaps:
```js
const { src, dest } = require('gulp');
const uglify = require('gulp-uglify');
src('input/**/*.js', { sourcemaps: true })
.pipe(uglify())
.pipe(dest('output/', { sourcemaps: '.' }));
```
[sourcemaps-section]: #sourcemaps
[options-section]: #options
[vinyl-concepts]: ../api/concepts.md#vinyl
[glob-base-concepts]: ../api/concepts.md#glob-base
[globs-concepts]: ../api/concepts.md#globs
[extglob-docs]: ../documentation-missing.md
[anymatch-external]: https://github.com/micromatch/anymatch
[glob-stream-external]: https://github.com/gulpjs/glob-stream
================================================
FILE: docs/api/symlink.md
================================================
<!-- front-matter
id: symlink
title: symlink()
hide_title: true
sidebar_label: symlink()
-->
# symlink()
Creates a stream for linking [Vinyl][vinyl-concepts] objects to the file system.
## Usage
```js
const { src, symlink } = require('gulp');
function link() {
return src('input/*.js')
.pipe(symlink('output/'));
}
exports.link = link;
```
## Signature
```js
symlink(directory, [options])
```
### Parameters
| parameter | type | note |
|:--------------:|:-----:|--------|
| directory<br />**(required)** | string<br />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. |
| options | object | Detailed in [Options][options-section] below. |
### Returns
A stream that can be used in the middle or at the end of a pipeline to create symbolic links on the file system.
Whenever 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.
Whenever a symbolic link is created on the file system, the Vinyl object will be modified.
* The `cwd`, `base`, and `path` properties will be updated to match the created symbolic link.
* The `stat` property will be updated to match the symbolic link on the file system.
* The `contents` property will be set to `null`.
* The `symlink` property will be added or replaced with original path.
**Note:** On Windows, directory links are created using junctions by default. The `useJunctions` option disables this behavior.
### Errors
When `directory` is an empty string, throws an error with the message, "Invalid symlink() folder argument. Please specify a non-empty string or a function."
When `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."
When `directory` is a function that returns an empty string or `undefined`, emits an error with the message, "Invalid output folder".
### Options
**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.**
| name | type | default | note |
|:-------:|:------:|-----------|-------|
| cwd | string<br />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()`. |
| dirMode | number<br />function | | The mode used when creating directories. If not set, the process' mode will be used. |
| overwrite | boolean<br />function | true | When true, overwrites existing files with the same path. |
| relativeSymlinks | boolean<br />function | false | When false, any symbolic links created will be absolute.<br />**Note**: Ignored if a junction is being created, as they must be absolute. |
| useJunctions | boolean<br />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. |
## Symbolic links on Windows
When 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:
* `'file'` when the target is a regular file
* `'junction'` when the target is a directory
* `'dir'` when the target is a directory and the user disables the `useJunctions` option
If 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()`.
For 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.
For 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.**
[options-section]: #options
[symbolic-links-section]: #symbolic-links-on-windows
[vinyl-concepts]: ../api/concepts.md#vinyl
================================================
FILE: docs/api/task.md
================================================
<!-- front-matter
id: task
title: task()
hide_title: true
sidebar_label: task()
-->
# task()
**Reminder**: This API isn't the recommended pattern anymore - [export your tasks][creating-tasks-docs].
Defines a task within the task system. The task can then be accessed from the command line and the `series()`, `parallel()`, and `lastRun()` APIs.
## Usage
Register a named function as a task:
```js
const { task } = require('gulp');
function build(cb) {
// body omitted
cb();
}
task(build);
```
Register an anonymous function as a task:
```js
const { task } = require('gulp');
task('build', function(cb) {
// body omitted
cb();
});
```
Retrieve a task that has been registered previously:
```js
const { task } = require('gulp');
task('build', function(cb) {
// body omitted
cb();
});
const build = task('build');
```
## Signature
```js
task([taskName], taskFunction)
```
### Parameters
If 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.
Since any registered task can be run from the command line, avoid using spaces in task names.
| parameter | type | note |
|:--------------:|:------:|-------|
| taskName | string | An alias for the task function within the task system. Not needed when using named functions for `taskFunction`. |
| taskFunction<br />**(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. |
### Returns
When registering a task, nothing is returned.
When 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.
### Errors
When registering a task where `taskName` is missing and `taskFunction` is anonymous, will throw an error with the message, "Task name must be specified".
## Task metadata
| property | type | note |
|:--------------:|:------:|-------|
| name | string | A special property of named functions. Used to register the task.<br />**Note:** [`name`][function-name-external] is not writable; it cannot be set or changed. |
| 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. |
| description | string | When attached to a `taskFunction` provides a description to be printed by the command line when listing tasks. |
| 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. |
```js
const { task } = require('gulp');
const clean = function(cb) {
// body omitted
cb();
};
clean.displayName = 'clean:all';
task(clean);
function build(cb) {
// body omitted
cb();
}
build.description = 'Build the project';
build.flags = { '-e': 'An example flag' };
task(build);
```
[task-metadata-section]: #task-metadata
[task-concepts]: ../api/concepts.md#tasks
[creating-tasks-docs]: ../getting-started/3-creating-tasks.md
[function-name-external]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/name
================================================
FILE: docs/api/tree.md
================================================
<!-- front-matter
id: tree
title: tree()
hide_title: true
sidebar_label: tree()
-->
# tree()
Fetches the current task dependency tree - in the rare case that it is needed.
Generally, `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.
## Usage
Example gulpfile:
```js
const { series, parallel } = require('gulp');
function one(cb) {
// body omitted
cb();
}
function two(cb) {
// body omitted
cb();
}
function three(cb) {
// body omitted
cb();
}
const four = series(one, two);
const five = series(four,
parallel(three, function(cb) {
// Body omitted
cb();
})
);
module.exports = { one, two, three, four, five };
```
Output for `tree()`:
```js
{
label: 'Tasks',
nodes: [ 'one', 'two', 'three', 'four', 'five' ]
}
```
Output for `tree({ deep: true })`:
```js
{
label: "Tasks",
nodes: [
{
label: "one",
type: "task",
nodes: []
},
{
label: "two",
type: "task",
nodes: []
},
{
label: "three",
type: "task",
nodes: []
},
{
label: "four",
type: "task",
nodes: [
{
label: "<series>",
type: "function",
branch: true,
nodes: [
{
label: "one",
type: "function",
nodes: []
},
{
label: "two",
type: "function",
nodes: []
}
]
}
]
},
{
label: "five",
type: "task",
nodes: [
{
label: "<series>",
type: "function",
branch: true,
nodes: [
{
label: "<series>",
type: "function",
branch: true,
nodes: [
{
label: "one",
type: "function",
nodes: []
},
{
label: "two",
type: "function",
nodes: []
}
]
},
{
label: "<parallel>",
type: "function",
branch: true,
nodes: [
{
label: "three",
type: "function",
nodes: []
},
{
label: "<anonymous>",
type: "function",
nodes: []
}
]
}
]
}
]
}
]
}
```
## Signature
```js
tree([options])
```
### Parameters
| parameter | type | note |
|:--------------:|------:|--------|
| options | object | Detailed in [Options][options-section] below. |
### Returns
An object detailing the tree of registered tasks - containing nested objects with `'label'` and `'nodes'` properties (which is [archy][archy-external] compatible).
Each object may have a `type` property that can be used to determine if the node is a `task` or `function`.
Each object may have a `branch` property that, when `true`, indicates the node was created using `series()` or `parallel()`.
### Options
| name | type | default | note |
|:-------:|:-------:|------------|--------|
| deep | boolean | false | If true, the entire tree will be returned. When false, only top level tasks will be returned. |
[options-section]: #options
[archy-external]: https://www.npmjs.com/package/archy
================================================
FILE: docs/api/vinyl-iscustomprop.md
================================================
<!-- front-matter
id: vinyl-iscustomprop
title: Vinyl.isCustomProp()
hide_title: true
sidebar_label: Vinyl.isCustomProp()
-->
# Vinyl.isCustomProp()
Determines 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.
This method is useful when extending the Vinyl class. Detailed in [Extending Vinyl][extending-vinyl-section] below.
## Usage
```js
const Vinyl = require('vinyl');
Vinyl.isCustomProp('sourceMap') === true;
Vinyl.isCustomProp('path') === false;
```
## Signature
```js
Vinyl.isCustomProp(property)
```
### Parameters
| parameter | type | note |
|:--------------:|:------:|-------|
| property | string | The property name to check. |
### Returns
True if the property is not internally managed.
## Extending Vinyl
When custom properties are managed internally, the static `isCustomProp` method must be extended and return false when one of the custom properties is queried.
```js
const Vinyl = require('vinyl');
const builtInProps = ['foo', '_foo'];
class SuperFile extends Vinyl {
constructor(options) {
super(options);
this._foo = 'example internal read-only value';
}
get foo() {
return this._foo;
}
static isCustomProp(name) {
return super.isCustomProp(name) && builtInProps.indexOf(name) === -1;
}
}
```
In the example above, `foo` and `_foo` will not be assigned to the new object when cloning or passed in `options` to `new SuperFile(options)`.
If your custom properties or logic require special handling during cloning, override the `clone` method while extending Vinyl.
[extending-vinyl-section]: #extending-vinyl
================================================
FILE: docs/api/vinyl-isvinyl.md
================================================
<!-- front-matter
id: vinyl-isvinyl
title: Vinyl.isVinyl()
hide_title: true
sidebar_label: Vinyl.isVinyl()
-->
# Vinyl.isVinyl()
Determines if an object is a Vinyl instance. Use this method instead of `instanceof`.
**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.
## Usage
```js
const Vinyl = require('vinyl');
const file = new Vinyl();
const notAFile = {};
Vinyl.isVinyl(file) === true;
Vinyl.isVinyl(notAFile) === false;
```
## Signature
```js
Vinyl.isVinyl(file);
```
### Parameters
| parameter | type | note |
|:--------------:|:------:|-------|
| file | object | The object to check. |
### Returns
True if the `file` object is a Vinyl instance.
================================================
FILE: docs/api/vinyl.md
================================================
<!-- front-matter
id: vinyl
title: Vinyl
hide_title: true
sidebar_label: Vinyl
-->
# Vinyl
A 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.
Vinyl objects can have transformations applied using [plugins][using-plugins-docs]. They may also be persisted to the file system using `dest()`.
When creating your own Vinyl objects - instead of generating with `src()` - use the external `vinyl` module, as shown in Usage below.
## Usage
```js
const Vinyl = require('vinyl');
const file = new Vinyl({
cwd: '/',
base: '/test/',
path: '/test/file.js',
contents: new Buffer('var x = 123')
});
file.relative === 'file.js';
file.dirname === '/test';
file.dirname = '/specs';
file.path === '/specs/file.js';
file.basename === 'file.js';
file.basename = 'file.txt';
file.path === '/specs/file.txt';
file.stem === 'file';
file.stem = 'foo';
file.path === '/specs/foo.txt';
file.extname === '.txt';
file.extname = '.js';
file.path === '/specs/foo.js';
```
## Signature
```js
new Vinyl([options])
```
### Parameters
| parameter | type | note |
|:--------------:|:------:|-------|
| options | object | Detailed in [Options][options-section] below. |
### Returns
An instance of the Vinyl class representing a single virtual file, detailed in [Vinyl instance][vinyl-instance-section] below.
### Errors
When 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.
### Options
| name | type | default | note |
|:-------:|:------:|-----------|--------|
| 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. |
| 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.|
| path | string | | The full, absolute file path. Will be [normalized][normalization-and-concatenation-section] and have trailing separators removed. |
| 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. |
| 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. |
| contents | ReadableStream<br />Buffer<br />`null` | `null` | The contents of the file. If `contents` is a ReadableStream, it is wrapped in a [cloneable-readable][cloneable-readable-external] stream. |
Any other properties on `options` will be directly assigned to the Vinyl instance.
```js
const Vinyl = require('vinyl');
const file = new Vinyl({ foo: 'bar' });
file.foo === 'bar';
```
## Vinyl instance
Each instance of a Vinyl object will have properties and methods to access and/or modify information about the virtual file.
### Instance properties
All 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.
| property | type | description | throws |
|:-----------:|:------:|----------------|----------|
| contents | ReadableStream<br />Buffer<br />`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`. |
| 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. | |
| 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. |
| 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`). |
| 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. |
| 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. | |
| 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. |
| dirname | string | Gets and sets the directory of the `path` instance property. | If accessed when `path` is not available. |
| stem | string | Gets and sets the stem (filename without extension) of the `path` instance property. | If accessed when `path` is not available. |
| extname | string | Gets and sets the extension of the `path` instance property. | If accessed when `path` is not available. |
| basename | string | Gets and sets the filename (`stem + extname`) of the `path` instance property. | If accessed when `path` is not available. |
| symlink | string | Gets and sets the reference path of a symbolic link. | If set to any non-string value. |
### Instance methods
| method | return type | returns |
|:----------:|:--------------:|--------|
| `isBuffer()` | boolean | If the `contents` instance property is a Buffer, returns true. |
| `isStream()` | boolean | If the `contents` instance property is a Stream, returns true. |
| `isNull()` | boolean | If the `contents` instance property is `null`, returns true. |
| `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. |
| `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. |
| `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. |
| `inspect()` | string | Returns a formatted interpretation of the Vinyl object. Automatically called by Node's console.log. |
## Normalization and concatenation
All 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.
```js
const file = new File();
file.path = '/' + 'test' + '/' + 'foo.bar';
console.log(file.path);
// posix => /test/foo.bar
// win32 => \\test\\foo.bar
```
[options-section]: #options
[vinyl-instance-section]: #vinyl-instance
[instance-properties-section]: #instance-properties
[normalization-and-concatenation-section]: #normalization-and-concatenation
[glob-base-concepts]: ../api/concepts.md#glob-base
[fs-stats-concepts]: ../api/concepts.md#file-system-stats
[using-plugins-docs]: ../getting-started/7-using-plugins.md
[cloneable-readable-external]: https://github.com/mcollina/cloneable-readable
================================================
FILE: docs/api/watch.md
================================================
<!-- front-matter
id: watch
title: watch()
hide_title: true
sidebar_label: watch()
-->
# watch()
Allows watching globs and running a task when a change occurs. Tasks are handled uniformly with the rest of the task system.
## Usage
```js
const { watch } = require('gulp');
watch(['input/*.js', '!input/something.js'], function(cb) {
// body omitted
cb();
});
```
## Signature
```js
watch(globs, [options], [task])
```
### Parameters
| parameter | type | note |
|:--------------:|:-----:|--------|
| globs<br />**(required)** | string<br />array | [Globs][globs-concepts] to watch on the file system. |
| options | object | Detailed in [Options][options-section] below. |
| task | function<br />string | A [task function][tasks-concepts] or composed task - generated by `series()` and `parallel()`. |
### Returns
An instance of [chokidar][chokidar-instance-section] for fine-grained control over your watch setup.
### Errors
When 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".
When 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)".
### Options
| name | type | default | note |
|:-------:|:------:|-----------|--------|
| ignoreInitial | boolean | true | If false, the task is called during instantiation as file paths are discovered. Use to trigger the task during startup.<br />**Note:** This option is passed to [chokidar][chokidar-external] but is defaulted to `true` instead of `false`. |
| 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. |
| 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. |
| events | string<br />array | [ 'add',<br />'change',<br />'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'`.<br />_This option is passed directly to [chokidar][chokidar-external]._ |
| persistent | boolean | true | If false, the watcher will not keep the Node process running. Disabling this option is not recommended.<br />_This option is passed directly to [chokidar][chokidar-external]._ |
| ignored | array<br />string<br />RegExp<br />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.<br />_This option is passed directly to [chokidar][chokidar-external]._ |
| 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.<br />_This option is passed directly to [chokidar][chokidar-external]._ |
| 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()`.<br />_This option is passed directly to [chokidar][chokidar-external]._ |
| disableGlobbing | boolean | false | If true, all `globs` are treated as literal path names, even if they have special characters.<br />_This option is passed directly to [chokidar][chokidar-external]._ |
| 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.<br />_This option is passed directly to [chokidar][chokidar-external]._ |
| interval | number | 100 | Combine with `usePolling: true`. Interval of file system polling.<br />_This option is passed directly to [chokidar][chokidar-external]._ |
| binaryInterval | number | 300 | Combine with `usePolling: true`. Interval of file system polling for binary files.<br />_This option is passed directly to [chokidar][chokidar-external]._ |
| 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.<br />_This option is passed directly to [chokidar][chokidar-external]._ |
| 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.<br />_This option is passed directly to [chokidar][chokidar-external]._ |
| depth | number | | Indicates how many nested levels of directories will be watched.<br />_This option is passed directly to [chokidar][chokidar-external]._ |
| awaitWriteFinish | boolean | false | Do not use this option, use `delay` instead.<br />_This option is passed directly to [chokidar][chokidar-external]._ |
| 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.<br />_This option is passed directly to [chokidar][chokidar-external]._ |
| 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.<br />_This option is passed directly to [chokidar][chokidar-external]._ |
## Chokidar instance
The `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.
**When using the chokidar instance directly, you will not have access to the task system integrations, including async completion, queueing, and delay.**
```js
const { watch } = require('gulp');
const watcher = watch(['input/*.js']);
watcher.on('change', function(path, stats) {
console.log(`File ${path} was changed`);
});
watcher.on('add', function(path, stats) {
console.log(`File ${path} was added`);
});
watcher.on('unlink', function(path, stats) {
console.log(`File ${path} was removed`);
});
watcher.close();
```
`watcher.on(eventName, eventHandler)`
Registers `eventHandler` functions to be called when the specified event occurs.
| parameter | type | note |
|:--------------:|:-----:|--------|
| eventName | string | The events that may be watched are `'add'`, `'addDir'`, `'change'`, `'unlink'`, `'unlinkDir'`, `'ready'`, `'error'`, or `'all'`. |
| eventHandler | function | Function to be called when the specified event occurs. Arguments detailed in the table below. |
| argument | type | note |
|:-------------:|:-----:|--------|
| 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`. |
| 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. |
`watcher.close()`
Shuts down the file watcher. Once shut down, no more events will be emitted.
`watcher.add(globs)`
Adds additional globs to an already-running watcher instance.
| parameter | type | note |
|:-------------:|:-----:|--------|
| globs | string<br />array | The additional globs to be watched. |
`watcher.unwatch(globs)`
Removes globs that are being watched, while the watcher continues with the remaining paths.
| parameter | type | note |
|:-------------:|:-----:|--------|
| globs | string<br />array | The globs to be removed. |
[chokidar-instance-section]: #chokidar-instance
[options-section]: #options
[tasks-concepts]: ../api/concepts.md#tasks
[globs-concepts]: ../api/concepts.md#globs
[fs-stats-concepts]: ../api/concepts.md#file-system-stats
[chokidar-external]: https://github.com/paulmillr/chokidar
[fsevents-external]: https://github.com/strongloop/fsevents
================================================
FILE: docs/documentation-missing.md
================================================
<!-- front-matter
id: documentation-missing
title: Documentation Missing
hide_title: true
-->
# Excuse our dust!
We'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.
-The Gulp Team
================================================
FILE: docs/getting-started/1-quick-start.md
================================================
<!-- front-matter
id: quick-start
title: Quick Start
hide_title: true
sidebar_label: Quick Start
-->
# Quick Start
If you've previously installed gulp globally, run `npm rm --global gulp` before following these instructions. For more information, read this [Sip][sip-article].
## Check for node, npm, and npx
```sh
node --version
```
![Output: v8.11.1][img-node-version-command]
```sh
npm --version
```
![Output: 5.6.0][img-npm-version-command]
```sh
npx --version
```
![Output: 9.7.1][img-npx-version-command]
If they are not installed, follow the instructions [here][node-install].
## Install the gulp command line utility
```sh
npm install --global gulp-cli
```
## Create a project directory and navigate into it
```sh
npx mkdirp my-project
```
```sh
cd my-project
```
## Create a package.json file in your project directory
```sh
npm init
```
This will guide you through giving your project a name, version, description, etc.
## Install the gulp package in your devDependencies
```sh
npm install --save-dev gulp
```
## Verify your gulp versions
```sh
gulp --version
```
Ensure the output matches the screenshot below or you might need to restart the steps in this guide.
![Output: CLI version 2.0.1 & Local version 4.0.0][img-gulp-version-command]
## Create a gulpfile
Using your text editor, create a file named gulpfile.js in your project root with these contents:
```js
function defaultTask(cb) {
// place code for your default task here
cb();
}
exports.default = defaultTask
```
## Test it
Run the gulp command in your project directory:
```sh
gulp
```
To run multiple tasks, you can use `gulp <task> <othertask>`.
## Result
The default task will run and do nothing.
![Output: Starting default & Finished default][img-gulp-command]
[sip-article]: https://medium.com/gulpjs/gulp-sips-command-line-interface-e53411d4467
[node-install]: https://nodejs.org/en/
[img-node-version-command]: https://gulpjs.com/img/docs-node-version-command.png
[img-npm-version-command]: https://gulpjs.com/img/docs-npm-version-command.png
[img-npx-version-command]: https://gulpjs.com/img/docs-npx-version-command.png
[img-gulp-version-command]: https://gulpjs.com/img/docs-gulp-version-command.png
[img-gulp-command]: https://gulpjs.com/img/docs-gulp-command.png
================================================
FILE: docs/getting-started/2-javascript-and-gulpfiles.md
================================================
<!-- front-matter
id: javascript-and-gulpfiles
title: JavaScript and Gulpfiles
hide_title: true
sidebar_label: JavaScript and Gulpfiles
-->
# JavaScript and Gulpfiles
Gulp 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.
## Gulpfile explained
A 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.
## Transpilation
You 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.
* For TypeScript, rename to `gulpfile.ts` and install the [ts-node][ts-node-module] module.
* For Babel, rename to `gulpfile.babel.js` and install the [@babel/register][babel-register-module] module.
__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.__
For a more advanced dive into this topic and the full list of supported extensions, see our [gulpfile transpilation][gulpfile-transpilation-advanced] documentation.
## Splitting a gulpfile
Many users start by adding all logic to a gulpfile. If it ever grows too big, it can be refactored into separate files.
Each 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.
Node'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.
[gulpfile-transpilation-advanced]: ../documentation-missing.md
[ts-node-module]: https://www.npmjs.com/package/ts-node
[babel-register-module]: https://www.npmjs.com/package/@babel/register
[esm-module]: https://www.npmjs.com/package/esm
================================================
FILE: docs/getting-started/3-creating-tasks.md
================================================
<!-- front-matter
id: creating-tasks
title: Creating Tasks
hide_title: true
sidebar_label: Creating Tasks
-->
# Creating Tasks
Each 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].
## Exporting
Tasks can be considered **public** or **private**.
* **Public tasks** are exported from your gulpfile, which allows them to be run by the `gulp` command.
* **Private tasks** are made to be used internally, usually used as part of `series()` or `parallel()` composition.
A 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.
```js
const { series } = require('gulp');
// The `clean` function is not exported so it can be considered a private task.
// It can still be used within the `series()` composition.
function clean(cb) {
// body omitted
cb();
}
// The `build` function is exported so it is public and can be run with the `gulp` command.
// It can also be used within the `series()` composition.
function build(cb) {
// body omitted
cb();
}
exports.build = build;
exports.default = series(clean, build);
```
![ALT TEXT MISSING][img-gulp-tasks-command]
<small>In 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.</small>
## Compose tasks
Gulp 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.
To have your tasks execute in order, use the `series()` method.
```js
const { series } = require('gulp');
function transpile(cb) {
// body omitted
cb();
}
function bundle(cb) {
// body omitted
cb();
}
exports.build = series(transpile, bundle);
```
For tasks to run at maximum concurrency, combine them with the `parallel()` method.
```js
const { parallel } = require('gulp');
function javascript(cb) {
// body omitted
cb();
}
function css(cb) {
// body omitted
cb();
}
exports.build = parallel(javascript, css);
```
Tasks are composed immediately when either `series()` or `parallel()` is called. This allows variation in the composition instead of conditional behavior inside individual tasks.
```js
const { series } = require('gulp');
function minify(cb) {
// body omitted
cb();
}
function transpile(cb) {
// body omitted
cb();
}
function livereload(cb) {
// body omitted
cb();
}
if (process.env.NODE_ENV === 'production') {
exports.build = series(transpile, minify);
} else {
exports.build = series(transpile, livereload);
}
```
`series()` and `parallel()` can be nested to any arbitrary depth.
```js
const { series, parallel } = require('gulp');
function clean(cb) {
// body omitted
cb();
}
function cssTranspile(cb) {
// body omitted
cb();
}
function cssMinify(cb) {
// body omitted
cb();
}
function jsTranspile(cb) {
// body omitted
cb();
}
function jsBundle(cb) {
// body omitted
cb();
}
function jsMinify(cb) {
// body omitted
cb();
}
function publish(cb) {
// body omitted
cb();
}
exports.build = series(
clean,
parallel(
cssTranspile,
series(jsTranspile, jsBundle)
),
parallel(cssMinify, jsMinify),
publish
);
```
When 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.
If you have code like this:
```js
// This is INCORRECT
const { series, parallel } = require('gulp');
const clean = function(cb) {
// body omitted
cb();
};
const css = series(clean, function(cb) {
// body omitted
cb();
});
const javascript = series(clean, function(cb) {
// body omitted
cb();
});
exports.build = parallel(css, javascript);
```
Migrate to this:
```js
const { series, parallel } = require('gulp');
function clean(cb) {
// body omitted
cb();
}
function css(cb) {
// body omitted
cb();
}
function javascript(cb) {
// body omitted
cb();
}
exports.build = series(clean, parallel(css, javascript));
```
[async-completion-docs]: ../getting-started/4-async-completion.md
[using-async-await-docs]: ../getting-started/4-async-completion.md#using-async-await
[img-gulp-tasks-command]: https://gulpjs.com/img/docs-gulp-tasks-command.png
[async-once]: https://github.com/gulpjs/async-once
================================================
FILE: docs/getting-started/4-async-completion.md
================================================
<!-- front-matter
id: async-completion
title: Async Completion
hide_title: true
sidebar_label: Async Completion
-->
# Async Completion
Node 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.
## Signal task completion
When 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.
When 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.
### Returning a stream
```js
const { src, dest } = require('gulp');
function streamTask() {
return src('*.js')
.pipe(dest('output'));
}
exports.default = streamTask;
```
### Returning a promise
```js
function promiseTask() {
return Promise.resolve('the value is ignored');
}
exports.default = promiseTask;
```
### Returning an event emitter
```js
const { EventEmitter } = require('events');
function eventEmitterTask() {
const emitter = new EventEmitter();
// Emit has to happen async otherwise gulp isn't listening yet
setTimeout(() => emitter.emit('finish'), 250);
return emitter;
}
exports.default = eventEmitterTask;
```
### Returning a child process
```js
const { exec } = require('child_process');
function childProcessTask() {
return exec('date');
}
exports.default = childProcessTask;
```
### Returning an observable
```js
const { of } = require('rxjs');
function observableTask() {
return of(1, 2, 3);
}
exports.default = observableTask;
```
### Using an error-first callback
If 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.
```js
function callbackTask(cb) {
// `cb()` should be called by some async work
cb();
}
exports.default = callbackTask;
```
To indicate to gulp that an error occurred in a task using an error-first callback, call it with an `Error` as the only argument.
```js
function callbackError(cb) {
// `cb()` should be called by some async work
cb(new Error('kaboom'));
}
exports.default = callbackError;
```
However, you'll often pass this callback to another API instead of calling it yourself.
```js
const fs = require('fs');
function passingCallback(cb) {
fs.access('gulpfile.js', cb);
}
exports.default = passingCallback;
```
## No synchronous tasks
Synchronous 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.
When 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.
## Using async/await
When 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.
```js
const fs = require('fs');
async function asyncAwaitTask() {
const { version } = JSON.parse(fs.readFileSync('package.json', 'utf8'));
console.log(version);
await Promise.resolve('some result');
}
exports.default = asyncAwaitTask;
```
[node-api-error-first-callbacks]: https://nodejs.org/api/errors.html#errors_error_first_callbacks
[stream-docs]: https://nodejs.org/api/stream.html#stream_stream
[promise-docs]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises
[event-emitter-docs]: https://nodejs.org/api/events.html#events_events
[child-process-docs]: https://nodejs.org/api/child_process.html#child_process_child_process
[observable-docs]: https://github.com/tc39/proposal-observable/blob/master/README.md
[async-await-docs]: https://developers.google.com/web/fundamentals/primers/async-functions
================================================
FILE: docs/getting-started/5-working-with-files.md
================================================
<!-- front-matter
id: working-with-files
title: Working with Files
hide_title: true
sidebar_label: Working with Files
-->
# Working with Files
The `src()` and `dest()` methods are exposed by gulp to interact with files on your computer.
`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.
The stream produced by `src()` should be returned from a task to signal async completion, as mentioned in [Creating Tasks][creating-tasks-docs].
```js
const { src, dest } = require('gulp');
exports.default = function() {
return src('src/*.js')
.pipe(dest('output/'));
}
```
The main API of a stream is the `.pipe()` method for chaining Transform or Writable streams.
```js
const { src, dest } = require('gulp');
const babel = require('gulp-babel');
exports.default = function() {
return src('src/*.js')
.pipe(babel())
.pipe(dest('output/'));
}
```
`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).
Most often plugins will be placed between `src()` and `dest()` using the `.pipe()` method and will transform the files within the stream.
## Adding files to the stream
`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.
This can be useful for transpiling some files before adding plain JavaScript files to the pipeline and uglifying everything.
```js
const { src, dest } = require('gulp');
const babel = require('gulp-babel');
const uglify = require('gulp-uglify');
exports.default = function() {
return src('src/*.js')
.pipe(babel())
.pipe(src('vendor/*.js'))
.pipe(uglify())
.pipe(dest('output/'));
}
```
## Output in phases
`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.
This feature can be useful to create unminified and minified files with the same pipeline.
```js
const { src, dest } = require('gulp');
const babel = require('gulp-babel');
const uglify = require('gulp-uglify');
const rename = require('gulp-rename');
exports.default = function() {
return src('src/*.js')
.pipe(babel())
.pipe(src('vendor/*.js'))
.pipe(dest('output/'))
.pipe(uglify())
.pipe(rename({ extname: '.min.js' }))
.pipe(dest('output/'));
}
```
## Modes: streaming, buffered, and empty
`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()`.
* 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.
* 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.
* Empty mode contains no contents and is useful when only working with file metadata.
[explaining-globs-docs]: ../getting-started/6-explaining-globs.md
[creating-tasks-docs]: ../getting-started/3-creating-tasks.md
[overlapping-globs-docs]: ../getting-started/6-explaining-globs.md#overlapping-globs
[node-streams-docs]: https://nodejs.org/api/stream.html
[symlink-api-docs]: ../api/symlink.md
[src-options-api-docs]: ../api/src.md#options
================================================
FILE: docs/getting-started/6-explaining-globs.md
================================================
<!-- front-matter
id: explaining-globs
title: Explaining Globs
hide_title: true
sidebar_label: Explaining Globs
-->
# Explaining Globs
A 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.
The `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.
## Segments and separators
A 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.
Here, the * is escaped, so it is treated as a literal instead of a wildcard character.
```js
'glob_with_uncommon_\\*_character.js'
```
Avoid 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.
```js
const invalidGlob = path.join(__dirname, 'src/*.js');
```
## Special character: * (single-star)
Matches any amount - including none - of characters within a single segment. Useful for globbing files within one directory.
This glob will match files like `index.js`, but not files like `scripts/index.js` or `scripts/nested/index.js`
```js
'*.js'
```
## Special character: ** (double-star)
Matches 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.
Here, 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`.
```js
'scripts/**/*.js'
```
<small>In the previous example, if `scripts/` wasn't prefixed, all dependencies in `node_modules` or other directories would also be matched.</small>
## Special character: ! (negative)
Globs 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.
Here, the `scripts/` directory will be traversed for all files ending in `.js`, but all files from the `scripts/vendor/` directory will be excluded.
```js
['scripts/**/*.js', '!scripts/vendor/**']
```
Negative globs can be used as an alternative for restricting double-star globs.
```js
['**/*.js', '!node_modules/**']
```
## Ordered globs
Versions of gulp before v5 allowed "ordered globs"; however, that has been removed to align with most globbing libraries in the ecosystem.
If you need the "ordered glob" functionality, you can use the [ordered-read-streams][ordered-read-streams-docs] library to combine streams:
```js
const order = require("ordered-read-streams");
exports.default = function () {
return order([
gulp.src("input/jquery/dist/jquery.js"),
gulp.src("input/detect_swipe/jquery.detect_swipe.js"),
]).pipe(gulp.dest('output/'));
}
```
## Overlapping globs
Two 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.
## Advanced resources
Most 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.
* [Micromatch Documentation][micromatch-docs]
* [node-glob's Glob Primer][glob-primer-docs]
* [Begin's Globbing Documentation][begin-globbing-docs]
* [Wikipedia's Glob Page][wikipedia-glob]
[micromatch-docs]: https://github.com/micromatch/micromatch
[glob-primer-docs]: https://github.com/isaacs/node-glob#glob-primer
[begin-globbing-docs]: https://github.com/begin/globbing#what-is-globbing
[wikipedia-glob]: https://en.wikipedia.org/wiki/Glob_(programming)
[ordered-read-streams-docs]: https://github.com/gulpjs/ordered-read-streams#orderedstreams-options
================================================
FILE: docs/getting-started/7-using-plugins.md
================================================
<!-- front-matter
id: using-plugins
title: Using Plugins
hide_title: true
sidebar_label: Using Plugins
-->
# Using Plugins
Gulp 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.
Plugins from npm - using the "gulpplugin" and "gulpfriendly" keywords - can be browsed and searched on the [plugin search page][gulp-plugin-site].
Each 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.
```js
const { src, dest } = require('gulp');
const uglify = require('gulp-uglify');
const rename = require('gulp-rename');
exports.default = function() {
return src('src/*.js')
// The gulp-uglify plugin won't update the filename
.pipe(uglify())
// So use gulp-rename to change the extension
.pipe(rename({ extname: '.min.js' }))
.pipe(dest('output/'));
}
```
## Do you need a plugin?
Not 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.
```js
const { rollup } = require('rollup');
// Rollup's promise API works great in an `async` task
exports.default = async function() {
const bundle = await rollup({
input: 'src/index.js'
});
return bundle.write({
file: 'output/bundle.js',
format: 'iife'
});
}
```
Plugins should always transform files. Use a (non-plugin) Node module or library for any other operations.
```js
const del = require('delete');
exports.default = function(cb) {
// Use the `delete` module directly, instead of using gulp-rimraf
del(['output/*.js'], cb);
}
```
## Conditional plugins
Since plugin operations shouldn't be file-type-aware, you may need a plugin like [gulp-if][gulp-if-package] to transform subsets of files.
```js
const { src, dest } = require('gulp');
const gulpif = require('gulp-if');
const uglify = require('gulp-uglify');
function isJavaScript(file) {
// Check if file extension is '.js'
return file.extname === '.js';
}
exports.default = function() {
// Include JavaScript and CSS files in a single pipeline
return src(['src/*.js', 'src/*.css'])
// Only apply gulp-uglify plugin to JavaScript files
.pipe(gulpif(isJavaScript, uglify()))
.pipe(dest('output/'));
}
```
## Inline plugins
Inline plugins are one-off Transform Streams you define inside your gulpfile by writing the desired behavior.
There are two situations where creating an inline plugin is helpful:
* Instead of creating and maintaining your own plugin.
* Instead of forking a plugin that exists to add a feature you want.
```js
const { src, dest } = require('gulp');
const uglify = require('uglify-js');
const through2 = require('through2');
exports.default = function() {
return src('src/*.js')
// Instead of using gulp-uglify, you can create an inline plugin
.pipe(through2.obj(function(file, _, cb) {
if (file.isBuffer()) {
const code = uglify.minify(file.contents.toString())
file.contents = Buffer.from(code.code)
}
cb(null, file);
}))
.pipe(dest('output/'));
}
```
[gulp-plugin-site]: https://gulpjs.com/plugins/
[through2-docs]: https://github.com/rvagg/through2
[gulp-if-package]: https://www.npmjs.com/package/gulp-if
================================================
FILE: docs/getting-started/8-watching-files.md
================================================
<!-- front-matter
id: watching-files
title: Watching Files
hide_title: true
sidebar_label: Watching Files
-->
# Watching Files
The `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.
This API provides built-in delay and queueing based on most-common-use defaults.
```js
const { watch, series } = require('gulp');
function clean(cb) {
// body omitted
cb();
}
function javascript(cb) {
// body omitted
cb();
}
function css(cb) {
// body omitted
cb();
}
exports.default = function() {
// You can use a single task
watch('src/*.css', css);
// Or a composed task
watch('src/*.js', series(clean, javascript));
};
```
## Warning: avoid synchronous
A 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.
There 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.
## Watched events
By default, the watcher executes tasks whenever a file is created, changed, or deleted.
If 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'`.
```js
const { watch } = require('gulp');
exports.default = function() {
// All events will be watched
watch('src/*.js', { events: 'all' }, function(cb) {
// body omitted
cb();
});
};
```
## Initial execution
Upon calling `watch()`, the tasks won't be executed, instead they'll wait for the first file change.
To execute tasks before the first file change, set the `ignoreInitial` option to `false`.
```js
const { watch } = require('gulp');
exports.default = function() {
// The task will be executed upon startup
watch('src/*.js', { ignoreInitial: false }, function(cb) {
// body omitted
cb();
});
};
```
## Queueing
Each `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.
To disable queueing, set the `queue` option to `false`.
```js
const { watch } = require('gulp');
exports.default = function() {
// The task will be run (concurrently) for every change made
watch('src/*.js', { queue: false }, function(cb) {
// body omitted
cb();
});
};
```
## Delay
Upon 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.
To adjust the delay duration, set the `delay` option to a positive integer.
```js
const { watch } = require('gulp');
exports.default = function() {
// The task won't be run until 500ms have elapsed since the first change
watch('src/*.js', { delay: 500 }, function(cb) {
// body omitted
cb();
});
};
```
## Using the watcher instance
You 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()`.
__Be careful:__ The returned chokidar instance doesn't have queueing, delay, or async completion features.
## Optional dependency
Gulp 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.
If fsevents installation is skipped, a fallback watcher will be used and any errors occurring in your gulpfile aren't related to this warning.
[globs-docs]: ../getting-started/6-explaining-globs.md
[creating-tasks-docs]: ../getting-started/3-creating-tasks.md
[async-completion-doc]: ../getting-started/4-async-completion.md
[chokidar-module-package]: https://www.npmjs.com/package/chokidar
[fsevents-package]: https://www.npmjs.com/package/fsevents
================================================
FILE: docs/getting-started/README.md
================================================
# Getting Started
1. [Quick Start](1-quick-start.md)
2. [JavaScript and Gulpfiles](2-javascript-and-gulpfiles.md)
3. [Creating Tasks](3-creating-tasks.md)
4. [Async Completion](4-async-completion.md)
5. [Working with Files](5-working-with-files.md)
6. [Explaining Globs](6-explaining-globs.md)
7. [Using Plugins](7-using-plugins.md)
8. [Watching Files](8-watching-files.md)
================================================
FILE: docs/getting-started.md
================================================
## This documentation has moved!
You can find the new documentation in our [Quick Start](getting-started/1-quick-start.md) guide.
While you are there, check out our expanded [Getting Started](getting-started/) documentation.
================================================
FILE: docs/recipes/README.md
================================================
# Recipes
* [Automate release workflow](automate-releases.md)
* [Combining streams to handle errors](combining-streams-to-handle-errors.md)
* [Delete files and folders](delete-files-folder.md)
* [Fast browserify builds with watchify](fast-browserify-builds-with-watchify.md)
* [Incremental rebuilding, including operating on full file sets](incremental-builds-with-concatenate.md)
* [Make stream from buffer (memory contents)](make-stream-from-buffer.md)
* [Mocha test-runner with gulp](mocha-test-runner-with-gulp.md)
* [Pass parameters from the command line](pass-arguments-from-cli.md)
* [Generating a file per folder](running-task-steps-per-folder.md)
* [Server with live-reloading and CSS injection](server-with-livereload-and-css-injection.md)
* [Sharing streams with stream factories](sharing-streams-with-stream-factories.md)
* [Using multiple sources in one task](using-multiple-sources-in-one-task.md)
* [Browserify + Uglify with sourcemaps](browserify-uglify-sourcemap.md)
* [Browserify + Globs](browserify-with-globs.md)
* [Browserify + Globs (multiple destination)](browserify-multiple-destination.md)
* [Output both a minified and non-minified version](minified-and-non-minified.md)
* [Templating with Swig and YAML front-matter](templating-with-swig-and-yaml-front-matter.md)
* [Run Grunt Tasks from Gulp](run-grunt-tasks-from-gulp.md)
* [Rollup with rollup-stream](rollup-with-rollup-stream.md)
* [Run gulp task via cron job](cron-task.md)
================================================
FILE: docs/recipes/automate-releases.md
================================================
<!-- front-matter
id: automate-releases
title: Automate Releases
hide_title: true
sidebar_label: Automate Releases
-->
# Automate Releases
If your project follows a semantic versioning, it may be a good idea to automatize the steps needed to do a release.
The recipe below bumps the project version, commits the changes to git and creates a new GitHub release.
For 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:
```
GH_TOKEN=ff34885...
```
Don't forget to add `.env` to your `.gitignore`.
Next, install all the necessary dependencies for this recipe:
```sh
npm install --save-dev conventional-recommended-bump conventional-changelog-cli conventional-github-releaser dotenv execa
```
Based on your environment, setup and preferences, your release workflow might look something like this:
``` js
const gulp = require('gulp');
const conventionalRecommendedBump = require('conventional-recommended-bump');
const conventionalGithubReleaser = require('conventional-github-releaser');
const execa = require('execa');
const fs = require('fs');
const { promisify } = require('util');
const dotenv = require('dotenv');
// load environment variables
const result = dotenv.config();
if (result.error) {
throw result.error;
}
// Conventional Changelog preset
const preset = 'angular';
// print output of commands into the terminal
const stdio = 'inherit';
async function bumpVersion() {
// get recommended version bump based on commits
const { releaseType } = await promisify(conventionalRecommendedBump)({ preset });
// bump version without committing and tagging
await execa('npm', ['version', releaseType, '--no-git-tag-version'], {
stdio,
});
}
async function changelog() {
await execa(
'npx',
[
'conventional-changelog',
'--preset',
preset,
'--infile',
'CHANGELOG.md',
'--same-file',
],
{ stdio }
);
}
async function commitTagPush() {
// even though we could get away with "require" in this case, we're taking the safe route
// because "require" caches the value, so if we happen to use "require" again somewhere else
// we wouldn't get the current value, but the value of the last time we called "require"
const { version } = JSON.parse(await promisify(fs.readFile)('package.json'));
const commitMsg = `chore: release ${version}`;
await execa('git', ['add', '.'], { stdio });
await execa('git', ['commit', '--message', commitMsg], { stdio });
await execa('git', ['tag', `v${version}`], { stdio });
await execa('git', ['push', '--follow-tags'], { stdio });
}
function githubRelease(done) {
conventionalGithubReleaser(
{ type: 'oauth', token: process.env.GH_TOKEN },
{ preset },
done
);
}
exports.release = gulp.series(
bumpVersion,
changelog,
commitTagPush,
githubRelease
);
```
================================================
FILE: docs/recipes/browserify-multiple-destination.md
================================================
# Browserify + Globs (multiple destination)
This example shows how to set up a task of bundling multiple entry points into multiple destinations using browserify.
The below `js` task bundles all the `.js` files under `src/` as entry points and writes the results under `dest/`.
```js
var gulp = require('gulp');
var browserify = require('browserify');
var log = require('gulplog');
var tap = require('gulp-tap');
var buffer = require('gulp-buffer');
var sourcemaps = require('gulp-sourcemaps');
var uglify = require('gulp-uglify');
gulp.task('js', function () {
return gulp.src('src/**/*.js', {read: false}) // no need of reading file because browserify does.
// transform file objects using gulp-tap plugin
.pipe(tap(function (file) {
log.info('bundling ' + file.path);
// replace file contents with browserify's bundle stream
file.contents = browserify(file.path, {debug: true}).bundle();
}))
// transform streaming contents into buffer contents (because gulp-sourcemaps does not support streaming contents)
.pipe(buffer())
// load and init sourcemaps
.pipe(sourcemaps.init({loadMaps: true}))
.pipe(uglify())
// write sourcemaps
.pipe(sourcemaps.write('./'))
.pipe(gulp.dest('dest'));
});
```
================================================
FILE: docs/recipes/browserify-transforms.md
================================================
# Browserify + Transforms
[Browserify](https://github.com/browserify/browserify) has become an important and indispensable
tool but requires being wrapped before working well with gulp. Below is a simple recipe for using
Browserify with transforms.
See 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.
``` javascript
'use strict';
var browserify = require('browserify');
var gulp = require('gulp');
var source = require('vinyl-source-stream');
var buffer = require('vinyl-buffer');
var log = require('gulplog');
var uglify = require('gulp-uglify');
var reactify = require('reactify');
gulp.task('javascript', function () {
// set up the browserify instance on a task basis
var b = browserify({
entries: './entry.js',
debug: true,
// defining transforms here will avoid crashing your stream
transform: [reactify]
});
return b.bundle()
.pipe(source('app.js', { sourcemaps: true }))
.pipe(buffer())
// Add transformation tasks to the pipeline here.
.pipe(uglify())
.on('error', log.error)
.pipe(gulp.dest('./dist/js/', { sourcemaps: '../sourcemaps/' }));
});
```
================================================
FILE: docs/recipes/browserify-uglify-sourcemap.md
================================================
# Browserify + Uglify2 with sourcemaps
[Browserify](https://github.com/browserify/browserify) has become an important and indispensable
tool but requires being wrapped before working well with gulp. Below is a simple recipe for using
Browserify with full sourcemaps that resolve to the original individual files.
See 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.
A simple `gulpfile.js` file for Browserify + Uglify2 with sourcemaps:
``` javascript
'use strict';
var browserify = require('browserify');
var gulp = require('gulp');
var source = require('vinyl-source-stream');
var buffer = require('vinyl-buffer');
var uglify = require('gulp-uglify');
var sourcemaps = require('gulp-sourcemaps');
var log = require('gulplog');
gulp.task('javascript', function () {
// set up the browserify instance on a task basis
var b = browserify({
entries: './entry.js',
debug: true
});
return b.bundle()
.pipe(source('app.js'))
.pipe(buffer())
.pipe(sourcemaps.init({loadMaps: true}))
// Add transformation tasks to the pipeline here.
.pipe(uglify())
.on('error', log.error)
.pipe(sourcemaps.write('./'))
.pipe(gulp.dest('./dist/js/'));
});
```
================================================
FILE: docs/recipes/browserify-with-globs.md
================================================
# Browserify + Globs
[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.
It does not, however, show how one may use gulp and Browserify with multiple entry files.
See 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.
``` javascript
'use strict';
var browserify = require('browserify');
var gulp = require('gulp');
var source = require('vinyl-source-stream');
var buffer = require('vinyl-buffer');
var globby = require('globby');
var through = require('through2');
var log = require('gulplog');
var uglify = require('gulp-uglify');
var sourcemaps = require('gulp-sourcemaps');
var reactify = require('reactify');
gulp.task('javascript', function () {
// gulp expects tasks to return a stream, so we create one here.
var bundledStream = through();
bundledStream
// turns the output bundle stream into a stream containing
// the normal attributes gulp plugins expect.
.pipe(source('app.js'))
// the rest of the gulp task, as you would normally write it.
// here we're copying from the Browserify + Uglify2 recipe.
.pipe(buffer())
.pipe(sourcemaps.init({loadMaps: true}))
// Add gulp plugins to the pipeline here.
.pipe(uglify())
.on('error', log.error)
.pipe(sourcemaps.write('./'))
.pipe(gulp.dest('./dist/js/'));
// "globby" replaces the normal "gulp.src" as Browserify
// creates it's own readable stream.
globby(['./entries/*.js']).then(function(entries) {
// create the Browserify instance.
var b = browserify({
entries: entries,
debug: true,
transform: [reactify]
});
// pipe the Browserify stream into the stream we created earlier
// this starts our gulp pipeline.
b.bundle().pipe(bundledStream);
}).catch(function(err) {
// ensure any errors from globby are handled
bundledStream.emit('error', err);
});
// finally, we return the stream, so gulp knows when this task is done.
return bundledStream;
});
```
================================================
FILE: docs/recipes/combining-streams-to-handle-errors.md
================================================
# Combining streams to handle errors
By 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.
By 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.
Here's an example of using it in a gulpfile:
```js
var combiner = require('stream-combiner2');
var uglify = require('gulp-uglify');
var gulp = require('gulp');
gulp.task('test', function() {
return combiner.obj([
gulp.src('bootstrap/js/*.js'),
uglify(),
gulp.dest('public/bootstrap')
])
// any errors in the above streams will get caught
// by this listener, instead of being thrown:
.on('error', console.error.bind(console));
});
```
================================================
FILE: docs/recipes/cron-task.md
================================================
# Run gulp task via cron job
While logged in via a user that has privileges to run `gulp`, run the following:
crontab -e
to edit your current "[crontab](https://en.wikipedia.org/wiki/Cron)" file.
Typically, within a cron job, you want to run any binary using absolute paths,
so an initial approach to running `gulp build` every minute might look like:
* * * * * cd /your/dir/to/run/in && /usr/local/bin/gulp build
However, you might see in the cron logs that you get this error:
> `/usr/bin/env: node: No such file or directory`
To fix this, we need to add a [symbolic link](https://en.wikipedia.org/wiki/Ln_\(Unix\))
within `/usr/bin` to point to the actual path of our node binary.
Be sure you are logged in as a **sudo** user, and paste in the following command to your terminal:
sudo ln -s $(which node) /usr/bin/node
Once this link is established, your cron task should run successfully.
================================================
FILE: docs/recipes/delete-files-folder.md
================================================
# Delete files and folders
You 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.
Let'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):
```sh
$ npm install --save-dev gulp del
```
Imagine the following file structure:
```
.
├── dist
│ ├── report.csv
│ ├── desktop
│ └── mobile
│ ├── app.js
│ ├── deploy.json
│ └── index.html
└── src
```
In the gulpfile we want to clean out the contents of the `mobile` folder before running our build:
```js
var gulp = require('gulp');
var del = require('del');
gulp.task('clean:mobile', function () {
return del([
'dist/report.csv',
// here we use a globbing pattern to match everything inside the `mobile` folder
'dist/mobile/**/*',
// we don't want to clean this file though so we negate the pattern
'!dist/mobile/deploy.json'
]);
});
gulp.task('default', gulp.series('clean:mobile'));
```
## Delete files in a pipeline
You might want to delete some files after processing them in a pipeline.
We'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.
```sh
$ npm install --save-dev gulp del vinyl-paths
```
Imagine the following file structure:
```
.
├── tmp
│ ├── rainbow.js
│ └── unicorn.js
└── dist
```
```js
var gulp = require('gulp');
var stripDebug = require('gulp-strip-debug'); // only as an example
var del = require('del');
var vinylPaths = require('vinyl-paths');
gulp.task('clean:tmp', function () {
return gulp.src('tmp/*')
.pipe(vinylPaths(del))
.pipe(stripDebug())
.pipe(gulp.dest('dist'));
});
gulp.task('default', gulp.series('clean:tmp'));
```
This will only delete the tmp dir.
Only do this if you're already using other plugins in the pipeline, otherwise just use the module directly as `gulp.src` is costly.
================================================
FILE: docs/recipes/fast-browserify-builds-with-watchify.md
================================================
# Fast browserify builds with watchify
As 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.
That'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.
Watchify 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.
``` javascript
'use strict';
var watchify = require('watchify');
var browserify = require('browserify');
var gulp = require('gulp');
var source = require('vinyl-source-stream');
var buffer = require('vinyl-buffer');
var log = require('gulplog');
var sourcemaps = require('gulp-sourcemaps');
var assign = require('lodash.assign');
// add custom browserify options here
var customOpts = {
entries: ['./src/index.js'],
debug: true
};
var opts = assign({}, watchify.args, customOpts);
var b = watchify(browserify(opts));
// add transformations here
// i.e. b.transform(coffeeify);
gulp.task('js', bundle); // so you can run `gulp js` to build the file
b.on('update', bundle); // on any dep update, runs the bundler
b.on('log', log.info); // output build logs to terminal
function bundle() {
return b.bundle()
// log errors if they happen
.on('error', log.error.bind(log, 'Browserify Error'))
.pipe(source('bundle.js'))
// optional, remove if you don't need to buffer file contents
.pipe(buffer())
// optional, remove if you dont want sourcemaps
.pipe(sourcemaps.init({loadMaps: true})) // loads map from browserify file
// Add transformation tasks to the pipeline here.
.pipe(sourcemaps.write('./')) // writes .map file
.pipe(gulp.dest('./dist'));
}
```
================================================
FILE: docs/recipes/handling-the-delete-event-on-watch.md
================================================
# Handling the Delete Event on Watch
You can listen for `'unlink'` events to fire on the watcher returned from `gulp.watch`.
This gets fired when files are removed, so you can delete the file from your destination
directory, using something like:
```js
'use strict';
var del = require('del');
var path = require('path');
var gulp = require('gulp');
var header = require('gulp-header');
var footer = require('gulp-footer');
gulp.task('scripts', function() {
return gulp.src('src/**/*.js', {base: 'src'})
.pipe(header('(function () {\r\n\t\'use strict\'\r\n'))
.pipe(footer('\r\n})();'))
.pipe(gulp.dest('build'));
});
gulp.task('watch', function () {
var watcher = gulp.watch('src/**/*.js', ['scripts']);
watcher.on('unlink', function (filepath) {
var filePathFromSrc = path.relative(path.resolve('src'), filepath);
// Concatenating the 'build' absolute path used by gulp.dest in the scripts task
var destFilePath = path.resolve('build', filePathFromSrc);
del.sync(destFilePath);
});
});
```
================================================
FILE: docs/recipes/incremental-builds-with-concatenate.md
================================================
# Incremental rebuilding, including operating on full file sets
The 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.
Use [gulp-cached](https://github.com/wearefractal/gulp-cached) and [gulp-remember](https://github.com/ahaurw01/gulp-remember) to achieve this.
```js
var gulp = require('gulp');
var header = require('gulp-header');
var footer = require('gulp-footer');
var concat = require('gulp-concat');
var jshint = require('gulp-jshint');
var cached = require('gulp-cached');
var remember = require('gulp-remember');
var scriptsGlob = 'src/**/*.js';
gulp.task('scripts', function() {
return gulp.src(scriptsGlob)
.pipe(cached('scripts')) // only pass through changed files
.pipe(jshint()) // do special things to the changed files...
.pipe(header('(function () {')) // e.g. jshinting ^^^
.pipe(footer('})();')) // and some kind of module wrapping
.pipe(remember('scripts')) // add back all files to the stream
.pipe(concat('app.js')) // do things that require all files
.pipe(gulp.dest('public/'));
});
gulp.task('watch', function () {
var watcher = gulp.watch(scriptsGlob, gulp.series('scripts')); // watch the same files in our scripts task
watcher.on('change', function (event) {
if (event.type === 'deleted') { // if a file is deleted, forget about it
delete cached.caches.scripts[event.path]; // gulp-cached remove api
remember.forget('scripts', event.path); // gulp-remember remove api
}
});
});
```
================================================
FILE: docs/recipes/maintain-directory-structure-while-globbing.md
================================================
# Maintain Directory Structure while Globbing
If 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()`.
For example, if you have a directory structure like
and want to read only a few files say
```js
[ 'index.html',
'css/**',
'js/**',
'lib/**',
'images/**',
'plugin/**'
]
```
In 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
If you want to maintain the structure, you need to pass `{base: '.'}` to `gulp.src()`. Like
```js
gulp.task('task', function () {
return gulp.src(['index.html',
'css/**',
'js/**',
'lib/**',
'images/**',
'plugin/**'
], {base: '.'})
.pipe(operation1())
.pipe(operation2());
});
```
And the input to your `operation1()` will be a folder structure like
================================================
FILE: docs/recipes/make-stream-from-buffer.md
================================================
# Make stream from buffer (memory contents)
Sometimes 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()`.
Let'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.
Logically we would break it down like this:
* load the lib files
* concatenate the lib file contents
* load the versions files
* for each version file, concatenate the libs' contents and the version file contents
* for each version file, output the result in a file
Imagine this file structure:
```sh
├── libs
│ ├── lib1.js
│ └── lib2.js
└── versions
├── version.1.js
└── version.2.js
```
You should get:
```sh
└── output
├── version.1.complete.js # lib1.js + lib2.js + version.1.js
└── version.2.complete.js # lib1.js + lib2.js + version.2.js
```
A simple and modular way to do this would be the following:
```js
var gulp = require('gulp');
var source = require('vinyl-source-stream');
var vinylBuffer = require('vinyl-buffer');
var tap = require('gulp-tap');
var concat = require('gulp-concat');
var size = require('gulp-size');
var path = require('path');
var es = require('event-stream');
var memory = {}; // we'll keep our assets in memory
// task of loading the files' contents in memory
gulp.task('load-lib-files', function() {
// read the lib files from the disk
return gulp.src('src/libs/*.js')
// concatenate all lib files into one
.pipe(concat('libs.concat.js'))
// tap into the stream to get each file's data
.pipe(tap(function(file) {
// save the file contents in memory
memory[path.basename(file.path)] = file.contents.toString();
}));
});
gulp.task('load-versions', function() {
memory.versions = {};
// read the version files from the disk
return gulp.src('src/versions/version.*.js')
// tap into the stream to get each file's data
.pipe( tap(function(file) {
// save the file contents in the assets
memory.versions[path.basename(file.path)] = file.contents.toString();
}));
});
gulp.task('write-versions', function() {
// we store all the different version file names in an array
var availableVersions = Object.keys(memory.versions);
// we make an array to store all the stream promises
var streams = [];
availableVersions.forEach(function(v) {
// make a new stream with fake file name
var stream = source('final.' + v);
var streamEnd = stream;
// we load the data from the concatenated libs
var fileContents = memory['libs.concat.js'] +
// we add the version's data
'\n' + memory.versions[v];
// write the file contents to the stream
stream.write(fileContents);
process.nextTick(function() {
// in the next process cycle, end the stream
stream.end();
});
streamEnd = streamEnd
// transform the raw data into the stream, into a vinyl object/file
.pipe(vinylBuffer())
//.pipe(tap(function(file) { /* do something with the file contents here */ }))
.pipe(gulp.dest('output'));
// add the end of the stream, otherwise the task would finish before all the processing
// is done
streams.push(streamEnd);
});
return es.merge.apply(this, streams);
});
//============================================ our main task
gulp.task('default', gulp.series(
// load the files in parallel
gulp.parallel('load-lib-files', 'load-versions'),
// ready to write once all resources are in memory
'write-versions'
)
);
//============================================ our watcher task
// only watch after having run 'default' once so that all resources
// are already in memory
gulp.task('watch', gulp.series(
'default',
function() {
gulp.watch('./src/libs/*.js', gulp.series(
'load-lib-files',
'write-versions'
));
gulp.watch('./src/versions/*.js', gulp.series(
'load-lib-files',
'write-versions'
));
}
));
```
================================================
FILE: docs/recipes/minified-and-non-minified.md
================================================
# Output both a minified and non-minified version
Outputting 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):
```js
'use strict';
var gulp = require('gulp');
var rename = require('gulp-rename');
var uglify = require('gulp-uglify');
var DEST = 'build/';
gulp.task('default', function() {
return gulp.src('foo.js')
// This will output the non-minified version
.pipe(gulp.dest(DEST))
// This will minify and rename to foo.min.js
.pipe(uglify())
.pipe(rename({ extname: '.min.js' }))
.pipe(gulp.dest(DEST));
});
```
================================================
FILE: docs/recipes/minimal-browsersync-setup-with-gulp4.md
================================================
# Minimal BrowserSync setup with Gulp 4
[BrowserSync](https://www.browsersync.io/) is a great tool to streamline
the development process with the ability to reflect code changes instantaneously
in the browser through live-reloading. Setting up a live-reloading
BrowserSync server with Gulp 4 is very clean and easy.
## Step 1: Install the dependencies
```
npm install --save-dev browser-sync
```
## Step 2: Setup the project structure
```
src/
scripts/
|__ index.js
dist/
scripts/
index.html
gulpfile.babel.js
```
The goal here is to be able to:
- Build the source script file in `src/scripts/`, e.g. compiling with babel, minifying, etc.
- Put the compiled version in `dist/scripts` for use in `index.html`
- Watch for changes in the source file and rebuild the `dist` package
- With each rebuild of the `dist` package, reload the browser to immediately reflect the changes
## Step 3: Write the gulpfile
The gulpfile could be broken in 3 parts.
### 1. Write the task to prepare the dist package as usual
Refer to the main [README](https://github.com/gulpjs/gulp/blob/master/docs/README.md)
for more information.
```javascript
import babel from 'gulp-babel';
import concat from 'gulp-concat';
import del from 'del';
import gulp from 'gulp';
import uglify from 'gulp-uglify';
const paths = {
scripts: {
src: 'src/scripts/*.js',
dest: 'dist/scripts/'
}
};
const clean = () => del(['dist']);
function scripts() {
return gulp.src(paths.scripts.src, { sourcemaps: true })
.pipe(babel())
.pipe(uglify())
.pipe(concat('index.min.js'))
.pipe(gulp.dest(paths.scripts.dest));
}
```
### 2. Setup the BrowserSync server
And write the tasks to serve and reload the server accordingly.
```javascript
import browserSync from 'browser-sync';
const server = browserSync.create();
function reload(done) {
server.reload();
done();
}
function serve(done) {
server.init({
server: {
baseDir: './'
}
});
done();
}
```
### 3. Watch for source change, rebuild the scripts and reload the server
This is trivially accomplished with `gulp.series`
```javascript
const watch = () => gulp.watch(paths.scripts.src, gulp.series(scripts, reload));
```
## Step 4: Bring it all together
The last step is to expose the default task
```javascript
const dev = gulp.series(clean, scripts, serve, watch);
export default dev;
```
And profit
```bash
$ gulp
```
Now if you go to [http://localhost:3000](http://localhost:3000), which is the default address of the
BrowserSync server, you will see that the end result in the browser is updated everytime you change
the content of the source file. Here is the whole gulpfile:
```javascript
import babel from 'gulp-babel';
import concat from 'gulp-concat';
import del from 'del';
import gulp from 'gulp';
import uglify from 'gulp-uglify';
import browserSync from 'browser-sync';
const server = browserSync.create();
const paths = {
scripts: {
src: 'src/scripts/*.js',
dest: 'dist/scripts/'
}
};
const clean = () => del(['dist']);
function scripts() {
return gulp.src(paths.scripts.src, { sourcemaps: true })
.pipe(babel())
.pipe(uglify())
.pipe(concat('index.min.js'))
.pipe(gulp.dest(paths.scripts.dest));
}
function reload(done) {
server.reload();
done();
}
function serve(done) {
server.init({
server: {
baseDir: './'
}
});
done();
}
const watch = () => gulp.watch(paths.scripts.src, gulp.series(scripts, reload));
const dev = gulp.series(clean, scripts, serve, watch);
export default dev;
```
================================================
FILE: docs/recipes/mocha-test-runner-with-gulp.md
================================================
# Mocha test-runner with gulp
### Passing shared module in all tests
```js
// npm install gulp gulp-mocha
var gulp = require('gulp');
var mocha = require('gulp-mocha');
gulp.task('default', function() {
return gulp.src(['test/test-*.js'], { read: false })
.pipe(mocha({
reporter: 'spec',
globals: {
should: require('should')
}
}));
});
```
### Running mocha tests when files change
```js
// npm install gulp gulp-mocha gulplog
var gulp = require('gulp');
var mocha = require('gulp-mocha');
var log = require('gulplog');
gulp.task('mocha', function() {
return gulp.src(['test/*.js'], { read: false })
.pipe(mocha({ reporter: 'list' }))
.on('error', log.error);
});
gulp.task('watch-mocha', function() {
gulp.watch(['lib/**', 'test/**'], gulp.series('mocha'));
});
```
================================================
FILE: docs/recipes/pass-arguments-from-cli.md
================================================
# Pass arguments from the command line
```js
// npm install --save-dev gulp gulp-if gulp-uglify minimist
var gulp = require('gulp');
var gulpif = require('gulp-if');
var uglify = require('gulp-uglify');
var minimist = require('minimist');
var knownOptions = {
string: 'env',
default: { env: process.env.NODE_ENV || 'production' }
};
var options = minimist(process.argv.slice(2), knownOptions);
gulp.task('scripts', function() {
return gulp.src('**/*.js')
.pipe(gulpif(options.env === 'production', uglify())) // only minify in production
.pipe(gulp.dest('dist'));
});
```
Then run gulp with:
```sh
$ gulp scripts --env development
```
================================================
FILE: docs/recipes/rollup-with-rollup-stream.md
================================================
# Rollup with rollup-stream
Like 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.
## Basic usage
```js
// npm install --save-dev gulp @rollup/stream@1 vinyl-source-stream
var gulp = require('gulp');
var rollup = require('rollup-stream');
var source = require('vinyl-source-stream');
gulp.task('rollup', function() {
return rollup({
input: './src/main.js'
})
// give the file the name you want to output with
.pipe(source('app.js'))
// and output to ./dist/app.js as normal.
.pipe(gulp.dest('./dist'));
});
```
## Usage with sourcemaps
```js
// npm install --save-dev gulp @rollup/stream@1 gulp-sourcemaps vinyl-source-stream vinyl-buffer
// optional: npm install --save-dev gulp-rename
var gulp = require('gulp');
var rollup = require('rollup-stream');
var sourcemaps = require('gulp-sourcemaps');
//var rename = require('gulp-rename');
var source = require('vinyl-source-stream');
var buffer = require('vinyl-buffer');
gulp.task('rollup', function() {
return rollup({
input: './src/main.js',
sourcemap: true,
format: 'umd'
})
// point to the entry file.
.pipe(source('main.js', './src'))
// buffer the output. most gulp plugins, including gulp-sourcemaps, don't support streams.
.pipe(buffer())
// tell gulp-sourcemaps to load the inline sourcemap produced by rollup-stream.
.pipe(sourcemaps.init({loadMaps: true}))
// transform the code further here.
// if you want to output with a different name from the input file, use gulp-rename here.
//.pipe(rename('index.js'))
// write the sourcemap alongside the output file.
.pipe(sourcemaps.write('.'))
// and output to ./dist/main.js as normal.
.pipe(gulp.dest('./dist'));
});
```
================================================
FILE: docs/recipes/run-grunt-tasks-from-gulp.md
================================================
# Run Grunt Tasks from Gulp
It 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.
**This approach requires Grunt >=1.0.0**
very simple example `gulpfile.js`:
```js
// npm install gulp grunt grunt-contrib-copy --save-dev
var gulp = require('gulp');
var grunt = require('grunt');
grunt.initConfig({
copy: {
main: {
src: 'src/*',
dest: 'dest/'
}
}
});
grunt.loadNpmTasks('grunt-contrib-copy');
gulp.task('copy', function (done) {
grunt.tasks(
['copy:main'], //you can add more grunt tasks in this array
{gruntfile: false}, //don't look for a Gruntfile - there is none. :-)
function () {done();}
);
});
```
Now start the task with:
`gulp copy`
With 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.**
### A few words on alternatives
There'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:
* It is at the moment not possible to pass options / cli args etc. to the grunt tasks via `gulp-grunt`
* All grunt tasks have to be defined in a separate Gruntfile
* You need to have the Grunt CLI installed
* The output of some grunt tasks gets malformatted (.i.e. color coding).
================================================
FILE: docs/recipes/running-task-steps-per-folder.md
================================================
# Generating a file per folder
If you have a set of folders, and wish to perform a set of tasks on each, for instance...
```
/scripts
/scripts/jquery/*.js
/scripts/angularjs/*.js
```
...and want to end up with...
```
/scripts
/scripts/jquery.min.js
/scripts/angularjs.min.js
```
...you'll need to do something like the following...
``` javascript
var fs = require('fs');
var path = require('path');
var merge = require('merge-stream');
var gulp = require('gulp');
var concat = require('gulp-concat');
var rename = require('gulp-rename');
var uglify = require('gulp-uglify');
var scriptsPath = 'src/scripts';
function getFolders(dir) {
return fs.readdirSync(dir)
.filter(function(file) {
return fs.statSync(path.join(dir, file)).isDirectory();
});
}
gulp.task('scripts', function(done) {
var folders = getFolders(scriptsPath);
if (folders.length === 0) return done(); // nothing to do!
var tasks = folders.map(function(folder) {
return gulp.src(path.join(scriptsPath, folder, '/**/*.js'))
// concat into foldername.js
.pipe(concat(folder + '.js'))
// write to output
.pipe(gulp.dest(scriptsPath))
// minify
.pipe(uglify())
// rename to folder.min.js
.pipe(rename(folder + '.min.js'))
// write to output again
.pipe(gulp.dest(scriptsPath));
});
// process all remaining files in scriptsPath root into main.js and main.min.js files
var root = gulp.src(path.join(scriptsPath, '/*.js'))
.pipe(concat('main.js'))
.pipe(gulp.dest(scriptsPath))
.pipe(uglify())
.pipe(rename('main.min.js'))
.pipe(gulp.dest(scriptsPath));
return merge(tasks, root);
});
```
A few notes:
- `folders.map` - executes the function once per folder, and returns the async stream
- `merge` - combines the streams and ends only when all streams emitted end
================================================
FILE: docs/recipes/server-with-livereload-and-css-injection.md
================================================
# Server with live-reloading and CSS injection
With [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.
First install the modules:
```sh
$ npm install --save-dev gulp browser-sync
```
Then, considering the following file structure...
```
gulpfile.js
app/
styles/
main.css
scripts/
main.js
index.html
```
... 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`:
```js
var gulp = require('gulp');
var browserSync = require('browser-sync');
var reload = browserSync.reload;
// watch files for changes and reload
gulp.task('serve', function() {
browserSync({
server: {
baseDir: 'app'
}
});
gulp.watch(['*.html', 'styles/**/*.css', 'scripts/**/*.js'], {cwd: 'app'}, reload);
});
```
and including the CSS in `index.html`:
```html
<html>
<head>
...
<link rel="stylesheet" href="styles/main.css">
...
```
to serve your files and launch a browser window pointing to the default URL (http://localhost:3000) run:
```bash
gulp serve
```
## + CSS pre-processors
A 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.
Considering this updated file structure...
```
gulpfile.js
app/
scss/
main.scss
scripts/
main.js
index.html
```
... 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`:
```js
var gulp = require('gulp');
var sass = require('gulp-ruby-sass');
var browserSync = require('browser-sync');
var reload = browserSync.reload;
gulp.task('sass', function() {
return sass('scss/styles.scss')
.pipe(gulp.dest('app/css'))
.pipe(reload({ stream:true }));
});
// watch Sass files for changes, run the Sass preprocessor with the 'sass' task and reload
gulp.task('serve', gulp.series('sass', function() {
browserSync({
server: {
baseDir: 'app'
}
});
gulp.watch('scss/*.scss', gulp.series('sass'));
}));
```
and including the pre-processed CSS in `index.html`:
```html
<html>
<head>
...
<link rel="stylesheet" href="css/main.css">
...
```
to serve your files and launch a browser window pointing to the default URL (http://localhost:3000) run:
```bash
gulp serve
```
## Extras
- Live reload, CSS injection and scroll/form syncing works seamlessly inside of [BrowserStack](https://www.browserstack.com/) virtual machines.
- Set `tunnel: true` to view your local site at a public URL (complete with all BrowserSync features).
================================================
FILE: docs/recipes/sharing-streams-with-stream-factories.md
================================================
# Sharing streams with stream factories
If 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.
We'll use [lazypipe](https://github.com/OverZealous/lazypipe) to get the job done.
This is our sample file:
```js
var gulp = require('gulp');
var uglify = require('gulp-uglify');
var coffee = require('gulp-coffee');
var jshint = require('gulp-jshint');
var stylish = require('jshint-stylish');
gulp.task('bootstrap', function() {
return gulp.src('bootstrap/js/*.js')
.pipe(jshint())
.pipe(jshint.reporter(stylish))
.pipe(uglify())
.pipe(gulp.dest('public/bootstrap'));
});
gulp.task('coffee', function() {
return gulp.src('lib/js/*.coffee')
.pipe(coffee())
.pipe(jshint())
.pipe(jshint.reporter(stylish))
.pipe(uglify())
.pipe(gulp.dest('public/js'));
});
```
and our file after using lazypipe looks like this:
```js
var gulp = require('gulp');
var uglify = require('gulp-uglify');
var coffee = require('gulp-coffee');
var jshint = require('gulp-jshint');
var stylish = require('jshint-stylish');
var lazypipe = require('lazypipe');
// give lazypipe
var jsTransform = lazypipe()
.pipe(jshint)
.pipe(jshint.reporter, stylish)
.pipe(uglify);
gulp.task('bootstrap', function() {
return gulp.src('bootstrap/js/*.js')
.pipe(jsTransform())
.pipe(gulp.dest('public/bootstrap'));
});
gulp.task('coffee', function() {
return gulp.src('lib/js/*.coffee')
.pipe(coffee())
.pipe(jsTransform())
.pipe(gulp.dest('public/js'));
});
```
You 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.
================================================
FILE: docs/recipes/templating-with-swig-and-yaml-front-matter.md
================================================
# Templating with Swig and YAML front-matter
Templating can be setup using `gulp-swig` and `gulp-front-matter`:
##### `page.html`
```html
---
title: Things to do
todos:
- First todo
- Another todo item
- A third todo item
---
<html>
<head>
<title>{{ title }}</title>
</head>
<body>
<h1>{{ title }}</h1>
<ul>{% for todo in todos %}
<li>{{ todo }}</li>
{% endfor %}</ul>
</body>
</html>
```
##### `gulpfile.js`
```js
var gulp = require('gulp');
var swig = require('gulp-swig');
var frontMatter = require('gulp-front-matter');
gulp.task('compile-page', function() {
gulp.src('page.html')
.pipe(frontMatter({ property: 'data' }))
.pipe(swig())
.pipe(gulp.dest('build'));
});
gulp.task('default', ['compile-page']);
```
================================================
FILE: docs/recipes/using-multiple-sources-in-one-task.md
================================================
# Using multiple sources in one task
```js
// npm install --save-dev gulp merge-stream
var gulp = require('gulp');
var merge = require('merge-stream');
gulp.task('test', function() {
var bootstrap = gulp.src('bootstrap/js/*.js')
.pipe(gulp.dest('public/bootstrap'));
var jquery = gulp.src('jquery.cookie/jquery.cookie.js')
.pipe(gulp.dest('public/jquery'));
return merge(bootstrap, jquery);
});
```
`gulp.src` will emit files in the order they were added:
```js
// npm install gulp gulp-concat
var gulp = require('gulp');
var concat = require('gulp-concat');
gulp.task('default', function() {
return gulp.src(['foo/*', 'bar/*'])
.pipe(concat('result.txt'))
.pipe(gulp.dest('build'));
});
================================================
FILE: docs/support/for-enterprise.md
================================================
<!-- front-matter
id: for-enterprise
title: For enterprise
hide_title: true
sidebar_label: For Enterprise
-->
# Gulp for enterprise
Available as part of the Tidelift Subscription.
Tidelift is working with the maintainers of Gulp and thousands of other
open 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.
<a className="tidelift-button" href="https://tidelift.com/subscription/pkg/npm-gulp?utm_source=npm-gulp&utm_medium=referral&utm_campaign=enterprise">Learn more</a>
<a className="tidelift-button" href="https://tidelift.com/subscription/request-a-demo?utm_source=npm-gulp&utm_medium=referral&utm_campaign=enterprise">Request a demo</a>
## Enterprise-ready open source software—managed for you
The 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.
Your subscription includes:
* **Security updates**
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.
* **Licensing verification and indemnification**
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.
* **Maintenance and code improvement**
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.
* **Package selection and version guidance**
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.
* **Roadmap input**
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.
* **Tooling and cloud integration**
Tidelift works with GitHub, GitLab, BitBucket, and more. We support every cloud platform (and other deployment targets, too).
The 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.
<a className="tidelift-button" href="https://tidelift.com/subscription/pkg/npm-gulp?utm_source=npm-gulp&utm_medium=referral&utm_campaign=enterprise">Learn more</a>
<a className="tidelift-button" href="https://tidelift.com/subscription/request-a-demo?utm_source=npm-gulp&utm_medium=referral&utm_campaign=enterprise">Request a demo</a>
================================================
FILE: docs/why-use-pump/README.md
================================================
# Why Use Pump?
When using `pipe` from the Node.js streams, errors are not propagated forward
through the piped streams, and source streams aren’t closed if a destination
stream closed. The
gitextract_5sxvhu_w/
├── .editorconfig
├── .eslintrc
├── .gitattributes
├── .github/
│ ├── SECURITY.md
│ └── workflows/
│ ├── dev.yml
│ └── release.yml
├── .gitignore
├── .npmrc
├── .prettierignore
├── .tidelift.yml
├── CHANGELOG.md
├── CONTRIBUTING.md
├── EXPENSE_POLICY.md
├── LICENSE
├── README.md
├── bin/
│ └── gulp.js
├── docs/
│ ├── CLI.md
│ ├── FAQ.md
│ ├── README.md
│ ├── advanced/
│ │ └── creating-custom-registries.md
│ ├── api/
│ │ ├── README.md
│ │ ├── concepts.md
│ │ ├── dest.md
│ │ ├── last-run.md
│ │ ├── parallel.md
│ │ ├── registry.md
│ │ ├── series.md
│ │ ├── src.md
│ │ ├── symlink.md
│ │ ├── task.md
│ │ ├── tree.md
│ │ ├── vinyl-iscustomprop.md
│ │ ├── vinyl-isvinyl.md
│ │ ├── vinyl.md
│ │ └── watch.md
│ ├── documentation-missing.md
│ ├── getting-started/
│ │ ├── 1-quick-start.md
│ │ ├── 2-javascript-and-gulpfiles.md
│ │ ├── 3-creating-tasks.md
│ │ ├── 4-async-completion.md
│ │ ├── 5-working-with-files.md
│ │ ├── 6-explaining-globs.md
│ │ ├── 7-using-plugins.md
│ │ ├── 8-watching-files.md
│ │ └── README.md
│ ├── getting-started.md
│ ├── recipes/
│ │ ├── README.md
│ │ ├── automate-releases.md
│ │ ├── browserify-multiple-destination.md
│ │ ├── browserify-transforms.md
│ │ ├── browserify-uglify-sourcemap.md
│ │ ├── browserify-with-globs.md
│ │ ├── combining-streams-to-handle-errors.md
│ │ ├── cron-task.md
│ │ ├── delete-files-folder.md
│ │ ├── fast-browserify-builds-with-watchify.md
│ │ ├── handling-the-delete-event-on-watch.md
│ │ ├── incremental-builds-with-concatenate.md
│ │ ├── maintain-directory-structure-while-globbing.md
│ │ ├── make-stream-from-buffer.md
│ │ ├── minified-and-non-minified.md
│ │ ├── minimal-browsersync-setup-with-gulp4.md
│ │ ├── mocha-test-runner-with-gulp.md
│ │ ├── pass-arguments-from-cli.md
│ │ ├── rollup-with-rollup-stream.md
│ │ ├── run-grunt-tasks-from-gulp.md
│ │ ├── running-task-steps-per-folder.md
│ │ ├── server-with-livereload-and-css-injection.md
│ │ ├── sharing-streams-with-stream-factories.md
│ │ ├── templating-with-swig-and-yaml-front-matter.md
│ │ └── using-multiple-sources-in-one-task.md
│ ├── support/
│ │ └── for-enterprise.md
│ ├── why-use-pump/
│ │ └── README.md
│ └── writing-a-plugin/
│ ├── README.md
│ ├── dealing-with-streams.md
│ ├── guidelines.md
│ ├── recommended-modules.md
│ ├── testing.md
│ └── using-buffers.md
├── index.js
├── index.mjs
├── package.json
└── test/
├── .gitkeep
├── dest.js
├── fixtures/
│ ├── copy/
│ │ └── example.txt
│ ├── gulpfiles/
│ │ ├── cjs/
│ │ │ └── gulpfile.cjs
│ │ └── mjs/
│ │ └── gulpfile.mjs
│ ├── stuff/
│ │ ├── run.dmc
│ │ └── test.dmc
│ ├── test/
│ │ └── run.jade
│ └── test.coffee
├── index.test.js
├── src.js
└── watch.js
SYMBOL INDEX (5 symbols across 3 files)
FILE: index.js
function Gulp (line 8) | function Gulp() {
FILE: test/dest.js
function testWriteDir (line 117) | function testWriteDir(srcOptions, done) {
FILE: test/watch.js
function createTempFile (line 18) | function createTempFile(path) {
function updateTempFile (line 22) | function updateTempFile(path) {
function removeTempFile (line 28) | function removeTempFile(path) {
Condensed preview — 94 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (251K chars).
[
{
"path": ".editorconfig",
"chars": 215,
"preview": "# https://editorconfig.org\nroot = true\n\n[*]\nindent_style = space\nindent_size = 2\ncharset = utf-8\ntrim_trailing_whitespac"
},
{
"path": ".eslintrc",
"chars": 24,
"preview": "{\n \"extends\": \"gulp\"\n}\n"
},
{
"path": ".gitattributes",
"chars": 110,
"preview": "* 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",
"chars": 365,
"preview": "# Security Policy\n\n## Supported Versions\n\n| Version | Supported |\n| ------- | ------------------ |\n| 4.x.x | "
},
{
"path": ".github/workflows/dev.yml",
"chars": 1617,
"preview": "name: dev\non:\n pull_request:\n push:\n branches:\n - master\n - main\nenv:\n CI: true\n\njobs:\n prettier:\n n"
},
{
"path": ".github/workflows/release.yml",
"chars": 324,
"preview": "name: release\non:\n push:\n branches:\n - master\n - main\n\njobs:\n release-please:\n runs-on: ubuntu-latest\n"
},
{
"path": ".gitignore",
"chars": 655,
"preview": "# Logs\nlogs\n*.log\n\n# Runtime data\npids\n*.pid\n*.seed\n\n# Directory for instrumented libs generated by jscoverage/JSCover\nl"
},
{
"path": ".npmrc",
"chars": 19,
"preview": "package-lock=false\n"
},
{
"path": ".prettierignore",
"chars": 36,
"preview": "coverage/\n.nyc_output/\nCHANGELOG.md\n"
},
{
"path": ".tidelift.yml",
"chars": 462,
"preview": "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 "
},
{
"path": "CHANGELOG.md",
"chars": 15753,
"preview": "# 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"
},
{
"path": "CONTRIBUTING.md",
"chars": 5332,
"preview": "# Request for contributions\n\nPlease contribute to this repository if any of the following is true:\n- You have expertise "
},
{
"path": "EXPENSE_POLICY.md",
"chars": 1760,
"preview": "# Expense Policy\n\n## Funding can be requested for significant changes made by Core Members.\n* Discuss the changes in the"
},
{
"path": "LICENSE",
"chars": 1149,
"preview": "The MIT License (MIT)\n\nCopyright (c) 2013-2024 Blaine Bublitz <blaine.bublitz@gmail.com> and Eric Schoffstall <yo@contra"
},
{
"path": "README.md",
"chars": 6708,
"preview": "<p align=\"center\">\n <a href=\"https://gulpjs.com\">\n <img height=\"257\" width=\"114\" src=\"https://raw.githubusercontent."
},
{
"path": "bin/gulp.js",
"chars": 44,
"preview": "#!/usr/bin/env node\n\nrequire('gulp-cli')();\n"
},
{
"path": "docs/CLI.md",
"chars": 3581,
"preview": "## 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- `"
},
{
"path": "docs/FAQ.md",
"chars": 2316,
"preview": "# 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"
},
{
"path": "docs/README.md",
"chars": 3370,
"preview": "# gulp documentation\n\n* [Getting Started](getting-started/) - Get started with gulp\n* [API documentation](api/) - The pr"
},
{
"path": "docs/advanced/creating-custom-registries.md",
"chars": 5776,
"preview": "<!-- front-matter\nid: creating-custom-registries\ntitle: Creating Custom Registries\nhide_title: true\nsidebar_label: Creat"
},
{
"path": "docs/api/README.md",
"chars": 391,
"preview": "## Table of Contents\n\n* [API Concepts](concepts.md)\n* [src()](src.md)\n* [dest()](dest.md)\n* [symlink()](symlink.md)\n* [l"
},
{
"path": "docs/api/concepts.md",
"chars": 5190,
"preview": "<!-- front-matter\nid: concepts\ntitle: API Concepts\nhide_title: true\nsidebar_label: Concepts\n-->\n\n# Concepts\n\nThe followi"
},
{
"path": "docs/api/dest.md",
"chars": 6605,
"preview": "<!-- front-matter\nid: dest\ntitle: dest()\nhide_title: true\nsidebar_label: dest()\n-->\n\n# dest()\n\nCreates a stream for writ"
},
{
"path": "docs/api/last-run.md",
"chars": 2632,
"preview": "<!-- front-matter\nid: lastrun\ntitle: lastRun()\nhide_title: true\nsidebar_label: lastRun()\n-->\n\n# lastRun()\n\nRetrieves the"
},
{
"path": "docs/api/parallel.md",
"chars": 3281,
"preview": "<!-- front-matter\nid: parallel\ntitle: parallel()\nhide_title: true\nsidebar_label: parallel()\n-->\n\n# parallel()\n\nCombines "
},
{
"path": "docs/api/registry.md",
"chars": 2441,
"preview": "<!-- front-matter\nid: registry\ntitle: registry()\nhide_title: true\nsidebar_label: registry()\n-->\n\n# registry()\n\nAllows cu"
},
{
"path": "docs/api/series.md",
"chars": 3268,
"preview": "<!-- front-matter\nid: series\ntitle: series()\nhide_title: true\nsidebar_label: series()\n-->\n\n# series()\n\nCombines task fun"
},
{
"path": "docs/api/src.md",
"chars": 6903,
"preview": "<!-- front-matter\nid: src\ntitle: src()\nhide_title: true\nsidebar_label: src()\n-->\n\n# src()\n\nCreates a stream for reading "
},
{
"path": "docs/api/symlink.md",
"chars": 4621,
"preview": "<!-- front-matter\nid: symlink\ntitle: symlink()\nhide_title: true\nsidebar_label: symlink()\n-->\n\n# symlink()\n\nCreates a str"
},
{
"path": "docs/api/task.md",
"chars": 3489,
"preview": "<!-- front-matter\nid: task\ntitle: task()\nhide_title: true\nsidebar_label: task()\n-->\n\n# task()\n\n**Reminder**: This API is"
},
{
"path": "docs/api/tree.md",
"chars": 3540,
"preview": "<!-- front-matter\nid: tree\ntitle: tree()\nhide_title: true\nsidebar_label: tree()\n-->\n\n# tree()\n\nFetches the current task "
},
{
"path": "docs/api/vinyl-iscustomprop.md",
"chars": 1692,
"preview": "<!-- front-matter\nid: vinyl-iscustomprop\ntitle: Vinyl.isCustomProp()\nhide_title: true\nsidebar_label: Vinyl.isCustomProp("
},
{
"path": "docs/api/vinyl-isvinyl.md",
"chars": 771,
"preview": "<!-- front-matter\nid: vinyl-isvinyl\ntitle: Vinyl.isVinyl()\nhide_title: true\nsidebar_label: Vinyl.isVinyl()\n-->\n\n# Vinyl."
},
{
"path": "docs/api/vinyl.md",
"chars": 8430,
"preview": "<!-- front-matter\nid: vinyl\ntitle: Vinyl\nhide_title: true\nsidebar_label: Vinyl\n-->\n\n# Vinyl\n\nA virtual file format. When"
},
{
"path": "docs/api/watch.md",
"chars": 8406,
"preview": "<!-- front-matter\nid: watch\ntitle: watch()\nhide_title: true\nsidebar_label: watch()\n-->\n\n# watch()\n\nAllows watching globs"
},
{
"path": "docs/documentation-missing.md",
"chars": 502,
"preview": "<!-- front-matter\nid: documentation-missing\ntitle: Documentation Missing\nhide_title: true\n-->\n\n# Excuse our dust!\n\nWe're"
},
{
"path": "docs/getting-started/1-quick-start.md",
"chars": 2273,
"preview": "<!-- front-matter\nid: quick-start\ntitle: Quick Start\nhide_title: true\nsidebar_label: Quick Start\n-->\n\n# Quick Start\n\nIf "
},
{
"path": "docs/getting-started/2-javascript-and-gulpfiles.md",
"chars": 2630,
"preview": "<!-- front-matter\nid: javascript-and-gulpfiles\ntitle: JavaScript and Gulpfiles\nhide_title: true\nsidebar_label: JavaScrip"
},
{
"path": "docs/getting-started/3-creating-tasks.md",
"chars": 4977,
"preview": "<!-- front-matter\nid: creating-tasks\ntitle: Creating Tasks\nhide_title: true\nsidebar_label: Creating Tasks\n-->\n\n# Creatin"
},
{
"path": "docs/getting-started/4-async-completion.md",
"chars": 4436,
"preview": "<!-- front-matter\nid: async-completion\ntitle: Async Completion\nhide_title: true\nsidebar_label: Async Completion\n-->\n\n# A"
},
{
"path": "docs/getting-started/5-working-with-files.md",
"chars": 4197,
"preview": "<!-- front-matter\nid: working-with-files\ntitle: Working with Files\nhide_title: true\nsidebar_label: Working with Files\n--"
},
{
"path": "docs/getting-started/6-explaining-globs.md",
"chars": 4348,
"preview": "<!-- front-matter\nid: explaining-globs\ntitle: Explaining Globs\nhide_title: true\nsidebar_label: Explaining Globs\n-->\n\n# E"
},
{
"path": "docs/getting-started/7-using-plugins.md",
"chars": 3498,
"preview": "<!-- front-matter\nid: using-plugins\ntitle: Using Plugins\nhide_title: true\nsidebar_label: Using Plugins\n-->\n\n# Using Plug"
},
{
"path": "docs/getting-started/8-watching-files.md",
"chars": 4549,
"preview": "<!-- front-matter\nid: watching-files\ntitle: Watching Files\nhide_title: true\nsidebar_label: Watching Files\n-->\n\n# Watchin"
},
{
"path": "docs/getting-started/README.md",
"chars": 375,
"preview": "# Getting Started\n\n1. [Quick Start](1-quick-start.md)\n2. [JavaScript and Gulpfiles](2-javascript-and-gulpfiles.md)\n3. [C"
},
{
"path": "docs/getting-started.md",
"chars": 227,
"preview": "## This documentation has moved!\n\nYou can find the new documentation in our [Quick Start](getting-started/1-quick-start."
},
{
"path": "docs/recipes/README.md",
"chars": 1457,
"preview": "# Recipes\n\n* [Automate release workflow](automate-releases.md)\n* [Combining streams to handle errors](combining-streams-"
},
{
"path": "docs/recipes/automate-releases.md",
"chars": 3116,
"preview": "<!-- front-matter\nid: automate-releases\ntitle: Automate Releases\nhide_title: true\nsidebar_label: Automate Releases \n-->\n"
},
{
"path": "docs/recipes/browserify-multiple-destination.md",
"chars": 1275,
"preview": "# Browserify + Globs (multiple destination)\n\nThis example shows how to set up a task of bundling multiple entry points i"
},
{
"path": "docs/recipes/browserify-transforms.md",
"chars": 1288,
"preview": "# Browserify + Transforms\n\n[Browserify](https://github.com/browserify/browserify) has become an important and indispensa"
},
{
"path": "docs/recipes/browserify-uglify-sourcemap.md",
"chars": 1364,
"preview": "# Browserify + Uglify2 with sourcemaps\n\n[Browserify](https://github.com/browserify/browserify) has become an important a"
},
{
"path": "docs/recipes/browserify-with-globs.md",
"chars": 2321,
"preview": "# Browserify + Globs\n\n[Browserify + Uglify2](https://github.com/gulpjs/gulp/blob/master/docs/recipes/browserify-uglify-s"
},
{
"path": "docs/recipes/combining-streams-to-handle-errors.md",
"chars": 932,
"preview": "# Combining streams to handle errors\n\nBy default, emitting an error on a stream will cause it to be thrown unless it alr"
},
{
"path": "docs/recipes/cron-task.md",
"chars": 916,
"preview": "# Run gulp task via cron job\n\nWhile logged in via a user that has privileges to run `gulp`, run the following:\n\n cron"
},
{
"path": "docs/recipes/delete-files-folder.md",
"chars": 2145,
"preview": "# Delete files and folders\n\nYou might want to delete some files before running your build. Since deleting files doesn't "
},
{
"path": "docs/recipes/fast-browserify-builds-with-watchify.md",
"chars": 2159,
"preview": "# Fast browserify builds with watchify\n\nAs a [browserify](https://github.com/browserify/browserify) project begins to ex"
},
{
"path": "docs/recipes/handling-the-delete-event-on-watch.md",
"chars": 1033,
"preview": "# Handling the Delete Event on Watch\n\nYou can listen for `'unlink'` events to fire on the watcher returned from `gulp.wa"
},
{
"path": "docs/recipes/incremental-builds-with-concatenate.md",
"chars": 1828,
"preview": "# Incremental rebuilding, including operating on full file sets\n\nThe trouble with incremental rebuilds is you often want"
},
{
"path": "docs/recipes/maintain-directory-structure-while-globbing.md",
"chars": 1410,
"preview": "# Maintain Directory Structure while Globbing\n\nIf you are planning to read a few files/folders from a directory and main"
},
{
"path": "docs/recipes/make-stream-from-buffer.md",
"chars": 4166,
"preview": "# Make stream from buffer (memory contents)\n\nSometimes you may need to start a stream with files that their contents are"
},
{
"path": "docs/recipes/minified-and-non-minified.md",
"chars": 686,
"preview": "# Output both a minified and non-minified version\n\nOutputting both a minified and non-minified version of your combined "
},
{
"path": "docs/recipes/minimal-browsersync-setup-with-gulp4.md",
"chars": 3552,
"preview": "# Minimal BrowserSync setup with Gulp 4\n\n[BrowserSync](https://www.browsersync.io/) is a great tool to streamline\nthe de"
},
{
"path": "docs/recipes/mocha-test-runner-with-gulp.md",
"chars": 836,
"preview": "# 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 = "
},
{
"path": "docs/recipes/pass-arguments-from-cli.md",
"chars": 657,
"preview": "# Pass arguments from the command line\n\n```js\n// npm install --save-dev gulp gulp-if gulp-uglify minimist\n\nvar gulp = re"
},
{
"path": "docs/recipes/rollup-with-rollup-stream.md",
"chars": 2201,
"preview": "# Rollup with rollup-stream\n\nLike Browserify, [Rollup](https://rollupjs.org/) is a bundler and thus only fits naturally "
},
{
"path": "docs/recipes/run-grunt-tasks-from-gulp.md",
"chars": 1750,
"preview": "# Run Grunt Tasks from Gulp\n\nIt is possible to run Grunt tasks / Grunt plugins from within Gulp. This can be useful duri"
},
{
"path": "docs/recipes/running-task-steps-per-folder.md",
"chars": 1907,
"preview": "# 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.."
},
{
"path": "docs/recipes/server-with-livereload-and-css-injection.md",
"chars": 2847,
"preview": "# Server with live-reloading and CSS injection\n\nWith [BrowserSync](https://browsersync.io) and gulp, you can easily crea"
},
{
"path": "docs/recipes/sharing-streams-with-stream-factories.md",
"chars": 2031,
"preview": "# Sharing streams with stream factories\n\nIf you use the same plugins in multiple tasks you might find yourself getting t"
},
{
"path": "docs/recipes/templating-with-swig-and-yaml-front-matter.md",
"chars": 811,
"preview": "# Templating with Swig and YAML front-matter\nTemplating can be setup using `gulp-swig` and `gulp-front-matter`:\n\n##### `"
},
{
"path": "docs/recipes/using-multiple-sources-in-one-task.md",
"chars": 721,
"preview": "# Using multiple sources in one task\n\n```js\n// npm install --save-dev gulp merge-stream\n\nvar gulp = require('gulp');\nvar"
},
{
"path": "docs/support/for-enterprise.md",
"chars": 3141,
"preview": "<!-- front-matter\nid: for-enterprise\ntitle: For enterprise\nhide_title: true\nsidebar_label: For Enterprise\n-->\n\n# Gulp fo"
},
{
"path": "docs/why-use-pump/README.md",
"chars": 3876,
"preview": "# Why Use Pump?\n\nWhen using `pipe` from the Node.js streams, errors are not propagated forward\nthrough the piped streams"
},
{
"path": "docs/writing-a-plugin/README.md",
"chars": 7897,
"preview": "# Writing a plugin\n\nIf you plan to create your own Gulp plugin, you will save time by reading the full documentation.\n\n*"
},
{
"path": "docs/writing-a-plugin/dealing-with-streams.md",
"chars": 2277,
"preview": "# Dealing with streams\n\n> It is highly recommended to write plugins supporting streams. Here is some information on crea"
},
{
"path": "docs/writing-a-plugin/guidelines.md",
"chars": 5954,
"preview": "# Guidelines\n\n> While these guidelines are totally optional, we **HIGHLY** recommend that everyone follows them. Nobody "
},
{
"path": "docs/writing-a-plugin/recommended-modules.md",
"chars": 574,
"preview": "# Recommended Modules\n\n> Sticking to this curated list of recommended modules will make sure you don't violate the plugi"
},
{
"path": "docs/writing-a-plugin/testing.md",
"chars": 2638,
"preview": "# Testing\n\n> Testing your plugin is the only way to ensure quality. It brings confidence to your users and makes your li"
},
{
"path": "docs/writing-a-plugin/using-buffers.md",
"chars": 2081,
"preview": "# Using buffers\n\n> Here is some information on creating gulp plugin that manipulates buffers.\n\n[Writing a Plugin](README"
},
{
"path": "index.js",
"chars": 1422,
"preview": "'use strict';\n\nvar util = require('util');\nvar Undertaker = require('undertaker');\nvar vfs = require('vinyl-fs');\nvar wa"
},
{
"path": "index.mjs",
"chars": 501,
"preview": "import gulp from \"./index.js\";\n\n// These are bound to the gulp instance in our CommonJS file\n// so it is okay to reassig"
},
{
"path": "package.json",
"chars": 1408,
"preview": "{\n \"name\": \"gulp\",\n \"version\": \"5.0.1\",\n \"description\": \"The streaming build system.\",\n \"homepage\": \"https://gulpjs."
},
{
"path": "test/.gitkeep",
"chars": 0,
"preview": ""
},
{
"path": "test/dest.js",
"chars": 4576,
"preview": "'use strict';\n\nvar fs = require('fs');\nvar path = require('path');\n\nvar expect = require('expect');\nvar rimraf = require"
},
{
"path": "test/fixtures/copy/example.txt",
"chars": 14,
"preview": "this is a test"
},
{
"path": "test/fixtures/gulpfiles/cjs/gulpfile.cjs",
"chars": 47,
"preview": "exports.default = function (done) {\n done()\n}\n"
},
{
"path": "test/fixtures/gulpfiles/mjs/gulpfile.mjs",
"chars": 673,
"preview": "import assert from \"assert\";\nimport EventEmitter from \"events\";\n\nimport gulp, {\n watch,\n task,\n series,\n parallel,\n "
},
{
"path": "test/fixtures/stuff/run.dmc",
"chars": 0,
"preview": ""
},
{
"path": "test/fixtures/stuff/test.dmc",
"chars": 0,
"preview": ""
},
{
"path": "test/fixtures/test/run.jade",
"chars": 13,
"preview": "test template"
},
{
"path": "test/fixtures/test.coffee",
"chars": 14,
"preview": "this is a test"
},
{
"path": "test/index.test.js",
"chars": 2557,
"preview": "'use strict';\n\nvar cp = require('child_process');\nvar path = require('path');\n\nvar expect = require('expect');\n\nvar gulp"
},
{
"path": "test/src.js",
"chars": 5018,
"preview": "'use strict';\n\nvar path = require('path');\n\nvar expect = require('expect');\n\nvar gulp = require('../');\n\ndescribe('gulp."
},
{
"path": "test/watch.js",
"chars": 6699,
"preview": "'use strict';\n\n/* eslint-disable no-use-before-define */\n\nvar fs = require('fs');\nvar path = require('path');\n\nvar expec"
}
]
About this extraction
This page contains the full source code of the gulpjs/gulp GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 94 files (232.5 KB), approximately 61.0k tokens, and a symbol index with 5 extracted functions, classes, methods, constants, and types. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.