realityforge-piston 1.4.1

data/CHANGELOG

@@ -0,0 +1,81 @@
+1.4.1 (Pending)
+
+1.4.0 (2008-02-07)
+* New piston diff subcommand, implemented by Graeme Mathieson.
+  http://rubyforge.org/tracker/index.php?func=detail&aid=17116&group_id=2105&atid=8179
+* Per http://rubyforge.org/tracker/?func=detail&atid=8179&aid=10717&group_id=2105
+  Don't set LC_ALL, but set LANGUAGE so that repositories with foreign
+  characters can be used.  Thanks go to Per Wigren.
+
+1.3.3 (2007-03-22)
+* Repaired problems with import subcommand.  Wrote specifications to prevent
+  the same failure mode again.
+
+1.3.2 (2007-03-09)
+* piston switch had a bad constant access which caused failures.
+
+1.3.1 (2007-03-09)
+* piston switch would fail if the branch from which we are reading had been
+  deleted.
+* piston switch had a major bug.  It did not update the piston:root property
+  to remember the new repository root.  Reported and fixed by Graeme
+  Mathieson.
+* piston switch errors out early if not provided with the right arguments.
+  Thanks to Graeme Mathieson for the info and patch.
+* New internal command parser.  No visible external changes.
+
+1.3.0 (2007-01-22)
+* Piston status shows the revision number of locked repositories.  Thanks to
+  Chris Wanstrath <http://errtheblog.com/>.
+* New piston switch subcommand to switch repository locations.  Thanks to
+  Greg Spurrier for the prompt which resulted in finally implementing this.
+
+1.2.1 (2006-11-20)
+* Import subcommand would fail with a "svn: Explicit target required
+  ('vendor/rails' interpreted as prop value)" error.  This was a minor
+  error in the import code.  Reported by Daniel N.
+* The import subcommand could import another revision than what was intended,
+  if HEAD was updated while the import is in progress.
+
+1.2.0 (2006-11-17)
+* New status subcommand.  Shows M if locally or remotely modified. Applies to
+  one, many, all folders.  This subcommand *requires* the use of a Subversion
+  1.2.0 client.  Thanks to Chris Wanstrath for the inspiration.  His Rake
+  tasks are available at http://errtheblog.com/post/38.
+* Minor patch by Miguel Ibero Carreras to make Subversion always use the
+  C locale, instead of the current one.  This allows Piston to be used
+  with internationalized versions of Subversion.  David Bittencourt later
+  reported the same problem.  Thanks!
+* Better handle how update finds it's latest local revision to prevent
+  conflicts.  If you had never locally changed your vendor repositories,
+  this fix will change nothing for you.  This helps prevent local conflicts
+  if you had ever applied a local patch.
+  *CAVEAT*: See the release announcement at
+            http://blog.teksol.info/articles/2006/11/17/piston-1-2-0-status-better-update
+            for a required local operation.
+
+1.1.1 (2006-08-30)
+* Add contrib/piston [Michael Schuerig]
+* Non-recursively add the root directory of the managed folder then set Piston
+  properties before adding the contents of the managed folder.  This is to
+  help ease work along if an inconsistent EOL is encountered during the
+  import.  The user can finish the import by svn add'ing the rest of the
+  folder until all files are added.  Piston properties will already have been
+  set.
+
+1.1.0 (2006-08-26)
+* New 'convert' subcommand converts existing svn:externals to Piston managed
+  folders.  Thanks to Dan Kubb for the idea.
+* update now recursively finds the folders to process.  It bases it's search
+  on the presence or absence of the piston:root property.
+* Changed lock and unlock messages to be more detailed.
+
+1.0.1 (2006-08-24)
+* Corrected minor bug where the core extensions were in core_ext/core_ext
+  instead of being in core_ext.
+* Require the parent working copy path be at HEAD before importing / updating.
+* Don't do unnecessary merges if the file had not changed prior to the update.
+* During the update, if adding a folder, do an svn mkdir instead of a cp_r.
+
+1.0.0 (2006-08-24)
+* Initial version

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2006 Francois Beausoleil <francois@teksol.info>
+
+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.

