rscm 0.1.0

data/README

@@ -0,0 +1,198 @@
+= RSCM - Ruby Source Control Management
+
+RSCM is to SCM what ODBC/JDBC is to databases - a common API to access a wide variety of SCMs. The features are roughly:
+
+* Check out a working copy (with possibility to specify branch/date/label)
+* Get changesets (changesets are emulated for non-transactional SCMs like CVS and StarTeam)
+* Get diffs
+* Add and commit files
+* Manipluate triggers
+
+== Download
+
+RSCM is available as a RubyGem, and can be installed like this:
+
+  gem install rscm
+
+If you want the latest and greatest, you can get the sources, which live alongside DamageControl's sources:
+
+  http://damagecontrol.codehaus.org/Installing
+
+== Supported SCMs
+
+* CVS - http://www.cvshome.org (stable)
+* Perforce - http://www.perforce.com (not thoroughly tested)
+* StarTeam - http://www.borland.com/starteam (not thoroughly tested)
+* Subversion - http://subversion.tigris.org (stable)
+
+In progress:
+
+* Darcs - http://www.abridgegame.org/darcs (very incomplete)
+* Monotone - http://www.venge.net/monotone (half way there)
+
+Planned:
+
+Loads! All of them! How to add support for a new one is described further down in this file.
+
+== Related projects
+
+* DamageControl - http://damagecontrol.codehaus.org. DamageControl adds a web interface to RSCM and tons of other features for continuous integration.
+
+== Sample usage
+
+Here is an example of how to use RSCM to get a list of changesets from a CVS repository:
+
+  require 'rscm'
+  
+  scm = RSCM::SVN.new("svn://some.server/some/path/trunk", "trunk")
+
+  scm.checkout("mycheckout")
+  changesets = scm.changesets("mycheckout", Time.utc(2004, 11, 10, 12, 34, 22))
+  changesets.each do |changeset|
+    puts changeset
+  end
+
+=== Using visitors
+
+Although ChangeSets and ChangeSet support external iteration (as in the example above), the preferred way 
+to operate on them is to let a ChangeSets object +accept+ a visitor. A visitor
+must respond to the following methods:
+
+  def visit_changesets(changesets); end
+  def visit_changeset(changeset); end
+  def visit_change(change); end
+
+=== Getting diffs
+
+RSCM allows you to get diffs for changesets. This is done in the following way:
+
+See the DamageControl sources for more detailed examples (DamageControl persists diffs to disk
+and presents them as colourised diffs in its user interface).
+
+== Future plans
+
+=== Cross-SCM synchronisation
+
+RSCM could be used as a tool to migrate files from one SCM to another (of a different type)
+while keeping the history. -Similar to cvs2svn.
+
+RSCM could also be used as a continuous synchronisation service between SCMs. This can be very useful
+when you have to work with an SCM and you'd rather use a different one. RSCM could synchronise between
+the central SCM and one that you set up on your local machine.
+
+= Implementing support for a new SCM
+
+We'd be happy to receive contributions for more SCMs. You can always
+file a JIRA issue and hope for someone to implement it for you, or
+you can do it yourself. The rest of this file should get you started.
+
+N.B. IF YOU START IMPLEMENTING A NEW RSCM PLUGIN, PLEASE SUBMIT YOUR CODE
+TO JIRA AT AN EARLY STAGE (BEFORE IT'S COMPLETE). THIS WAY IT'S EASIER
+FOR EXISTING DEVELOPERS TO PROVIDE TIPS AND HELP UNDERWAY.
+
+Let's write an RSCM implementation for the imaginary SCM called Mooky.
+You should be able to use the same recipe for most SCMs.
+
+== Writing the API
+
+Start by writing a test:
+
+  test/rscm/mooky/mooky_test.rb
+
+By including GenericSCMTests your test will automatically include the
+acceptance test suite for RSCM. By doing this you'll actually follow a TDD
+approach for your new Mooky class - except that the tests are already written
+for you!
+
+IMPORTANT NOTE: If your SCM doesn't provide an easy way to create new local repositories
+- such as with StarTeam - you're probably better off writing the tests from scratch and not
+include GenericSCMTests. Instead, just make sure you have an SCM repository set up somewhere
+and write tests to work against that repository. This way you won't be able to pass the
+generic acceptance test suite, and other people (like the RSCM dev team) will probably
+not be able to run the tests for it. -But it's better than nothing. We'll happily accept
+contributions that don't use the generic tests, although it would be best if they did.
+
+OK, back to mooky. As you will see in a minute, the generic test suite will be of great
+help when developing the Mooky class. The tests will attempt to check in some sample files
+and call various methods on the mooky object to verify that it behaves correctly according
+to the RSCM API. (The sample files consist of some java sources, but you don't need Java installed.
+They're just files).
+
+Let's implement the Mooky class. Take a look at.
+
+  lib/rscm/mooky/mooky.rb
+
+Try running Mooky's test:
+
+  rake test TEST=test/rscm/mooky/mooky_test.rb
+  
+Whoops - we got some failures! It failed because our checkout method returned 
+nothing (nil). Let'see if we can get the a little further by implementing this
+method.
+
+The Mooky SCM happens to have a command line utility to perform a checkout.
+From the command line a checkout with mooky would be done like this:
+
+  cd somewhere
+  mooky checkout --repo mooky://some/where/else
+
+Running this command will print the following to standard out:
+
+  checkout build.xml
+  checkout project.xml
+  checkout src/java/com/thoughtworks/damagecontrolled/Thingy.java
+  checkout src/test/com/thoughtworks/damagecontrolled/ThingyTestCase.java
+  
+What we need to do is to execute these commands from Ruby. We also need to 
+parse the output from the mooky command to determine the files that were checked out,
+so that we can return an array with the file names of the checked out files (the method 
+should also yield each file name as the execution proceeds).
+
+Once your checkout command works okay, the test will get you a little further. Just keep
+on going until all tests pass.
+
+NOTE: If the SCM doesn't have a command line utility or a 3rd party Ruby API, but instead
+provides libraries (perhaps in C), then you should consider writing a Ruby C extension
+instead.
+
+If the SCM has a Java interface, you can take the same approach as for StarTeam. There are
+Java classes for ChangeSets that allow easy interaction between Ruby and Java over YAML. 
+You can reuse these classes for other Java based SCMs (if there are any, I don't know).
+
+== Writing the web interface (DamageControl only)
+
+If you're contributing a new SCM it would be nice if you took the time to implement a web interface
+that can be used to embed it into DamageControl.
+
+In trunk/damagecontrol, start by creating +app/views/project/_mooky.rhtml+. 
+
+Create a table with 2 columns and a row for each +attr_accessor+ in the Mooky class, preferrably
+with some explanatory text for the users so they know how to fill it in. See how the tooltips
+are used in some of the existing implementations.
+
+You also need a javascript section at the top
+with a function called +mooky_init()+. This will be called when the page is loaded. If you don't
+have plans to do anything fancy here, just leave it blank.
+
+=== Wiring it all up
+
+Just edit +lib/rscm.rb+ and +require+ your new scm class. Now you should see it coming up
+on the Source Control tab in the web interface.
+
+= Building RSCM
+This section is for developers who are new to ruby development and do not already know how to build and install Ruby gems.
+
+You need to install rubygems from http://rubyforge.org/projects/rubygems
+Afterwards you need to install rake and rails
+
+  gem install rake
+
+Now change to the RSCM root directory and type
+
+  rake gem
+
+This will create a gem for RSCM. To install this gem, you have to change to the pgk directory and type
+
+  sudo gem install pkg/rscm-0.1.0.gem
+  
+Now you can use RSCM in other Ruby apps.

data/Rakefile

@@ -0,0 +1,118 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/contrib/compositepublisher'
+require 'rake/contrib/sshpublisher'
+require 'rake/contrib/rubyforgepublisher'
+
+PKG_BUILD     = ENV['PKG_BUILD'] ? '.' + ENV['PKG_BUILD'] : ''
+PKG_NAME      = 'rscm'
+PKG_VERSION   = '0.1.0' + PKG_BUILD
+PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
+
+desc "Default Task"
+task :default => [ :all ]
+task :all => [:ant, :gem]
+
+# Run the unit tests
+# To run a specific test: rake test TEST=path/to/test
+fl = FileList.new('test/**/*_test.rb')
+fl.exclude('test/**/mooky*.rb')
+fl.exclude('test/**/monotone*.rb') # Incomplete/unsupported for now - reactivate when more complete!
+fl.exclude('test/**/darcs*.rb')    # Incomplete/unsupported for now - reactivate when more complete!
+fl.exclude('test/**/perforce*.rb') # Incomplete/unsupported for now - reactivate when more complete!
+fl.exclude('test/**/starteam*.rb') # Too bloody hard to test without a StarTeam server license! Tested ad-hoc.
+Rake::TestTask.new { |t|
+  t.libs << "test"
+  t.test_files = fl
+  t.verbose = true
+}
+
+rd = Rake::RDocTask.new { |rdoc|
+  rdoc.title    = 'RSCM - Ruby Source Control Management API'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_files.include('docs/**/*.rd')
+}
+
+task :ant do |t|
+  if(!ENV['RSCM_STARTEAM'])
+    puts "WARNING - NOT BUILDING STARTEAM SUPPORT SINCE 'RSCM_STARTEAM' IS NOT DEFINED."
+  else
+    ant = RUBY_PLATFORM == "i386-mswin32" ? "ant.bat" : system("which ant.sh") ? "ant.sh" : "ant" 
+    IO.popen("#{ant} -f ext/java/build.xml clean jar") do |io|
+      io.each_line do |line|
+        puts line
+      end
+    end
+  end
+end
+
+PKG_FILES = FileList[
+  '[A-Z]*',
+  'lib/**/*.rb', 
+  'test/**/*.rb',
+  'doc/**/*',
+  'ext/rscm.jar'
+]
+
+if ! defined?(Gem)
+  puts "Package Target requires RubyGEMs"
+else
+  spec = Gem::Specification.new do |s|
+    
+    #### Basic information.
+
+    s.name    = PKG_NAME
+    s.version = PKG_VERSION
+    s.summary = "RSCM - Ruby Source Control Management"
+    s.description = <<-EOF
+      RSCM is a Ruby library for various Source Control Management (SCM) systems.
+    EOF
+
+    #### Which files are to be included in this gem?  Everything!  (Except CVS directories.)
+
+    s.files = PKG_FILES.to_a
+
+    #### Load-time details: library and application (you will need one or both).
+
+    s.require_path = 'lib'
+    s.autorequire = 'rscm'
+
+    #### Documentation and testing.
+
+    s.has_rdoc = true
+    s.extra_rdoc_files = rd.rdoc_files.reject { |fn| fn =~ /\.rb$/ }.to_a
+    rd.options.each do |op|
+      s.rdoc_options << op
+    end
+
+    #### Author and project details.
+
+    s.author = "Aslak Hellesoy"
+    s.email = "dev@damagecontrol.codehaus.org"
+    s.homepage = "http://rscm.rubyforge.org"
+    s.rubyforge_project = "rscm"
+  end
+
+  Rake::GemPackageTask.new(spec) do |pkg|
+    pkg.need_zip = true
+    pkg.need_tar = true
+  end
+end
+
+task :publish => [:rdoc] do
+  publisher = Rake::CompositePublisher.new  
+  publisher.add Rake::RubyForgePublisher.new('rscm', 'aslak_hellesoy')  
+  #publisher.add Rake::SshFilePublisher.new(  
+  #  'umlcoop',  
+  #  'htdocs/software/rake',  
+  #  '.',  
+  #  'rake.blurb')
+
+  publisher.upload
+end

data/lib/rscm.rb

@@ -0,0 +1,10 @@
+require 'rscm/abstract_scm'
+require 'rscm/changes'
+require 'rscm/logging'
+require 'rscm/time_ext'
+# scms
+require 'rscm/mooky/mooky' # for demo purposes only
+require 'rscm/cvs/cvs'
+require 'rscm/darcs/darcs'
+require 'rscm/starteam/starteam'
+require 'rscm/svn/svn'

data/lib/rscm/abstract_log_parser.rb

@@ -0,0 +1,49 @@
+module RSCM
+  
+  # NOTE: It is recommended to use the Parser class in parser.rb
+  # as a basis for new SCM parsers
+  #
+  # Some utilities for log-parsers
+  # TODO: make this a module and remove the attr_reader
+  class AbstractLogParser
+  
+    attr_reader :io
+  
+    def initialize(io)
+      @io = io
+      @current_line_number = 0
+      @had_error = false
+    end
+  
+    def read_until_matching_line(regexp)
+      return nil if io.eof?
+      result = ""
+      io.each_line do |line|
+        @current_line_number += 1
+        line.gsub!(/\r\n$/, "\n")
+        break if line=~regexp
+        result<<line
+      end
+      if result.strip == ""
+        read_until_matching_line(regexp) 
+      else
+        result
+      end
+    end
+    
+    def convert_all_slashes_to_forward_slashes(file)
+      file.gsub(/\\/, "/")
+    end
+    
+    def error(msg)
+      @had_error=true
+      $stderr.puts(msg + "\ncurrent line: #{@current_line}\nstack trace:\n")
+      $stderr.puts(caller.backtrace.join('\n\t'))
+    end
+    
+    def had_error?
+      @had_error
+    end
+  end
+
+end

data/lib/rscm/abstract_scm.rb

@@ -0,0 +1,229 @@
+require 'fileutils'
+require 'rscm/changes'
+require 'rscm/path_converter'
+
+class String
+  # Turns a String into a Time or an int
+  def to_identifier
+    if(self =~ /20\d\d\d\d\d\d\d\d\d\d\d\d/)
+      # Assume it's a timestamp string - convert to time.
+      Time.parse_ymdHMS(self)
+    else
+      # Assume it's an arbitrary integer.
+      self.to_i
+    end
+  end
+end
+
+class Time
+  def to_s
+    self.ymdHMS
+  end
+end
+
+module RSCM
+  # This class defines the RSCM API. The documentation of the various methods
+  # uses CVS' terminology.
+  #
+  # Some of the methods in this API use +from_identifier+ and +to_identifier+.
+  # These identifiers can be either a UTC Time (according to the SCM's clock)
+  # or a String representing a label (according to the SCM's label system).
+  #
+  # If +from_identifier+ or +to_identifier+ are +nil+ they respectively represent
+  # epoch or the infinite future.
+  #
+  # Most of the methods take a mandatory +checkout_dir+ - even if this may seem
+  # unnecessary. The reason is that some SCMs require a working copy to be checked
+  # out in order to perform certain operations. In order to develop portable code,
+  # you should always pass in a non +nil+ value for +checkout_dir+.
+  #
+  class AbstractSCM
+    include FileUtils
+
+# TODO: Make changesets yield changesets as they are determined, to avoid
+# having to load them all into memory before the method exits. Careful not to
+# use yielded changesets to do another scm hit - like get diffs. Some SCMs
+# might dead lock on this. Implement a guard for that.
+# TODO: Add some visitor support here too?
+
+  public
+  
+    # Whether the physical SCM represented by this instance exists.
+    #
+    def exists?
+      # The default implementation assumes yes - override if it can be
+      # determined programmatically.
+      true
+    end
+    
+    # Whether or not this SCM is transactional.
+    #
+    def transactional?
+      false
+    end
+
+    # Creates a new repository. Throws an exception if the
+    # repository cannot be created.
+    #
+    def create
+    end
+
+    # Whether a repository can be created.
+    #
+    def can_create?
+    end
+
+    # Recursively imports files from a directory
+    #
+    def import(dir, message)
+    end
+
+    # The display name of this SCM
+    #
+    def name
+      # Should be overridden by subclasses to display a nicer name
+      self.class.name
+    end
+
+    # Gets the label for the working copy currently checked out in +checkout_dir+.
+    #
+    def label(checkout_dir)
+    end
+
+    # Open a file for edit - required by scms that checkout files in read-only mode e.g. perforce
+    #
+    def edit(file)
+    end
+
+    # Checks out or updates contents from an SCM to +checkout_dir+ - a local working copy.
+    #
+    # The +to_identifier+ parameter may be optionally specified to obtain files up to a
+    # particular time or label. +time_label+ should either be a Time (in UTC - according to
+    # the clock on the SCM machine) or a String - reprsenting a label.
+    #
+    # This method will yield the relative file name of each checked out file, and also return
+    # them in an array. Only files, not directories, should be yielded/returned.
+    #
+    # This method should be overridden for SCMs that are able to yield checkouts as they happen.
+    # For some SCMs this is not possible, or at least very hard. In that case, just override
+    # the checkout_silent method instead of this method (should be protected).
+    def checkout(checkout_dir, to_identifier=Time.infinity) # :yield: file
+      before = Dir["#{checkout_dir}/**/*"]
+
+      # We expect subclasses to implement this as a protected method (unless this whole method is overridden).
+      checkout_silent(checkout_dir, to_identifier)
+
+      after = Dir["#{checkout_dir}/**/*"]
+      added = (after - before)
+      ignore_paths.each do |regex|
+        added.delete_if{|path| path =~ regex}
+      end
+      added_file_paths = added.find_all do |path|
+        File.file?(path)
+      end
+      relative_added_file_paths = to_relative(checkout_dir, added_file_paths)
+      relative_added_file_paths.each do |path|
+        yield path
+      end
+      relative_added_file_paths
+    end
+  
+    # Returns a ChangeSets object for the period specified by +from_identifier+
+    # and +to_identifier+. See AbstractSCM for details about the parameters.
+    #
+    def changesets(checkout_dir, from_identifier, to_identifier=Time.infinity, files=nil)
+      # Should be overridden by subclasses
+      changesets = ChangeSets.new
+      changesets.add(
+        Change.new(
+          "up/the/chimney",
+          "DamageControl",
+          "The #{name} SCM class in #{__FILE__} doesn't\n" +
+            "correctly implement the changesets method. This is\n" +
+            "not a real changeset, but a hint to the developer to go and implement it.\n\n" +
+            "Do It Now!",
+          "999",
+          Time.now.utc
+        )
+      )
+      changesets
+    end
+
+    # Whether the working copy in +checkout_dir+ is uptodate with the repository
+    # since +from_identifier+.
+    #
+    def uptodate?(checkout_dir, from_identifier)
+      # Suboptimal algorithm that works for all SCMs.
+      # Subclasses can override this to increase efficiency.
+      
+      changesets(checkout_dir, from_identifier).empty?
+    end
+
+    # Whether the project is checked out or not.
+    # Subclasses should override this to check for SCM-specific administrative
+    # files if appliccable
+    def checked_out?(checkout_dir)
+      File.exists?(checkout_dir)
+    end
+
+    # Whether triggers are supported by this SCM
+    def supports_trigger?
+      # The default implementation assumes no - override if it can be
+      # determined programmatically.
+      false
+    end
+
+    # Installs +trigger_command+ in the SCM.
+    # The +install_dir+ parameter should be an empty local
+    # directory that the SCM can use for temporary files
+    # if necessary (CVS needs this to check out its administrative files).
+    # Most implementations will ignore this parameter.
+    #
+    def install_trigger(trigger_command, install_dir)
+    end
+
+    # Uninstalls +trigger_command+ from the SCM.
+    #
+    def uninstall_trigger(trigger_command, install_dir)
+    end
+
+    # Whether the command denoted by +trigger_command+ is installed in the SCM.
+    #
+    def trigger_installed?(trigger_command, install_dir)
+    end
+
+    # The command line to run in order to check out a fresh working copy.
+    #
+    def checkout_commandline(to_identifier=Time.infinity)
+    end
+
+    # The command line to run in order to update a working copy.
+    #
+    def update_commandline(to_identifier=Time.infinity)
+    end
+
+    # Returns/yields an IO containing the unified diff of the change.
+    def diff(checkout_dir, change, &block)
+      return(yield("Diff not implemented"))
+    end
+
+    def ==(other_scm)
+      return false if self.class != other_scm.class
+      self.instance_variables.each do |var|
+        return false if self.instance_eval(var) != other_scm.instance_eval(var)
+      end
+      true
+    end
+
+  protected
+
+    # Takes an array of +absolute_path+s and turn them into an array
+    # of paths relative to +dir+
+    # 
+    def to_relative(dir, absolute_paths)
+      dir = File.expand_path(dir)
+      absolute_paths.collect{|p| File.expand_path(p)[dir.length+1..-1]}
+    end
+
+  end
+end