=============== Version control =============== .. module:: sumatra.versioncontrol The :mod:`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 :class:`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 :class:`Repository` class: * :class:`SubversionRepository`, * :class:`MercurialRepository`, * :class:`GitRepository`, * :class:`BazaarRepository`. These subclasses are only available if the appropriate Python bindings for the underlying VCS are installed - see :doc:`../installation`. Each of the subclasses implements the following interface: .. autoclass:: sumatra.versioncontrol.base.Repository :members: :inherited-members: :undoc-members: .. attribute:: url The repository URL, generally a local file system path for distributed VCSs. .. attribute:: upstream For distributed VCSs, the repository from which the local repository was cloned. Working copy objects ==================== :class:`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 :class:`WorkingCopy` class: * :class:`SubversionWorkingCopy`, * :class:`MercurialWorkingCopy`, * :class:`GitWorkingCopy`, * :class:`BazaarWorkingCopy`. Each of these subclasses implements the following interface: .. autoclass:: sumatra.versioncontrol.base.WorkingCopy :members: :inherited-members: :undoc-members: Functions ========= It is seldom necessary to create a :class:`Repository` or :class:`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. .. autofunction:: sumatra.versioncontrol.get_repository .. autofunction:: sumatra.versioncontrol.get_working_copy Exceptions ========== .. autoclass:: VersionControlError :members: .. autoclass:: UncommittedModificationsError :members: