node-gulp-4.0.2+~cs38.20.35/ 0000775 0000000 0000000 00000000000 14156670073 0015040 5 ustar 00root root 0000000 0000000 node-gulp-4.0.2+~cs38.20.35/.ci/ 0000775 0000000 0000000 00000000000 14156670073 0015511 5 ustar 00root root 0000000 0000000 node-gulp-4.0.2+~cs38.20.35/.ci/.azure-pipelines-steps.yml 0000664 0000000 0000000 00000002066 14156670073 0022566 0 ustar 00root root 0000000 0000000 steps:
- script: npm i -g npm@$(npm_version)
displayName: Use legacy npm version $(npm_version)
condition: ne(variables['npm_version'], '')
- task: NodeTool@0
inputs:
versionSpec: '$(node_version)'
displayName: Use Node $(node_version)
- script: npm install
displayName: npm install
- script: npm test
displayName: Run tests
- script: npm run coveralls
displayName: Run coveralls
env:
# Pretend to be AppVeyor for now
APPVEYOR: true
APPVEYOR_BUILD_NUMBER: $(Build.BuildNumber)
APPVEYOR_BUILD_ID: $(Agent.OS)_$(node_version)
APPVEYOR_REPO_COMMIT: $(Build.SourceVersion)
APPVEYOR_REPO_BRANCH: $(Build.SourceBranchName)
# Overwrite the AppVeyor Service Name
COVERALLS_SERVICE_NAME: Azure Pipelines
COVERALLS_REPO_TOKEN: $(COVERALLS_REPO_TOKEN_SECRET)
COVERALLS_PARALLEL: true
CI_PULL_REQUEST: $(System.PullRequest.PullRequestNumber)
- script: npm run azure-pipelines
displayName: Write tests to xml
- task: PublishTestResults@2
inputs:
testResultsFiles: '**/test.xunit'
condition: succeededOrFailed()
node-gulp-4.0.2+~cs38.20.35/.ci/.azure-pipelines.yml 0000664 0000000 0000000 00000004050 14156670073 0021425 0 ustar 00root root 0000000 0000000 trigger:
- master
- releases/*
jobs:
- job: Test_Linux
displayName: Run Tests on Linux
pool:
vmImage: "Ubuntu 16.04"
strategy:
matrix:
Node_v12:
node_version: 12
Node_v10:
node_version: 10
Node_v8:
node_version: 8
Node_v6:
node_version: 6
Node_v4:
node_version: 4
Node_v0_12:
node_version: 0.12
Node_v0_10:
node_version: 0.10
steps:
- template: .azure-pipelines-steps.yml
- job: Test_Windows
displayName: Run Tests on Windows
pool:
vmImage: vs2017-win2016
strategy:
matrix:
Node_v12:
node_version: 12
Node_v10:
node_version: 10
Node_v8:
node_version: 8
Node_v6:
node_version: 6
Node_v4:
node_version: 4
npm_version: 2
Node_v0_12:
node_version: 0.12
npm_version: 2
Node_v0_10:
node_version: 0.10
npm_version: 2
steps:
- template: .azure-pipelines-steps.yml
- job: Test_MacOS
displayName: Run Tests on MacOS
pool:
vmImage: macos-10.13
strategy:
matrix:
Node_v12:
node_version: 12
Node_v10:
node_version: 10
Node_v8:
node_version: 8
Node_v6:
node_version: 6
Node_v4:
node_version: 4
Node_v0_12:
node_version: 0.12
Node_v0_10:
node_version: 0.10
steps:
- template: .azure-pipelines-steps.yml
- job: Notify_Coveralls
displayName: Notify Coveralls that the parallel report is done
pool:
vmImage: "Ubuntu 16.04"
dependsOn:
- Test_Linux
- Test_Windows
- Test_MacOS
steps:
- script: curl -k https://coveralls.io/webhook?repo_token=$COVERALLS_REPO_TOKEN -d "payload[build_num]=$BUILD_NAME&payload[status]=done"
env:
COVERALLS_REPO_TOKEN: $(COVERALLS_REPO_TOKEN_SECRET)
BUILD_NAME: $(Build.BuildNumber)
node-gulp-4.0.2+~cs38.20.35/.editorconfig 0000664 0000000 0000000 00000000327 14156670073 0017517 0 ustar 00root root 0000000 0000000 # 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
node-gulp-4.0.2+~cs38.20.35/.eslintrc 0000664 0000000 0000000 00000000030 14156670073 0016655 0 ustar 00root root 0000000 0000000 {
"extends": "gulp"
}
node-gulp-4.0.2+~cs38.20.35/.gitattributes 0000664 0000000 0000000 00000000156 14156670073 0017735 0 ustar 00root root 0000000 0000000 * text eol=lf
# Denote all files that are truly binary and should not be modified.
*.png binary
*.jpg binary
node-gulp-4.0.2+~cs38.20.35/.github/ 0000775 0000000 0000000 00000000000 14156670073 0016400 5 ustar 00root root 0000000 0000000 node-gulp-4.0.2+~cs38.20.35/.github/ISSUE_TEMPLATE.md 0000664 0000000 0000000 00000001670 14156670073 0021111 0 ustar 00root root 0000000 0000000 This tracker is for bug reports only.
Before opening an issue, please make sure you've checked the following:
- For support requests, please use Stack Overflow (stackoverflow.com) or Gitter (see the README).
- If the bug is in a plugin, open an issue on the plugin repository, not the gulp repository.
- If you're getting a deprecated module warning, don't worry about it: we're aware of it and it's not an issue. To make it go away, update to Gulp 4.0.
- If you're asking about the status of Gulp 4, please don't! You can see the remaining issues on the gulp4 label: https://github.com/gulpjs/gulp/issues?q=is%3Aissue+is%3Aopen+label%3Agulp4
----
**What were you expecting to happen?**
**What actually happened?**
**Please post a sample of your gulpfile (preferably reduced to just the bit that's not working)**
```js
gulp.task(function () {});
```
**What version of gulp are you using?**
**What versions of npm and node are you using?**
node-gulp-4.0.2+~cs38.20.35/.github/support.yml 0000664 0000000 0000000 00000001605 14156670073 0020641 0 ustar 00root root 0000000 0000000 # Configuration for support-requests - https://github.com/dessant/support-requests
supportLabel: support
supportComment: >
Issues are reserved for bugs and features. Here are a few places to find answers to your question:
* For community support, use the `gulp` tag on [StackOverflow](https://stackoverflow.com/questions/tagged/gulp).
* Participate in community chat on [Gitter](https://gitter.im/gulpjs/gulp).
* To get paid support directly from the maintainers, sign up for [Tidelift](https://tidelift.com/subscription/pkg/npm-gulp?utm_source=npm-gulp&utm_medium=referral&utm_campaign=support). Subscribers should email support@tidelift.com, mention that it's a question for Gulp, and describe your question. Straightforward questions are answered as part of your subscription. Additional consulting hours are available for more complex help.
close: true
lock: false
setLockReason: false
node-gulp-4.0.2+~cs38.20.35/.tidelift.yml 0000664 0000000 0000000 00000000716 14156670073 0017451 0 ustar 00root root 0000000 0000000 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
node-gulp-4.0.2+~cs38.20.35/.travis.yml 0000664 0000000 0000000 00000000213 14156670073 0017145 0 ustar 00root root 0000000 0000000 sudo: false
language: node_js
node_js:
- '12'
- '10'
- '8'
- '6'
- '4'
- '0.12'
- '0.10'
after_script:
- npm run coveralls
node-gulp-4.0.2+~cs38.20.35/CHANGELOG.md 0000664 0000000 0000000 00000017234 14156670073 0016660 0 ustar 00root root 0000000 0000000 # gulp changelog
## 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
node-gulp-4.0.2+~cs38.20.35/CONTRIBUTING.md 0000664 0000000 0000000 00000012321 14156670073 0017270 0 ustar 00root root 0000000 0000000 # 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/4.0/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)
node-gulp-4.0.2+~cs38.20.35/EXPENSE_POLICY.md 0000664 0000000 0000000 00000003354 14156670073 0017555 0 ustar 00root root 0000000 0000000 # 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!
node-gulp-4.0.2+~cs38.20.35/LICENSE 0000664 0000000 0000000 00000002221 14156670073 0016042 0 ustar 00root root 0000000 0000000 The MIT License (MIT)
Copyright (c) 2013-2018 Blaine Bublitz , Eric Schoffstall and other contributors
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.
node-gulp-4.0.2+~cs38.20.35/README.md 0000664 0000000 0000000 00000021525 14156670073 0016324 0 ustar 00root root 0000000 0000000
The streaming build system
[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Azure Pipelines Build Status][azure-pipelines-image]][azure-pipelines-url] [![Build Status][travis-image]][travis-url] [![AppVeyor Build Status][appveyor-image]][appveyor-url] [![Coveralls Status][coveralls-image]][coveralls-url] [![OpenCollective Backers][backer-badge]][backer-url] [![OpenCollective Sponsors][sponsor-badge]][sponsor-url] [![Gitter chat][gitter-image]][gitter-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 2000 curated plugins for streaming file transformations
- **Simple** - By providing only a minimal API surface, gulp is easy to learn and simple to use
## What's new in 4.0?!
* The task system was rewritten from the ground-up, allowing task composition using `series()` and `parallel()` methods
* The watcher was updated, now using chokidar (no more need for gulp-watch!), with feature parity to our task system
* First-class support was added for incremental builds using `lastRun()`
* A `symlink()` method was exposed to create symlinks instead of copying files
* Built-in support for sourcemaps was added - the gulp-sourcemaps plugin is no longer necessary!
* Task registration of exported functions - using node or ES exports - is now recommended
* Custom registries were designed, allowing for shared tasks or augmented functionality
* Stream implementations were improved, allowing for better conditional and phased builds
## 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
__Most new versions of node support most features that Babel provides, except the `import`/`export` syntax. When only that syntax is desired, rename to `gulpfile.esm.js`, install the [esm][esm-module] module, and skip the Babel portion below.__
Node already supports a lot of __ES2015+__ features, but to avoid compatibility problems we suggest to install Babel and rename your `gulpfile.js` to `gulpfile.babel.js`.
```sh
npm install --save-dev @babel/register @babel/core @babel/preset-env
```
Then create a **.babelrc** file with the preset configuration.
```js
{
"presets": [ "@babel/preset-env" ]
}
```
And here's the same sample from above written in **ES2015+**.
```js
import gulp 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 del 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 = () => del([ 'assets' ]);
/*
* You can also declare named functions and export them as tasks
*/
export 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));
}
export 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));
}
/*
* You could even use `export as` to rename exported tasks
*/
function watchFiles() {
gulp.watch(paths.scripts.src, scripts);
gulp.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({optimizationLevel: 5}))
.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)!
## Backers
Support us with a monthly donation and help us continue our activities.
[![Backers][backers-image]][support-url]
## Sponsors
Become a sponsor to get your logo on our README on Github.
[![Sponsors][sponsors-image]][support-url]
[downloads-image]: https://img.shields.io/npm/dm/gulp.svg
[npm-url]: https://www.npmjs.com/package/gulp
[npm-image]: https://img.shields.io/npm/v/gulp.svg
[azure-pipelines-url]: https://dev.azure.com/gulpjs/gulp/_build/latest?definitionId=1&branchName=master
[azure-pipelines-image]: https://dev.azure.com/gulpjs/gulp/_apis/build/status/gulp?branchName=master
[travis-url]: https://travis-ci.org/gulpjs/gulp
[travis-image]: https://img.shields.io/travis/gulpjs/gulp.svg?label=travis-ci
[appveyor-url]: https://ci.appveyor.com/project/gulpjs/gulp
[appveyor-image]: https://img.shields.io/appveyor/ci/gulpjs/gulp.svg?label=appveyor
[coveralls-url]: https://coveralls.io/r/gulpjs/gulp
[coveralls-image]: https://img.shields.io/coveralls/gulpjs/gulp/master.svg
[gitter-url]: https://gitter.im/gulpjs/gulp
[gitter-image]: https://badges.gitter.im/gulpjs/gulp.svg
[backer-url]: #backers
[backer-badge]: https://opencollective.com/gulpjs/backers/badge.svg?color=blue
[sponsor-url]: #sponsors
[sponsor-badge]: https://opencollective.com/gulpjs/sponsors/badge.svg?color=blue
[support-url]: https://opencollective.com/gulpjs#support
[backers-image]: https://opencollective.com/gulpjs/backers.svg
[sponsors-image]: https://opencollective.com/gulpjs/sponsors.svg
[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
node-gulp-4.0.2+~cs38.20.35/appveyor.yml 0000664 0000000 0000000 00000000756 14156670073 0017440 0 ustar 00root root 0000000 0000000 # https://www.appveyor.com/docs/appveyor-yml
# https://www.appveyor.com/docs/lang/nodejs-iojs
environment:
matrix:
# node.js
- nodejs_version: "0.10"
- nodejs_version: "0.12"
- nodejs_version: "4"
- nodejs_version: "6"
- nodejs_version: "8"
- nodejs_version: "10"
install:
- ps: Install-Product node $env:nodejs_version
- npm install
test_script:
- node --version
- npm --version
- cmd: npm test
build: off
# build version format
version: "{build}"
node-gulp-4.0.2+~cs38.20.35/bin/ 0000775 0000000 0000000 00000000000 14156670073 0015610 5 ustar 00root root 0000000 0000000 node-gulp-4.0.2+~cs38.20.35/bin/gulp.js 0000775 0000000 0000000 00000000054 14156670073 0017117 0 ustar 00root root 0000000 0000000 #!/usr/bin/env node
require('gulp-cli')();
node-gulp-4.0.2+~cs38.20.35/docs/ 0000775 0000000 0000000 00000000000 14156670073 0015770 5 ustar 00root root 0000000 0000000 node-gulp-4.0.2+~cs38.20.35/docs/CLI.md 0000664 0000000 0000000 00000007171 14156670073 0016727 0 ustar 00root root 0000000 0000000 ## 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 ` 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 ` will manually set path of gulpfile. Useful if you have multiple gulpfiles. This will set the CWD to the gulpfile directory as well
- `--cwd ` 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 ...`.
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] │ └─┬
[20:58:55] │ ├── one
[20:58:55] │ └── two
[20:58:55] ├─┬ five
[20:58:55] │ └─┬
[20:58:55] │ ├─┬ four
[20:58:55] │ │ └─┬
[20:58:55] │ │ ├── one
[20:58:55] │ │ └── two
[20:58:55] │ └─┬
[20:58:55] │ ├── three
[20:58:55] │ └──
```
### `--tasks-simple`
Command: `gulp --tasks-simple`
Output:
```shell
one
two
three
four
five
```
node-gulp-4.0.2+~cs38.20.35/docs/FAQ.md 0000664 0000000 0000000 00000003405 14156670073 0016723 0 ustar 00root root 0000000 0000000 # 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.
## 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
node-gulp-4.0.2+~cs38.20.35/docs/README.md 0000664 0000000 0000000 00000006375 14156670073 0017262 0 ustar 00root root 0000000 0000000 # 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 한국어 참조 문서
## 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
node-gulp-4.0.2+~cs38.20.35/docs/api/ 0000775 0000000 0000000 00000000000 14156670073 0016541 5 ustar 00root root 0000000 0000000 node-gulp-4.0.2+~cs38.20.35/docs/api/README.md 0000664 0000000 0000000 00000000607 14156670073 0020023 0 ustar 00root root 0000000 0000000 ## 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)
node-gulp-4.0.2+~cs38.20.35/docs/api/concepts.md 0000664 0000000 0000000 00000012106 14156670073 0020701 0 ustar 00root root 0000000 0000000
# 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
node-gulp-4.0.2+~cs38.20.35/docs/api/dest.md 0000664 0000000 0000000 00000014665 14156670073 0020036 0 ustar 00root root 0000000 0000000
# 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 **(required)** | string function | The path of the output directory where files will be written. If a function is used, the function will be called with each Vinyl object and must return a string directory path. |
| 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 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 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 function | | The mode used when creating directories. If not set, the process' mode will be used. |
| overwrite | boolean function | true | When true, overwrites existing files with the same path. |
| append | boolean function | false | If true, adds contents to the end of the file, instead of replacing existing contents. |
| sourcemaps | boolean string function | false | If true, writes inline sourcemaps to the output file. Specifying a `string` path will write external [sourcemaps][sourcemaps-section] at the given path. |
| relativeSymlinks | boolean function | false | When false, any symbolic links created will be absolute. **Note**: Ignored if a junction is being created, as they must be absolute. |
| useJunctions | boolean function | true | This option is only relevant on Windows and ignored elsewhere. When true, creates directory symbolic link as a junction. Detailed in [Symbolic links on Windows][symbolic-links-section] below. |
## 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
node-gulp-4.0.2+~cs38.20.35/docs/api/last-run.md 0000664 0000000 0000000 00000005104 14156670073 0020630 0 ustar 00root root 0000000 0000000
# 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 **(required)** | function 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
node-gulp-4.0.2+~cs38.20.35/docs/api/parallel.md 0000664 0000000 0000000 00000006315 14156670073 0020664 0 ustar 00root root 0000000 0000000
# 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 **(required)** | function string | Any number of task functions can be passed as individual arguments. Strings can be used if you've registered tasks previously, but this is not recommended. |
### 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
node-gulp-4.0.2+~cs38.20.35/docs/api/registry.md 0000664 0000000 0000000 00000004355 14156670073 0020742 0 ustar 00root root 0000000 0000000
# 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
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".
When a registry without a `get` method is passed as `registryInstance`, throws an error with the message, "Custom registry must have `get` function".
When a registry without a `set` method is passed as `registryInstance`, throws an error with the message, "Custom registry must have `set` function".
When a registry without an `init` method is passed as `registryInstance`, throws an error with the message, "Custom registry must have `init` function"
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]: ../documentation-missing.md
node-gulp-4.0.2+~cs38.20.35/docs/api/series.md 0000664 0000000 0000000 00000006300 14156670073 0020354 0 ustar 00root root 0000000 0000000
# 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 **(required)** | function string | Any number of task functions can be passed as individual arguments. Strings can be used if you've registered tasks previously, but this is not recommended. |
### 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
node-gulp-4.0.2+~cs38.20.35/docs/api/src.md 0000664 0000000 0000000 00000021564 14156670073 0017662 0 ustar 00root root 0000000 0000000
# 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 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 |
|:--------:|:------:|------------|--------|
| buffer | boolean function | true | When true, file contents are buffered into memory. If false, the Vinyl object's `contents` property will be a paused stream. It may not be possible to buffer the contents of large files. **Note:** Plugins may not implement support for streaming contents. |
| read | boolean function | true | If false, files will be not be read and their Vinyl objects won't be writable to disk via `.dest()`. |
| since | date timestamp function | | When set, only creates Vinyl objects for files modified since the specified time. |
| removeBOM | boolean function | true | When true, removes the BOM from UTF-8 encoded files. If false, ignores a BOM. |
| sourcemaps | boolean function | false | If true, enables [sourcemaps][sourcemaps-section] support on Vinyl objects created. Loads inline sourcemaps and resolves external sourcemap links. |
| resolveSymlinks | boolean function | true | When true, recursively resolves symbolic links to their targets. If false, preserves the symbolic links and sets the Vinyl object's `symlink` property to the original file's path. |
| cwd | string | `process.cwd()` | The directory that will be combined with any relative path to form an absolute path. Is ignored for absolute paths. Use to avoid combining `globs` with `path.join()`. _This option is passed directly to [glob-stream][glob-stream-external]._ |
| base | string | | Explicitly set the `base` property on created Vinyl objects. Detailed in [API Concepts][glob-base-concepts]. _This option is passed directly to [glob-stream][glob-stream-external]._ |
| cwdbase | boolean | false | If true, `cwd` and `base` options should be aligned. _This option is passed directly to [glob-stream][glob-stream-external]._ |
| root | string | | The root path that `globs` are resolved against. _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. _This option is passed directly to [glob-stream][glob-stream-external]._ |
| uniqueBy | string function | `'path'` | Remove duplicates from the stream by comparing the string property name or the result of the function. **Note:** When using a function, the function receives the streamed data (objects containing `cwd`, `base`, `path` properties). |
| dot | boolean | false | If true, compare globs against dot files, like `.gitignore`. _This option is passed directly to [node-glob][node-glob-external]._ |
| silent | boolean | true | When true, suppresses warnings from printing on `stderr`. **Note:** This option is passed directly to [node-glob][node-glob-external] but defaulted to `true` instead of `false`. |
| mark | boolean | false | If true, a `/` character will be appended to directory matches. Generally not needed because paths are normalized within the pipeline. _This option is passed directly to [node-glob][node-glob-external]._ |
| nosort | boolean | false | If true, disables sorting the glob results. _This option is passed directly to [node-glob][node-glob-external]._ |
| stat | boolean | false | If true, `fs.stat()` is called on all results. This adds extra overhead and generally should not be used. _This option is passed directly to [node-glob][node-glob-external]._ |
| strict | boolean | false | If true, an error will be thrown if an unexpected problem is encountered while attempting to read a directory. _This option is passed directly to [node-glob][node-glob-external]._ |
| nounique | boolean | false | When false, prevents duplicate files in the result set. _This option is passed directly to [node-glob][node-glob-external]._ |
| debug | boolean | false | If true, debugging information will be logged to the command line. _This option is passed directly to [node-glob][node-glob-external]._ |
| nobrace | boolean | false | If true, avoids expanding brace sets - e.g. `{a,b}` or `{1..3}`. _This option is passed directly to [node-glob][node-glob-external]._ |
| noglobstar | boolean | false | If true, treats double-star glob character as single-star glob character. _This option is passed directly to [node-glob][node-glob-external]._ |
| noext | boolean | false | If true, avoids matching [extglob][extglob-docs] patterns - e.g. `+(ab)`. _This option is passed directly to [node-glob][node-glob-external]._ |
| nocase | boolean | false | If true, performs a case-insensitive match. **Note:** On case-insensitive file systems, non-magic patterns will match by default. _This option is passed directly to [node-glob][node-glob-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`. _This option is passed directly to [node-glob][node-glob-external]._ |
| nodir | boolean | false | If true, only matches files, not directories. **Note:** To match only directories, end your glob with a `/`. _This option is passed directly to [node-glob][node-glob-external]._ |
| ignore | string array | | Globs to exclude from matches. This option is combined with negated `globs`. **Note:** These globs are always matched against dot files, regardless of any other settings. _This option is passed directly to [node-glob][node-glob-external]._ |
| follow | boolean | false | If true, symlinked directories will be traversed when expanding `**` globs. **Note:** This can cause problems with cyclical links. _This option is passed directly to [node-glob][node-glob-external]._ |
| realpath | boolean | false | If true, `fs.realpath()` is called on all results. This may result in dangling links. _This option is passed directly to [node-glob][node-glob-external]._ |
| cache | object | | A previously generated cache object - avoids some file system calls. _This option is passed directly to [node-glob][node-glob-external]._ |
| statCache | object | | A previously generated cache of `fs.Stat` results - avoids some file system calls. _This option is passed directly to [node-glob][node-glob-external]._ |
| symlinks | object | | A previously generated cache of symbolic links - avoids some file system calls. _This option is passed directly to [node-glob][node-glob-external]._ |
| nocomment | boolean | false | When false, treat a `#` character at the start of a glob as a comment. _This option is passed directly to [node-glob][node-glob-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
[node-glob-external]: https://github.com/isaacs/node-glob
[glob-stream-external]: https://github.com/gulpjs/glob-stream
node-gulp-4.0.2+~cs38.20.35/docs/api/symlink.md 0000664 0000000 0000000 00000010777 14156670073 0020565 0 ustar 00root root 0000000 0000000
# 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 **(required)** | string function | The path of the output directory where symbolic links will be created. If a function is used, the function will be called with each Vinyl object and must return a string directory path. |
| 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 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 function | | The mode used when creating directories. If not set, the process' mode will be used. |
| overwrite | boolean function | true | When true, overwrites existing files with the same path. |
| relativeSymlinks | boolean function | false | When false, any symbolic links created will be absolute. **Note**: Ignored if a junction is being created, as they must be absolute. |
| useJunctions | boolean function | true | This option is only relevant on Windows and ignored elsewhere. When true, creates directory symbolic link as a junction. Detailed in [Symbolic links on Windows][symbolic-links-section] below. |
## 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
node-gulp-4.0.2+~cs38.20.35/docs/api/task.md 0000664 0000000 0000000 00000006641 14156670073 0020034 0 ustar 00root root 0000000 0000000
# 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 the task system. Not needed when using named functions for `taskFunction`. |
| taskFunction **(required)** | function | A [task function][task-concepts] or composed task - generated by `series()` and `parallel()`. Ideally a named function. [Task metadata][task-metadata-section] can be attached to provide extra information to the command line. |
### 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. **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
node-gulp-4.0.2+~cs38.20.35/docs/api/tree.md 0000664 0000000 0000000 00000006724 14156670073 0020033 0 ustar 00root root 0000000 0000000
# 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: "",
type: "function",
branch: true,
nodes: [
{
label: "one",
type: "function",
nodes: []
},
{
label: "two",
type: "function",
nodes: []
}
]
}
]
},
{
label: "five",
type: "task",
nodes: [
{
label: "",
type: "function",
branch: true,
nodes: [
{
label: "",
type: "function",
branch: true,
nodes: [
{
label: "one",
type: "function",
nodes: []
},
{
label: "two",
type: "function",
nodes: []
}
]
},
{
label: "",
type: "function",
branch: true,
nodes: [
{
label: "three",
type: "function",
nodes: []
},
{
label: "",
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
node-gulp-4.0.2+~cs38.20.35/docs/api/vinyl-iscustomprop.md 0000664 0000000 0000000 00000003234 14156670073 0022773 0 ustar 00root root 0000000 0000000
# 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
node-gulp-4.0.2+~cs38.20.35/docs/api/vinyl-isvinyl.md 0000664 0000000 0000000 00000001403 14156670073 0021715 0 ustar 00root root 0000000 0000000
# 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.
node-gulp-4.0.2+~cs38.20.35/docs/api/vinyl.md 0000664 0000000 0000000 00000020347 14156670073 0020232 0 ustar 00root root 0000000 0000000
# 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/file.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 Buffer `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 Buffer `null` | Gets and sets the contents of the virtual file. If set to a ReadableStream, it is wrapped in a [cloneable-readable][cloneable-readable-external] stream. | If set to any value other than a ReadableStream, a Buffer, or `null`. |
| 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
node-gulp-4.0.2+~cs38.20.35/docs/api/watch.md 0000664 0000000 0000000 00000020240 14156670073 0020167 0 ustar 00root root 0000000 0000000
# 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 **(required)** | string array | [Globs][globs-concepts] to watch on the file system. |
| options | object | Detailed in [Options][options-section] below. |
| task | function 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. **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 array | [ 'add', 'change', 'unlink' ] | The events being watched to trigger task execution. Can be `'add'`, `'addDir'`, `'change'`, `'unlink'`, `'unlinkDir'`, `'ready'`, and/or `'error'`. Additionally `'all'` is available, which represents all events other than `'ready'` and `'error'`. _This option is passed directly to [chokidar][chokidar-external]._ |
| persistent | boolean | true | If false, the watcher will not keep the Node process running. Disabling this option is not recommended. _This option is passed directly to [chokidar][chokidar-external]._ |
| ignored | array string RegExp function | | Defines globs to be ignored. If a function is provided, it will be called twice per path - once with just the path, then with the path and the `fs.Stats` object of that file. _This option is passed directly to [chokidar][chokidar-external]._ |
| followSymlinks | boolean | true | When true, changes to both symbolic links and the linked files trigger events. If false, only changes to the symbolic links trigger events. _This option is passed directly to [chokidar][chokidar-external]._ |
| cwd | string | | The directory that will be combined with any relative path to form an absolute path. Is ignored for absolute paths. Use to avoid combining `globs` with `path.join()`. _This option is passed directly to [chokidar][chokidar-external]._ |
| disableGlobbing | boolean | false | If true, all `globs` are treated as literal path names, even if they have special characters. _This option is passed directly to [chokidar][chokidar-external]._ |
| usePolling | boolean | false | When false, the watcher will use `fs.watch()` (or [fsevents][fsevents-external] on Mac) for watching. If true, use `fs.watchFile()` polling instead - needed for successfully watching files over a network or other non-standard situations. Overrides the `useFsEvents` default. _This option is passed directly to [chokidar][chokidar-external]._ |
| interval | number | 100 | Combine with `usePolling: true`. Interval of file system polling. _This option is passed directly to [chokidar][chokidar-external]._ |
| binaryInterval | number | 300 | Combine with `usePolling: true`. Interval of file system polling for binary files. _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. _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. _This option is passed directly to [chokidar][chokidar-external]._ |
| depth | number | | Indicates how many nested levels of directories will be watched. _This option is passed directly to [chokidar][chokidar-external]._ |
| awaitWriteFinish | boolean | false | Do not use this option, use `delay` instead. _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. _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. _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 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 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
node-gulp-4.0.2+~cs38.20.35/docs/documentation-missing.md 0000664 0000000 0000000 00000000766 14156670073 0022643 0 ustar 00root root 0000000 0000000
# 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
node-gulp-4.0.2+~cs38.20.35/docs/getting-started.md 0000664 0000000 0000000 00000000343 14156670073 0021417 0 ustar 00root root 0000000 0000000 ## 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.
node-gulp-4.0.2+~cs38.20.35/docs/getting-started/ 0000775 0000000 0000000 00000000000 14156670073 0021075 5 ustar 00root root 0000000 0000000 node-gulp-4.0.2+~cs38.20.35/docs/getting-started/1-quick-start.md 0000664 0000000 0000000 00000004341 14156670073 0024026 0 ustar 00root root 0000000 0000000
# 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 `.
## 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
node-gulp-4.0.2+~cs38.20.35/docs/getting-started/2-javascript-and-gulpfiles.md 0000664 0000000 0000000 00000005106 14156670073 0026456 0 ustar 00root root 0000000 0000000
# 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
node-gulp-4.0.2+~cs38.20.35/docs/getting-started/3-creating-tasks.md 0000664 0000000 0000000 00000011561 14156670073 0024502 0 ustar 00root root 0000000 0000000
# 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]
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.
## 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
node-gulp-4.0.2+~cs38.20.35/docs/getting-started/4-async-completion.md 0000664 0000000 0000000 00000010523 14156670073 0025045 0 ustar 00root root 0000000 0000000
# 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 { Observable } = require('rxjs');
function observableTask() {
return Observable.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 } = fs.readFileSync('package.json');
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
node-gulp-4.0.2+~cs38.20.35/docs/getting-started/5-working-with-files.md 0000664 0000000 0000000 00000010145 14156670073 0025313 0 ustar 00root root 0000000 0000000
# 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
node-gulp-4.0.2+~cs38.20.35/docs/getting-started/6-explaining-globs.md 0000664 0000000 0000000 00000010170 14156670073 0025023 0 ustar 00root root 0000000 0000000
# 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, they are matched in array order - especially useful for negative globs.
## 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'
```
In the previous example, if `scripts/` wasn't prefixed, all dependencies in `node_modules` or other directories would also be matched.
## Special character: ! (negative)
Since globs are matched in array order, a negative glob must follow at least one non-negative glob in an array. The first finds a set of matches, then the negative glob removes a portion of those results. When excluding all files within a directory, you must add `/**` after the directory name, which the globbing library optimizes internally.
```js
['scripts/**/*.js', '!scripts/vendor/**']
```
If any non-negative globs follow a negative, nothing will be removed from the later set of matches.
```js
['scripts/**/*.js', '!scripts/vendor/**', 'scripts/vendor/react.js']
```
Negative globs can be used as an alternative for restricting double-star globs.
```js
['**/*.js', '!node_modules/**']
```
In the previous example, if the negative glob was `!node_modules/**/*.js`, the globbing library wouldn't optimize the negation and every match would have to be compared against the negative glob, which would be extremely slow. To ignore all files in a directory, only add the `/**` glob after the directory name.
## 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)
node-gulp-4.0.2+~cs38.20.35/docs/getting-started/7-using-plugins.md 0000664 0000000 0000000 00000006654 14156670073 0024402 0 ustar 00root root 0000000 0000000
# 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.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)
}
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
node-gulp-4.0.2+~cs38.20.35/docs/getting-started/8-watching-files.md 0000664 0000000 0000000 00000010705 14156670073 0024473 0 ustar 00root root 0000000 0000000
# 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
node-gulp-4.0.2+~cs38.20.35/docs/getting-started/README.md 0000664 0000000 0000000 00000000567 14156670073 0022364 0 ustar 00root root 0000000 0000000 # 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)
node-gulp-4.0.2+~cs38.20.35/docs/recipes/ 0000775 0000000 0000000 00000000000 14156670073 0017422 5 ustar 00root root 0000000 0000000 node-gulp-4.0.2+~cs38.20.35/docs/recipes/README.md 0000664 0000000 0000000 00000003663 14156670073 0020711 0 ustar 00root root 0000000 0000000 # Recipes
* [Automate release workflow](automate-release-workflow.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)
* [Only pass through changed files](only-pass-through-changed-files.md)
* [Pass parameters from the command line](pass-arguments-from-cli.md)
* [Rebuild only files that change](rebuild-only-files-that-change.md)
* [Generating a file per folder](running-task-steps-per-folder.md)
* [Running tasks in series](running-tasks-in-series.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)
* [Specifying a new cwd (current working directory)](specifying-a-cwd.md)
* [Split tasks across multiple files](split-tasks-across-multiple-files.md)
* [Using external config file](using-external-config-file.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)
* [Exports as tasks](exports-as-tasks.md)
* [Rollup with rollup-stream](rollup-with-rollup-stream.md)
* [Run gulp task via cron job](cron-task.md)
* [Running shell commands](running-shell-commands.md)
node-gulp-4.0.2+~cs38.20.35/docs/recipes/automate-release-workflow.md 0000664 0000000 0000000 00000004666 14156670073 0025065 0 ustar 00root root 0000000 0000000 # Automate release workflow
If your project follows a semantic versioning, it may be a good idea to automatize the steps needed to do a release.
Below you have a simple recipe that bumps the project version, commits the changes to git and creates a new tag.
``` javascript
var gulp = require('gulp');
var conventionalChangelog = require('gulp-conventional-changelog');
var conventionalGithubReleaser = require('conventional-github-releaser');
var bump = require('gulp-bump');
var log = require('gulplog');
var git = require('gulp-git');
var fs = require('fs');
gulp.task('changelog', function () {
return gulp.src('CHANGELOG.md', {
buffer: false
})
.pipe(conventionalChangelog({
preset: 'angular' // Or to any other commit message convention you use.
}))
.pipe(gulp.dest('./'));
});
gulp.task('github-release', function(done) {
conventionalGithubReleaser({
type: "oauth",
token: '0126af95c0e2d9b0a7c78738c4c00a860b04acc8' // change this to your own GitHub token or use an environment variable
}, {
preset: 'angular' // Or to any other commit message convention you use.
}, done);
});
gulp.task('bump-version', function () {
// We hardcode the version change type to 'patch' but it may be a good idea to
// use minimist (https://www.npmjs.com/package/minimist) to determine with a
// command argument whether you are doing a 'major', 'minor' or a 'patch' change.
return gulp.src(['./bower.json', './package.json'])
.pipe(bump({type: "patch"}).on('error', log.error))
.pipe(gulp.dest('./'));
});
gulp.task('commit-changes', function () {
return gulp.src('.')
.pipe(git.add())
.pipe(git.commit('[Prerelease] Bumped version number'));
});
gulp.task('push-changes', function (done) {
git.push('origin', 'master', done);
});
gulp.task('create-new-tag', function (done) {
var version = getPackageJsonVersion();
git.tag(version, 'Created Tag for version: ' + version, function (error) {
if (error) {
return done(error);
}
git.push('origin', 'master', {args: '--tags'}, done);
});
function getPackageJsonVersion () {
// We parse the json file instead of using require because require caches
// multiple calls so the version number won't be updated
return JSON.parse(fs.readFileSync('./package.json', 'utf8')).version;
};
});
gulp.task('release', gulp.series(
'bump-version',
'changelog',
'commit-changes',
'push-changes',
'create-new-tag',
'github-release'
));
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/browserify-multiple-destination.md 0000664 0000000 0000000 00000002373 14156670073 0026314 0 ustar 00root root 0000000 0000000 # 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'));
});
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/browserify-transforms.md 0000664 0000000 0000000 00000002514 14156670073 0024335 0 ustar 00root root 0000000 0000000 # 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 sourcemaps = require('gulp-sourcemaps');
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'))
.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/'));
});
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/browserify-uglify-sourcemap.md 0000664 0000000 0000000 00000002524 14156670073 0025433 0 ustar 00root root 0000000 0000000 # 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/'));
});
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/browserify-with-globs.md 0000664 0000000 0000000 00000004421 14156670073 0024215 0 ustar 00root root 0000000 0000000 # 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;
});
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/combining-streams-to-handle-errors.md 0000664 0000000 0000000 00000001644 14156670073 0026555 0 ustar 00root root 0000000 0000000 # 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));
});
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/cron-task.md 0000664 0000000 0000000 00000001624 14156670073 0021650 0 ustar 00root root 0000000 0000000 # 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.
node-gulp-4.0.2+~cs38.20.35/docs/recipes/delete-files-folder.md 0000664 0000000 0000000 00000004311 14156670073 0023556 0 ustar 00root root 0000000 0000000 # 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.
node-gulp-4.0.2+~cs38.20.35/docs/recipes/exports-as-tasks.md 0000664 0000000 0000000 00000000737 14156670073 0023203 0 ustar 00root root 0000000 0000000 # Exports as Tasks
Using the ES2015 module syntax you can use your exports as tasks.
```js
import gulp from 'gulp';
import babel from 'gulp-babel';
// named task
export function build() {
return gulp.src('src/*.js')
.pipe(babel())
.pipe(gulp.dest('lib'));
}
// default task
export default function dev() {
gulp.watch('src/*.js', ['build']);
}
```
This will **not** work with the gulp-cli version bundled with gulp 3.x. You must use the latest published version.
node-gulp-4.0.2+~cs38.20.35/docs/recipes/fast-browserify-builds-with-watchify.md 0000664 0000000 0000000 00000004161 14156670073 0027141 0 ustar 00root root 0000000 0000000 # 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'));
}
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/handling-the-delete-event-on-watch.md 0000664 0000000 0000000 00000002011 14156670073 0026375 0 ustar 00root root 0000000 0000000 # 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);
});
});
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/incremental-builds-with-concatenate.md 0000664 0000000 0000000 00000003444 14156670073 0026765 0 ustar 00root root 0000000 0000000 # 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
}
});
});
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/maintain-directory-structure-while-globbing.md 0000664 0000000 0000000 00000002602 14156670073 0030473 0 ustar 00root root 0000000 0000000 # 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

node-gulp-4.0.2+~cs38.20.35/docs/recipes/make-stream-from-buffer.md 0000664 0000000 0000000 00000010204 14156670073 0024357 0 ustar 00root root 0000000 0000000 # 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'
));
}
));
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/minified-and-non-minified.md 0000664 0000000 0000000 00000001256 14156670073 0024646 0 ustar 00root root 0000000 0000000 # 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));
});
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/minimal-browsersync-setup-with-gulp4.md 0000664 0000000 0000000 00000007005 14156670073 0027112 0 ustar 00root root 0000000 0000000 # 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/4.0/README.md#use-last-javascript-version-in-your-gulpfile)
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;
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/mocha-test-runner-with-gulp.md 0000664 0000000 0000000 00000001504 14156670073 0025235 0 ustar 00root root 0000000 0000000 # 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'));
});
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/only-pass-through-changed-files.md 0000664 0000000 0000000 00000001607 14156670073 0026042 0 ustar 00root root 0000000 0000000 # Only pass through changed files
Files are passed through the whole pipe chain on every run by default. By using [gulp-changed](https://github.com/sindresorhus/gulp-changed) only changed files will be passed through. This can speed up consecutive runs considerably.
```js
// npm install --save-dev gulp gulp-changed gulp-jscs gulp-uglify
var gulp = require('gulp');
var changed = require('gulp-changed');
var jscs = require('gulp-jscs');
var uglify = require('gulp-uglify');
// we define some constants here so they can be reused
var SRC = 'src/*.js';
var DEST = 'dist';
gulp.task('default', function() {
return gulp.src(SRC)
// the `changed` task needs to know the destination directory
// upfront to be able to figure out which files changed
.pipe(changed(DEST))
// only files that has changed will pass through here
.pipe(jscs())
.pipe(uglify())
.pipe(gulp.dest(DEST));
});
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/pass-arguments-from-cli.md 0000664 0000000 0000000 00000001221 14156670073 0024417 0 ustar 00root root 0000000 0000000 # 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
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/rebuild-only-files-that-change.md 0000664 0000000 0000000 00000000543 14156670073 0025634 0 ustar 00root root 0000000 0000000 # Rebuild only files that change
With [`gulp-watch`](https://github.com/floatdrop/gulp-watch):
```js
var gulp = require('gulp');
var sass = require('gulp-sass');
var watch = require('gulp-watch');
gulp.task('default', function() {
return gulp.src('sass/*.scss')
.pipe(watch('sass/*.scss'))
.pipe(sass())
.pipe(gulp.dest('dist'));
});
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/rollup-with-rollup-stream.md 0000664 0000000 0000000 00000004176 14156670073 0025046 0 ustar 00root root 0000000 0000000 # 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 vinyl-source-stream
var gulp = require('gulp');
var rollup = require('rollup-stream');
var source = require('vinyl-source-stream');
gulp.task('rollup', function() {
return rollup({
entry: './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 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({
entry: './src/main.js',
sourceMap: true
})
// 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'));
});
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/run-grunt-tasks-from-gulp.md 0000664 0000000 0000000 00000003326 14156670073 0024742 0 ustar 00root root 0000000 0000000 # 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).
node-gulp-4.0.2+~cs38.20.35/docs/recipes/running-shell-commands.md 0000664 0000000 0000000 00000001431 14156670073 0024327 0 ustar 00root root 0000000 0000000 # Running Shell Commands
Sometimes it is helpful to be able to call existing command line tools from gulp.
There are 2 ways to handle this: node's [`child_process`](https://nodejs.org/api/child_process.html)
built-in module or [`gulp-exec`](https://github.com/robrich/gulp-exec) if you need to integrate the
command with an existing pipeline.
```js
'use strict';
var cp = require('child_process');
var gulp = require('gulp');
gulp.task('reset', function() {
// In gulp 4, you can return a child process to signal task completion
return cp.execFile('git checkout -- .');
});
```
```js
'use strict';
var gulp = require('gulp');
var exec = require('gulp-exec');
gulp.task('reset', function() {
return gulp.src('./**/**')
.pipe(exec('git checkout -- <%= file.path %>'));
});
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/running-task-steps-per-folder.md 0000664 0000000 0000000 00000003563 14156670073 0025564 0 ustar 00root root 0000000 0000000 # 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
node-gulp-4.0.2+~cs38.20.35/docs/recipes/running-tasks-in-series.md 0000664 0000000 0000000 00000004735 14156670073 0024454 0 ustar 00root root 0000000 0000000 # Running tasks in series
By default, gulp CLI run tasks with maximum concurrency - e.g. it launches
all the tasks at once and waits for nothing. If you want to create a series
where tasks run in a particular order, you should use `gulp.series`;
```js
var gulp = require('gulp');
var doAsyncStuff = require('./stuff');
gulp.task('one', function(done) {
doAsyncStuff(function(err){
done(err);
});
});
gulp.task('two', function(done) {
// do things
done();
});
gulp.task('default', gulp.series('one', 'two'));
```
Another example, using a dependency pattern. It uses
[`async-once`](https://www.npmjs.com/package/async-once) to run the `clean`
task operations only once:
```js
var gulp = require('gulp');
var del = require('del'); // rm -rf
var once = require('async-once');
gulp.task('clean', once(function(done) {
// run only once.
// for the next call to the clean task, once will call done with
// the same arguments as the first call.
del(['output'], done);
}));
gulp.task('templates', gulp.series('clean', function() {
return gulp.src(['src/templates/*.hbs'])
// do some concatenation, minification, etc.
.pipe(gulp.dest('output/templates/'));
}));
gulp.task('styles', gulp.series('clean', function() {
return gulp.src(['src/styles/app.less'])
// do some hinting, minification, etc.
.pipe(gulp.dest('output/css/app.css'));
}));
// templates and styles will be processed in parallel.
// `clean` will be guaranteed to complete before either start.
// `clean` operations will not be run twice,
// even though it is called as a dependency twice.
gulp.task('build', gulp.parallel('templates', 'styles'));
// an alias.
gulp.task('default', gulp.parallel('build'));
```
Note that it's an anti-pattern in Gulp 4 and the logs will show the clean task
running twice. Instead, `templates` and `style` should use dedicated `clean:*`
tasks:
```js
var gulp = require('gulp');
var del = require('del');
gulp.task('clean:templates', function() {
return del(['output/templates/']);
});
gulp.task('templates', gulp.series('clean:templates', function() {
return gulp.src(['src/templates/*.hbs'])
.pipe(gulp.dest('output/templates/'));
});
gulp.task('clean:styles', function() {
return del(['output/css/']);
});
gulp.task('styles', gulp.series('clean:styles', function() {
return gulp.src(['src/styles/app.less'])
.pipe(gulp.dest('output/css/app.css'));
}));
gulp.task('build', gulp.parallel('templates', 'styles'));
gulp.task('default', gulp.parallel('build'));
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/server-with-livereload-and-css-injection.md 0000664 0000000 0000000 00000005437 14156670073 0027666 0 ustar 00root root 0000000 0000000 # 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
...
...
```
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
...
...
```
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).
node-gulp-4.0.2+~cs38.20.35/docs/recipes/sharing-streams-with-stream-factories.md 0000664 0000000 0000000 00000003757 14156670073 0027306 0 ustar 00root root 0000000 0000000 # 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.
node-gulp-4.0.2+~cs38.20.35/docs/recipes/specifying-a-cwd.md 0000664 0000000 0000000 00000000730 14156670073 0023075 0 ustar 00root root 0000000 0000000 # Specifying a new cwd (current working directory)
This is helpful for projects using a nested directory structure, such as:
```
/project
/layer1
/layer2
```
You can use the gulp CLI option `--cwd`.
From the `project/` directory:
```sh
gulp --cwd layer1
```
If you only need to specify a cwd for a certain glob, you can use the `cwd` option on a [glob-stream](https://github.com/gulpjs/glob-stream):
```js
gulp.src('./some/dir/**/*.js', { cwd: 'public' });
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/split-tasks-across-multiple-files.md 0000664 0000000 0000000 00000001604 14156670073 0026444 0 ustar 00root root 0000000 0000000 # Split tasks across multiple files
If your `gulpfile.js` is starting to grow too large, you can split the tasks
into separate files by using the [gulp-hub](https://github.com/frankwallis/gulp-hub/tree/4.0)
module as a [custom registry](https://github.com/phated/undertaker#registryregistryinstance).
Imagine the following file structure:
```
gulpfile.js
tasks/
├── dev.js
├── release.js
└── test.js
```
Install the `gulp-hub` module:
```sh
npm install --save-dev gulp gulp-hub
```
Add the following lines to your `gulpfile.js` file:
```js
'use strict';
var gulp = require('gulp');
var HubRegistry = require('gulp-hub');
/* load some files into the registry */
var hub = new HubRegistry(['tasks/*.js']);
/* tell gulp to use the tasks just loaded */
gulp.registry(hub);
```
This recipe can also be found at https://github.com/frankwallis/gulp-hub/tree/4.0/examples/recipe
node-gulp-4.0.2+~cs38.20.35/docs/recipes/templating-with-swig-and-yaml-front-matter.md 0000664 0000000 0000000 00000001453 14156670073 0030153 0 ustar 00root root 0000000 0000000 # 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
---
{{ title }}
{{ title }}
{% for todo in todos %}
{{ todo }}
{% endfor %}
```
##### `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']);
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/using-external-config-file.md 0000664 0000000 0000000 00000001666 14156670073 0025102 0 ustar 00root root 0000000 0000000 # Using external config file
Beneficial because it's keeping tasks DRY and config.json can be used by another task runner, like `grunt`.
-
###### `config.json`
```json
{
"desktop" : {
"src" : [
"dev/desktop/js/**/*.js",
"!dev/desktop/js/vendor/**"
],
"dest" : "build/desktop/js"
},
"mobile" : {
"src" : [
"dev/mobile/js/**/*.js",
"!dev/mobile/js/vendor/**"
],
"dest" : "build/mobile/js"
}
}
```
-
###### `gulpfile.js`
```js
// npm install --save-dev gulp gulp-uglify merge-stream
var gulp = require('gulp');
var uglify = require('gulp-uglify');
var merge = require('merge-stream');
var config = require('./config.json');
function doStuff(cfg) {
return gulp.src(cfg.src)
.pipe(uglify())
.pipe(gulp.dest(cfg.dest));
}
gulp.task('dry', function() {
// return a stream to signal completion
return merge([
doStuff(config.desktop),
doStuff(config.mobile)
])
});
```
node-gulp-4.0.2+~cs38.20.35/docs/recipes/using-multiple-sources-in-one-task.md 0000664 0000000 0000000 00000001321 14156670073 0026523 0 ustar 00root root 0000000 0000000 # 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'));
});
node-gulp-4.0.2+~cs38.20.35/docs/why-use-pump/ 0000775 0000000 0000000 00000000000 14156670073 0020350 5 ustar 00root root 0000000 0000000 node-gulp-4.0.2+~cs38.20.35/docs/why-use-pump/README.md 0000664 0000000 0000000 00000007502 14156670073 0021633 0 ustar 00root root 0000000 0000000 # 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 [`pump`][pump] module normalizes these problems and passes
you the errors in a callback.
## A common gulpfile example
A common pattern in gulp files is to simply return a Node.js stream, and expect
the gulp tool to handle errors.
```javascript
// example of a common gulpfile
var gulp = require('gulp');
var uglify = require('gulp-uglify');
gulp.task('compress', function () {
// returns a Node.js stream, but no handling of error messages
return gulp.src('lib/*.js')
.pipe(uglify())
.pipe(gulp.dest('dist'));
});
```

There’s an error in one of the JavaScript files, but that error message is the
opposite of helpful. You want to know what file and line contains the error. So
what is this mess?
When there’s an error in a stream, the Node.js stream fire the 'error' event,
but if there’s no handler for this event, it instead goes to the defined
[uncaught exception][uncaughtException] handler. The default behavior of the
uncaught exception handler is documented:
> By default, Node.js handles such exceptions by printing the stack trace to
> stderr and exiting.
## Handling the Errors
Since allowing the errors to make it to the uncaught exception handler isn’t
useful, we should handle the exceptions properly. Let’s give that a quick shot.
```javascript
var gulp = require('gulp');
var uglify = require('gulp-uglify');
gulp.task('compress', function () {
return gulp.src('lib/*.js')
.pipe(uglify())
.pipe(gulp.dest('dist'))
.on('error', function(err) {
console.error('Error in compress task', err.toString());
});
});
```
Unfortunately, Node.js stream’s `pipe` function doesn’t forward errors through
the chain, so this error handler only handles the errors given by
`gulp.dest`. Instead we need to handle errors for each stream.
```javascript
var gulp = require('gulp');
var uglify = require('gulp-uglify');
gulp.task('compress', function () {
function createErrorHandler(name) {
return function (err) {
console.error('Error from ' + name + ' in compress task', err.toString());
};
}
return gulp.src('lib/*.js')
.on('error', createErrorHandler('gulp.src'))
.pipe(uglify())
.on('error', createErrorHandler('uglify'))
.pipe(gulp.dest('dist'))
.on('error', createErrorHandler('gulp.dest'));
});
```
This is a lot of complexity to add in each of your gulp tasks, and it’s easy to
forget to do it. In addition, it’s still not perfect, as it doesn’t properly
signal to gulp’s task system that the task has failed. We can fix this, and we
can handle the other pesky issues with error propogations with streams, but it’s
even more work!
## Using pump
The [`pump`][pump] module is a cheat code of sorts. It’s a wrapper around the
`pipe` functionality that handles these cases for you, so you can stop hacking
on your gulpfiles, and get back to hacking new features into your app.
```javascript
var gulp = require('gulp');
var uglify = require('gulp-uglify');
var pump = require('pump');
gulp.task('compress', function (cb) {
pump([
gulp.src('lib/*.js'),
uglify(),
gulp.dest('dist')
],
cb
);
});
```
The gulp task system provides a gulp task with a callback, which can signal
successful task completion (being called with no arguments), or a task failure
(being called with an Error argument). Fortunately, this is the exact same
format `pump` uses!

Now it’s very clear what plugin the error was from, what the error actually was,
and from what file and line number.
[pump]: https://github.com/mafintosh/pump
[uncaughtException]: https://nodejs.org/api/process.html#process_event_uncaughtexception
node-gulp-4.0.2+~cs38.20.35/docs/why-use-pump/pipe-error.png 0000664 0000000 0000000 00000432222 14156670073 0023147 0 ustar 00root root 0000000 0000000 PNG
IHDR !q sRGB @ IDATx]`S$^(m@lAT
*n' D\:RB{YܛI{s2@{{ 졇5yѡu e2@P(@9C?B*~ؾ/ZER OVjPh e2@P( a@ P(d֮]ޛo >>M6m% e2@P( eoʀX,'|rhҤI;::jPؔ e2@P( aĶ\zكBP( e2@)|r{uu(Aq"(sͅ|A
A+6T*?ʊlʳ[ǂOUWUga.05\-{'WȔ e2@P(;'_PZZڣu {}^XKA`iWˠ|3l`Re"G