capistrano 3.4.0 → 3.17.1

data/lib/capistrano/i18n.rb

@@ -1,37 +1,45 @@
-require 'i18n'
+require "i18n"
 
 en = {
-  starting:                    'Starting',
-  capified:                    'Capified',
-  start:                       'Start',
-  update:                      'Update',
-  finalize:                    'Finalise',
-  finishing:                   'Finishing',
-  finished:                    'Finished',
-  stage_not_set:               'Stage not set, please call something such as `cap production deploy`, where production is a stage you have defined.',
-  written_file:                'create %{file}',
-  question:                    'Please enter %{key} (%{default_value}): ',
-  keeping_releases:            'Keeping %{keep_releases} of %{releases} deployed releases on %{host}',
-  no_old_releases:             'No old releases (keeping newest %{keep_releases}) on %{host}',
-  linked_file_does_not_exist:  'linked file %{file} does not exist on %{host}',
-  cannot_rollback:             'There are no older releases to rollback to',
-  mirror_exists:               'The repository mirror is at %{at}',
-  revision_log_message:        'Branch %{branch} (at %{sha}) deployed as release %{release} by %{user}',
-  rollback_log_message:        '%{user} rolled back to release %{release}',
-  deploy_failed:               'The deploy has failed with an error: %{ex}',
+  starting: "Starting",
+  capified: "Capified",
+  start: "Start",
+  update: "Update",
+  finalize: "Finalise",
+  finishing: "Finishing",
+  finished: "Finished",
+  stage_not_set: "Stage not set, please call something such as `cap production deploy`, where production is a stage you have defined.",
+  written_file: "create %{file}",
+  question: "Please enter %{key}: ",
+  question_default: "Please enter %{key} (%{default_value}): ",
+  question_prompt: "%{key}: ",
+  question_prompt_default: "%{key} (%{default_value}): ",
+  keeping_releases: "Keeping %{keep_releases} of %{releases} deployed releases on %{host}",
+  skip_cleanup: "Skipping cleanup of invalid releases on %{host}; unexpected foldername found (should be timestamp)",
+  wont_delete_current_release: "Current release was marked for being removed but it's going to be skipped on %{host}",
+  no_current_release: "There is no current release present on %{host}",
+  no_old_releases: "No old releases (keeping newest %{keep_releases}) on %{host}",
+  linked_file_does_not_exist: "linked file %{file} does not exist on %{host}",
+  cannot_rollback: "There are no older releases to rollback to",
+  cannot_found_rollback_release: "Cannot rollback because release %{release} does not exist",
+  mirror_exists: "The repository mirror is at %{at}",
+  revision_log_message: "Branch %{branch} (at %{sha}) deployed as release %{release} by %{user}",
+  rollback_log_message: "%{user} rolled back to release %{release}",
+  deploy_failed: "The deploy has failed with an error: %{ex}",
   console: {
-    welcome:  'capistrano console - enter command to execute on %{stage}',
-    bye:      'bye'
+    welcome: "capistrano console - enter command to execute on %{stage}",
+    bye: "bye"
   },
   error: {
+    invalid_stage_name: '"%{name}" is a reserved word and cannot be used as a stage. Rename "%{path}" to something else.',
     user: {
-      does_not_exist:  'User %{user} does not exists',
-      cannot_switch:   'Cannot switch to user %{user}'
+      does_not_exist: "User %{user} does not exists",
+      cannot_switch: "Cannot switch to user %{user}"
     }
   }
 }
 
-I18n.backend.store_translations(:en, { capistrano: en })
+I18n.backend.store_translations(:en, capistrano: en)
 
 if I18n.respond_to?(:enforce_available_locales=)
   I18n.enforce_available_locales = true

data/lib/capistrano/immutable_task.rb

@@ -0,0 +1,30 @@
+module Capistrano
+  # This module extends a Rake::Task to freeze it to prevent it from being
+  # enhanced. This is used to prevent users from enhancing a task at the wrong
+  # point of Capistrano's boot process, which can happen if a Capistrano plugin
+  # is loaded in deploy.rb by mistake (instead of in the Capfile).
+  #
+  # Usage:
+  #
+  # task = Rake.application["load:defaults"]
+  # task.invoke
+  # task.extend(Capistrano::ImmutableTask) # prevent further modifications
+  #
+  module ImmutableTask
+    def self.extended(task)
+      task.freeze
+    end
+
+    def enhance(*args, &block)
+      $stderr.puts <<-MESSAGE
+ERROR: #{name} has already been invoked and can no longer be modified.
+Check that you haven't loaded a Capistrano plugin in deploy.rb or a stage
+(e.g. deploy/production.rb) by mistake.
+Plugins must be loaded in the Capfile to initialize properly.
+MESSAGE
+
+      # This will raise a frozen object error
+      super(*args, &block)
+    end
+  end
+end

