documentation, prepping for publication to github

LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 by 37signals, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.rdoc

@@ -0,0 +1,48 @@
+= Fast Remote Cache
+
+The FastRemoteCache is a custom deployment strategy that specializes the standard RemoteCache strategy. It works just like the RemoteCache, but instead of actually copying the cache to the final release directory, it uses a custom "copy.rb" script to hard link the files. This allows the copy stage to be very fast.
+
+For small applications, and especially for those that aren't bundling vendor/rails, this won't make much of a difference. But for large applications the speed-up will be significant.
+
+== Dependencies
+
+* Capistrano 2 or later (http://www.capify.org)
+
+== Assumptions
+
+The FastRemoteCache, as the RemoteCache, assumes that your source repository is accessible from both your local (deploying) host, as well as the remote (target) hosts. If either of these is not true, you will not be able to use the FastRemoteCache strategy.
+
+Furthermore, it assumes that you have Ruby (1.8.6, preferably) installed on the target machines. If it is not installed in a standard location, you can set the :ruby variable to the location of the ruby executable.
+
+== Usage
+
+When using this with Rails applications, all you need to do is install this as a plugin in your application. Make sure your Capfile has a line like the following:
+
+  Dir['vendor/plugins/*/recipes/*.rb'].each { |plugin| load(plugin) }
+
+It should be just before the line that loads the 'config/deploy' file. If that line is not there, add it (or rerun "capify .").
+
+If you are not using this with a Rails application, you'll need to explicitly load recipes/fast_remote_cache.rb in your Capfile.
+
+Next, tell Capistrano to use the fast_remote_cache deployment strategy by putting the following line in your config/deploy.rb (or Capfile, if you aren't deploying a Rails app):
+
+  set :deploy_via, :fast_remote_cache
+
+Lastly, if you want to exclude certain directories or files from being deployed, set the copy_exclude variable:
+
+  set :copy_exclude, %w(test .git doc config/database.yml)
+
+The copy_exclude array can also include glob patterns, if you want to get tricky.
+
+== Tips
+
+For the fastest possible deploys:
+
+* Always deploy as the same user. If you're part of a team where everyone can (and does) deploy, create a new user (e.g., "deploy") and set it up so that your team can all log in as this user. Make sure this user also has read access to your source code repository.
+* Avoid sudo if at all possible. set(:use_sudo, false), and then make sure that the deploy user has sufficient permissions to start and stop the mongrels, write to the necessary directories, etc.
+* Disable the "group_writable" setting: set(:group_writable, false). This is only necessary when you have multiple users deploying.
+* Don't include Rails (or other large libraries) in your application. Yes, it is convenient to include them, but they bloat your app and make checkouts and copies much slower. You have to balance convenience in development versus speed of deployment. Find a compromise that works for you.
+
+== License
+
+This code is released under the MIT license, and is copyright (c) 2008 by 37signals, LLC. Please see the accompanying LICENSE file for the full text of the license.

lib/capistrano/recipes/deploy/strategy/fast_remote_cache.rb

@@ -1,3 +1,14 @@
+# ---------------------------------------------------------------------------
+# This implements a specialization of the standard Capistrano RemoteCache
+# deployment strategy. The most significant difference between this strategy
+# and the RemoteCache is the way the cache is copied to the final release
+# directory: it uses the bundled "copy.rb" script to use hard links to the
+# files instead of actually copying, so the copy stage is much, much faster.
+# ---------------------------------------------------------------------------
+# This file is distributed under the terms of the MIT license by 37signals,
+# LLC, and is copyright (c) 2008 by the same. See the LICENSE file distributed
+# with this file for the complete text of the license.
+# ---------------------------------------------------------------------------
 require 'capistrano/recipes/deploy/strategy/remote_cache'
 
 class Capistrano::Deploy::Strategy::FastRemoteCache < Capistrano::Deploy::Strategy::RemoteCache

lib/capistrano/recipes/deploy/strategy/utilities/copy.rb

@@ -1,7 +1,25 @@
+# ---------------------------------------------------------------------------
+# A simple copy script for doing hard links and symbolic links instead of
+# explicit copies. Some OS's will already have a utility to do this, but
+# some won't; this file suffices in either case.
+#
+# Usage: ruby copy.rb <source> <target> <exclude> ...
+#
+# The <source> directory is recursively descended, and hard links to all of
+# the files are created in corresponding locations under <target>. Symbolic
+# links in <source> map to symbolic links in <target> that point to the same
+# destination.
+#
+# All arguments after <target> are taken to be exclude patterns. Any file
+# or directory in <source> that matches any of those patterns will be
+# skipped, and will thus not be present in <target>.
+# ---------------------------------------------------------------------------
+# This file is distributed under the terms of the MIT license by 37signals,
+# LLC, and is copyright (c) 2008 by the same. See the LICENSE file distributed
+# with this file for the complete text of the license.
+# ---------------------------------------------------------------------------
 require 'fileutils'
 
-verbose = false
-
 from = ARGV.shift or abort "need source directory"
 to   = ARGV.shift or abort "need target directory"
 

recipes/fast_remote_cache.rb

@@ -1,3 +1,11 @@
+# ---------------------------------------------------------------------------
+# This is a recipe definition file for Capistrano. The tasks are documented
+# below.
+# ---------------------------------------------------------------------------
+# This file is distributed under the terms of the MIT license by 37signals,
+# LLC, and is copyright (c) 2008 by the same. See the LICENSE file distributed
+# with this file for the complete text of the license.
+# ---------------------------------------------------------------------------
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), "..", "lib"))
 
 namespace :fast_remote_cache do