class RSCM::Base
This class defines the RSCM API, which offers access to an SCM working copy as well as a 'central' repository.
Concrete subclasses of this class (concrete adapters) implement the integration with the respective SCMs.
Most of the methods take an optional options
Hash (named
parameters), allowing the following options:
-
:stdout
: Path to file name where stdout of SCM operations are written. -
:stdout
: Path to file name where stderr of SCM operations are written.
In stead of specifying the options
parameters for every API
method, it's possible to assign default options via the
default_options
attribute.
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
or Integer representing a label/revision (according to the SCM's
native label/revision scheme).
If from_identifier
or to_identifier
are
nil
they should respectively default to Time.epoch or Time.infinite.
Attributes
Public Instance Methods
# File lib/rscm/base.rb, line 258 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
Adds relative_filename
to the working copy.
# File lib/rscm/base.rb, line 110 def add(relative_filename, options={}) raise NotImplementedError end
Returns true if the underlying SCM tool is available on this system.
# File lib/rscm/base.rb, line 40 def available? raise NotImplementedError end
Whether a repository can be created.
# File lib/rscm/base.rb, line 105 def can_create_central? false end
Whether or not the SCM represented by this instance exists.
# File lib/rscm/base.rb, line 73 def central_exists? # The default implementation assumes yes - override if it can be # determined programmatically. true end
Whether the project is checked out from the central repository or not. Subclasses should override this to check for SCM-specific administrative files if appliccable
# File lib/rscm/base.rb, line 200 def checked_out? File.exists?(@checkout_dir) end
# File lib/rscm/base.rb, line 163 def checked_out_files raise "checkout_dir not set" if @checkout_dir.nil? files = Dir["#{@checkout_dir}/**/*"] files.delete_if{|file| File.directory?(file)} ignore_paths.each do |regex| files.delete_if{|file| file =~ regex} end dir = File.expand_path(@checkout_dir) files.collect{|file| File.expand_path(file)[dir.length+1..-1]} end
Checks out or updates contents from a central SCM to
checkout_dir
- a local working copy. If this is a distributed
SCM, this method should create a 'working copy' repository if one
doesn't already exist. Then the contents of the central SCM should be
pulled into the working copy.
The to_identifier
parameter may be optionally specified to
obtain files up to a particular time or label. to_identifier
should either be a Time (in UTC - according to
the clock on the SCM machine) or a String - reprsenting a label or
revision.
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).
# File lib/rscm/base.rb, line 152 def checkout(to_identifier=Time.infinity, options={}) # :yield: file to_identifier = Time.infinity if to_identifier.nil? before = checked_out_files # We expect subclasses to implement this as a protected method (unless this whole method is overridden). checkout_silent(to_identifier, options) after = checked_out_files (after - before).sort! end
The command line to run in order to check out a fresh working copy.
# File lib/rscm/base.rb, line 242 def checkout_commandline(to_identifier=Time.infinity) raise NotImplementedError end
Gets the working copy directory.
# File lib/rscm/base.rb, line 56 def checkout_dir @checkout_dir end
Sets the checkout dir (working copy). Should be set prior to most other method invocations (depending on the implementation).
# File lib/rscm/base.rb, line 51 def checkout_dir=(dir) @checkout_dir = PathConverter.filepath_to_nativepath(dir, false) end
Commit (check in) modified files.
# File lib/rscm/base.rb, line 132 def commit(message, options={}) raise NotImplementedError end
Creates a new 'central' repository. This is intended only for creation of 'central' repositories (not for working copies). You shouldn't have to call this method if a central repository already exists. This method is used primarily for testing of RSCM, but can also be used if you really want to use RSCM to create a central repository.
This method should throw an exception if the repository cannot be created (for example if the repository is 'remote' or if it already exists).
# File lib/rscm/base.rb, line 93 def create_central(options={}) raise NotImplementedError end
# File lib/rscm/base.rb, line 35 def default_options @default_options ||= {} end
Destroys the central repository. Shuts down any server processes and deletes the repository. WARNING: calling this may result in loss of data. Only call this if you really want to wipe it out for good!
# File lib/rscm/base.rb, line 100 def destroy_central raise NotImplementedError end
Destroys the working copy
# File lib/rscm/base.rb, line 68 def destroy_working_copy(options={}) FileUtils.rm_rf(checkout_dir) unless checkout_dir.nil? end
Yields an IO containing the unified diff of the change. Also see RSCM::RevisionFile#diff
# File lib/rscm/base.rb, line 254 def diff(path, from, to, options={}, &block) raise NotImplementedError end
Open a file for edit - required by scms that check out files in read-only mode e.g. perforce
# File lib/rscm/base.rb, line 128 def edit(file, options={}) end
Recursively imports files from :dir
into the central scm,
using commit message :message
# File lib/rscm/base.rb, line 123 def import_central(options) raise NotImplementedError 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.
# File lib/rscm/base.rb, line 224 def install_trigger(trigger_command, install_dir) raise NotImplementedError end
Schedules a move of relative_src
to relative_dest
Should not take effect in the central repository until commit
is invoked.
# File lib/rscm/base.rb, line 117 def move(relative_src, relative_dest, options={}) raise NotImplementedError end
Opens a readonly IO to a file at path
# File lib/rscm/base.rb, line 185 def open(path, native_revision_identifier, options={}, &block) #:yield: io raise NotImplementedError end
Returns a Revisions object for the interval
specified by from_identifier
(exclusive, i.e. after) and
optionally :to_identifier
(exclusive too). If
relative_path
is specified, the result will only contain
revisions pertaining to that path.
For example, revisions(223, 229) should return revisions 224..228
# File lib/rscm/base.rb, line 180 def revisions(from_identifier, options={}) raise NotImplementedError end
Whether or not to store the revision command in the Revisions instance returned by
revisions
# File lib/rscm/base.rb, line 267 def store_revisions_command?; @store_revisions_command.nil? ? true : @store_revisions_command; end
Whether triggers are supported by this SCM. A trigger is a command that can be executed upon a completed commit to the SCM.
# File lib/rscm/base.rb, line 206 def supports_trigger? # The default implementation assumes no - override if it can be # determined programmatically. false end
Transforms raw_identifier
into the native rype used for
revisions.
# File lib/rscm/base.rb, line 45 def to_identifier(raw_identifier) raw_identifier.to_s end
Whether or not this SCM is transactional (atomic).
# File lib/rscm/base.rb, line 80 def transactional? false end
Whether the command denoted by trigger_command
is installed in
the SCM.
# File lib/rscm/base.rb, line 236 def trigger_installed?(trigger_command, install_dir) raise NotImplementedError end
Descriptive name of the trigger mechanism
# File lib/rscm/base.rb, line 214 def trigger_mechanism raise NotImplementedError end
Uninstalls trigger_command
from the SCM.
# File lib/rscm/base.rb, line 230 def uninstall_trigger(trigger_command, install_dir) raise NotImplementedError end
The command line to run in order to update a working copy.
# File lib/rscm/base.rb, line 248 def update_commandline(to_identifier=Time.infinity) raise NotImplementedError end
Whether the working copy is in synch with the central repository's
revision/time identified by identifier
. If
identifier
is nil, 'HEAD' of repository should be
assumed.
# File lib/rscm/base.rb, line 193 def uptodate?(identifier) raise NotImplementedError end
Protected Instance Methods
Directory where commands must be run
# File lib/rscm/base.rb, line 272 def cmd_dir nil end
Wrapper for RSCM::CommandLine#execute that provides default values for dir plus any options set in #default_options (typically stdout and stderr).
# File lib/rscm/base.rb, line 278 def execute(cmd, options={}, &proc) options = {:dir => cmd_dir}.merge(default_options).merge(options) begin CommandLine.execute(cmd, options, &proc) rescue CommandLine::OptionError => e e.message += "\nEither specify default_options on the scm object, or pass the required options to the method" raise e end end