Class RSCM::Base
In: lib/rscm/base.rb
lib/rscm/revision_poller.rb
Parent: Object

This class defines the RSCM API. The documentation of the various methods uses CVS and Subversion‘s terminology. (For example, checkout means ‘get working copy’, not ‘lock for private edit’ as in ClearCase or VSS terminology).

Concrete subclasses of this class provide an API to manage a local working copy as well as an associated ‘central’ repository. The main responsibility is working copy operations:

In addition to operations related to working copies, the same instance should provide methods to administer the working copy‘s associated ‘central’ repository. These are:

Some methods are a bit fuzzy with respect to their relevance to the working copy or the associated central repository, as it depends on the nature of the individual underlying SCMs. These methods are:

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.

TODO: rename this superclass to ‘Base

Methods

Constants

TWO_WEEKS_AGO = 2*7*24*60*60
THIRTY_TWO_WEEKS_AGO = TWO_WEEKS_AGO * 16
DEFAULT_QUIET_PERIOD = 15   Default time to wait for scm to be quiet (applies to non-transactional scms only)

Attributes

logger  [RW] 

Public Instance methods

[Source]

     # File lib/rscm/base.rb, line 294
294:     def ==(other_scm)
295:       return false if self.class != other_scm.class
296:       self.instance_variables.each do |var|
297:         return false if self.instance_eval(var) != other_scm.instance_eval(var)
298:       end
299:       true
300:     end

Adds relative_filename to the working copy.

[Source]

     # File lib/rscm/base.rb, line 128
128:     def add(relative_filename)
129:       raise NotImplementedError
130:     end
atomic?()

Alias for transactional?

Whether a repository can be created.

[Source]

     # File lib/rscm/base.rb, line 123
123:     def can_create_central?
124:       false
125:     end
can_install_trigger?()

Alias for supports_trigger?

Whether the physical SCM represented by this instance exists.

[Source]

    # File lib/rscm/base.rb, line 90
90:     def central_exists?
91:       # The default implementation assumes yes - override if it can be
92:       # determined programmatically.
93:       true
94:     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

[Source]

     # File lib/rscm/base.rb, line 236
236:     def checked_out?
237:       File.exists?(@checkout_dir)
238:     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).

[Source]

     # File lib/rscm/base.rb, line 169
169:     def checkout(to_identifier=Time.infinity) # :yield: file
170:       # the OS doesn't store file timestamps with fractions.
171:       before_checkout_time = Time.now.utc - 1
172: 
173:       # We expect subclasses to implement this as a protected method (unless this whole method is overridden).
174:       checkout_silent(to_identifier)
175:       files = Dir["#{@checkout_dir}/**/*"]
176:       added = []
177:       files.each do |file|
178:         added << file if File.mtime(file).utc > before_checkout_time
179:       end
180:       ignore_paths.each do |regex|
181:         added.delete_if{|path| path =~ regex}
182:       end
183:       added_file_paths = added.find_all do |path|
184:         File.file?(path)
185:       end
186:       relative_added_file_paths = to_relative(checkout_dir, added_file_paths)
187:       relative_added_file_paths.each do |path|
188:         yield path if block_given?
189:       end
190:       relative_added_file_paths
191:     end

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

[Source]

     # File lib/rscm/base.rb, line 278
278:     def checkout_commandline(to_identifier=Time.infinity)
279:       raise NotImplementedError
280:     end

[Source]

    # File lib/rscm/base.rb, line 73
73:     def checkout_dir
74:       @checkout_dir
75:     end

TODO: Make revisions yield revisions as they are determined, to avoid having to load them all into memory before the method exits. Careful not to use yielded revisions 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?

[Source]

    # File lib/rscm/base.rb, line 69
69:     def checkout_dir=(dir)
70:       @checkout_dir = PathConverter.filepath_to_nativepath(dir, false)
71:     end

Commit (check in) modified files.

[Source]

     # File lib/rscm/base.rb, line 149
149:     def commit(message)
150:       raise NotImplementedError
151:     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 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).

[Source]

     # File lib/rscm/base.rb, line 111
111:     def create_central
112:       raise NotImplementedError
113:     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!

[Source]

     # File lib/rscm/base.rb, line 118
118:     def destroy_central
119:       raise NotImplementedError
120:     end

Destroys the working copy

[Source]

    # File lib/rscm/base.rb, line 84
84:     def destroy_working_copy
85:       FileUtils.rm_rf(checkout_dir) unless checkout_dir.nil?
86:     end

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

[Source]

     # File lib/rscm/base.rb, line 290
290:     def diff(change, &block)
291:       raise NotImplementedError
292:     end

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

[Source]

     # File lib/rscm/base.rb, line 145
145:     def edit(file)
146:     end

Returns a HistoricFile for relative_path

[Source]

     # File lib/rscm/base.rb, line 207
207:     def file(relative_path, dir)
208:       HistoricFile.new(relative_path, dir, self)
209:     end

Recursively imports files from a dir into the central scm

[Source]

     # File lib/rscm/base.rb, line 140
140:     def import_central(dir, message)
141:       raise "Not implemented"
142:     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.

[Source]

     # File lib/rscm/base.rb, line 260
260:     def install_trigger(trigger_command, install_dir)
261:       raise NotImplementedError
262:     end

Returns an Array of the children under relative_path

[Source]

     # File lib/rscm/base.rb, line 212
212:     def ls(relative_path)
213:       raise NotImplementedError
214:     end

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

[Source]

     # File lib/rscm/base.rb, line 135
135:     def move(relative_src, relative_dest)
136:       raise NotImplementedError
137:     end

Opens a revision_file

[Source]

     # File lib/rscm/base.rb, line 217
