initial commit

2014-02-12 12:36:59 +04:00
commit d3fcd7f10c
@@ -0,0 +1,38 @@
+# 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 [gulp-util](https://github.com/gulpjs/gulp-util)'s `combine`
+method 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:
+
+``` javascript
+var combine = require('gulp-util').combine
+var uglify = require('gulp-uglify')
+var gulp = require('gulp')
+
+gulp.task('test', function() {
+  var combined = combine(
+    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:
+  combined.on('error', function(err) {
+    console.warn(err.message)
+  })
+
+  return combined
+})
+```
+
+You can use this technique in your gulp plugins and node modules too using
+the [multipipe](http://npmjs.org/package/multipipe) module, and is a generally useful means of ensuring that errors aren't thrown from inaccessible streams
+somewhere deep inside `./node_modules`.
@@ -0,0 +1,69 @@
+# Mocha test-runner with gulp
+
+### Passing shared module in all tests
+
+```js
+var gulp = require('gulp');
+var mocha = require('gulp-mocha');
+ 
+gulp.task('tests', function() {
+    return gulp.src(['test/test-*.js'], { read: false })
+        .pipe(mocha({
+            reporter: 'spec',
+            globals: {
+                should: require('should')
+            }
+        }));
+});
+```
+
+### Running mocha tests when files change
+
+With bundled `gulp.watch` and [`gulp-batch`](https://github.com/floatdrop/gulp-batch) (see readme of gulp-batch for reasons):
+
+```js
+// npm install gulp gulp-watch gulp-mocha gulp-batch
+ 
+var gulp = require('gulp');
+var mocha = require('gulp-mocha');
+var batch = require('gulp-batch');
+var gutil = require('gulp-util');
+
+gulp.task('mocha', function () {
+    return gulp.src(['test/*.js'], { read: false })
+        .pipe(mocha({ reporter: 'list' }))
+        .on('error', gutil.log);
+});
+
+gulp.watch(['lib/**', 'test/**'], batch(function(events, cb) {
+    gulp.run('mocha', cb);
+}));
+```
+
+With [`gulp-watch`](https://github.com/floatdrop/gulp-watch) plugin:
+
+```js
+// npm i gulp gulp-watch gulp-mocha
+
+var gulp = require('gulp');
+var mocha = require('gulp-mocha');
+var watch = require('gulp-watch');
+var gutil = require('gulp-util')
+
+gulp.task('mocha', function () {
+    return gulp.src(['test/*.js'], { read: false })
+        .pipe(mocha({ reporter: 'list' }))
+        .on('error', gutil.log);
+});
+
+gulp.task('watch', function() {
+    return gulp.src(['lib/**', 'test/**'], { read: false })
+        .pipe(watch(function(events, cb) {
+            gulp.run('mocha', cb);
+        }));
+});
+
+gulp.task('default', ['mocha', 'watch']);
+
+// run `gulp watch` or just `gulp` for watching and rerunning tests
+```
@@ -0,0 +1,27 @@
+# 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
+// run `npm install 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));
+});
+```
@@ -0,0 +1,28 @@
+# Pass parameters from the command line
+## bonus: keeping those tasks DRY
+
+---
+
+`gulpfile.js`
+
+```js
+// npm install gulp gulp-util gulp-if gulp-uglify 
+var gulp   = require('gulp');
+var gutil  = require('gulp-util');
+var gulpif = require('gulp-if');
+var uglify = require('gulp-uglify');
+
+var isProduction = gutil.env.type === 'production';
+
+gulp.task('scripts', function () {
+  return gulp.src('**/*.js')
+    .pipe(gulpif(isProduction, uglify())) // only minify if production
+    .pipe(gulp.dest('dist'));
+});
+```
+
+---
+
+`cli`
+
+`gulp scripts --type production`
@@ -0,0 +1,16 @@
+# 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())
+        .pipe(sass())
+        .pipe(gulp.dest('./dist/'));
+});
+```
@@ -0,0 +1,34 @@
+# Running tasks in series
+
+By default, tasks run 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 need to do two things:
+
+- give it a hint to tell it when the task is done,
+- and give it a hint that a task depends on completion of another.
+
+For these examples, let's presume you have two tasks, "one" and "two" that you specifically want to run in this order:
+
+1. In task "one" you add a hint to tell it when the task is done.  Either take in a callback and call it when you're
+done or return a promise or stream that the engine should wait to resolve or end respectively.
+
+2. In task "two" you add a hint telling the engine that it depends on completion of the first task.
+
+So this example would look like this:
+
+```javascript
+var gulp = require('gulp');
+
+// takes in a callback so the engine knows when it'll be done
+gulp.task('one', function (cb) {
+    // do stuff -- async or otherwise
+    cb(err); // if err is not null and not undefined, the orchestration will stop, and 'two' will not run
+});
+
+// identifies a dependent task must be complete before this one begins
+gulp.task('two', ['one'], function () {
+    // task 'one' is done now
+});
+
+gulp.task('default', ['one', 'two']);
+// alternatively: gulp.task('default', ['two']);
+```
@@ -0,0 +1,37 @@
+# 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
+
+```bash
+gulp --cwd ./layer1/
+```
+
+Another option is to use `process.chdir` which is just vanilla node.
+
+`gulpfile.js`
+
+```js
+var gulp = require('gulp');
+
+try {
+  process.chdir(gulp.env.cwd);
+} catch (err) {
+  console.error('Unable to chdir to %s', gulp.env.cwd);
+}
+```
+
+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/wearefractal/glob-stream)
+
+```js
+gulp.src('./some/dir/**/*.js', { cwd: './public' });
+```
@@ -0,0 +1,23 @@
+# Using coffee-script for gulpfile
+
+As discussed in [issue #103](https://github.com/gulpjs/gulp/issues/103), there are 2 ways to do this.
+
+1. Use `gulp --require coffee-script/register` at the command line
+
+2. Require in `gulpfile.coffee` after requiring `coffee-script` in `gulpfile.js`
+
+`gulpfile.js`
+
+```js
+require('coffee-script/register');
+require('./gulpfile.coffee');
+```
+
+`gulpfile.coffee`
+
+```coffeescript
+gulp = require 'gulp'
+
+gulp.task 'default', ->
+  console.log('default task called')
+```
@@ -0,0 +1,49 @@
+# Using external config file
+## bonus: keeping those tasks DRY
+## bonus2: 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 gulp gulp-uglify
+var gulp   = require('gulp');
+var uglify = require('gulp-uglify');
+var config = require('./config.json');
+
+function doStuff(cfg) {
+  return gulp.src(cfg.src)
+    .pipe(uglify())
+    .pipe(gulp.dest(cfg.dest));
+}
+
+gulp.task('dry', function () {
+  doStuff(config.desktop);
+  doStuff(config.mobile);
+});
+```
+
@@ -0,0 +1,17 @@
+# Using multiple sources in one task
+
+```js
+// npm install gulp event-stream
+
+var gulp = require('gulp');
+var es = require('event-stream');
+
+gulp.task('test', function(cb) {
+    return es.concat(
+        gulp.src('bootstrap/js/*.js')
+            .pipe(gulp.dest('public/bootstrap')),
+        gulp.src('jquery.cookie/jquery.cookie.js')
+            .pipe(gulp.dest('public/jquery'))
+    );
+});
+```