Version control

The versioncontrol sub-package provides an abstraction layer around different revision/version control systems (VCSs). Only the functionality required for recording version numbers and switching the working copy between different versions is wrapped - for more complex tasks such as merging, branching, etc., the version control tool should be used directly.

Repository objects

A Repository object represents a version control repository. Its main roles in Sumatra are

1. to contain the information necessary to identify the repository for reproducibility purposes (i.e. its URL)
2. to provide a uniform interface for obtaining a working copy (“checkout” in Subversion parlance, “clone” for Git/Mercurial)

There are four subclasses of the abstract base Repository class:

• SubversionRepository,
• MercurialRepository,
• GitRepository,
• BazaarRepository.

These subclasses are only available if the appropriate Python bindings for the underlying VCS are installed - see Installation. Each of the subclasses implements the following interface:

class sumatra.versioncontrol.base.Repository(url, upstream=None)

Represents, and enables limited interaction with, the version control system repository located at url.

If upstream is not provided, this information will be obtained, if possible, from the version control system.

url

The repository URL, generally a local file system path for distributed VCSs.

upstream

For distributed VCSs, the repository from which the local repository was cloned.

checkout(path=u'.')

Clone a repository (“checkout” in Subversion) from self.url to the local filesystem at path.

exists

Does the repository represented by this object actually exist?

get_working_copy(path=None)

Return a WorkingCopy object corresponding to a checkout of this repository.

next()

required_attributes = (u'exists', u'checkout', u'get_working_copy')

vcs_type

Working copy objects

WorkingCopy objects provide functionality for inspecting the status of a version control working copy (which files have been modified, what version is currently checked out) and to change the version in use (to repeat previous computations, etc.)

There are four subclasses of the abstract base WorkingCopy class:

• SubversionWorkingCopy,
• MercurialWorkingCopy,
• GitWorkingCopy,
• BazaarWorkingCopy.

Each of these subclasses implements the following interface:

class sumatra.versioncontrol.base.WorkingCopy(path=None)

Represents, and enables limited interaction with, the version control system working copy located in the path directory.

If path is not specified, the current working directory is assumed.

For each version control system supported by Sumatra, there is a specific subclass of the abstract WorkingCopy base class.

contains(path)

Does the repository contain the file with the given path?

where path is relative to the working copy root.

current_version()

Return the version of the current state of the working copy.

diff()

Return the difference between working copy and repository.

exists

Does the working copy represented by this object actually exist?

get_username()

Return the username and e-mail of the current user, as understood by the version control system, in the format ‘username <e-mail>’.

has_changed()

Are there any uncommitted changes to the working copy?

next()

required_attributes = (u'contains', u'current_version', u'use_version', u'use_latest_version', u'status', u'has_changed', u'diff', u'get_username')

status()

Return a dict containing the sets of files that have been modified, added, removed, are missing, not under version control (‘unknown’), are being ignored, or are unchanged (‘clean’).

use_latest_version()

Switch the working copy to the most recent version.

Any uncommitted changes are retained/merged in.

use_version(version)

Switch the working copy to version.

If the working copy has uncommitted changes, raises an UncommittedModificationsError.

Functions

It is seldom necessary to create a Repository or WorkingCopy object directly, or even to know which version control system is in use. Instead, the following functions will return the correct object, given a URL or a filesystem path.

sumatra.versioncontrol.get_repository(url)

Return a Repository object which represents, and enables limited interaction with, the version control repository at url.

If no repository is found at url, raises a VersionControlError.

sumatra.versioncontrol.get_working_copy(path=None)

Return a WorkingCopy object which represents, and enables limited interaction with, the version control working copy at path.

If path is not specified, the current working directory is used. If no working copy is found at path, raises a VersionControlError.

Exceptions

class sumatra.versioncontrol.VersionControlError

class sumatra.versioncontrol.UncommittedModificationsError