= Capistrano 2.0 rsync_remote_cache Deployment Strategy

== Description

This gem provides a deployment strategy for Capistrano which combines the
<tt>rsync</tt> command with a remote cache, allowing fast deployments from SCM
repositories behind firewalls.

== Aim

The original gem is outdated. In this gem, I have merged all the pull requests
that were interesting, such as rsync in parallel, rsh parameters, etc.

== Original gem

For the original gem, visit: https://github.com/vigetlabs/capistrano_rsync_with_remote_cache

== Installation

    gem install capistrano-rsync-remote-cache

== Usage

To use this deployment strategy, add this line to your <tt>deploy.rb</tt> file:

    set :deploy_via, :rsync_remote_cache

If you want to enable the parallel deployment:

    set :rsync_in_parallel, true

If you want to tune the number of threads:

    set :rsync_concurrency, 8

By default, the deployments spawns 8 threads.

== Under the Hood

This strategy maintains two cache directories:

* The local cache directory is a checkout from the SCM repository. The local
  cache directory is specified with the <tt>:local_cache</tt> variable in the
  configuration. If not specified, it will default to <tt>.rsync_cache</tt>
  in the same directory as the Capfile.

* The remote cache directory is an <tt>rsync</tt> copy of the local cache directory.
  The remote cache directory is specified with the <tt>:repository_cache</tt> variable
  in the configuration (this name comes from the <tt>:remote_cache</tt> strategy that
  ships with Capistrano, and has been maintained for compatibility.) If not
  specified, it will default to <tt>shared/cached-copy</tt> (again, for compatibility
  with remote_cache.)

Deployment happens in three major steps. First, the local cache directory is
processed. There are three possibilities:

* If the local cache does not exist, it is created with a checkout of the
  revision to be deployed.
* If the local cache exists and matches the <tt>:repository</tt> variable, it is
  updated to the revision to be deployed.
* If the local cache exists and does not match the <p>:repository</p> variable,
  the local cache is purged and recreated with a checkout of the revision
  to be deployed.
* If the local cache exists but is not a directory, an exception is raised

Second, <tt>rsync</tt> runs on the local side to sync the remote cache to the local
cache. When the <tt>rsync</tt> is complete, the remote cache should be an exact
replica of the local cache.

Finally, a copy of the remote cache is made in the appropriate release
directory. The end result is the same as if the code had been checked out
directly on the remote server, as in the default strategy.