Task

Definition: task(name, options={}, &block)
Module: Capistrano::Configuration::Namespaces
File: capistrano/configuration/namespaces.rb

Tasks are the fundamental unit of work in Capistrano. With the task method, you can declare certain actions to be taken against some set of servers. You can also invoke other tasks.

Arguments

`name`

This should be a symbol naming the task. The name should include only letters, numbers, and the underscore character; using other characters in task names may make it difficult to invoke the task from other tasks.

`options`

When declaring a task, you can specify any of the options that run accepts. Additionally, you can specify:

:desc: A string describing the task. This is typically provided via the desc method, but sometimes it is more convenient to pass it as an option.
:on_error: This must be a symbol, or nil. If a symbol, it must be either :continue, or :abort. If nil, it defaults to :abort. If this value is :abort, then a command that fails within the task will cause Capistrano to abort processing at this task. If it is :continue, then a command that fails within the task will allow Capistrano to proceed, despite the failure.

Note that, of the additional options that run provides, typically you'll only use :roles, :only, or :except with task. However, you are free to use any of them if you need them.

`&block`

A block must be given; it defines the body of the task. Within the body of a task, you'll typically make use of run, transaction, on_rollback, and so forth. You can also invoke other tasks, either via find_and_execute_task, or by invoking the task directly, as if it were a method.

Examples

task :restart, :roles => [:web, :app] do
  parallel do |session|
    session.when "in?(:web)", "#{sudo} apachectl restart"
    session.when "in?(:app)", "#{sudo} restart_mongrel"
  end
end
task :deploy do
  transaction do
    update_code
    symlink
  end
  restart
end
task :backup_database, :roles => :db, :only => { :backup => true } do
  run "#{sudo} mysqldump ... > /tmp/backup.sql"
  run "#{sudo} bzip2 /tmp/backup.sql"
  run "scp /tmp/backup.sql.bz2 offsite.host:/u/backups"
  run "#{sudo} rm /tmp/backup.sql.bz2"
end

Caveats

Unlike Rake where task name collisions implicitly extend the original definition, Capistrano tasks replace existing tasks of the same name.

This can be worked-around by defining your task with a slightly different name, or in their own namespace; these tasks can then be appended to the original task by means of the before or after task callbacks.

Toolbox