data/README.rdoc

@@ -0,0 +1,134 @@
+Piston is a utility that eases vendor branch management.
+This is similar to <tt>svn:externals</tt>, except you have a local copy of
+the files, which you can modify at will.  As long as the changes are
+mergeable, you should have no problems.
+
+This tool has a similar purpose than svnmerge.py which you can find in the
+contrib/client-side folder of the main Subversion repository at
+http://svn.collab.net/repos/svn/trunk/contrib/client-side/svnmerge.py.
+The main difference is that Piston is designed to work with remote
+repositories.  Another tool you might want to look at, SVK, which you can find
+at http://svk.elixus.org/.
+
+From Wikipedia's Piston page (http://en.wikipedia.org/wiki/Piston):
+  In general, a piston is a sliding plug that fits closely inside the bore
+  of a cylinder.
+
+  Its purpose is either to change the volume enclosed by the cylinder, or
+  to exert a force on a fluid inside the cylinder.
+
+For this utility, I retain the second meaning, "to exert a force on a fluid
+inside the cylinder."  Piston forces the content of a remote repository
+location back into our own.
+
+
+= Installation
+
+Nothing could be simpler:
+
+ $ gem install --include-dependencies piston
+
+
+= Usage
+
+First, you need to import the remote repository location:
+
+ $ piston import http://dev.rubyonrails.org/svn/rails/trunk vendor/rails
+ Exported r4720 from 'http://dev.rubyonrails.org/svn/rails/trunk' to 'vendor/rails'
+
+ $ svn commit -m "Importing local copy of Rails"
+
+When you want to get the latest changes from the remote repository location:
+
+ $ piston update vendor/rails
+ Updated 'vendor/rails' to r4720.
+
+ $ svn commit -m "Updates vendor/rails to the latest revision"
+
+You can prevent a local Piston-managed folder from updating by using the
++lock+ subcommand:
+
+ $ piston lock vendor/rails
+ 'vendor/rails' locked at r4720.
+
+When you want to update again, you unlock:
+
+ $ piston unlock vendor/rails
+ 'vendor/rails' unlocked.
+
+If the branch you are following moves, you should use the switch subcommand:
+
+ $ piston import http://dev.rubyonrails.org/svn/rails/branches/1-2-pre-release vendor/rails
+ $ svn commit vendor/rails
+
+ # Vendor branch is renamed, let's follow it
+ $ piston switch http://dev.rubyonrails.org/svn/rails/branches/1-2-stable vendor/rails
+
+
+= Contributions
+
+== Bash Shell Completion Script
+
+Michael Schuerig contributed a Bash shell completion script.  You should copy
++contrib/piston+ from your gem repository to the appropriate folder.  Michael
+said:
+
+  I've put together a bash completion function for piston. On Debian, I
+  just put it in /etc/bash_completion.d, alternatively, the contents can
+  be copied to ~/.bash_completion. I don't know how things are organized
+  on other Unix/Linux systems.
+
+
+= Caveats
+
+== Speed
+
+This tool is SLOW.  The update process particularly so.  I use a brute force
+approach.  Subversion cannot merge from remote repositories, so instead I
+checkout the folder at the initial revision, and then run svn update and
+parse the results of that to determine what changes have occured.
+
+If a local copy of a file was changed, it's changes will be merged back in.
+If that introduces a conflict, Piston will not detect it.  The commit will be
+rejected by Subversion anyway.
+
+== Copies / Renames
+
+Piston *does not* track copies.  Since Subversion does renames in two
+phases (copy + delete), that is what Piston does.
+
+== Local Operations Only
+
+Piston only works if you have a working copy.  It also never commits your
+working copy directly.  You are responsible for reviewing the changes and
+applying any pending fixes.
+
+== Remote Repository UUID
+
+Piston caches the remote repository UUID, allowing it to know if the remote
+repos is still the same.  Piston refuses to work against a different
+repository than the one we checked out from originally.
+
+
+= Subversion Properties Used
+
+* <tt>piston:uuid</tt>: The remote repository's UUID, which we always confirm
+  before doing any operations.
+* <tt>piston:root</tt>: The repository root URL from which this Piston folder
+  was exported from.
+* <tt>piston:remote-revision</tt>: The <tt>Last Changed Rev</tt> of the remote
+  repository.
+* <tt>piston:local-revision</tt>: The <tt>Last Changed Rev</tt> of the Piston
+  managed folder, to enable us to know if we need to do any merging.
+* <tt>piston:locked</tt>: The revision at which this folder is locked.  If
+  this property is set and non-blank, Piston will skip the folder with
+  an appropriate message.
+
+
+= Dependencies
+
+Piston depends on the following libraries:
+
+* yaml
+* uri
+* fileutils

