Gulp.js task, return on src?

I'm new to gulp and have been looking through example set-ups. Some people have the following structure:

gulp.task("XXXX", function() {
    gulp.src("....

Other people have this:

gulp.task("XXXX", function() {
   return gulp.src("....

I'm wondering what difference the return on the src makes??

You return to indicate that the task is async. gulp.src() returns a stream, so it's async.

Without it the task system wouldn't know when it finished. Read the docs.

If you have dependent tasks you need to return the stream for the tasks to wait on their dependent tasks to complete before running themselves.

eg

// without return
gulp.task('task1', function() {
    gulp.src('src/coffee/*.coffee')
      /* eg compile coffeescript here */
     .pipe(gulp.dest('src'));
});

gulp.task('task2', ['task1'], function() {
    gulp.src('src/*.js')
      /* eg minfify js here */
     .pipe(gulp.dest('dest'));
});

in that example you'd expect task1 to complete ( eg compiling the coffeescript or whatever ) before task2 runs ... but unless we add return – like the example below – then they will run synchronously not asynchronously; and the compiled coffeescript will not be minified because task2 will not have waited for task 1 to complete and so will not pick up on the compiled output of task1. So we should always return in these circumstances.

// with return
gulp.task('task1', function() {
    return gulp.src('**/*.coffee')
      /* your operations here */
     .pipe(gulp.dest('dest'));
});

gulp.task('task2', ['task1'], function() {
    return gulp.src('**/*.js')
      /* your operations here */
     .pipe(gulp.dest('dest'));
});

Edit: The recipe here explains it further. https://github.com/gulpjs/gulp/blob/master/docs/recipes/running-tasks-in-series.md

I found this helpful, if you have multiple streams per task. You need to combine/merge the multiple streams and return them.

var gulp = require('gulp');
var merge = require('gulp-merge');

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);
});

The alternative, using Gulps task definition structure, would be:

var gulp = require('gulp');

gulp.task('bootstrap', function() {
    return gulp.src('bootstrap/js/*.js')
        .pipe(gulp.dest('public/bootstrap'));
});

gulp.task('jquery', function() {
    return gulp.src('jquery.cookie/jquery.cookie.js')
        .pipe(gulp.dest('public/jquery'));
});

gulp.task('test', ['bootstrap', 'jquery']);