Skip to content
Deploy with Rsync from any local (or remote) repository when using Capistrano. Capistrano v3 ready!
Branch: master
Clone or download
Pull request Compare This branch is 16 commits ahead of seantanly:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Capistrano::Rsync for Capistrano v3

Gem Version

Deploy with Rsync to your server from any local (or remote) repository when using Capistrano. Saves you from having to install Git on your production machine and allows you to customize which files you want to deploy. Also allows you to easily precompile things on your local machine before deploying.


  • Works with Capistrano v3 (source code) versions >= 3.0.0pre14 and < 4.
  • Suitable for deploying any apps, be it Ruby, Rails, Node.js or others.
  • Exclude files from being deployed with Rsync's --exclude options.
  • Precompile files or assets easily before deploying, like JavaScript or CSS.
  • Caches your previously deployed code to speed up deployments ~1337%.
  • Works with git and svn.

Using Mina instead of Capistrano? I've (actuall not me, but Moll) built Mina::Rsync as well.


Install with:

gem install capistrano-rsync-local

Require it at the top of your Capfile (or config/deploy.rb):

require "capistrano/rsync"

Set some rsync_options to your liking:

set :rsync_options, %w[--recursive --delete --delete-excluded --exclude .git*]

And after setting regular Capistrano options, deploy as usual!

cap deploy


  1. Clones and updates your repository to rsync_stage (defaults to tmp/deploy) on your local machine.
  2. Checks out the branch set in the branch variable (defaults to master).
  3. If rsync_cache set (defaults to shared/deploy), rsyncs to that directory on the server.
  4. If rsync_cache set, copies the content of that directory to a new release directory.
  5. If rsync_cache is nil, rsyncs straight to a new release directory.

After that, Capistrano takes over and runs its usual tasks and symlinking.

Exclude files from being deployed

If you don't want to deploy everything you've committed to your repository, pass some --exclude options to Rsync:

set :rsync_options, %w[
  --recursive --delete --delete-excluded
  --exclude .git*
  --exclude .svn*
  --exclude /config/database.yml
  --exclude /test/***

Precompile assets before deploy

Capistrano::Rsync runs rsync:stage before rsyncing. Hook to that like this:

task :precompile do
  Dir.chdir fetch(:rsync_stage) do
    system "rake", "assets:precompile"

after "rsync:stage", "precompile"

Deploy release without symlinking the current directory

cap rsync:release


Set Capistrano variables with set name, value.

Name Default Description
rsync_scm git Available options: git, svn.
rsync_scm_username nil Used for Svn (Optional).
rsync_scm_password nil Used for Svn (Optional).
repo_url . The path or URL to a SCM repository to clone from.
branch master The Git branch to checkout. This is ignored for Svn.
rsync_stage tmp/deploy Path where to clone your repository for staging, checkouting and rsyncing. Can be both relative or absolute.
rsync_cache shared/deploy Path where to cache your repository on the server to avoid rsyncing from scratch each time. Can be both relative or absolute.
Set to nil if you want to disable the cache.
rsync_options [] Array of options to pass to rsync.
rsync_local_repo false The flag of the local repository, it disables any request to the scm
rsync_with_ext false Enables checking out an external project
repo_ext_url nil The URL of the external project. Required if rsync_with_ext is true.
rsync_ext_stage tmp/deploy_ext Path where to clone the external project.


Capistrano::Rsync is released under a Lesser GNU Affero General Public License, which in summary means:

  • You can use this program for no cost.
  • You can use this program for both personal and commercial reasons.
  • You do not have to share your own program's code which uses this program.
  • You have to share modifications (e.g bug-fixes) you've made to this program.

For more convoluted language, see the LICENSE file.

You can’t perform that action at this time.