data/Rakefile

@@ -0,0 +1,25 @@
+require 'rake'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'spec/rake/spectask'
+require File.join(File.dirname(__FILE__), 'lib', 'piston', 'version')
+
+gem_spec = Gem::Specification.load(File.expand_path('piston.gemspec', File.dirname(__FILE__)))
+
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['specs/**/*_spec.rb']
+end
+
+task :default => :spec
+
+desc "Generate RDoc documentation in rdoc/"
+Rake::RDocTask.new :rdoc do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = gem_spec.name
+  rdoc.options = gem_spec.rdoc_options.clone
+  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_files.include gem_spec.extra_rdoc_files
+end
+
+Rake::GemPackageTask.new(gem_spec).define

data/bin/piston

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+
+begin
+  require 'rubygems'
+rescue LoadError
+  # no rubygems to load, so we fail silently
+end
+
+require 'piston'
+PistonCommandLineProcessor.parse_and_execute

data/contrib/piston

@@ -0,0 +1,43 @@
+have piston &&
+_piston()
+{
+  local cur prev commands options command
+
+  COMPREPLY=()
+  cur=${COMP_WORDS[COMP_CWORD]}
+
+  commands='update convert help unlock lock import switch'
+
+  if [[ $COMP_CWORD -eq 1 ]] ; then
+    if [[ "$cur" == -* ]]; then
+      COMPREPLY=( $( compgen -W '--version' -- $cur ) )
+    else
+      COMPREPLY=( $( compgen -W "$commands" -- $cur ) )
+    fi
+  else
+
+    prev=${COMP_WORDS[COMP_CWORD-1]}
+    command=${COMP_WORDS[1]}
+
+    if [[ "$cur" == -* ]]; then
+      case $command in
+        @(update|import))
+          options='-r --revision --lock --verbose'
+          ;;
+      esac
+      options="$options --verbose"
+
+      COMPREPLY=( $( compgen -W "$options" -- $cur ) )
+    else
+      if [[ "$command" == @(help|h|\?) ]]; then
+        COMPREPLY=( $( compgen -W "$commands" -- $cur ) )
+      else
+        _filedir
+      fi
+    fi
+  fi
+
+  return 0
+}
+
+[ -n "${have:-}" ] && complete -F _piston $default piston

data/lib/core_ext/range.rb

@@ -0,0 +1,5 @@
+class Range
+  def to_svn
+    to_s.gsub(/\.{2,3}/, ':')
+  end
+end

data/lib/core_ext/string.rb

@@ -0,0 +1,9 @@
+class String
+  def tmp
+    self + ".tmp"
+  end
+
+  def blank?
+    self.empty? || self.strip.empty?
+  end
+end

data/lib/piston.rb