data/lib/capistrano/install.rb

@@ -1 +1 @@
-load File.expand_path(File.join(File.dirname(__FILE__),'tasks/install.rake'))
+load File.expand_path(File.join(File.dirname(__FILE__), "tasks/install.rake"))

data/lib/capistrano/plugin.rb

@@ -0,0 +1,95 @@
+require "capistrano/all"
+require "rake/tasklib"
+
+# IMPORTANT: The Capistrano::Plugin system is not yet considered a stable,
+# public API, and is subject to change without notice. Eventually it will be
+# officially documented and supported, but for now, use it at your own risk.
+#
+# Base class for Capistrano plugins. Makes building a Capistrano plugin as easy
+# as writing a `Capistrano::Plugin` subclass and overriding any or all of its
+# three template methods:
+#
+# * set_defaults
+# * register_hooks
+# * define_tasks
+#
+# Within the plugin you can use any methods of the Rake or Capistrano DSLs, like
+# `fetch`, `invoke`, etc. In cases when you need to use SSHKit's backend outside
+# of an `on` block, use the `backend` convenience method. E.g. `backend.test`,
+# `backend.execute`, or `backend.capture`.
+#
+# Package up and distribute your plugin class as a gem and you're good to go!
+#
+# To use a plugin, all a user has to do is install it in the Capfile, like this:
+#
+#   # Capfile
+#   require "capistrano/superfancy"
+#   install_plugin Capistrano::Superfancy
+#
+# Or, to install the plugin without its hooks:
+#
+#   # Capfile
+#   require "capistrano/superfancy"
+#   install_plugin Capistrano::Superfancy, load_hooks: false
+#
+class Capistrano::Plugin < Rake::TaskLib
+  include Capistrano::DSL
+
+  # Implemented by subclasses to provide default values for settings needed by
+  # this plugin. Typically done using the `set_if_empty` Capistrano DSL method.
+  #
+  # Example:
+  #
+  #   def set_defaults
+  #     set_if_empty :my_plugin_option, true
+  #   end
+  #
+  def set_defaults; end
+
+  # Implemented by subclasses to hook into Capistrano's deployment flow using
+  # using the `before` and `after` DSL methods. Note that `register_hooks` will
+  # not be called if the user has opted-out of hooks when installing the plugin.
+  #
+  # Example:
+  #
+  #   def register_hooks
+  #     after "deploy:updated", "my_plugin:do_something"
+  #   end
+  #
+  def register_hooks; end
+
+  # Implemented by subclasses to define Rake tasks. Typically a plugin will call
+  # `eval_rakefile` to load Rake tasks from a separate .rake file.
+  #
+  # Example:
+  #
+  #   def define_tasks
+  #     eval_rakefile File.expand_path("../tasks.rake", __FILE__)
+  #   end
+  #
+  # For simple tasks, you can define them inline. No need for a separate file.
+  #
+  #   def define_tasks
+  #     desc "Do something fantastic."
+  #     task "my_plugin:fantastic" do
+  #       ...
+  #     end
+  #   end
+  #
+  def define_tasks; end
+
+  private
+
+  # Read and eval a .rake file in such a way that `self` within the .rake file
+  # refers to this plugin instance. This gives the tasks in the file access to
+  # helper methods defined by the plugin.
+  def eval_rakefile(path)
+    contents = IO.read(path)
+    instance_eval(contents, path, 1)
+  end
+
+  # Convenience to access the current SSHKit backend outside of an `on` block.
+  def backend
+    SSHKit::Backend.current
+  end
+end

data/lib/capistrano/proc_helpers.rb

@@ -0,0 +1,13 @@
+module Capistrano
+  module ProcHelpers
+    module_function
+
+    # Tests whether the given object appears to respond to `call` with
+    # zero parameters. In Capistrano, such a proc is used to represent a
+    # "deferred value". That is, a value that is resolved by invoking `call` at
+    # the time it is first needed.
+    def callable_without_parameters?(x)
+      x.respond_to?(:call) && (!x.respond_to?(:arity) || x.arity.zero?)
+    end
+  end
+end

data/lib/capistrano/scm/git.rb

