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‘
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) |
logger | [RW] |
# 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.
# File lib/rscm/base.rb, line 128 128: def add(relative_filename) 129: raise NotImplementedError 130: end
Whether a repository can be created.
# File lib/rscm/base.rb, line 123 123: def can_create_central? 124: false 125: end
Whether the physical SCM represented by this instance exists.
# 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
# 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).
# 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.
# File lib/rscm/base.rb, line 278 278: def checkout_commandline(to_identifier=Time.infinity) 279: raise NotImplementedError 280: 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?
# 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.
# 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).
# 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!
# File lib/rscm/base.rb, line 118 118: def destroy_central 119: raise NotImplementedError 120: end
Destroys the working copy
# 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
# File lib/rscm/base.rb, line 290 290: def diff(change, &block) 291: raise NotImplementedError 292: end
Returns a HistoricFile for relative_path
# 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
# 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.
# 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
# File lib/rscm/base.rb, line 212 212: def ls(relative_path) 213: raise NotImplementedError 214: end
Opens a revision_file
# 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.
# 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.
# 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
# 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.
# 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
# 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).
# 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.
# 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
# File lib/rscm/base.rb, line 250 250: def trigger_mechanism 251: raise NotImplementedError 252: end
Uninstalls trigger_command from the SCM.
# 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.
# 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?
# 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