# eric7.VCS.VersionControl

Module implementing an abstract base class to be subclassed by all specific VCS interfaces.

### Global Attributes

None

### Classes

VersionControl | Class implementing an abstract base class to be subclassed by all specific VCS interfaces.

### Functions

None

## VersionControl

Class implementing an abstract base class to be subclassed by all specific VCS interfaces.

It defines the vcs interface to be implemented by subclasses and the common methods.

### Signals

committed()
  emitted after the commit action has completed
vcsStatusChanged()
  emitted to indicate a change of the overall VCS status
vcsStatusMonitorAllData(dict)
  emitted to signal all VCS status (key is project relative file name, value is status)
vcsStatusMonitorData(list of str)
  emitted to update the VCS status
vcsStatusMonitorInfo(str)
  emitted to signal some info of the monitoring thread
vcsStatusMonitorStatus(str, str)
  emitted to signal the status of the monitoring thread (ok, nok, op, off) and a status message

### Derived from

QObject

### Class Attributes

canBeAdded
canBeCommitted
commitHistoryData
commitHistoryLock

### Class Methods

None

### Methods

VersionControl | Constructor
__statusMonitorAllData | Private method to receive all status monitor data.
__statusMonitorData | Private method to receive the status monitor data update.
__statusMonitorInfo | Private slot to receive the status monitor info message.
__statusMonitorStatus | Private slot to receive the status monitor status.
_createStatusMonitorThread | Protected method to create an instance of the VCS status monitor thread.
_vcsAddProjectCommitMessage | Protected method to add a commit message to the list of project specific saved messages.
_vcsClearProjectCommitMessages | Protected method to clear the list of project specific saved messages.
_vcsProjectCommitMessages | Protected method to get the list of saved commit messages.
addArguments | Public method to add an argument list to the already present arguments.
checkVCSStatus | Public method to wake up the VCS status monitor thread.
clearStatusCache | Public method to clear the status cache.
clearStatusMonitorCachedState | Public method to clear the cached VCS state of a file/directory.
getStatusMonitorAutoUpdate | Public method to retrieve the status of the auto update function.
getStatusMonitorInterval | Public method to get the monitor interval.
setStatusMonitorAutoUpdate | Public method to enable the auto update function.
setStatusMonitorInterval | Public method to change the monitor interval.
splitPath | Public method splitting name into a directory part and a file part.
splitPathList | Public method splitting the list of names into a common directory part and a file list.
startStatusMonitor | Public method to start the VCS status monitor thread.
startSynchronizedProcess | Public method to start a synchroneous process.
stopStatusMonitor | Public method to stop the VCS status monitor thread.
vcsAdd | Public method used to add a file/directory in the vcs.
vcsAddBinary | Public method used to add a file/directory in binary mode in the vcs.
vcsAddCommitMessage | Public method to add a commit message to the list of saved messages.
vcsAddTree | Public method to add a directory tree rooted at path in the vcs.
vcsAllRegisteredStates | Public method used to get the registered states of a number of files in the vcs.
vcsCheckout | Public method used to check the project out of the vcs.
vcsCleanup | Public method used to cleanup the local copy.
vcsClearCommitMessages | Public method to clear the list of saved messages.
vcsCommandLine | Public method used to execute arbitrary vcs commands.
vcsCommit | Public method used to make the change of a file/directory permanent in the vcs.
vcsCommitMessages | Public method to get the list of saved commit messages.
vcsConvertProject | Public method to convert an uncontrolled project to a version controlled project.
vcsDiff | Public method used to view the diff of a file/directory in the vcs.
vcsExists | Public method used to test for the presence of the vcs.
vcsExport | Public method used to export a directory from the vcs.
vcsForget | Public method used to remove a file from the repository.
vcsGetOptions | Public method used to retrieve the options of the vcs.
vcsGetOtherData | Public method used to retrieve vcs specific data.
vcsGetProjectBrowserHelper | Public method to instanciate a helper object for the different project browsers.
vcsGetProjectHelper | Public method to instanciate a helper object for the project.
vcsImport | Public method used to import the project into the vcs.
vcsInit | Public method used to initialize the vcs.
vcsInitConfig | Public method to initialize the VCS configuration.
vcsLogBrowser | Public method used to view the log of a file/directory in the vcs with a log browser dialog.
vcsMerge | Public method used to merge a tag/branch into the local project.
vcsMove | Public method used to move a file/directory.
vcsName | Public method returning the name of the vcs.
vcsNewProjectOptionsDialog | Public method to get a dialog to enter repository info for getting a new project.
vcsOptionsDialog | Public method to get a dialog to enter repository info.
vcsRegisteredState | Public method used to get the registered state of a file in the vcs.
vcsRemove | Public method used to add a file/directory in the vcs.
vcsRepositoryInfos | Public method to retrieve information about the repository.
vcsResolved | Public method used to resolve conflicts of a file/directory.
vcsRevert | Public method used to revert changes made to a file/directory.
vcsSbsDiff | Public method used to view the difference of a file to the Mercurial repository side-by-side.
vcsSetData | Public method used to set an entry in the otherData dictionary.
vcsSetDataFromDict | Public method used to set entries in the otherData dictionary.
vcsSetOptions | Public method used to set the options for the vcs.
vcsSetOtherData | Public method used to set vcs specific data.
vcsShutdown | Public method used to shutdown the vcs interface.
vcsStatus | Public method used to view the status of a file/directory in the vcs.
vcsSupportCommandOptions | Public method to signal the support of user settable command options.
vcsSwitch | Public method used to switch a directory to a different tag/branch.
vcsTag | Public method used to set the tag of a file/directory in the vcs.
vcsUpdate | Public method used to update a file/directory in the vcs.