@@ -0,0 +1,100 @@
+require "capistrano/scm/plugin"
+require "cgi"
+require "securerandom"
+require "shellwords"
+require "uri"
+
+class Capistrano::SCM::Git < Capistrano::SCM::Plugin
+  def set_defaults
+    set_if_empty :git_shallow_clone, false
+    set_if_empty :git_wrapper_path, lambda {
+      # Use a unique name that won't collide with other deployments, and
+      # that cannot be guessed by other processes that have access to /tmp.
+      "#{fetch(:tmp_dir)}/git-ssh-#{SecureRandom.hex(10)}.sh"
+    }
+    set_if_empty :git_environmental_variables, lambda {
+      {
+        git_askpass: "/bin/echo",
+        git_ssh: fetch(:git_wrapper_path)
+      }
+    }
+    set_if_empty :git_max_concurrent_connections, 10
+    set_if_empty :git_wait_interval, 0
+  end
+
+  def register_hooks
+    after "deploy:new_release_path", "git:create_release"
+    before "deploy:check", "git:check"
+    before "deploy:set_current_revision", "git:set_current_revision"
+  end
+
+  def define_tasks
+    eval_rakefile File.expand_path("../tasks/git.rake", __FILE__)
+  end
+
+  def repo_mirror_exists?
+    backend.test " [ -f #{repo_path}/HEAD ] "
+  end
+
+  def check_repo_is_reachable
+    git :'ls-remote', git_repo_url, "HEAD"
+  end
+
+  def clone_repo
+    if (depth = fetch(:git_shallow_clone))
+      git :clone, "--mirror", "--depth", depth, "--no-single-branch", git_repo_url, repo_path.to_s
+    else
+      git :clone, "--mirror", git_repo_url, repo_path.to_s
+    end
+  end
+
+  def update_mirror
+    # Update the origin URL if necessary.
+    git :remote, "set-url", "origin", git_repo_url
+
+    # Note: Requires git version 1.9 or greater
+    if (depth = fetch(:git_shallow_clone))
+      git :fetch, "--depth", depth, "origin", fetch(:branch)
+    else
+      git :remote, :update, "--prune"
+    end
+  end
+
+  def verify_commit
+    git :"verify-commit", fetch_revision
+  end
+
+  def archive_to_release_path
+    if (tree = fetch(:repo_tree))
+      tree = tree.slice %r#^/?(.*?)/?$#, 1
+      components = tree.split("/").size
+      git :archive, fetch(:branch), tree, "| #{SSHKit.config.command_map[:tar]} -x --strip-components #{components} -f - -C", release_path
+    else
+      git :archive, fetch(:branch), "| #{SSHKit.config.command_map[:tar]} -x -f - -C", release_path
+    end
+  end
+
+  def fetch_revision
+    backend.capture(:git, "rev-list --max-count=1 #{fetch(:branch)}")
+  end
+
+  def git(*args)
+    args.unshift :git
+    backend.execute(*args)
+  end
+
+  def git_repo_url
+    if fetch(:git_http_username) && fetch(:git_http_password)
+      URI.parse(repo_url).tap do |repo_uri|
+        repo_uri.user     = fetch(:git_http_username)
+        repo_uri.password = CGI.escape(fetch(:git_http_password))
+      end.to_s
+    elsif fetch(:git_http_username)
+      URI.parse(repo_url).tap do |repo_uri|
+        repo_uri.user = fetch(:git_http_username)
+      end.to_s
+    else
+      repo_url
+    end
+  end
+end

data/lib/capistrano/scm/hg.rb

@@ -0,0 +1,55 @@
+require "capistrano/scm/plugin"
+require "securerandom"
+
+class Capistrano::SCM::Hg < Capistrano::SCM::Plugin
+  def register_hooks
+    after "deploy:new_release_path", "hg:create_release"
+    before "deploy:check", "hg:check"
+    before "deploy:set_current_revision", "hg:set_current_revision"
+  end
+
+  def define_tasks
+    eval_rakefile File.expand_path("../tasks/hg.rake", __FILE__)
+  end
+
+  def hg(*args)
+    args.unshift(:hg)
+    backend.execute(*args)
+  end
+
+  def repo_mirror_exists?
+    backend.test " [ -d #{repo_path}/.hg ] "
+  end
+
+  def check_repo_is_reachable
+    hg "id", repo_url
+  end
+
+  def clone_repo
+    hg "clone", "--noupdate", repo_url, repo_path.to_s
+  end
+
+  def update_mirror
+    hg "pull"
+  end
+
+  def archive_to_release_path
+    if (tree = fetch(:repo_tree))
+      tree = tree.slice %r#^/?(.*?)/?$#, 1
+      components = tree.split("/").size
+      temp_tar = "#{fetch(:tmp_dir)}/#{SecureRandom.hex(10)}.tar"
+
+      hg "archive -p . -I", tree, "--rev", fetch(:branch), temp_tar
+
+      backend.execute :mkdir, "-p", release_path
+      backend.execute :tar, "-x --strip-components #{components} -f", temp_tar, "-C", release_path
+      backend.execute :rm, temp_tar
+    else
+      hg "archive", release_path, "--rev", fetch(:branch)
+    end
+  end
+
+  def fetch_revision
+    backend.capture(:hg, "log --rev #{fetch(:branch)} --template \"{node}\n\"")
+  end
+end