@@ -0,0 +1,70 @@
+# Copyright (c) 2006 Francois Beausoleil <francois@teksol.info>
+#
+# 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.
+
+# $HeadURL: svn+ssh://rubyforge.org/var/svn/piston/tags/1.4.0/lib/piston.rb $
+# $Id: piston.rb 139 2008-02-07 15:28:24Z fbos $
+
+require 'yaml'
+require 'uri'
+require 'fileutils'
+
+PISTON_ROOT = File.dirname(__FILE__)
+Dir[File.join(PISTON_ROOT, 'core_ext', '*.rb')].each do |file|
+  require file
+end
+
+require "piston/version"
+require "piston/command"
+require "piston/command_error"
+
+require "transat/parser"
+Dir[File.join(PISTON_ROOT, "piston", "commands", "*.rb")].each do |file|
+  require file.gsub(PISTON_ROOT, "")[1..-4]
+end
+
+module Piston
+  ROOT        = "piston:root"
+  UUID        = "piston:uuid"
+  REMOTE_REV  = "piston:remote-revision"
+  LOCAL_REV   = "piston:local-revision"
+  LOCKED      = "piston:locked"
+end
+
+PistonCommandLineProcessor = Transat::Parser.new do
+  program_name "Piston"
+  version [Piston::VERSION::STRING]
+
+  option :verbose, :short => :v, :default => true, :message => "Show subversion commands and results as they are executed"
+  option :quiet, :short => :q, :default => false, :message => "Do not output any messages except errors"
+  option :revision, :short => :r, :param_name => "REVISION", :type => :int
+  option :show_updates, :short => :u, :message => "Query the remote repository for out of dateness information"
+  option :lock, :short => :l, :message => "Close down and lock the imported directory from further changes"
+  option :dry_run, :message => "Does not actually execute any commands"
+  option :force, :message => "Force the command to run, even if Piston thinks it would cause a problem"
+
+  command :switch, Piston::Commands::Switch, :valid_options => %w(lock dry_run force revision quiet verbose)
+  command :update, Piston::Commands::Update, :valid_options => %w(lock dry_run force revision quiet verbose)
+  command :diff,   Piston::Commands::Diff,   :valid_options => %w(lock dry_run force revision quiet verbose)
+  command :import, Piston::Commands::Import, :valid_options => %w(lock dry_run force revision quiet verbose)
+  command :convert, Piston::Commands::Convert, :valid_options => %w(lock verbose dry_run)
+  command :unlock, Piston::Commands::Unlock, :valid_options => %w(force dry_run verbose)
+  command :lock, Piston::Commands::Lock, :valid_options => %w(force dry_run revision verbose)
+  command :status, Piston::Commands::Status, :valid_options => %w(show_updates verbose)
+end

data/lib/piston/command.rb

@@ -0,0 +1,68 @@
+require "piston"
+
+module Piston
+  # The base class which all commands subclass to obtain services from.
+  class Command
+    attr_accessor :revision, :dry_run, :quiet, :verbose, :force, :lock,
+                  :recursive, :show_updates
+    attr_reader :args
+    attr_writer :logging_stream
+
+    def initialize(non_options, options)
+      @args = non_options
+
+      # Because the Windows shell does not process wildcards, we must do it
+      # here ourselves
+      @args.collect! do |arg|
+        next arg unless arg =~ /[*?]/
+        Dir[arg]
+      end
+
+      options.each do |option, value|
+        self.send("#{option}=", value)
+      end
+    end
+
+    # Run a Subversion command using the shell.  If the Subversion command
+    # returns an existstatus different from zero, a RuntimeError is raised.
+    def svn(*args)
+      args = args.flatten.compact.map do |arg|
+        if arg.to_s =~ /[ *?@]/ then
+          %Q("#{arg}")
+        else
+          arg
+        end
+      end
+
+      command = "svn #{args.join(' ')}"
+      logging_stream.puts command if verbose
+      return if dry_run
+      ENV['LANGUAGE'] = 'en_US'
+      result = `#{command}`
+      logging_stream.puts result if verbose
+      raise "Command #{command} resulted in an error:\n\n#{result}" unless $?.exitstatus.zero?
+      result
+    end
+
+    # Returns an IO-like object to which all information should be logged.
+    def logging_stream
+      @logging_stream ||= $stdout
+    end
+
+    def skip(dir, msg, header=true)
+      logging_stream.print "Skipping '#{dir}': " if header
+      logging_stream.puts msg
+    end
+
+    def find_targets
+      targets = Array.new
+      svn(:propget, '--recursive', Piston::ROOT).each_line do |line|
+        next unless line =~ /^([^ ]+)\s-\s.*$/
+        targets << $1
+      end
+
+      targets
+    end
+
+  end
+end