rsync.rb in nanoc3-3.1.0a1

- old
+ new

@@ -3,12 +3,58 @@
 module Nanoc3::Extra::Deployers
 
   # Nanoc3::Extra::Deployers::Rsync is a deployer that deploys a site using rsync.
   class Rsync
 
-    # Creates a new deployment task that uses rsync. The deployment
-    # configuration will be taken from the site's configuration file.
+    DEFAULT_OPTIONS = [
+      '-glpPrtvz',
+      '--exclude=".hg"',
+      '--exclude=".svn"',
+      '--exclude=".git"'
+    ]
+
+    # Creates a new deployer that uses rsync. The deployment configurations
+    # will be read from the configuration file of the site (which is assumed
+    # to be the current working directory).
+    #
+    # The deployment configurations are stored like this in the site's
+    # configuration file:
+    #
+    #     deploy:
+    #       NAME:
+    #         options: [ OPTIONS ]
+    #         dst:     "DST"
+    #
+    # +NAME+ is a unique name for the deployment configuration. By default,
+    # the deployer will use the deployment configuration named "default".
+    #
+    # +OPTIONS+ is an array containing options to pass to the rsync
+    # executable. This is not required; by default, +-glpPrtvz+ and
+    # +--exclude+s for +.svn+, +.hg+ and +.git+ are used.
+    #
+    # +DST+ is a string containing the destination to where rsync should
+    # upload its data. It will likely be in +host:path+ format. For example,
+    # "example.com:/var/www/sites/mysite/html". It should not end with a
+    # trailing slash.
+    #
+    # Example: This deployment configuration defines a "default" and a
+    # "staging" deployment configuration. The default options are used.
+    #
+    #     deploy:
+    #       default:
+    #         dst: "ectype:sites/stoneship/public"
+    #       staging:
+    #         dst: "ectype:sites/stoneship-staging/public"
+    #         options: [ "-glpPrtvz" ]
+    #
+    # When running the deployer with the "default" resp. "staging"
+    # configurations, the following rsync commands will be executed:
+    #
+    #     rsync -glpPrtvz --exclude=".hg" --exclude=".svn"
+    #       --exclude=".git" output ectype:sites/stoneship/public
+    #
+    #     rsync -glpPrtvz output ectype:sites/stoneship-staging/public
     def initialize
       # Get site
       error 'No site configuration found' unless File.file?('config.yaml')
       @site = Nanoc3::Site.new('.')
     end
@@ -30,10 +76,10 @@
       error "No deploy configuration found for #{config_name}" if @site.config[:deploy][config_name].nil?
 
       # Set arguments
       src = File.expand_path(@site.config[:output_dir]) + '/'
       dst = @site.config[:deploy][config_name][:dst]
-      options = @site.config[:deploy][config_name][:options] || []
+      options = @site.config[:deploy][config_name][:options] || DEFAULT_OPTIONS
 
       # Validate arguments
       error 'No dst found in deployment configuration' if dst.nil?
       error 'dst requires no trailing slash' if dst[-1,1] == '/'
 