data/lib/capistrano/scm/plugin.rb

@@ -0,0 +1,13 @@
+require "capistrano/plugin"
+require "capistrano/scm"
+
+# Base class for all built-in and third-party SCM plugins. Notice that this
+# class doesn't really do anything other than provide an `scm?` predicate. This
+# tells Capistrano that the plugin provides SCM functionality. All other plugin
+# features are inherited from Capistrano::Plugin.
+#
+class Capistrano::SCM::Plugin < Capistrano::Plugin
+  def scm?
+    true
+  end
+end

data/lib/capistrano/scm/svn.rb

@@ -0,0 +1,56 @@
+require "capistrano/scm/plugin"
+
+class Capistrano::SCM::Svn < Capistrano::SCM::Plugin
+  def register_hooks
+    after "deploy:new_release_path", "svn:create_release"
+    before "deploy:check", "svn:check"
+    before "deploy:set_current_revision", "svn:set_current_revision"
+  end
+
+  def define_tasks
+    eval_rakefile File.expand_path("../tasks/svn.rake", __FILE__)
+  end
+
+  def svn(*args)
+    args.unshift(:svn)
+    args.push "--username #{fetch(:svn_username)}" if fetch(:svn_username)
+    args.push "--password #{fetch(:svn_password)}" if fetch(:svn_password)
+    args.push "--revision #{fetch(:svn_revision)}" if fetch(:svn_revision)
+    backend.execute(*args)
+  end
+
+  def repo_mirror_exists?
+    backend.test " [ -d #{repo_path}/.svn ] "
+  end
+
+  def check_repo_is_reachable
+    svn_username = fetch(:svn_username) ? "--username #{fetch(:svn_username)}" : ""
+    svn_password = fetch(:svn_password) ? "--password #{fetch(:svn_password)}" : ""
+    backend.test :svn, :info, repo_url, svn_username, svn_password
+  end
+
+  def clone_repo
+    svn :checkout, repo_url, repo_path.to_s
+  end
+
+  def update_mirror
+    # Switch the repository URL if necessary.
+    repo_mirror_url = fetch_repo_mirror_url
+    svn :switch, repo_url unless repo_mirror_url == repo_url
+    svn :update
+  end
+
+  def archive_to_release_path
+    svn :export, "--force", ".", release_path
+  end
+
+  def fetch_revision
+    backend.capture(:svnversion, repo_path.to_s)
+  end
+
+  def fetch_repo_mirror_url
+    backend.capture(:svn, :info, repo_path.to_s).each_line do |line|
+      return $1 if /\AURL: (.*)\n\z/ =~ line
+    end
+  end
+end

data/lib/capistrano/scm/tasks/git.rake

@@ -0,0 +1,73 @@
+# This trick lets us access the Git plugin within `on` blocks.
+git_plugin = self
+
+namespace :git do
+  desc "Upload the git wrapper script, this script guarantees that we can script git without getting an interactive prompt"
+  task :wrapper do
+    on release_roles(:all), in: :groups, limit: fetch(:git_max_concurrent_connections), wait: fetch(:git_wait_interval) do
+      execute :mkdir, "-p", File.dirname(fetch(:git_wrapper_path)).shellescape
+      upload! StringIO.new("#!/bin/sh -e\nexec /usr/bin/env ssh -o PasswordAuthentication=no -o StrictHostKeyChecking=no \"$@\"\n"), fetch(:git_wrapper_path)
+      execute :chmod, "700", fetch(:git_wrapper_path).shellescape
+    end
+  end
+
+  desc "Check that the repository is reachable"
+  task check: :'git:wrapper' do
+    fetch(:branch)
+    on release_roles(:all), in: :groups, limit: fetch(:git_max_concurrent_connections), wait: fetch(:git_wait_interval) do
+      with fetch(:git_environmental_variables) do
+        git_plugin.check_repo_is_reachable
+      end
+    end
+  end
+
+  desc "Clone the repo to the cache"
+  task clone: :'git:wrapper' do
+    on release_roles(:all), in: :groups, limit: fetch(:git_max_concurrent_connections), wait: fetch(:git_wait_interval) do
+      if git_plugin.repo_mirror_exists?
+        info t(:mirror_exists, at: repo_path)
+      else
+        within deploy_path do
+          with fetch(:git_environmental_variables) do
+            git_plugin.clone_repo
+          end
+        end
+      end
+    end
+  end
+
+  desc "Update the repo mirror to reflect the origin state"
+  task update: :'git:clone' do
+    on release_roles(:all), in: :groups, limit: fetch(:git_max_concurrent_connections), wait: fetch(:git_wait_interval) do
+      within repo_path do
+        with fetch(:git_environmental_variables) do
+          git_plugin.update_mirror
+          git_plugin.verify_commit if fetch(:git_verify_commit)
+        end
+      end
+    end
+  end
+
+  desc "Copy repo to releases"
+  task create_release: :'git:update' do
+    on release_roles(:all), in: :groups, limit: fetch(:git_max_concurrent_connections), wait: fetch(:git_wait_interval) do
+      with fetch(:git_environmental_variables) do
+        within repo_path do
+          execute :mkdir, "-p", release_path
+          git_plugin.archive_to_release_path
+        end
+      end
+    end
+  end
+
+  desc "Determine the revision that will be deployed"
+  task :set_current_revision do
+    on release_roles(:all), in: :groups, limit: fetch(:git_max_concurrent_connections), wait: fetch(:git_wait_interval) do
+      within repo_path do
+        with fetch(:git_environmental_variables) do
+          set :current_revision, git_plugin.fetch_revision
+        end
+      end
+    end
+  end
+end

data/lib/capistrano/scm/tasks/hg.rake

@@ -0,0 +1,53 @@
+# TODO: this is nearly identical to git.rake. DRY up?
+
+# This trick lets us access the Hg plugin within `on` blocks.
+hg_plugin = self
+
+namespace :hg do
+  desc "Check that the repo is reachable"
+  task :check do
+    on release_roles :all do
+      hg_plugin.check_repo_is_reachable
+    end
+  end
+
+  desc "Clone the repo to the cache"
+  task :clone do
+    on release_roles :all do
+      if hg_plugin.repo_mirror_exists?
+        info t(:mirror_exists, at: repo_path)
+      else
+        within deploy_path do
+          hg_plugin.clone_repo
+        end
+      end
+    end
+  end
+
+  desc "Pull changes from the remote repo"
+  task update: :'hg:clone' do
+    on release_roles :all do
+      within repo_path do
+        hg_plugin.update_mirror
+      end
+    end
+  end
+
+  desc "Copy repo to releases"
+  task create_release: :'hg:update' do
+    on release_roles :all do
+      within repo_path do
+        hg_plugin.archive_to_release_path
+      end
+    end
+  end
+
+  desc "Determine the revision that will be deployed"
+  task :set_current_revision do
+    on release_roles :all do
+      within repo_path do
+        set :current_revision, hg_plugin.fetch_revision
+      end
+    end
+  end
+end

data/lib/capistrano/scm/tasks/svn.rake

@@ -0,0 +1,53 @@
+# TODO: this is nearly identical to git.rake. DRY up?
+
+# This trick lets us access the Svn plugin within `on` blocks.
+svn_plugin = self
+
+namespace :svn do
+  desc "Check that the repo is reachable"
+  task :check do
+    on release_roles :all do
+      svn_plugin.check_repo_is_reachable
+    end
+  end
+
+  desc "Clone the repo to the cache"
+  task :clone do
+    on release_roles :all do
+      if svn_plugin.repo_mirror_exists?
+        info t(:mirror_exists, at: repo_path)
+      else
+        within deploy_path do
+          svn_plugin.clone_repo
+        end
+      end
+    end
+  end
+
+  desc "Pull changes from the remote repo"
+  task update: :'svn:clone' do
+    on release_roles :all do
+      within repo_path do
+        svn_plugin.update_mirror
+      end
+    end
+  end
+
+  desc "Copy repo to releases"
+  task create_release: :'svn:update' do
+    on release_roles :all do
+      within repo_path do
+        svn_plugin.archive_to_release_path
+      end
+    end
+  end
+
+  desc "Determine the revision that will be deployed"
+  task :set_current_revision do
+    on release_roles :all do
+      within repo_path do
+        set :current_revision, svn_plugin.fetch_revision
+      end
+    end
+  end
+end