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
- to contain the information necessary to identify the repository for reproducibility purposes (i.e. its URL)
- 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
.