Class: Origen::RevisionControl::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/origen/revision_control/base.rb

Overview

Base class of all revision control system drivers, all drivers should support the API methods defined here.

Each instance of this class represents the concept of mapping a local directory to a remote repository.

Origen.app.rc will return an instance of this class for the revision control system used by the current application, the :local attribute will be automatically set to Origen.root and the :remote attribute will be set per the revision control attributes defined in config/application.rb.

Direct Known Subclasses

DesignSync, Git, Perforce, Subversion

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Base

All revision control instances represent a remote server mapping to a local directory, :remote and :local options are required



24
25
26
27
28
29
30
31
32
33
 
# File 'lib/origen/revision_control/base.rb', line 24

def initialize(options = {})
  unless options[:remote] && options[:local]
    fail ':remote and :local options must be supplied when instantiating a new RevisionControl object'
  end

  @remote = Pathname.new(options[:remote])
  @local = Pathname.new(options[:local]).expand_path
  @remotes_method = :checkout
  initialize_local_dir(options)
end

Instance Attribute Details

#local ⇒ Object (readonly)

Returns a pointer to the local location (a Pathname object)



18
19
20
 
# File 'lib/origen/revision_control/base.rb', line 18

def local
  @local
end

#remote ⇒ Object (readonly)

Returns a pointer to the remote location (a Pathname object)



16
17
18
 
# File 'lib/origen/revision_control/base.rb', line 16

def remote
  @remote
end

#remotes_method ⇒ Object (readonly)

Method to use by Origen::RemoteManager to handle fetching a remote file



20
21
22
 
# File 'lib/origen/revision_control/base.rb', line 20

def remotes_method
  @remotes_method
end

Instance Method Details

#build(options = {}) ⇒ Object

Build the local workspace for the first time.

This is roughly equivalent to running the checkout command, but should be used in the case where the local workspace is being setup for the first time.



39
40
41
 
# File 'lib/origen/revision_control/base.rb', line 39

def build(options = {})
  fail "The #{self.class} driver does not support the build method!"
end

#changes(dir = nil, options = {}) ⇒ Object

Returns a hash containing the list of files that have changes compared to the given tag or compared to the latest version (on the server).

{
  :added => [],           # Paths to files that have been added since the previous tag
  :removed => [],         # Paths to files that have been removed since the previous tag
  :changed => [],         # Paths to files that have changed since the previous tag
  :present => true/false, # Convenience attribute for the caller to check if there are any changes, when
                          # true at least one of the other arrays will contain a value
}

The dir argument is optional and when not supplied the entire directory will be checked for changes.

Note that added files only refers to those files which have been checked into revision control since the compared to version, it does not refer to unmanaged files in the workspace. Use the unmanaged method to get a list of those.

