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



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

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.



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

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.



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

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.



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

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.



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

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



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

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.



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

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) 


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

def dssc?
  is_a?(DesignSync)
end

#git? ⇒ Boolean

Returns true if the revision controller object uses Git

Returns:

  • (Boolean) 


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

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.



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

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) 


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

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.



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

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) 


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

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.



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

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