Class: RSCM::Base

Inherits:
Object
  • Object
show all
Includes:
RevisionPoller
Defined in:
lib/rscm/base.rb

Overview

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.

Direct Known Subclasses

ClearCase, Cvs, Darcs, Monotone, Mooky, Perforce, StarTeam, Subversion

Constant Summary

Constants included from RevisionPoller

RevisionPoller::BASE_INCREMENT, RevisionPoller::CRITICAL_REVISION_SIZE, RevisionPoller::TWENTY_FOUR_HOURS

Instance Attribute Summary collapse

Attributes included from RevisionPoller

#logger

Instance Method Summary collapse

Methods included from RevisionPoller

#poll

Instance Attribute Details

#default_options ⇒ Object 



35
36
37
 
# File 'lib/rscm/base.rb', line 35

def default_options
  @default_options ||= {}
end

#store_revisions_command=(value) ⇒ Object (writeonly)

Sets the attribute store_revisions_command

Parameters:

  • value —

    the value to set the attribute store_revisions_command to.



33
34
35
 
# File 'lib/rscm/base.rb', line 33

def store_revisions_command=(value)
  @store_revisions_command = value
end

Instance Method Details

#==(other_scm) ⇒ Object 



258
259
260
261
262
263
264
 
# 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

#add(relative_filename, options = {}) ⇒ Object

Adds relative_filename to the working copy.

Raises:

  • (NotImplementedError) 


110
111
112
 
# File 'lib/rscm/base.rb', line 110

def add(relative_filename, options={})
  raise NotImplementedError
end

#available? ⇒ Boolean

Returns true if the underlying SCM tool is available on this system.

Returns:

  • (Boolean)

Raises:

  • (NotImplementedError) 


40
41
42
 
# File 'lib/rscm/base.rb', line 40

def available?
  raise NotImplementedError
end

#can_create_central? ⇒ Boolean

Whether a repository can be created.

Returns:

  • (Boolean) 


105
106
107
 
# File 'lib/rscm/base.rb', line 105

def can_create_central?
  false
end

#central_exists? ⇒ Boolean

Whether or not the SCM represented by this instance exists.

Returns:

  • (Boolean) 


73
74
75
76
77
 
# File 'lib/rscm/base.rb', line 73

def central_exists?
  # The default implementation assumes yes - override if it can be
  # determined programmatically.
  true
end

#checked_out? ⇒ Boolean

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

Returns:

  • (Boolean) 


200
201
202
 
# File 'lib/rscm/base.rb', line 200

def checked_out?
  File.exists?(@checkout_dir)
end

#checked_out_files ⇒ Object 



163
164
165
166
167
168
169
170
171
172
173
 
# 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

#checkout(to_identifier = Time.infinity, options = {}) ⇒ Object

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).



152
153
154
155
156
157
158
159
160
161
 
# 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

#checkout_commandline(to_identifier = Time.infinity) ⇒ Object

The command line to run in order to check out a fresh working copy.

Raises:

  • (NotImplementedError) 


242
243
244
 
# File 'lib/rscm/base.rb', line 242

def checkout_commandline(to_identifier=Time.infinity)
  raise NotImplementedError
end

#checkout_dir ⇒ Object

Gets the working copy directory.



56
57
58
 
# File 'lib/rscm/base.rb', line 56

def checkout_dir
  @checkout_dir
end

#checkout_dir=(dir) ⇒ Object

Sets the checkout dir (working copy). Should be set prior to most other method invocations (depending on the implementation).



51
52
53
 
# File 'lib/rscm/base.rb', line 51

def checkout_dir=(dir)
  @checkout_dir = PathConverter.filepath_to_nativepath(dir, false)
end

#commit(message, options = {}) ⇒ Object

Commit (check in) modified files.

Raises:

  • (NotImplementedError) 


132
133
134
 
# File 'lib/rscm/base.rb', line 132

def commit(message, options={})
  raise NotImplementedError
end

#create_central(options = {}) ⇒ Object

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).

Raises:

  • (NotImplementedError) 


93
94
95
 
# File 'lib/rscm/base.rb', line 93

def create_central(options={})
  raise NotImplementedError
end

#destroy_central ⇒ Object

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!

Raises:

  • (NotImplementedError) 


100
101
102
 
# File 'lib/rscm/base.rb', line 100

def destroy_central
  raise NotImplementedError
end

#destroy_working_copy(options = {}) ⇒ Object

Destroys the working copy



68
69
70
 
# File 'lib/rscm/base.rb', line 68

def destroy_working_copy(options={})
  FileUtils.rm_rf(checkout_dir) unless checkout_dir.nil?
end

#diff(path, from, to, options = {}, &block) ⇒ Object

Yields an IO containing the unified diff of the change. Also see RevisionFile#diff

Raises:

  • (NotImplementedError) 


254
255
256
 
