2.x-DSL-Configuration-Tasks-Top.md

Definition

top() 

Module

Capistrano::Configuration::Namespaces

When invoking tasks from within other tasks, or when referring to other namespaces, Capistrano will first look in the current namespace scope for anything matching the request. Only if it doesn't find anything will it look back up the namespace stack. This works just fine, most of the time. For example:

namespace :cache do
  task :warm_up do
    # ...
  end
end

namespace :deploy do
  task :default do
    update_code # calls the task in the same scope
    cache.warm_up # calls the task in the higher-level cache namespace
  end

  task :update_code do
    # ...
  end
end

However, when there is a task or namespace in the current scope with the same name as a task or namespace in other scope, it can make it difficult to access the one that is masked:

namespace :cache do
  task :warm_up do
    # ...
  end
end

namespace :deploy do
  namespace :cache do
    task :restart do
      # ...
    end
  end
  
  task :default do
    update_code # calls the task in the same scope
    cache.warm_up # tries to use the deploy:cache namespace, instead of the top-level cache namespace
  end
  
  task :update_code do
    # ...
  end
end

To force Capistrano to begin searching the scope at the top-level, you can use the top method.

task :default do
  update_code # calls the task in the same scope
  top.cache.warm_up # uses the top-level cache namespace
end