### Static Methods

None

#### VersionControl (Constructor)

VersionControl(parent=None, name=None)

Constructor

parent
  parent widget (QWidget)
name
  name of this object (string)

#### VersionControl.__statusMonitorAllData

__statusMonitorAllData(statusDict)

Private method to receive all status monitor data.

It simply re-emits the received status list.

statusDict (dict)
  dictionary of status records

#### VersionControl.__statusMonitorData

__statusMonitorData(statusList)

Private method to receive the status monitor data update.

It simply re-emits the received status list.

statusList (list of str)
  list of status records

#### VersionControl.__statusMonitorInfo

__statusMonitorInfo(info)

Private slot to receive the status monitor info message.

It simply re-emits the received info message.

info (str)
  received info message

#### VersionControl.__statusMonitorStatus

__statusMonitorStatus(status, statusMsg)

Private slot to receive the status monitor status.

It simply re-emits the received status.

status (str (one of ok, nok or off))
  status of the monitoring thread
statusMsg (str)
  explanotory text for the signaled status

#### VersionControl._createStatusMonitorThread

_createStatusMonitorThread(interval, project)

Protected method to create an instance of the VCS status monitor thread.

Note: This method should be overwritten in subclasses in order to support VCS status monitoring.

interval
  check interval for the monitor thread in seconds (integer)
project
  reference to the project object

Return:
  reference to the monitor thread (QThread)

#### VersionControl._vcsAddProjectCommitMessage

_vcsAddProjectCommitMessage(message)

Protected method to add a commit message to the list of project specific saved messages.

message (str)
  message to be added

Return:
  flag indicating success

Return Type:
  bool

#### VersionControl._vcsClearProjectCommitMessages

_vcsClearProjectCommitMessages()

Protected method to clear the list of project specific saved messages.

Return:
  flag indicating success

Return Type:
  bool

#### VersionControl._vcsProjectCommitMessages

_vcsProjectCommitMessages()

Protected method to get the list of saved commit messages.

Return:
  list of saved commit messages

Return Type:
  list of str

#### VersionControl.addArguments

addArguments(args, argslist)

