Namespace

Definition
namespace(name, &block)
Module
Capistrano::Configuration::Namespaces
File
capistrano/configuration/namespaces.rb

Namespaces are the tool Capistrano provides for recipe authors to differentiate their tasks from other tasks with the same name. When you write tasks for yourself, you can control their names and rename them easily, but if you are writing a library of tasks that will be distributed to other users, you need to be more careful. In that case, you could create a namespace and put your tasks in there, so that your library's users could define tasks with the same names, and not worry about conflicts.

Namespaces may be nested to arbitrary depths. In this case, a namespace's fully qualified name includes the name of all parent namespaces. For example: 

namespace :deploy do
  namespace :web do
    task :enable, :roles => :web do
      # ...
    end
  end
end

In this case, the outer namespace's fully qualified name is simply :deploy, but the inner namespace, :web, has a fully qualified name of "deploy:web".

When you reference namespaces (and tasks) by name, you'll typically use the fully qualified name as a string. However, when you are executing a task within a namespace, the namespaces and tasks are treated as Ruby methods, so you delimit them with periods, not colons.

Continuing the above example: 

# extend the enable task with another task, using the after method
after "deploy:web:enable", "enable_email"
# invoke deploy:web:enable directly from within another task
task :enable_everything do
  deploy.web.enable
end

Arguments

name

This should be a symbol, identifying the namespace. It must be unique, not shadowing any existing tasks or methods. On the other hand, you can reopen an existing namespace, simply by using the namespace method with an existing namespace name: 

# create the namespace and add a task...
namespace :demo do
  task :first do
    # ...
  end
end
# then, later, reopen the namespace and add another task...
namespace :demo do
  task :second do
    # ...
  end
end

The :demo namespace, in the above example, would contain both the :first and :second tasks.

&block

A block must be given; it defines the contents of the namespace. Within the body of the namespace, you'll declare other namespaces (namespace) or tasks (task).

See Also