# File 'lib/rscm/base.rb', line 254

def diff(path, from, to, options={}, &block)
  raise NotImplementedError
end

#edit(file, options = {}) ⇒ Object

Open a file for edit - required by scms that check out files in read-only mode e.g. perforce



128
129
 
# File 'lib/rscm/base.rb', line 128

def edit(file, options={})
end

#import_central(options) ⇒ Object

Recursively imports files from :dir into the central scm, using commit message :message

Raises:

  • (NotImplementedError) 


123
124
125
 
# File 'lib/rscm/base.rb', line 123

def import_central(options)
  raise NotImplementedError
end

#install_trigger(trigger_command, install_dir) ⇒ Object

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.

Raises:

  • (NotImplementedError) 


224
225
226
 
# File 'lib/rscm/base.rb', line 224

def install_trigger(trigger_command, install_dir)
  raise NotImplementedError
end

#move(relative_src, relative_dest, options = {}) ⇒ Object

Schedules a move of relative_src to relative_dest Should not take effect in the central repository until commit is invoked.

Raises:

  • (NotImplementedError) 


117
118
119
 
# File 'lib/rscm/base.rb', line 117

def move(relative_src, relative_dest, options={})
  raise NotImplementedError
end

#open(path, native_revision_identifier, options = {}, &block) ⇒ Object

Opens a readonly IO to a file at path

Raises:

  • (NotImplementedError) 


185
186
187
 
# File 'lib/rscm/base.rb', line 185

def open(path, native_revision_identifier, options={}, &block) #:yield: io
  raise NotImplementedError
end

#revisions(from_identifier, options = {}) ⇒ Object

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

Raises:

  • (NotImplementedError) 


180
181
182
 
# File 'lib/rscm/base.rb', line 180

def revisions(from_identifier, options={})
  raise NotImplementedError
end

#store_revisions_command? ⇒ Boolean

Whether or not to store the revision command in the Revisions instance returned by revisions

Returns:

  • (Boolean) 


267
 
# File 'lib/rscm/base.rb', line 267

def store_revisions_command?; @store_revisions_command.nil? ? true : @store_revisions_command; end

#supports_trigger? ⇒ Boolean Also known as: can_install_trigger?

Whether triggers are supported by this SCM. A trigger is a command that can be executed upon a completed commit to the SCM.

Returns:

  • (Boolean) 


206
207
208
209
210
 
# File 'lib/rscm/base.rb', line 206

def supports_trigger?
  # The default implementation assumes no - override if it can be
  # determined programmatically.
  false
end

#to_identifier(raw_identifier) ⇒ Object

Transforms raw_identifier into the native rype used for revisions.



45
46
47
 
# File 'lib/rscm/base.rb', line 45

def to_identifier(raw_identifier)
  raw_identifier.to_s
end

#to_yaml_properties ⇒ Object

:nodoc:



60
61
62
63
64
65
 
# File 'lib/rscm/base.rb', line 60

def to_yaml_properties #:nodoc:
  props = instance_variables
  props.delete("@checkout_dir")
  props.delete("@default_options")
  props.sort!
end

#transactional? ⇒ Boolean Also known as: atomic?

Whether or not this SCM is transactional (atomic).

Returns:

  • (Boolean) 


80
81
82
 
# File 'lib/rscm/base.rb', line 80

def transactional?
  false
end

#trigger_installed?(trigger_command, install_dir) ⇒ Boolean

Whether the command denoted by trigger_command is installed in the SCM.

Returns:

  • (Boolean)

Raises:

  • (NotImplementedError) 


236
237
238
 
# File 'lib/rscm/base.rb', line 236

def trigger_installed?(trigger_command, install_dir)
  raise NotImplementedError
end

#trigger_mechanism ⇒ Object

Descriptive name of the trigger mechanism

Raises:

  • (NotImplementedError) 


214
215
216
 
# File 'lib/rscm/base.rb', line 214

def trigger_mechanism
  raise NotImplementedError
end

#uninstall_trigger(trigger_command, install_dir) ⇒ Object

Uninstalls trigger_command from the SCM.

Raises:

  • (NotImplementedError) 


230
231
232
 
# File 'lib/rscm/base.rb', line 230

def uninstall_trigger(trigger_command, install_dir)
  raise NotImplementedError
end

#update_commandline(to_identifier = Time.infinity) ⇒ Object

The command line to run in order to update a working copy.

Raises:

  • (NotImplementedError) 


248
249
250
 
# File 'lib/rscm/base.rb', line 248

def update_commandline(to_identifier=Time.infinity)
  raise NotImplementedError
end

#uptodate?(identifier) ⇒ Boolean

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.

Returns:

  • (Boolean)

Raises:

  • (NotImplementedError) 


193
194
195
 
# File 'lib/rscm/base.rb', line 193

def uptodate?(identifier)
  raise NotImplementedError
end