Note also that while a file is considered added or removed depends on the chronological relationship between the current version (the user's workspace) and the reference version. If the reference version is older than the current version (i.e. an earlier tag), then an added file means a file that the current version has and the reference (previous) version did not have.

However if the reference version is newer than the current version (e.g. when comparing to a newer tag or the latest version on the server), then an added file means a file that the current version does not have and which has been added in a newer version of the remote directory.

Parameters:

  • dir (String, Pathname) (defaults to: nil) —

    The path to a sub-directory to check for changes, it can either be a relative path or an absolute path to either the local or remote locations.

  • options (Hash) (defaults to: {}) —

    Options to customize the operation

Options Hash (options):

  • :version (String) — default: nil —

    A specific version to compare against, will compare to latest if not supplied

  • :verbose (Boolean) — default: false —

    When true will show the command being executed and the raw output from the underlying revision control tool. When false will show nothing. False is the default as with this command the user is more concerned with seeing the organized summary that is returned from this method.



120
121
122
 
# File 'lib/origen/revision_control/base.rb', line 120

def changes(dir = nil, options = {})
  fail "The #{self.class} driver does not support the changes method!"
end

#checkin(path = nil, options = {}) ⇒ Object

Checkin the given file or directory, it returns a path to the local file.

The path argument is optional and when not supplied the entire directory will be checked in.

Parameters:

  • path (String, Pathname) (defaults to: nil) —

    The path to the remote item to checkout, this can be a pointer to a file or directory and it can either be a relative path or absolute path to either the local or remote locations. Multiple values can be supplied and should be separated by a space.

  • options (Hash) (defaults to: {}) —

    Options to customize the operation

Options Hash (options):

  • :force (Boolean) — default: false —

    Force overwrite of any newer version of the file that may exist, i.e. force checkin the current version to become the latest.

  • :unmanaged (Boolean) — default: false —

    Include files matching the given path that are not currently managed by the revision control system.

  • :comment (Boolean) — default: nil —

    Optionally supply a checkin comment.

  • :verbose (Boolean) — default: true —

    When true will show the command being executed and the raw output from the underlying revision control tool. When false will show nothing, but will still raise an error if the underlying command fails.



79
80
81
 
# File 'lib/origen/revision_control/base.rb', line 79

def checkin(path = nil, options = {})
  fail "The #{self.class} driver does not support the checkin method!"
end

#checkout(path = nil, options = {}) ⇒ Object

Checkout the given file or directory, it returns a path to the local file.

The path argument is optional and when not supplied the entire directory will be checked out.

Parameters:

  • path (String, Pathname) (defaults to: nil) —

    The path to the remote item to checkout, this can be a pointer to a file or directory and it can either be a relative path or absolute path to either the local or remote locations. Multiple values can be supplied and should be separated by a space.

  • options (Hash) (defaults to: {}) —

    Options to customize the operation

Options Hash (options):

  • :force (Boolean) — default: false —

    Force overwrite of any existing local copy

  • :version (String) — default: nil —

    A specific version to checkout, will get latest if not supplied

  • :verbose (Boolean) — default: true —

    When true will show the command being executed and the raw output from the underlying revision control tool. When false will show nothing, but will still raise an error if the underlying command fails.



58
59
60
 
# File 'lib/origen/revision_control/base.rb', line 58

def checkout(path = nil, options = {})
  fail "The #{self.class} driver does not support the checkout method!"
end

#current_branch ⇒ Object

Returns the name of the current branch in the local workspace



182
183
184
 
# File 'lib/origen/revision_control/base.rb', line 182

def current_branch
  fail "The #{self.class} driver does not support the current_branch method!"
end

#diff_cmd(file, version) ⇒ Object

Returns the command the user must run to execute a diff of the current version of the given file against the given version of it.

Parameters:

  • file (String, Pathname) —

    The local path to the file to be compared.

  • version (String) —

    The version of the file to compare to.



166
167
168
 
# File 'lib/origen/revision_control/base.rb', line 166

def diff_cmd(file, version)
  fail "The #{self.class} driver does not support the diff_cmd method!"
end

#dssc? ⇒ Boolean Also known as: design_sync?

Returns true if the revision controller object uses Design Sync

Returns:

  • (Boolean) 


187
188
189
 
# File 'lib/origen/revision_control/base.rb', line 187

def dssc?
  is_a?(DesignSync)
end

#git? ⇒ Boolean

Returns true if the revision controller object uses Git

Returns:

  • (Boolean) 


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

def git?
  is_a?(Git) # :-)
end

#local_modifications(dir = nil, options = {}) ⇒ Object

Returns an array containing the files that have un-committed local changes.

The dir argument is optional and when not supplied the entire directory will be checked for changes.

Parameters:

  • dir (String, Pathname) (defaults to: nil) —

    The path to a sub-directory to check for changes, it can either be a relative path or an absolute path to either the local or remote locations.

  • options (Hash) (defaults to: {}) —

    Options to customize the operation

Options Hash (options):

  • :verbose (Boolean) — default: false —

    When true will show the command being executed and the raw output from the underlying revision control tool. When false will show nothing. False is the default as with this command the user is more concerned with seeing the organized summary that is returned from this method.



137
138
139
 
# File 'lib/origen/revision_control/base.rb', line 137

def local_modifications(dir = nil, options = {})
  fail "The #{self.class} driver does not support the local_modifications method!"
end

#p4? ⇒ Boolean Also known as: perforce?

Returns true if the revision controller object uses Perforce

Returns:

  • (Boolean) 


198
199
200
 
# File 'lib/origen/revision_control/base.rb', line 198

def p4?
  is_a?(Perforce)
end

#root ⇒ Object

Returns what is considered to be the top-level root directory by the revision control system.

In the case of an application's revision controller (returned by Origen.app.rc) this method will often return the same directory as Origen.root. However in some cases an application owner may choose to store their application in a sub directory of a larger project entity that is revision controlled. In that case Origen.root will return the sub directory and this method will return the top-level directory of the wider project.



177
178
179
 
# File 'lib/origen/revision_control/base.rb', line 177

def root
  fail "The #{self.class} driver does not support the root method!"
end

#svn? ⇒ Boolean Also known as: subversion?

Returns true if the revision controller object uses Subversion

Returns:

  • (Boolean) 


204
205
206
 
# File 'lib/origen/revision_control/base.rb', line 204

def svn?
  is_a?(Subversion) # :-)
end

#unmanaged(dir = nil, options = {}) ⇒ Object

Returns an array containing the list of files that are present in the given directory but which are not managed by the revision control system.

The dir argument is optional and when not supplied the entire directory will be checked for unmanaged files.

Parameters:

  • dir (String, Pathname) (defaults to: nil) —

    The path to a sub-directory to check for unmanaged files, it can either be a relative path or an absolute path to either the local or remote locations.

  • options (Hash) (defaults to: {}) —

    Options to customize the operation

Options Hash (options):

  • :verbose (Boolean) — default: false —

    When true will show the command being executed and the raw output from the underlying revision control tool. When false will show nothing. False is the default as with this command the user is more concerned with seeing the organized summary that is returned from this method.



155
156
157
 
# File 'lib/origen/revision_control/base.rb', line 155

def unmanaged(dir = nil, options = {})
  fail "The #{self.class} driver does not support the unmanaged method!"
end