Public method to add an argument list to the already present arguments.

args
  current arguments list (list of strings)
argslist
  list of arguments (list of strings)

#### VersionControl.checkVCSStatus

checkVCSStatus()

Public method to wake up the VCS status monitor thread.

#### VersionControl.clearStatusCache

clearStatusCache()

Public method to clear the status cache.

#### VersionControl.clearStatusMonitorCachedState

clearStatusMonitorCachedState(name)

Public method to clear the cached VCS state of a file/directory.

name
  name of the entry to be cleared (string)

#### VersionControl.getStatusMonitorAutoUpdate

getStatusMonitorAutoUpdate()

Public method to retrieve the status of the auto update function.

Return:
  status of the auto update function (boolean)

#### VersionControl.getStatusMonitorInterval

getStatusMonitorInterval()

Public method to get the monitor interval.

Return:
  interval in seconds (integer)

#### VersionControl.setStatusMonitorAutoUpdate

setStatusMonitorAutoUpdate(auto)

Public method to enable the auto update function.

auto
  status of the auto update function (boolean)

#### VersionControl.setStatusMonitorInterval

setStatusMonitorInterval(interval, project)

Public method to change the monitor interval.

interval
  new interval in seconds (integer)
project
  reference to the project object

#### VersionControl.splitPath

splitPath(name)

Public method splitting name into a directory part and a file part.

name
  path name (string)

Return:
  a tuple of 2 strings (dirname, filename).

#### VersionControl.splitPathList

splitPathList(names)

Public method splitting the list of names into a common directory part and a file list.

names
  list of paths (list of strings)

Return:
  a tuple of string and list of strings (dirname, filenamelist)

#### VersionControl.startStatusMonitor

startStatusMonitor(project)

Public method to start the VCS status monitor thread.

project
  reference to the project object

Return:
  reference to the monitor thread (QThread)

#### VersionControl.startSynchronizedProcess

startSynchronizedProcess(proc, program, arguments, workingDir=None)

Public method to start a synchroneous process.

This method starts a process and waits for its end while still serving the Qt event loop.

proc
  process to start (QProcess)
program
  path of the executable to start (string)
arguments
  list of arguments for the process (list of strings)
workingDir
  working directory for the process (string)

Return:
  flag indicating normal exit (boolean)

#### VersionControl.stopStatusMonitor

stopStatusMonitor()

Public method to stop the VCS status monitor thread.

#### VersionControl.vcsAdd

vcsAdd(name, isDir=False, noDialog=False)

Public method used to add a file/directory in the vcs.

name
  file/directory name to be added (string)
isDir
  flag indicating name is a directory (boolean)
noDialog
  flag indicating quiet operations (boolean)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsAddBinary

vcsAddBinary(name, isDir=False)

Public method used to add a file/directory in binary mode in the vcs.

name
  file/directory name to be added (string)
isDir
  flag indicating name is a directory (boolean)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsAddCommitMessage

vcsAddCommitMessage(message)

Public method to add a commit message to the list of saved messages.

message (str)
  message to be added

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsAddTree

vcsAddTree(path)

Public method to add a directory tree rooted at path in the vcs.

path
  root directory of the tree to be added (string)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsAllRegisteredStates

vcsAllRegisteredStates(names, dname)

Public method used to get the registered states of a number of files in the vcs.

names
  dictionary with all filenames to be checked as keys
dname
  directory to check in (string)

Return:
  the received dictionary completed with a combination of canBeCommited and canBeAdded or None in order to signal an error

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsCheckout

vcsCheckout(vcsDataDict, projectDir, noDialog=False)

Public method used to check the project out of the vcs.

vcsDataDict
  dictionary of data required for the checkout
projectDir
  project directory to create (string)
noDialog
  flag indicating quiet operations

Return:
  flag indicating an execution without errors (boolean)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsCleanup

vcsCleanup(name)

Public method used to cleanup the local copy.

name
  directory name to be cleaned up (string)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsClearCommitMessages

