Class: RSCM::Base

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

Overview

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:

  • add

  • checkout

  • checked_out?

  • diff

  • edit

  • move

  • revisions

  • uptodate?

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:

  • central_exists?

  • create_central

  • can_create_central?

  • import_central

  • install_trigger

  • supports_trigger? # TODO: rename to can_install_trigger?

  • trigger_installed?

  • uninstall_trigger

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:

  • checkout_command_line

  • label

  • name

  • transactional?

  • update_command_line

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’

Direct Known Subclasses

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

Constant Summary collapse

@@classes = 
[]

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#checkout_dir ⇒ Object

Returns the value of attribute checkout_dir.



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

def checkout_dir
  @checkout_dir
end

Class Method Details

.classes ⇒ Object 



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

def self.classes
  @@classes
end

.register(cls) ⇒ Object 



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

def self.register(cls) 
  @@classes << cls unless @@classes.index(cls)
end

Instance Method Details

#==(other_scm) ⇒ Object 



276
277
278
279
280
281
282
 
# File 'lib/rscm/base.rb', line 276

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) ⇒ Object

Adds relative_filename to the working copy.



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

def add(relative_filename)
end

#can_create_central? ⇒ Boolean

Whether a repository can be created.

Returns:

  • (Boolean) 


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

def can_create_central?
  false
end

#central_exists? ⇒ Boolean

Whether the physical SCM represented by this instance exists.

Returns:

  • (Boolean) 


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

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) 


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

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

#checkout(to_identifier = Time.infinity) ⇒ 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).



164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/rscm/base.rb', line 164

def checkout(to_identifier=Time.infinity) # :yield: file
  # the OS doesn't store file timestamps with fractions.
  before_checkout_time = Time.now.utc - 1

  # We expect subclasses to implement this as a protected method (unless this whole method is overridden).
  checkout_silent(to_identifier)
  files = Dir["#{@checkout_dir}/**/*"]
  added = []
  files.each do |file|
    added << file if File.mtime(file).utc > before_checkout_time
  end
  ignore_paths.each do |regex|
    added.delete_if{|path| path =~ regex}
  end
  added_file_paths = added.find_all do |path|
    File.file?(path)
  end
  relative_added_file_paths = to_relative(checkout_dir, added_file_paths)
  relative_added_file_paths.each do |path|
    yield path if block_given?
  end
  relative_added_file_paths
end

#checkout_commandline(to_identifier = Time.infinity) ⇒ Object

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



261
262
263
 
# File 'lib/rscm/base.rb', line 261

def checkout_commandline(to_identifier=Time.infinity)
  raise "Not implemented"
end

#commit(message) ⇒ Object

Commit (check in) modified files.



145
146
 
# File 'lib/rscm/base.rb', line 145

def commit(message)
end

#create_central ⇒ 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 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).



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

def create_central
  raise "Not implemented"
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!



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

def destroy_central
end

#diff(change, &block) ⇒ Object

Returns/yields an IO containing the unified diff of the change.



272
273
274
 
# File 'lib/rscm/base.rb', line 272

def diff(change, &block)
  return(yield("Not implemented"))
end

#edit(file) ⇒ Object

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



141
142
 
# File 'lib/rscm/base.rb', line 141

def edit(file)
end

#import_central(dir, message) ⇒ Object

Recursively imports files from a dir into the central scm



136
137
138
 
# File 'lib/rscm/base.rb', line 136

def import_central(dir, message)
  raise "Not implemented"
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.



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

def install_trigger(trigger_command, install_dir)
  raise "Not implemented"
end

#move(relative_src, relative_dest) ⇒ Object

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



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

def move(relative_src, relative_dest)
end

#revisions(from_identifier, to_identifier = Time.infinity) ⇒ Object

Returns a Revisions object for the period specified by from_identifier (exclusive, i.e. after) and to_identifier (inclusive).



191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/rscm/base.rb', line 191

def revisions(from_identifier, to_identifier=Time.infinity)
  # Should be overridden by subclasses
  revisions = Revisions.new
  revisions.add(
    Revision.new(
      "up/the/chimney",
      Revision::DELETED,
      "DamageControl",
      "The #{name} class doesn't\n" +
        "correctly implement the revisions method. This is\n" +
        "not a real revision, but a hint to the developer to go and implement it.\n\n" +
        "Do It Now!",
      "999",
      Time.now.utc
    )
  )
  revisions
end

#supports_trigger? ⇒ Boolean

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) 


231
232
233
234
235
 
# File 'lib/rscm/base.rb', line 231

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

#to_yaml_properties ⇒ Object 



82
83
84
85
86
 
# File 'lib/rscm/base.rb', line 82

def to_yaml_properties
  props = instance_variables
  props.delete("@checkout_dir")
  props.sort!
end

#transactional? ⇒ Boolean

Whether or not this SCM is transactional (atomic).

Returns:

  • (Boolean) 


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

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) 


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

def trigger_installed?(trigger_command, install_dir)
  raise "Not implemented"
end

#uninstall_trigger(trigger_command, install_dir) ⇒ Object

Uninstalls trigger_command from the SCM.



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

def uninstall_trigger(trigger_command, install_dir)
  raise "Not implemented"
end

#update_commandline(to_identifier = Time.infinity) ⇒ Object

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



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

def update_commandline(to_identifier=Time.infinity)
  raise "Not implemented"
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.

TODO: rename to in_synch?

Returns:

  • (Boolean) 


215
216
217
218
219
220
 
# File 'lib/rscm/base.rb', line 215

def uptodate?(identifier)
  # Suboptimal algorithm that works for all SCMs.
  # Subclasses can override this to improve efficiency.
  
  revisions(identifier).empty?
end