Skip to content

Latest commit

 

History

History
180 lines (120 loc) · 4.13 KB

tasks.md

File metadata and controls

180 lines (120 loc) · 4.13 KB
Raw

Tasks

Tasks are used for wrapping code that should be executed at a later point, either when specified by command line or explicitly run when using the API.

Creating tasks

Tasks are asynchronous functions that are registered by name using the .task method, and can be run using the .build method.

app.task('foo', function(cb) {
  // since tasks are asynchronous, you must call the callback when the task is complete
  cb();
});

Running tasks

Tasks can be run by command line or API.

Command line

Pass the names of the tasks to run after the update command.

Examples

Run task foo:

update foo

Run tasks foo, bar and baz:

update foo bar baz

Conflict resolution

You might notice that updaters can also be run from the command line using the same syntax. Update can usually determine whether you meant to call tasks or updaters. Visit the running updaters documentation for more information.

Task API

.task

Create a task:

app.task(name, fn);

Params

  • name {String}: name of the task to register
  • fn {Function}: asynchronous callback function, or es6 generator function

Example

app.task('default', function(cb) {
  // do task stuff (be sure to call the callback)
  cb();
});

Stream or callback

When using update's file system API (.src/.dest etc), you can optionally return a stream instead of calling a callback. Either a callback must be called, or a stream must be returned, otherwise update has no way of knowing when a task is complete.

.build

Run one or more tasks.

Params

  • names {String|Array|Function}: names of one or more tasks to run, or callback function if you only want to run the default task
  • callback: callback function, invoked after all tasks have finished executing. The callback function exposes err as the only argument, with any errors that occurred during the execution of any tasks.

Example

app.task('foo', function(cb) {
  // do task stuff
  cb();
});

app.task('bar', function(cb) {
  // do task stuff
  cb();
});

app.build(['foo', 'bar'], function(err) {
  if (err) return console.log(err);
  console.log('done');
});

.update

The .update method may also be used to run tasks. However, .update can be used to run tasks and updaters, thus it will also look for updaters to run when a task is not found.

To ensure that only tasks are run, use the .build method.

See the updaters documentation for more details.

Task composition

Task dependencies

When a task has "dependencies", this means that one or more other tasks need to finish before the task is executed.

Dependencies can be passed as the second argument to the .task method.

Example

In the following example, task foo has dependencies bar and baz:

app.task('foo', ['bar', 'baz'], function(cb) {
  // do task stuff
  cb();
});

Task foo will not execute until tasks bar and baz have completed.

Alias tasks

An "alias" task is a task with one or more dependencies and no callback.

Example

In this example, task foo is an alias for tasks bar and baz:

app.task('foo', ['bar', 'baz']);

In this example, task foo is an alias for task baz

app.task('foo', ['baz']);

default task

The default task is run automatically when a callback is passed as the only argument:

app.task('default', function(cb) {
  // do task stuff
  cb();
});

// no need to specify "default", but you can if you want
app.build(function(err) {
  if (err) return console.log(err);
  console.log('done');
});

Related

Docs