Because gulp tasks are actually from another package, orchestrator, the gulp people don't feel the need to document how gulp tasks work very much. So...
Gulp tasks are asynchronous. Here are some patterns to use.
THIS IS ALMOST ALWAYS WRONG
Gulp calls the task function, which returns when it's done.
Even if everything your task is doing is synchronous, this is still wrong because Gulp is allowed to kick it off in the background and then immediately assume it's done and start running other tasks that depend on it, which might or might not work. A real bear to debug. But here's how it looks:
# DO NOT DO THIS:
gulp.task('sync_task', function() {
stuff that runs immediately;
})
Gulp passes a callback. The tasks calls it when done:
gulp.task('foo', function(cb) {
stuff...;
cb();
})
Gulp pipes, and lots of gulp plugins, return a promise or even stream. We can just return the thing they gave us, and gulp will use that to tell when the work is done:
gulp.task('make_promise', function() {
return some_gulp_plugin.pipe(stuff).pipe(more_stuff);
})
Call a task whenever any of a group of files changes:
gulp.watch('filepattern', ['task1', 'task2'])
After calling this, anytime a file that existed when this was called and matched the filepattern changes, task1 and task2 will be called.
This will result in the gulp command not exiting, because it's hanging around to watch for changes!
(But the watch() function itself does return, no worries there.)
TBD: What does gulp.watch return? Anything?