217:     def open(revision_file, &block) #:yield: io
218:       raise NotImplementedError
219:     end

Polls new revisions for since last_revision, or if last_revision is nil, polls since ‘now’ - seconds_before_now. If no revisions are found AND the poll was using seconds_before_now (i.e. it‘s the first poll, and no revisions were found), calls itself recursively with twice the seconds_before_now. This happens until revisions are found, ot until the 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.

[Source]

    # File lib/rscm/revision_poller.rb, line 19
19:     def poll_new_revisions(latest_revision=nil, quiet_period=DEFAULT_QUIET_PERIOD, seconds_before_now=TWO_WEEKS_AGO, max_time_before_now=THIRTY_TWO_WEEKS_AGO)
20:       max_past = Time.new.utc - max_time_before_now
21:   
22:       if(!central_exists?)
23:         logger.info "Not polling for revisions - central scm repo doesn't seem to exist" if logger
24:         return []
25:       end
26:       
27:       # Default value for start time (in case there are no detected revisions yet)

28:       from = Time.new.utc - seconds_before_now
29:       if(latest_revision)
30:         from = latest_revision.identifier
31:       else
32:         if(from < max_past)
33:           logger.info "Checked for revisions as far back as #{max_past}. There were none, so we give up." if logger
34:           return []
35:         else
36:           logger.info "Latest revision is not known. Checking for revisions since: #{from}" if logger
37:         end
38:       end
39: 
40:       logger.info "Polling revisions after #{from} (#{from.class.name})" if logger
41:       
42:       revisions = revisions(from)
43:       if(revisions.empty?)
44:         logger.info "No new revisions after #{from}" if logger
45:         unless(latest_revision)
46:           double_seconds_before_now = 2*seconds_before_now
47:           logger.info "Last revision still not found, checking since #{double_seconds_before_now.ago}" if logger
48:           return poll_new_revisions(project, double_seconds_before_now, max_time_before_now)
49:         end
50:       else
51:         logger.info "There were #{revisions.length} new revision(s) after #{from}" if logger
52:       end
53: 
54:       if(!revisions.empty? && !transactional?)
55:         # We're dealing with a non-transactional SCM (like CVS/StarTeam/ClearCase,

56:         # unlike Subversion/Monotone). Sleep a little, get the revisions again.

57:         # When the revisions are not changing, we can consider the last commit done

58:         # and the quiet period elapsed. This is not 100% failsafe, but will work

59:         # under most circumstances. In the worst case, we'll miss some files in

60:         # the revisions for really slow commits, but they will be part of the next 

61:         # revision (on next poll).

62:         commit_in_progress = true
63:         while(commit_in_progress)
64:           logger.info "Sleeping for #{quiet_period} seconds because #{visual_name} is not transactional." if logger
65:           
66:           sleep(quiet_period)
67:           previous_revisions = revisions
68:           revisions = revisions(from)
69:           commit_in_progress = revisions != previous_revisions
70:           if(commit_in_progress)
71:             logger.info "Commit still in progress." if logger
72:           end
73:         end
74:         logger.info "Quiet period elapsed" if logger
75:       end
76:       return revisions
77:     end

Returns a Revisions object for the period specified by from_identifier (exclusive, i.e. after) and to_identifier (inclusive). If relative_path is specified, the result will only contain revisions pertaining to that path.

[Source]

     # File lib/rscm/base.rb, line 197
197:     def revisions(from_identifier, to_identifier=Time.infinity, relative_path=nil)
198:       raise NotImplementedError
199:     end

Returns the HistoricFile representing the root of the repo

[Source]

     # File lib/rscm/base.rb, line 202
202:     def rootdir
203:       file("", true)
204:     end

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

[Source]

     # File lib/rscm/base.rb, line 242
242:     def supports_trigger?
243:       # The default implementation assumes no - override if it can be
244:       # determined programmatically.
245:       false
246:     end

[Source]

    # File lib/rscm/base.rb, line 77
77:     def to_yaml_properties
78:       props = instance_variables
79:       props.delete("@checkout_dir")
80:       props.sort!
81:     end

Whether or not this SCM is transactional (atomic).

[Source]

     # File lib/rscm/base.rb, line 98
 98:     def transactional?
 99:       false
100:     end

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

[Source]

     # File lib/rscm/base.rb, line 272
272:     def trigger_installed?(trigger_command, install_dir)
273:       raise NotImplementedError
274:     end

Descriptive name of the trigger mechanism

[Source]

     # File lib/rscm/base.rb, line 250
250:     def trigger_mechanism
251:       raise NotImplementedError
252:     end

Uninstalls trigger_command from the SCM.

[Source]

     # File lib/rscm/base.rb, line 266
266:     def uninstall_trigger(trigger_command, install_dir)
267:       raise NotImplementedError
268:     end

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

[Source]

     # File lib/rscm/base.rb, line 284
284:     def update_commandline(to_identifier=Time.infinity)
285:       raise NotImplementedError
286:     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.

TODO: rename to in_synch?

[Source]

     # File lib/rscm/base.rb, line 226
226:     def uptodate?(identifier)
227:       # Suboptimal algorithm that works for all SCMs.
228:       # Subclasses can override this to improve efficiency.
229:       
230:       revisions(identifier).empty?
231:     end

Protected Instance methods

Takes an array of absolute_paths and turns it into an array of paths relative to dir

[Source]

     # File lib/rscm/base.rb, line 307
307:     def to_relative(dir, absolute_paths)
308:       dir = File.expand_path(dir)
309:       absolute_paths.collect{|p| File.expand_path(p)[dir.length+1..-1]}
310:     end

[Validate]