Class: RSCM::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/rscm/base.rb,
lib/rscm/revision_poller.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 collapse

TWO_WEEKS_AGO = 
2*7*24*60*60
THIRTY_TWO_WEEKS_AGO = 
TWO_WEEKS_AGO * 16
DEFAULT_QUIET_PERIOD =

Default time to wait for scm to be quiet (applies to non-transactional scms only)

15

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#default_options ⇒ Object 



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

def default_options
  @default_options ||= {:stdout=>'stdout.log', :stderr=>'stderr.log'}
end

#logger ⇒ Object

Returns the value of attribute logger.



3
4
5
 
# File 'lib/rscm/revision_poller.rb', line 3

def logger
  @logger
end

Instance Method Details

#==(other_scm) ⇒ Object 



257
258
259
260
261
262
263
 
# File 'lib/rscm/base.rb', line 257

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) 


102
103
104
 
# File 'lib/rscm/base.rb', line 102

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

#can_create_central? ⇒ Boolean

Whether a repository can be created.

Returns:

  • (Boolean) 


97
98
99
 
# File 'lib/rscm/base.rb', line 97

def can_create_central?
  false
end

#central_exists? ⇒ Boolean

Whether or not the SCM represented by this instance exists.

Returns:

  • (Boolean) 


65
66
67
68
69
 
# File 'lib/rscm/base.rb', line 65

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) 


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

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

#checked_out_files ⇒ Object 



155
156
157
158
159
160
161
162
163
 
# File 'lib/rscm/base.rb', line 155

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



144
145
146
147
148
149
150
151
152
153
 
# File 'lib/rscm/base.rb', line 144

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) 


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

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

#checkout_dir ⇒ Object

Gets the working copy directory.



48
49
50
 
# File 'lib/rscm/base.rb', line 48

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



43
44
45
 
# File 'lib/rscm/base.rb', line 43

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

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

Commit (check in) modified files.

Raises:

  • (NotImplementedError) 


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

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) 


85
86
87
 
# File 'lib/rscm/base.rb', line 85

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) 


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

def destroy_central
  raise NotImplementedError
end

#destroy_working_copy ⇒ Object

Destroys the working copy



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

def destroy_working_copy
  FileUtils.rm_rf(checkout_dir) unless checkout_dir.nil?
end

#diff(change, &block) ⇒ Object

Returns/yields an IO containing the unified diff of the change. Also see RevisionFile#diff

Raises:

  • (NotImplementedError) 


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

def diff(change, &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



120
121
 
# File 'lib/rscm/base.rb', line 120

def edit(file, options={})
end

#file(relative_path, dir) ⇒ Object

Returns a HistoricFile for relative_path



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

def file(relative_path, dir)
  HistoricFile.new(relative_path, dir, self)
end

#import_central(options) ⇒ Object

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

Raises:

  • (NotImplementedError) 


115
116
117
 
# File 'lib/rscm/base.rb', line 115

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) 


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

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) 


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

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

#open(revision_file, &block) ⇒ Object

Opens a revision_file

Raises:

  • (NotImplementedError) 


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

def open(revision_file, &block) #:yield: io
  raise NotImplementedError
end

#poll_new_revisions(options) ⇒ Object

Polls new revisions for since last_revision, or if last_revision is nil, polls since ‘now’ - options[:seconds_before_now]. If no revisions are found AND the poll was using options[:seconds_before_now] (i.e. it’s the first poll, and no revisions were found), calls itself recursively with twice the options[:seconds_before_now]. This happens until revisions are found, ot until the options[:seconds_before_now] Exceeds 32 weeks, which means it’s probably not worth looking further in the past, the scm is either completely idle or not yet active.



19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/rscm/revision_poller.rb', line 19

def poll_new_revisions(options)
  options = {
    :latest_revision => nil, 
    :quiet_period => DEFAULT_QUIET_PERIOD, 
    :seconds_before_now => TWO_WEEKS_AGO, 
    :max_time_before_now => THIRTY_TWO_WEEKS_AGO,
  }.merge(options)
  max_past = Time.new.utc - options[:max_time_before_now]
  
  # Default value for start time (in case there are no detected revisions yet)
  from = Time.new.utc - options[:seconds_before_now]
  if(options[:latest_revision])
    from = options[:latest_revision].identifier
  else
    if(from < max_past)
      logger.info "Checked for revisions as far back as #{max_past}. There were none, so we give up." if logger
      return []
    else
      logger.info "Latest revision is not known. Checking for revisions since: #{from}" if logger
    end
  end

  logger.info "Polling revisions after #{from} (#{from.class.name})" if logger
  
  revisions = revisions(from, options)
  if(revisions.empty?)
    logger.info "No new revisions after #{from}" if logger
    unless(options[:latest_revision])
      double_seconds_before_now = 2*options[:seconds_before_now]
      logger.info "Last revision still not found, checking since #{double_seconds_before_now.ago}" if logger
      new_opts = options.dup
      new_opts[:seconds_before_now] = double_seconds_before_now
      return poll_new_revisions(new_opts)
    end
  else
    logger.info "There were #{revisions.length} new revision(s) after #{from}" if logger
  end

  if(!revisions.empty? && !transactional?)
    # We're dealing with a non-transactional SCM (like CVS/StarTeam/ClearCase,
    # unlike Subversion/Monotone). Sleep a little, get the revisions again.
    # When the revisions are not changing, we can consider the last commit done
    # and the quiet period elapsed. This is not 100% failsafe, but will work
    # under most circumstances. In the worst case, we'll miss some files in
    # the revisions for really slow commits, but they will be part of the next 
    # revision (on next poll).
    commit_in_progress = true
    while(commit_in_progress)
      logger.info "Sleeping for #{options[:quiet_period]} seconds because #{visual_name} is not transactional." if logger
      
      sleep(options[:quiet_period])
      previous_revisions = revisions
      revisions = revisions(from)
      commit_in_progress = revisions != previous_revisions
      if(commit_in_progress)
        logger.info "Commit still in progress." if logger
      end
    end
    logger.info "Quiet period elapsed" if logger
  end
  return revisions
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 (inclusive). If relative_path is specified, the result will only contain revisions pertaining to that path.

Raises:

  • (NotImplementedError) 


169
170
171
 
# File 'lib/rscm/base.rb', line 169

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

#rootdir ⇒ Object

Returns the HistoricFile representing the root of the repo



174
175
176
 
# File 'lib/rscm/base.rb', line 174

def rootdir
  file("", true)
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) 


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

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.



37
38
39
 
# File 'lib/rscm/base.rb', line 37

def to_identifier(raw_identifier)
  raw_identifier.to_s
end

#to_yaml_properties ⇒ Object

:nodoc:



52
53
54
55
56
57
 
# File 'lib/rscm/base.rb', line 52

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) 


72
73
74
 
# File 'lib/rscm/base.rb', line 72

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) 


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

def trigger_installed?(trigger_command, install_dir)
  raise NotImplementedError
end

#trigger_mechanism ⇒ Object

Descriptive name of the trigger mechanism

Raises:

  • (NotImplementedError) 


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

def trigger_mechanism
  raise NotImplementedError
end

#uninstall_trigger(trigger_command, install_dir) ⇒ Object

Uninstalls trigger_command from the SCM.

Raises:

  • (NotImplementedError) 


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

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) 


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

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) 


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

def uptodate?(identifier)
  raise NotImplementedError
end