vcsClearCommitMessages()

Public method to clear the list of saved messages.

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsCommandLine

vcsCommandLine(name)

Public method used to execute arbitrary vcs commands.

name
  directory name of the working directory (string)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsCommit

vcsCommit(name, message, noDialog=False)

Public method used to make the change of a file/directory permanent in the vcs.

name
  file/directory name to be committed (string)
message
  message for this operation (string)
noDialog
  flag indicating quiet operations (boolean)

Return:
  flag indicating success (boolean)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsCommitMessages

vcsCommitMessages()

Public method to get the list of saved commit messages.

Return:
  list of saved commit messages

Return Type:
  list of str

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsConvertProject

vcsConvertProject(vcsDataDict, project, addAll=True)

Public method to convert an uncontrolled project to a version controlled project.

vcsDataDict (dict)
  dictionary of data required for the conversion
project (Project)
  reference to the project object
addAll (bool)
  flag indicating to add all files to the repository

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsDiff

vcsDiff(name)

Public method used to view the diff of a file/directory in the vcs.

name
  file/directory name to be diffed (string)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsExists

vcsExists()

Public method used to test for the presence of the vcs.

Return:
  tuple of flag indicating the existence and a string giving an error message in case of failure

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsExport

vcsExport(vcsDataDict, projectDir)

Public method used to export a directory from the vcs.

vcsDataDict
  dictionary of data required for the export
projectDir
  project directory to create (string)

Return:
  flag indicating an execution without errors (boolean)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsForget

vcsForget(name)

Public method used to remove a file from the repository.

name (str or list of str)
  file/directory name to be removed

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsGetOptions

vcsGetOptions()

Public method used to retrieve the options of the vcs.

Return:
  a dictionary of option strings that can be passed to vcsSetOptions.

#### VersionControl.vcsGetOtherData

vcsGetOtherData()

Public method used to retrieve vcs specific data.

Return:
  a dictionary of vcs specific data

#### VersionControl.vcsGetProjectBrowserHelper

vcsGetProjectBrowserHelper(browser, project, isTranslationsBrowser=False)

Public method to instanciate a helper object for the different project browsers.

browser
  reference to the project browser object
project
  reference to the project object
isTranslationsBrowser
  flag indicating, the helper is requested for the translations browser (this needs some special treatment)

Return:
  the project browser helper object

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsGetProjectHelper

vcsGetProjectHelper(project)

Public method to instanciate a helper object for the project.

project
  reference to the project object

Return:
  the project helper object

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsImport

vcsImport(vcsDataDict, projectDir, noDialog=False, addAll=True)

Public method used to import the project into the vcs.

vcsDataDict (dict)
  dictionary of data required for the import
projectDir (str)
  project directory (string)
noDialog (bool)
  flag indicating quiet operations
addAll (bool)
  flag indicating to add all files to the repository

Return:
  tuple containing a flag indicating an execution without errors and a flag indicating the version control status

Return Type:
  tuple of (bool, bool)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsInit

vcsInit(vcsDir, noDialog=False)

Public method used to initialize the vcs.

vcsDir
  name of the VCS directory (string)
noDialog
  flag indicating quiet operations (boolean)

Return:
  flag indicating success (boolean)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsInitConfig

vcsInitConfig(project)

Public method to initialize the VCS configuration.

This method could ensure, that certain files or directories are exclude from being version controlled.

project
  reference to the project (Project)

#### VersionControl.vcsLogBrowser

vcsLogBrowser(name, isFile=False)

Public method used to view the log of a file/directory in the vcs with a log browser dialog.

name
  file/directory name to show the log for (string)
isFile
  flag indicating log for a file is to be shown (boolean)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsMerge

vcsMerge(name)

Public method used to merge a tag/branch into the local project.

name
  file/directory name to be merged (string)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsMove

vcsMove(name, project, target=None, noDialog=False)

Public method used to move a file/directory.

