maid 0.1.4.alpha.2 → 0.2.0.alpha.1

data/.gitignore

@@ -1,6 +1,7 @@
 *.gem
 .bundle
-.roboconf.sh
 .vagrant
+.yardoc/*
 Gemfile.lock
+tmp/*
 doc/*

data/ChangeLog

@@ -1,7 +1,21 @@
-maid (0.1.4.alpha.1) unstable; urgency=low
+maid (0.2.0.alpha.1) unstable; urgency=low
 
-  * Noted license in gemspec for RubyGems.org (Closes: #61)
-  * Minor development-only changes for CONTRIBUTING and ChangeLog
+  * Started semver.org-like version numbering.  Total adoption is
+    forthcoming.  This forced v0.2.0 vs. v0.1.4.
+  * Changed "dir" tool to always sort. (Closes: #62)
+  * Added "version --long" command which gives information about the platform
+    version and Ruby version. (Closes: #65)
+  * Improved user documentation, now in Markdown.  (Closes: #66)
+  * Updated development dependencies.
+  * Various minor internal changes.
+
+ -- Benjamin Oakes <hello@benjaminoakes.com>  Mon, 26 Nov 2012 14:51:13 +0000
+
+maid (0.1.4.alpha.2) unstable; urgency=low
+
+  * Noted license in gemspec.  Was incorrect value in alpha.1. Made an early
+    alpha release to test effect on RubyGems.org listing. (Closes: #61)
+  * Minor development-only documentation changes.
 
  -- Benjamin Oakes <hello@benjaminoakes.com>  Sat, 24 Nov 2012 00:00:00 +0000
 

data/Gemfile

@@ -1,4 +1,4 @@
-source "http://rubygems.org"
+source 'http://rubygems.org'
 
 # Specify your gem's dependencies in maid.gemspec
 gemspec

data/Guardfile

@@ -3,6 +3,6 @@
 
 guard 'rspec' do
   watch(%r{^spec/.+_spec\.rb$})
-  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
-  watch('spec/spec_helper.rb')  { "spec" }
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{ m[1] }_spec.rb" }
+  watch('spec/spec_helper.rb')  { 'spec' }
 end

data/README.md

@@ -2,7 +2,7 @@
 
 Be lazy!  Let Maid clean up after you, based on rules you define.
 
-[Installation](https://github.com/benjaminoakes/maid#installation) | [Tutorial](https://github.com/benjaminoakes/maid#tutorial) | [Documentation](http://rubydoc.info/gems/maid/Maid/Tools)
+[Installation](https://github.com/benjaminoakes/maid#installation) | [Tutorial](https://github.com/benjaminoakes/maid#tutorial) | [Documentation](http://rubydoc.info/gems/maid/Maid/Tools) | [Change Log](https://github.com/benjaminoakes/maid/blob/master/ChangeLog)
 
 Maid keeps files from sitting around too long, untouched.  Many of the downloads and other files you collect can easily be categorized and handled appropriately by rules you define.  Let the maid in your computer take care of the easy stuff, so you can spend more of your time on what matters.
 

data/Rakefile

@@ -1,6 +1,7 @@
+require 'bundler'
 require 'rake'
 require 'rspec/core/rake_task'
-require 'bundler'
+require 'yard'
 
 task :default => :spec
 
@@ -8,6 +9,15 @@ Bundler::GemHelper.install_tasks
 
 RSpec::Core::RakeTask.new(:spec)
 
+YARD::Rake::YardocTask.new do |t|
+  t.files = %w(
+    lib/maid/app.rb
+    lib/maid/tools.rb
+    lib/maid/numeric_extensions.rb
+  )
+  t.options = %w(--no-private --markup markdown)
+end
+
 task :console do
-  sh 'irb -I lib -r maid'
+  sh('irb -I lib -r maid')
 end

data/lib/maid.rb

@@ -1,16 +1,20 @@
 require 'deprecated'
 Deprecated.set_action(:warn)
 
-module Maid
-  autoload :App, 'maid/app'
-  autoload :Maid, 'maid/maid'
-  autoload :Tools, 'maid/tools'
-  autoload :NumericExtensions, 'maid/numeric_extensions'
-  autoload :Platform, 'maid/platform'
-  autoload :Rule, 'maid/rule'
-  autoload :TrashMigration, 'maid/trash_migration'
-  autoload :VERSION, 'maid/version'
+# Must be in this order:
+require 'maid/version'
+require 'maid/tools'
+require 'maid/maid'
+
+# Alphabetical:
+require 'maid/app'
+require 'maid/numeric_extensions'
+require 'maid/platform'
+require 'maid/rule'
+require 'maid/trash_migration'
+require 'maid/user_agent'
 
+module Maid
   class << self
     # Execute the block with the Maid instance set to <tt>instance</tt>.
     def with_instance(instance)
@@ -31,5 +35,3 @@ class Numeric
   include Maid::NumericExtensions::Time
   include Maid::NumericExtensions::SizeToKb
 end
-
-# TODO Is there a no-conflict way of including the extensions?

data/lib/maid/app.rb

@@ -1,6 +1,5 @@
 require 'fileutils'
 
-require 'rubygems'
 require 'thor'
 
 class Maid::App < Thor
@@ -12,9 +11,9 @@ class Maid::App < Thor
   end
 
   desc 'clean', 'Clean based on rules'
-  method_option :rules,  :type => :string,  :aliases => %w[-r]
-  method_option :noop,   :type => :boolean, :aliases => %w[-n --dry-run]
-  method_option :silent, :type => :boolean, :aliases => %w[-s]
+  method_option :rules,  :type => :string,  :aliases => %w(-r)
+  method_option :noop,   :type => :boolean, :aliases => %w(-n --dry-run)
+  method_option :silent, :type => :boolean, :aliases => %w(-s)
   def clean
     maid = Maid::Maid.new(maid_options(options))
 
@@ -24,26 +23,31 @@ class Maid::App < Thor
     end
 
     unless options.silent? || options.noop?
-      say "Logging actions to #{maid.log_device.inspect}"
+      say "Logging actions to #{ maid.log_device.inspect }"
     end
 
     maid.load_rules
     maid.clean
   end
 
-  desc 'version', 'Print version number'
+  desc 'version', 'Print version information (optionally: system info)'
+  method_option :long, :type => :boolean, :aliases => %w(-l)
   def version
-    say Maid::VERSION
+    if options.long?
+      say Maid::UserAgent.value
+    else
+      say Maid::VERSION
+    end
   end
 
-  desc 'sample', "Create sample rules at #{self.sample_rules_path}"
+  desc 'sample', "Create sample rules at #{ self.sample_rules_path }"
   def sample
     path = self.class.sample_rules_path
 
     FileUtils.mkdir_p(File.dirname(path))
     File.open(path, 'w').puts(File.read(File.join(File.dirname(__FILE__), 'rules.sample.rb')))
 
-    say "Sample rules created at #{path.inspect}", :green
+    say "Sample rules created at #{ path.inspect }", :green
   end
 
   no_tasks do
@@ -52,12 +56,12 @@ class Maid::App < Thor
 
       if options['noop']
         # You're testing, so a simple log goes to STDOUT and no actions are taken
-        h[:file_options] = {:noop => true}
+        h[:file_options] = { :noop => true }
 
         unless options['silent']
           h[:logger] = false
           h[:log_device] = STDOUT
-          h[:log_formatter] = lambda { |_, _, _, msg| "#{msg}\n" }
+          h[:log_formatter] = lambda { |_, _, _, msg| "#{ msg }\n" }
         end
       end
 

data/lib/maid/maid.rb

@@ -9,7 +9,7 @@ class Maid::Maid
     :progname     => 'Maid',
     :log_device   => File.expand_path('~/.maid/maid.log'),
     :rules_path   => File.expand_path('~/.maid/rules.rb'),
-    :file_options => {:noop => false}, # for FileUtils
+    :file_options => { :noop => false }, # for `FileUtils`
   }.freeze
 
   attr_reader :file_options, :logger, :log_device, :rules, :rules_path, :trash_path
@@ -19,7 +19,7 @@ class Maid::Maid
   # 
   # Sane defaults for a log and trash path are set for Mac OS X, but they can easily be overridden like so:
   # 
-  #   Maid::Maid.new(:log_device => '/home/username/log/maid.log', :trash_path => '/home/username/.local/share/Trash/files/')
+  #     Maid::Maid.new(:log_device => '/home/username/log/maid.log', :trash_path => '/home/username/my_trash')
   # 
   def initialize(options = {})
     options = DEFAULTS.merge(options.reject { |k, v| v.nil? })
@@ -50,7 +50,7 @@ class Maid::Maid
   # Start cleaning, based on the rules defined at rules_path.
   def clean
     unless @log_device.kind_of?(IO)
-      @logger.info "v#{Maid::VERSION}"
+      @logger.info "v#{ Maid::VERSION }"
       @logger.info 'Started'
     end
 
@@ -66,8 +66,9 @@ class Maid::Maid
     path = @rules_path
 
     Maid.with_instance(self) do
-      # Using 'Kernel' here to help with testability
-      # Kernel.load must be used for non-".rb" files to be required, it seems.
+      # Using `Kernel` here to help with testability.
+      #
+      # `Kernel.load` must be used for non-".rb" files to be required, it seems.
       Kernel.load(path)
     end
   rescue LoadError => e
@@ -82,23 +83,23 @@ class Maid::Maid
   # Follow all registered rules.
   def follow_rules
     @rules.each do |rule|
-      @logger.info("Rule: #{rule.description}")
+      @logger.info("Rule: #{ rule.description }")
       rule.follow
     end
   end
 
   # Run a shell command.
   #--
-  # Delegates to Kernel.`.  Made primarily for testing other commands and some error handling.
+  # Delegates to `Kernel.\``.  Made primarily for testing other commands and some error handling.
   def cmd(command) #:nodoc:
     if supported_command?(command)
-      %x(#{command})
+      %x(#{ command })
     else
-      raise ArgumentError, "Unsupported system command: #{command.inspect}"
+      raise ArgumentError, "Unsupported system command: #{ command.inspect }"
     end
   end
 
-private
+  private
 
   # Does the OS support this command?
   def supported_command?(command) #:nodoc:
@@ -106,7 +107,10 @@ private
 
     command_name = command.strip.split(/\s+/)[0]
     supported = @@supported_commands[command_name]
-    @@supported_commands[command_name] = supported ? supported : !%x(which #{command_name}).empty?
+    # TODO: Instead of using `which`, use an alternative listed at:
+    #
+    #     http://stackoverflow.com/questions/592620/check-if-a-program-exists-from-a-bash-script
+    @@supported_commands[command_name] = supported ? supported : !%x(which #{ command_name }).empty?
   end
 
   def default_trash_path

data/lib/maid/tools.rb

@@ -2,59 +2,70 @@ require 'fileutils'
 require 'find'
 require 'time'
 
-# Collection of utility methods included in Maid::Maid (and thus available in the rules DSL).
+# These "tools" are methods available in the Maid DSL.
 #
-# In general, all paths are automatically expanded (e.g. '~/Downloads/foo.zip' becomes '/home/username/Downloads/foo.zip').
+# In general, methods are expected to:
 #
-# Some methods are not available on all platforms.  An <tt>ArgumentError</tt> is raised when a command is not available.  See tags: [Mac OS X]
+# * Automatically expand paths (that is, `'~/Downloads/foo.zip'` becomes `'/home/username/Downloads/foo.zip'`)
+# * Respect the `noop` (`dry-run`) option if it is set
+#
+# Some methods are not available on all platforms.  An `ArgumentError` is raised when a command is not available.  See tags such as: [Mac OS X]
 module Maid::Tools
   include Deprecated
 
-  # Move from <tt>from</tt> to <tt>to</tt>.
+  # Move from `sources` to `destination`
   #
   # The path is not moved if a file already exists at the destination with the same name.  A warning is logged instead.
   #
-  # This method delegates to FileUtils.  The instance-level <tt>file_options</tt> hash is passed to control the <tt>:noop</tt> option.
+  # ## Examples
+  #
+  # Single path:
   #
-  #   move('~/Downloads/foo.zip', '~/Archive/Software/Mac OS X/')
+  #     move('~/Downloads/foo.zip', '~/Archive/Software/Mac OS X/')
   # 
-  # This method can handle multiple from paths.
-  #
-  #   move(['~/Downloads/foo.zip', '~/Downloads/bar.zip'], '~/Archive/Software/Mac OS X/')
-  #   move(dir('~/Downloads/*.zip'), '~/Archive/Software/Mac OS X/')
-  def move(froms, to)
-    Array(froms).each do |from|
-      from = File.expand_path(from)
-      to = File.expand_path(to)
-      target = File.join(to, File.basename(from))
+  # Multiple paths:
+  #
+  #     move(['~/Downloads/foo.zip', '~/Downloads/bar.zip'], '~/Archive/Software/Mac OS X/')
+  #     move(dir('~/Downloads/*.zip'), '~/Archive/Software/Mac OS X/')
+  def move(sources, destination)
+    Array(sources).each do |source|
+      source = File.expand_path(source)
+      destination = File.expand_path(destination)
+      target = File.join(destination, File.basename(source))
 
       unless File.exist?(target)
-        @logger.info "mv #{from.inspect} #{to.inspect}"
-        FileUtils.mv(from, to, @file_options)
+        @logger.info("mv #{ source.inspect } #{ destination.inspect }")
+        FileUtils.mv(source, destination, @file_options)
       else
-        @logger.warn "skipping #{from.inspect} because #{target.inspect} already exists"
+        @logger.warn("skipping #{ source.inspect } because #{ target.inspect } already exists")
       end
     end
   end
 
-  # Move the given path to the trash (as set by <tt>trash_path</tt>).
+  # Move the given paths to the user's trash.
   #
-  # The path is moved if a file already exists in the trash with the same name.  However, the current date and time is appended to the filename.
+  # The path is still moved if a file already exists in the trash with the same name.  However, the current date and time is appended to the filename.
   # 
-  # Note: the OS native "restore" or "put back" functionality for trashed files is not currently supported.  However, they can be restored manually, and the Maid log can help assist with this.
+  # **Note:** the OS-native "restore" or "put back" functionality for trashed files is not currently supported.  (See [issue #63](https://github.com/benjaminoakes/maid/issues/63).)  However, they can be restored manually, and the Maid log can help assist with this.
   # 
-  # Options:
+  # ## Options
+  #
+  # `:remove_over => Fixnum` (e.g. `1.gigabyte`, `1024.megabytes`)
+  #
+  # Delete files over the given size rather than moving to the trash.
+  #
+  # See also `Maid::NumericExtensions::SizeToKb`
+  #
+  # ## Examples
   #
-  # - :remove_over => Fixnum (e.g. 1.gigabyte, 1024.megabytes)
-  #     Remove files over the given size rather than moving to the trash.
-  #     See also Maid::NumericExtensions::SizeToKb
+  # Single path:
   #
-  #   trash('~/Downloads/foo.zip')
+  #     trash('~/Downloads/foo.zip')
   # 
-  # This method can also handle multiple paths.
+  # Multiple paths:
   #
-  #   trash(['~/Downloads/foo.zip', '~/Downloads/bar.zip'])
-  #   trash(dir('~/Downloads/*.zip'))
+  #     trash(['~/Downloads/foo.zip', '~/Downloads/bar.zip'])
+  #     trash(dir('~/Downloads/*.zip'))
   def trash(paths, options = {})
     # ## Implementation Notes
     #
@@ -70,7 +81,7 @@ module Maid::Tools
       path = File.expand_path(path)
 
       target = File.join(@trash_path, File.basename(path))
-      safe_trash_path = File.join(@trash_path, "#{File.basename(path)} #{Time.now.strftime('%Y-%m-%d-%H-%M-%S')}")
+      safe_trash_path = File.join(@trash_path, "#{ File.basename(path) } #{ Time.now.strftime('%Y-%m-%d-%H-%M-%S') }")
 
       if options[:remove_over] &&
           File.exist?(path) &&
@@ -88,59 +99,79 @@ module Maid::Tools
     end
   end
 
-  # Remove the given path recursively.
+  # Delete the files at the given path recursively.
   # 
-  # Options:
+  # ## Options
+  #
+  # `:force => boolean`
+  #
+  # Force deletion (no error is raised if the file does not exist).
+  #
+  # `:secure => boolean`
+  #
+  # Infrequently needed. See [`FileUtils.remove_entry_secure`](http://www.ruby-doc.org/stdlib-1.9.3/libdoc/fileutils/rdoc/FileUtils.html#method-c-remove_entry_secure)
+  #
+  # ## Examples
   #
-  # - :force => boolean
-  # - :secure => boolean (See FileUtils.remove_entry_secure for further details)
+  # Single path:
   #
-  #   remove('~/Downloads/foo.zip')
+  #     remove('~/Downloads/foo.zip')
   #
-  # This method can handle multiple remove paths.
+  # Multiple path:
   #
-  #   remove(['~/Downloads/foo.zip', '~/Downloads/bar.zip'])
-  #   remove(dir('~/Downloads/*.zip'))
+  #     remove(['~/Downloads/foo.zip', '~/Downloads/bar.zip'])
+  #     remove(dir('~/Downloads/*.zip'))
   def remove(paths, options = {})
     Array(paths).each do |path|
       path = File.expand_path(path)
       options = @file_options.merge(options)
 
-      @logger.info "Removing #{path.inspect}"
-      FileUtils.rm_r(path,options)
+      @logger.info("Removing #{ path.inspect }")
+      FileUtils.rm_r(path, options)
     end
   end
 
   # Give all files matching the given glob.
   #
-  #   dir('~/Downloads/*.zip')
+  # The matches are sorted lexically to aid in readability when using `--dry-run`.
+  #
+  # ## Examples
+  #
+  #     dir('~/Downloads/*.zip')
   def dir(glob)
-    Dir[File.expand_path(glob)]
+    Dir[File.expand_path(glob)].sort
   end
 
-  # Creates a directory and all its parent directories.
+  # Creates a directory and all of its parent directories.
+  #
+  # ## Options
   #
-  # Options:
+  # `:mode`
   #
-  # - :mode,  the symbolic and absolute mode both can be used.
-  #           eg. 0700, 'u=wr,go=rr'
+  # The symbolic and absolute mode can both be used, for example: `0700`, `'u=wr,go=rr'`
   #
-  #   mkdir('~/Downloads/Music/Pink.Floyd/', :mode => 0644)
+  # ## Examples
+  #
+  #     mkdir('~/Downloads/Music/Pink.Floyd/', :mode => 0644)
   def mkdir(path, options = {})
     FileUtils.mkdir_p(File.expand_path(path), options)
   end
 
-  # Find matching files, akin to the Unix utility <tt>find</tt>.
+  # Find matching files, akin to the Unix utility `find`.
+  #
+  # If no block is given, it will return an array.  Otherwise, it acts like `Find.find`.
   #
-  # If no block is given, it will return an array.
+  # ## Examples
   #
-  #   find '~/Downloads/' # => [...]
+  # Without a block:
   #
-  # or delegates to Find.find.
+  #     find('~/Downloads/') # => [...]
   #
-  #   find '~/Downloads/' do |path|
-  #     # ...
-  #   end
+  # Recursing with a block:
+  #
+  #     find('~/Downloads/') do |path|
+  #       # ...
+  #     end
   #
   def find(path, &block)
     expanded_path = File.expand_path(path)
@@ -156,84 +187,115 @@ module Maid::Tools
 
   # [Mac OS X] Use Spotlight to locate all files matching the given filename.
   #
-  #   locate('foo.zip') # => ['/a/foo.zip', '/b/foo.zip']
-  #--
-  # TODO use `locate` elsewhere -- it isn't available by default on OS X starting with OS X Leopard.
+  # [Ubuntu] Not currently supported.  See [issue #67](https://github.com/benjaminoakes/maid/issues/67).
+  #
+  # ## Examples
+  #
+  #     locate('foo.zip') # => ['/a/foo.zip', '/b/foo.zip']
   def locate(name)
-    cmd("mdfind -name #{name.inspect}").split("\n")
+    cmd("mdfind -name #{ name.inspect }").split("\n")
   end
 
   # [Mac OS X] Use Spotlight metadata to determine the site from which a file was downloaded.
   #
-  #   downloaded_from('foo.zip') # => ['http://www.site.com/foo.zip', 'http://www.site.com/']
+  # ## Examples
+  #
+  #     downloaded_from('foo.zip') # => ['http://www.site.com/foo.zip', 'http://www.site.com/']
   def downloaded_from(path)
-    raw = cmd("mdls -raw -name kMDItemWhereFroms #{path.inspect}")
+    raw = cmd("mdls -raw -name kMDItemWhereFroms #{ path.inspect }")
     clean = raw[1, raw.length - 2]
     clean.split(/,\s+/).map { |s| t = s.strip; t[1, t.length - 2] }
   end
 
   # [Mac OS X] Use Spotlight metadata to determine audio length.
   #
-  #   duration_s('foo.mp3') # => 235.705
+  # ## Examples
+  #
+  #     duration_s('foo.mp3') # => 235.705
   def duration_s(path)
-    cmd("mdls -raw -name kMDItemDurationSeconds #{path.inspect}").to_f
+    cmd("mdls -raw -name kMDItemDurationSeconds #{ path.inspect }").to_f
   end
 
-  # Inspect the contents of a .zip file.
+  # List the contents of a zip file.
   #
-  #   zipfile_contents('foo.zip') # => ['foo/foo.exe', 'foo/README.txt']
+  # ## Examples
+  #
+  #     zipfile_contents('foo.zip') # => ['foo/foo.exe', 'foo/README.txt']
   def zipfile_contents(path)
-    raw = cmd("unzip -Z1 #{path.inspect}")
+    raw = cmd("unzip -Z1 #{ path.inspect }")
     raw.split("\n")
   end
 
-  # Calculate disk usage of a given path.
+  # Calculate disk usage of a given path in kilobytes.
+  #
+  # See also: `Maid::NumericExtensions::SizeToKb`.
   #
-  # FIXME: This reports in kilobytes, but should probably report in bytes.
+  # ## Examples
   #
-  #   disk_usage('foo.zip') # => 136
+  #     disk_usage('foo.zip') # => 136
   def disk_usage(path)
-    raw = cmd("du -s #{path.inspect}")
+    raw = cmd("du -s #{ path.inspect }")
+    # FIXME: This reports in kilobytes, but should probably report in bytes.
     usage_kb = raw.split(/\s+/).first.to_i
    
     if usage_kb.zero?
-      raise "Stopping pessimistically because of unexpected value from du (#{raw.inspect})"
+      raise "Stopping pessimistically because of unexpected value from du (#{ raw.inspect })"
     else
       usage_kb
     end
   end
 
-  # In Unix speak, "ctime".
+  # Get the creation time of a file.
+  #
+  # In Unix speak, `ctime`.
   #
-  #   created_at('foo.zip') # => Sat Apr 09 10:50:01 -0400 2011
+  # ## Examples
+  #
+  #     created_at('foo.zip') # => Sat Apr 09 10:50:01 -0400 2011
   def created_at(path)
     File.ctime(File.expand_path(path))
   end
 
-  # In Unix speak, "atime".
+  # Get the time that a file was last accessed.
+  #
+  # In Unix speak, `atime`.
+  #
+  # ## Examples
   #
-  #   accessed_at('foo.zip') # => Sat Apr 09 10:50:01 -0400 2011
+  #     accessed_at('foo.zip') # => Sat Apr 09 10:50:01 -0400 2011
   def accessed_at(path)
     File.atime(File.expand_path(path))
   end
 
-  alias :last_accessed :accessed_at
+  # @deprecated
+  #
+  # Alias of `accessed_at`.
+  def last_accessed(path)
+    # Not a normal `alias` so the deprecation notice shows in the docs.
+    accessed_at(path)
+  end
   deprecated :last_accessed, :accessed_at
 
-  # In Unix speak, "mtime".
+  # Get the modification time of a file.
+  #
+  # In Unix speak, `mtime`.
+  #
+  # ## Examples
   #
-  #   modified_at('foo.zip') # => Sat Apr 09 10:50:01 -0400 2011
+  #     modified_at('foo.zip') # => Sat Apr 09 10:50:01 -0400 2011
   def modified_at(path)
     File.mtime(File.expand_path(path))
   end
 
-  # Pulls and pushes the given git repository.
+  # @deprecated
   #
-  # Since this is deprecated, you might also be interested in SparkleShare (http://sparkleshare.org/), a great git-based file syncronization project.
+  # Pulls and pushes the `git` repository at the given path.
   #
-  #   git_piston('~/code/projectname')
+  # Since this is deprecated, you might also be interested in [SparkleShare](http://sparkleshare.org/), a great `git`-based file syncronization project.
   #
-  # @deprecated
+  # ## Examples
+  #
+  #     git_piston('~/code/projectname')
   def git_piston(path)
     full_path = File.expand_path(path)
     stdout = cmd("cd #{full_path.inspect} && git pull && git push 2>&1")
@@ -242,20 +304,34 @@ module Maid::Tools
 
   deprecated :git_piston, 'SparkleShare (http://sparkleshare.org/)'
 
-  # [Rsync] Simple sync of two files/folders using rsync.
+  # Simple sync of two files/folders using `rsync`.
   #
-  # See rsync man page for a detailed description.
+  # The host OS must provide `rsync`.  See the `rsync` man page for a detailed description.
+  #
+  #     man rsync
   # 
-  # Options:
+  # ## Options
+  #
+  # `:delete      => boolean`
+  # `:verbose     => boolean`
+  # `:archive     => boolean` (default `true`)
+  # `:update      => boolean` (default `true`)
+  # `:exclude     => string`
+  # `:prune_empty => boolean`
+  #
+  # ## Examples
+  #
+  # Syncing a directory to a backup:
+  #
+  #     sync('~/music', '/backup/music')
+  #
+  # Excluding a path:
+  #
+  #     sync('~/code', '/backup/code', :exclude => '.git')
   #
-  # - :delete => boolean
-  # - :verbose => boolean
-  # - :archive => boolean (default true)
-  # - :update => boolean (default true)
-  # - :exclude => string EXE :exclude => ".git" or :exclude => [".git", ".rvmrc"]
-  # - :prune_empty => boolean
+  # Excluding multiple paths:
   #
-  #   sync('~/music', '/backup/music')
+  #     sync('~/code', '/backup/code', :exclude => ['.git', '.rvmrc'])
   def sync(from, to, options = {})
     # expand path removes trailing slash
     # cannot use str[-1] due to ruby 1.8.7 restriction
@@ -271,11 +347,11 @@ module Maid::Tools
     ops << '-n' if @file_options[:noop]
 
     Array(options[:exclude]).each do |path|
-      ops << "--exclude=#{path.inspect}"
+      ops << "--exclude=#{ path.inspect }"
     end
 
     ops << '--delete' if options[:delete]
-    stdout = cmd("rsync #{ops.join(' ')} #{from.inspect} #{to.inspect} 2>&1")
-    @logger.info "Fired sync from #{from.inspect} to #{to.inspect}.  STDOUT:\n\n#{stdout}"
+    stdout = cmd("rsync #{ ops.join(' ') } #{ from.inspect } #{ to.inspect } 2>&1")
+    @logger.info("Fired sync from #{ from.inspect } to #{ to.inspect }.  STDOUT:\n\n#{ stdout }")
   end
 end