name
  file/directory name to be moved (string)
project
  reference to the project object
target
  new name of the file/directory (string)
noDialog
  flag indicating quiet operations

Return:
  flag indicating successfull operation (boolean)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsName

vcsName()

Public method returning the name of the vcs.

Return:
  name of the vcs (string)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsNewProjectOptionsDialog

vcsNewProjectOptionsDialog(parent=None)

Public method to get a dialog to enter repository info for getting a new project.

parent
  parent widget (QWidget)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsOptionsDialog

vcsOptionsDialog(project, archive, editable=False, parent=None)

Public method to get a dialog to enter repository info.

project
  reference to the project object
archive
  name of the project in the repository (string)
editable
  flag indicating that the project name is editable (boolean)
parent
  parent widget (QWidget)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsRegisteredState

vcsRegisteredState(name)

Public method used to get the registered state of a file in the vcs.

name
  filename to check (string)

Return:
  a combination of canBeCommited and canBeAdded or 0 in order to signal an error

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsRemove

vcsRemove(name, project=False, noDialog=False)

Public method used to add a file/directory in the vcs.

name
  file/directory name to be removed (string)
project
  flag indicating deletion of a project tree (boolean)
noDialog
  flag indicating quiet operations

Return:
  flag indicating success (boolean)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsRepositoryInfos

vcsRepositoryInfos(ppath)

Public method to retrieve information about the repository.

ppath
  local path to get the repository infos (string)

Return:
  string with ready formated info for display (string)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsResolved

vcsResolved(name)

Public method used to resolve conflicts of a file/directory.

name (str)
  file/directory name to be resolved

#### VersionControl.vcsRevert

vcsRevert(name)

Public method used to revert changes made to a file/directory.

name (str)
  file/directory name to be reverted

Return:
  flag indicating, that the update contained an add or delete

Return Type:
  bool

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsSbsDiff

vcsSbsDiff(name, extended=False, revisions=None)

Public method used to view the difference of a file to the Mercurial repository side-by-side.

name (str)
  file name to be diffed
extended (bool)
  flag indicating the extended variant
revisions (tuple of two str)
  tuple of two revisions

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsSetData

vcsSetData(key, value)

Public method used to set an entry in the otherData dictionary.

key
  the key of the data (string)
value
  the value of the data

#### VersionControl.vcsSetDataFromDict

vcsSetDataFromDict(dictionary)

Public method used to set entries in the otherData dictionary.

dictionary
  dictionary to pick entries from

#### VersionControl.vcsSetOptions

vcsSetOptions(options)

Public method used to set the options for the vcs.

options
  a dictionary of option strings with keys as defined by the default options

#### VersionControl.vcsSetOtherData

vcsSetOtherData(data)

Public method used to set vcs specific data.

data
  a dictionary of vcs specific data

#### VersionControl.vcsShutdown

vcsShutdown()

Public method used to shutdown the vcs interface.

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsStatus

vcsStatus(name)

Public method used to view the status of a file/directory in the vcs.

name
  file/directory name to show the status for (string)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsSupportCommandOptions

vcsSupportCommandOptions()

Public method to signal the support of user settable command options.

Return:
  flag indicating the support of user settable command options (boolean)

#### VersionControl.vcsSwitch

vcsSwitch(name)

Public method used to switch a directory to a different tag/branch.

name
  directory name to be switched (string)

Return:
  flag indicating, that the switch contained an add or delete (boolean)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsTag

vcsTag(name)

Public method used to set the tag of a file/directory in the vcs.

name
  file/directory name to be tagged (string)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

#### VersionControl.vcsUpdate

vcsUpdate(name, noDialog=False)

Public method used to update a file/directory in the vcs.

name
  file/directory name to be updated (string)
noDialog
  flag indicating quiet operations (boolean)

Return:
  flag indicating, that the update contained an add or delete (boolean)

Raises RuntimeError:
  to indicate that this method must be implemented by a subclass

Up