python3-vcstools - Man Page
Name
vcstools — vcstools Documentation
The vcstools module provides a Python API for interacting with different version control systems (VCS/SCMs). The VcsClient class provides an API for seamless interacting with Git, Mercurial (Hg), Bzr and SVN. The focus of the API is manipulating on-disk checkouts of source-controlled trees. Its main use is to support the rosinstall tool.
General Vcs/Scm API
The VcsClient class provides a generic API for
- Subversion (svn)
- Mercurial (hg)
- Git (git)
- Bazaar (bzr)
- class vcstools.VcsClient(vcs_type, path)
API for interacting with source-controlled paths independent of actual version-control implementation.
- Parameters
- vcs_type – type of VCS to use (e.g. ‘svn’, ‘hg’, ‘bzr’, ‘git’), str
- path – filesystem path where code is/will be checked out , str
- path_exists() -> bool
- Returns
True if path exists on disk.
- get_path() -> str
- Returns
filesystem path this client is initialized with.
- url_matches(self, url, url_or_shortcut) -> bool
client can decide whether the url and the other url are equivalent. Checks string equality by default
- Parameters
url_or_shortcut – url or shortcut (e.g. bzr launchpad url)
- Returns
bool if params are equivalent
- get_version([spec=None]) -> str
- Parameters
spec –
token for identifying repository revision desired. Token might be a tagname, branchname, version-id, or SHA-ID depending on the VCS implementation.
- svn: anything accepted by svn info --help, e.g. a revnumber, {date}, HEAD, BASE, PREV, or COMMITTED
- git: anything accepted by git log, e.g. a tagname, branchname, or sha-id.
- hg: anything accepted by hg log -r, e.g. a tagname, sha-ID, revision-number
- bzr: revisionspec as returned by bzr help revisionspec, e.g. a tagname or revno:<number>
- Returns
current revision number of the repository. Or if spec is provided, the globally unique identifier (e.g. revision number, or SHA-ID) of a revision specified by some token.
- get_remote_version(self, fatch=False) -> str
Find an identifier for the current revision on remote. Token spec might be a tagname, version-id, SHA-ID, … depending on the VCS implementation.
- Parameters
fetch – if False, only local information may be used
- Returns
current revision number of the remote repository.
- get_current_version_label() -> str
Find an description for the current local version. Token spec might be a branchname, version-id, SHA-ID, … depending on the VCS implementation.
- returns
short description of local version (e.g. branchname, tagename).
- checkout(url[, version=''][, verbose=False][, shallow=False])
Checkout the given URL to the path associated with this client.
- Parameters
- url – URL of source control to check out
- version – specific version to check out
- verbose – flag to run verbosely
- shallow – flag to create shallow clone without history
- update(version)
Update the local checkout from upstream source control.
- detect_presence() -> bool
- Returns
True if path has a checkout with matching VCS type, e.g. if the type of this client is ‘svn’, the checkout at the path is managed by Subversion.
- get_vcs_type_name() -> str
- Returns
type of VCS this client is initialized with.
- get_url() -> str
- Returns
Upstream URL that this code was checked out from.
- get_branch_parent()
(Git Only)
- Returns
parent branch.
- get_diff([basepath=None])
- Parameters
basepath – compute diff relative to this path, if provided
- Returns
A string showing local differences
- get_status([basepath=None[, untracked=False]])
Calls scm status command. semantics of untracked are difficult to generalize. In SVN, this would be new files only. In git, hg, bzr, this would be changes that have not been added for commit.
- Parameters
- basepath – status path will be relative to this, if provided.
- untracked – If True, also show changes that would not commit
- Returns
A string summarizing locally modified files
Example:
import vcstools # interrogate an existing tree client = vcstools.VcsClient('svn', '/path/to/checkout') print client.get_url() print client.get_version() print client.get_diff() # create a new tree client = vcstools.VcsClient('hg', '/path/to/new/checkout') client.checkout('https://bitbucket.org/foo/bar')
vcstools is available on pypi and can be installed via pip
pip install vcstools
or easy_install:
easy_install vcstools
The vcstools module is meant to be used as a normal Python module. After it has been installed, you can import it normally and do not need to declare as a ROS package dependency.
Developer’s Guide
Code API
Packages
vcstools Package
vcstools Package
Library for tools that need to interact with ROS-support version control systems.
- vcstools.setup_logger()
creates a logger 'vcstools'
bzr Module
bzr vcs support.
- vcstools.bzr.BZRClient
alias of vcstools.bzr.BzrClient
- class vcstools.bzr.BzrClient(path)
Bases: vcstools.vcs_base.VcsClientBase
- checkout(url, version=None, verbose=False, shallow=False, timeout=None)
Attempts to create a local repository given a remote url. Fails if a target path exists, unless it's an empty directory. If a version is provided, the local repository will be updated to that revision. It is possible that after a failed call to checkout, a repository still exists, e.g. if an invalid revision was given. If shallow is provided, the scm client may checkout less than the full repository history to save time / disk space. If a timeout is specified, any pending operation will fail after the specified amount (in seconds). NOTE: this parameter might or might not be honored, depending on VCS client implementation. :param url: where to checkout from :type url: str :param version: token for identifying repository revision :type version: str :param shallow: hint to checkout less than a full repository :type shallow: bool :param timeout: maximum allocated time to perform operation :type shallow: int :returns: True if successful
- export_repository(version, basepath)
Calls scm equivalent to svn export, removing scm meta information and tar gzip'ing the repository at a given version to the given basepath.
- Parameters
version -- version of the repository to export. This can
be a branch, tag, or path (svn). When specifying the version as a path for svn, the path should be relative to the root of the svn repository, i.e. 'trunk', or 'tags/1.2.3', or './' for the root. :param basepath: this is the path to the tar gzip, excluding the extension which will be .tar.gz :returns: True on success, False otherwise.
- get_affected_files(revision)
Get the files that were affected by a specific revision :param revision: SHA or revision number. :returns: A list of strings with the files affected by a specific commit
- get_branches(local_only=False)
Returns a list of all branches in the vcs repository.
- Parameters
local_only -- if True it will only list local branches
- Returns
list of branches in the repository, [] if none exist
- get_current_version_label()
Find an description for the current local version. Token spec might be a branchname, version-id, SHA-ID, ... depending on the VCS implementation.
- Returns
short description of local version (e.g. branchname, tagename).
- Return type
str
- get_diff(basepath=None)
- Parameters
basepath -- diff paths will be relative to this, if any
- Returns
A string showing local differences
- Return type
str
- static get_environment_metadata()
For debugging purposes, returns a dict containing information about the environment, like the version of the SCM client, or version of libraries involved. Suggest considering keywords "version", "dependency", "features" first. :returns: a dict containing relevant information :rtype: dict
- get_log(relpath=None, limit=None)
Calls scm log command.
- This returns a list of dictionaries with the following fields:
- id: the commit SHA or revision number
- date: the date the commit was made (python datetime)
- author: the name of the author of the commit, if available
- email: the e-mail address of the author of the commit
- message: the commit message, if any
- Parameters
relpath -- (optional) restrict logs to events on this
resource path (folder or file) relative to the root of the repository. If None (default), this is the root of the repository. :param limit: (optional) the maximum number of log entries that should be retrieved. If None (default), there is no limit.
- get_remote_version(fetch=False)
Find an identifier for the current revision on remote. Token spec might be a tagname, version-id, SHA-ID, ... depending on the VCS implementation.
- Parameters
fetch -- if False, only local information may be used
- Returns
current revision number of the remote repository.
- Return type
str
- get_status(basepath=None, untracked=False)
Calls scm status command. Output must be terminated by newline unless empty.
Semantics of untracked are difficult to generalize. In SVN, this would be new files only. In git, hg, bzr, this would be changes that have not been added for commit.
Extra keyword arguments are passed along to the underlying vcs code. See the specific implementations of get_status() for extra options.
- Parameters
- basepath -- status path will be relative to this, if any
- untracked -- whether to also show changes that would not commit
- Returns
A string summarizing locally modified files
- Return type
str
- get_url()
- Returns
BZR URL of the branch (output of bzr info command),
or None if it cannot be determined
- get_version(spec=None)
- Parameters
spec -- (optional) revisionspec of desired version. May be any revisionspec as returned by 'bzr help revisionspec', e.g. a tagname or 'revno:<number>'
- Returns
the current revision number of the repository. Or if spec is provided, the number of a revision specified by some token.
- static static_detect_presence(path)
For auto detection
- update(version='', verbose=False, timeout=None)
Sets the local copy of the repository to a version matching the version parameter. Fails when there are uncommited changes. On failures (also e.g. network failure) grants the checked out files are in the same state as before the call. If a timeout is specified, any pending operation will fail after the specified amount (in seconds)
- Parameters
- version -- token for identifying repository revision desired. Token might be a tagname, branchname, version-id, SHA-ID, ... depending on the VCS implementation.
- timeout -- maximum allocated time to perform operation
- Returns
True on success, False else
- url_matches(url, url_or_shortcut)
client can decide whether the url and the other url are equivalent. Checks string equality by default :param url_or_shortcut: url or shortcut (e.g. bzr launchpad url) :returns: bool if params are equivalent
git Module
git vcs support.
refnames in git can be branchnames, hashes, partial hashes, tags. On checkout, git will disambiguate by checking them in that order, taking the first that applies
This class aims to provide git for linear centralized workflows. This means in case of ambiguity, we assume that the only relevant remote is the one named "origin", and we assume that commits once on origin remain on origin.
A challenge with git is that it has strong reasonable conventions, but is very allowing for breaking them. E.g. it is possible to name remotes and branches with names like "refs/heads/master", give branches and tags the same name, or a valid SHA-ID as name, etc. Similarly git allows plenty of ways to reference any object, in case of ambiguities, git attempts to take the most reasonable disambiguation, and in some cases warns.
- vcstools.git.GITClient
alias of vcstools.git.GitClient
- class vcstools.git.GitClient(path)
Bases: vcstools.vcs_base.VcsClientBase
- checkout(url, version=None, verbose=False, shallow=False, timeout=None)
calls git clone and then, if version was given, update(version)
- export_repository(version, basepath)
Calls scm equivalent to svn export, removing scm meta information and tar gzip'ing the repository at a given version to the given basepath.
- Parameters
version -- version of the repository to export. This can
be a branch, tag, or path (svn). When specifying the version as a path for svn, the path should be relative to the root of the svn repository, i.e. 'trunk', or 'tags/1.2.3', or './' for the root. :param basepath: this is the path to the tar gzip, excluding the extension which will be .tar.gz :returns: True on success, False otherwise.
- get_affected_files(revision)
Get the files that were affected by a specific revision :param revision: SHA or revision number. :returns: A list of strings with the files affected by a specific commit
- get_branches(local_only=False)
Returns a list of all branches in the vcs repository.
- Parameters
local_only -- if True it will only list local branches
- Returns
list of branches in the repository, [] if none exist
- get_current_version_label()
For git we change the label to clarify when a different remote is configured.
- get_default_remote_version_label()
Find a label for the default branch on remote, meaning the one that would be checked out on a clean checkout.
- Returns
a label or None (if not applicable)
- Return type
str
- get_diff(basepath=None)
- Parameters
basepath -- diff paths will be relative to this, if any
- Returns
A string showing local differences
- Return type
str
- static get_environment_metadata()
For debugging purposes, returns a dict containing information about the environment, like the version of the SCM client, or version of libraries involved. Suggest considering keywords "version", "dependency", "features" first. :returns: a dict containing relevant information :rtype: dict
- get_log(relpath=None, limit=None)
Calls scm log command.
- This returns a list of dictionaries with the following fields:
- id: the commit SHA or revision number
- date: the date the commit was made (python datetime)
- author: the name of the author of the commit, if available
- email: the e-mail address of the author of the commit
- message: the commit message, if any
- Parameters
relpath -- (optional) restrict logs to events on this
resource path (folder or file) relative to the root of the repository. If None (default), this is the root of the repository. :param limit: (optional) the maximum number of log entries that should be retrieved. If None (default), there is no limit.
- get_remote_version(fetch=False)
Find an identifier for the current revision on remote. Token spec might be a tagname, version-id, SHA-ID, ... depending on the VCS implementation.
- Parameters
fetch -- if False, only local information may be used
- Returns
current revision number of the remote repository.
- Return type
str
- get_status(basepath=None, untracked=False, porcelain=False)
Calls scm status command. Output must be terminated by newline unless empty.
Semantics of untracked are difficult to generalize. In SVN, this would be new files only. In git, hg, bzr, this would be changes that have not been added for commit.
Extra keyword arguments are passed along to the underlying vcs code. See the specific implementations of get_status() for extra options.
- Parameters
- basepath -- status path will be relative to this, if any
- untracked -- whether to also show changes that would not commit
- Returns
A string summarizing locally modified files
- Return type
str
- get_url()
- Returns
git URL of the directory path (output of git info command), or None if it cannot be determined
- get_version(spec=None)
- Parameters
- spec -- (optional) token to identify desired version. For git, this may be anything accepted by git log, e.g. a tagname, branchname, or sha-id.
- fetch -- When spec is given, can be used to suppress git fetch call
- Returns
current SHA-ID of the repository. Or if spec is provided, the SHA-ID of a commit specified by some token if found, else None
- is_tag(tag_name, fetch=True)
checks list of tags for match. Set fetch to False if you just fetched already.
- Returns
True if tag_name among known tags
- Raises
GitError when call to git fetch fails
- static static_detect_presence(path)
For auto detection
- update(version=None, verbose=False, force_fetch=False, timeout=None)
if version is None, attempts fast-forwarding current branch, if any.
Else interprets version as a local branch, remote branch, tagname, hash, etc.
If it is a branch, attempts to move to it unless already on it, and to fast-forward, unless not a tracking branch. Else go untracked on tag or whatever version is. Does not leave if current commit would become dangling.
- Returns
True if already up-to-date with remote or after successful fast_foward
- exception vcstools.git.GitError
Bases: Exception
hg Module
hg vcs support.
using ui object to redirect output into a string
- vcstools.hg.HGClient
alias of vcstools.hg.HgClient
- class vcstools.hg.HgClient(path)
Bases: vcstools.vcs_base.VcsClientBase
- checkout(url, version='', verbose=False, shallow=False, timeout=None)
Attempts to create a local repository given a remote url. Fails if a target path exists, unless it's an empty directory. If a version is provided, the local repository will be updated to that revision. It is possible that after a failed call to checkout, a repository still exists, e.g. if an invalid revision was given. If shallow is provided, the scm client may checkout less than the full repository history to save time / disk space. If a timeout is specified, any pending operation will fail after the specified amount (in seconds). NOTE: this parameter might or might not be honored, depending on VCS client implementation. :param url: where to checkout from :type url: str :param version: token for identifying repository revision :type version: str :param shallow: hint to checkout less than a full repository :type shallow: bool :param timeout: maximum allocated time to perform operation :type shallow: int :returns: True if successful
- export_repository(version, basepath)
Calls scm equivalent to svn export, removing scm meta information and tar gzip'ing the repository at a given version to the given basepath.
- Parameters
version -- version of the repository to export. This can
be a branch, tag, or path (svn). When specifying the version as a path for svn, the path should be relative to the root of the svn repository, i.e. 'trunk', or 'tags/1.2.3', or './' for the root. :param basepath: this is the path to the tar gzip, excluding the extension which will be .tar.gz :returns: True on success, False otherwise.
- get_affected_files(revision)
Get the files that were affected by a specific revision :param revision: SHA or revision number. :returns: A list of strings with the files affected by a specific commit
get_branch()
- get_branches(local_only=False)
Returns a list of all branches in the vcs repository.
- Parameters
local_only -- if True it will only list local branches
- Returns
list of branches in the repository, [] if none exist
- get_current_version_label()
- Parameters
spec -- (optional) spec can be what 'svn info --help' allows, meaning a revnumber, {date}, HEAD, BASE, PREV, or COMMITTED.
- Returns
current revision number of the repository. Or if spec provided, the number of a revision specified by some token.
- get_diff(basepath=None)
- Parameters
basepath -- diff paths will be relative to this, if any
- Returns
A string showing local differences
- Return type
str
- static get_environment_metadata()
For debugging purposes, returns a dict containing information about the environment, like the version of the SCM client, or version of libraries involved. Suggest considering keywords "version", "dependency", "features" first. :returns: a dict containing relevant information :rtype: dict
- get_log(relpath=None, limit=None)
Calls scm log command.
- This returns a list of dictionaries with the following fields:
- id: the commit SHA or revision number
- date: the date the commit was made (python datetime)
- author: the name of the author of the commit, if available
- email: the e-mail address of the author of the commit
- message: the commit message, if any
- Parameters
relpath -- (optional) restrict logs to events on this
resource path (folder or file) relative to the root of the repository. If None (default), this is the root of the repository. :param limit: (optional) the maximum number of log entries that should be retrieved. If None (default), there is no limit.
- get_remote_version(fetch=False)
Find an identifier for the current revision on remote. Token spec might be a tagname, version-id, SHA-ID, ... depending on the VCS implementation.
- Parameters
fetch -- if False, only local information may be used
- Returns
current revision number of the remote repository.
- Return type
str
- get_status(basepath=None, untracked=False)
Calls scm status command. Output must be terminated by newline unless empty.
Semantics of untracked are difficult to generalize. In SVN, this would be new files only. In git, hg, bzr, this would be changes that have not been added for commit.
Extra keyword arguments are passed along to the underlying vcs code. See the specific implementations of get_status() for extra options.
- Parameters
- basepath -- status path will be relative to this, if any
- untracked -- whether to also show changes that would not commit
- Returns
A string summarizing locally modified files
- Return type
str
- get_url()
- Returns
HG URL of the directory path. (output of hg paths
command), or None if it cannot be determined
- get_version(spec=None)
- Parameters
spec -- (optional) token for identifying version. spec can be a whatever is allowed by 'hg log -r', e.g. a tagname, sha-ID, revision-number
- Returns
the current SHA-ID of the repository. Or if spec is provided, the SHA-ID of a revision specified by some token.
- static static_detect_presence(path)
For auto detection
- update(version='', verbose=False, timeout=None)
Sets the local copy of the repository to a version matching the version parameter. Fails when there are uncommited changes. On failures (also e.g. network failure) grants the checked out files are in the same state as before the call. If a timeout is specified, any pending operation will fail after the specified amount (in seconds)
- Parameters
- version -- token for identifying repository revision desired. Token might be a tagname, branchname, version-id, SHA-ID, ... depending on the VCS implementation.
- timeout -- maximum allocated time to perform operation
- Returns
True on success, False else
svn Module
svn vcs support.
- vcstools.svn.SVNClient
alias of vcstools.svn.SvnClient
- class vcstools.svn.SvnClient(path)
Bases: vcstools.vcs_base.VcsClientBase
- checkout(url, version='', verbose=False, shallow=False, timeout=None)
Attempts to create a local repository given a remote url. Fails if a target path exists, unless it's an empty directory. If a version is provided, the local repository will be updated to that revision. It is possible that after a failed call to checkout, a repository still exists, e.g. if an invalid revision was given. If shallow is provided, the scm client may checkout less than the full repository history to save time / disk space. If a timeout is specified, any pending operation will fail after the specified amount (in seconds). NOTE: this parameter might or might not be honored, depending on VCS client implementation. :param url: where to checkout from :type url: str :param version: token for identifying repository revision :type version: str :param shallow: hint to checkout less than a full repository :type shallow: bool :param timeout: maximum allocated time to perform operation :type shallow: int :returns: True if successful
- export_repository(version, basepath)
Calls scm equivalent to svn export, removing scm meta information and tar gzip'ing the repository at a given version to the given basepath.
- Parameters
version -- version of the repository to export. This can
be a branch, tag, or path (svn). When specifying the version as a path for svn, the path should be relative to the root of the svn repository, i.e. 'trunk', or 'tags/1.2.3', or './' for the root. :param basepath: this is the path to the tar gzip, excluding the extension which will be .tar.gz :returns: True on success, False otherwise.
- get_affected_files(revision)
Get the files that were affected by a specific revision :param revision: SHA or revision number. :returns: A list of strings with the files affected by a specific commit
- get_branches(local_only=False)
Returns a list of all branches in the vcs repository.
- Parameters
local_only -- if True it will only list local branches
- Returns
list of branches in the repository, [] if none exist
- get_current_version_label()
Find an description for the current local version. Token spec might be a branchname, version-id, SHA-ID, ... depending on the VCS implementation.
- Returns
short description of local version (e.g. branchname, tagename).
- Return type
str
- get_diff(basepath=None)
- Parameters
basepath -- diff paths will be relative to this, if any
- Returns
A string showing local differences
- Return type
str
- static get_environment_metadata()
For debugging purposes, returns a dict containing information about the environment, like the version of the SCM client, or version of libraries involved. Suggest considering keywords "version", "dependency", "features" first. :returns: a dict containing relevant information :rtype: dict
- get_log(relpath=None, limit=None)
Calls scm log command.
- This returns a list of dictionaries with the following fields:
- id: the commit SHA or revision number
- date: the date the commit was made (python datetime)
- author: the name of the author of the commit, if available
- email: the e-mail address of the author of the commit
- message: the commit message, if any
- Parameters
relpath -- (optional) restrict logs to events on this
resource path (folder or file) relative to the root of the repository. If None (default), this is the root of the repository. :param limit: (optional) the maximum number of log entries that should be retrieved. If None (default), there is no limit.
- get_remote_version(fetch=False)
Find an identifier for the current revision on remote. Token spec might be a tagname, version-id, SHA-ID, ... depending on the VCS implementation.
- Parameters
fetch -- if False, only local information may be used
- Returns
current revision number of the remote repository.
- Return type
str
- get_status(basepath=None, untracked=False)
Calls scm status command. Output must be terminated by newline unless empty.
Semantics of untracked are difficult to generalize. In SVN, this would be new files only. In git, hg, bzr, this would be changes that have not been added for commit.
Extra keyword arguments are passed along to the underlying vcs code. See the specific implementations of get_status() for extra options.
- Parameters
- basepath -- status path will be relative to this, if any
- untracked -- whether to also show changes that would not commit
- Returns
A string summarizing locally modified files
- Return type
str
- get_url()
- Returns
SVN URL of the directory path (output of svn info command), or None if it cannot be determined
- get_version(spec=None)
- Parameters
- spec -- (optional) spec can be what 'svn info --help' allows, meaning a revnumber, {date}, HEAD, BASE, PREV, or COMMITTED.
- path -- the url to use, default is for this repo
- Returns
current revision number of the repository. Or if spec provided, the number of a revision specified by some token.
- static static_detect_presence(path)
For auto detection
- update(version=None, verbose=False, timeout=None)
Sets the local copy of the repository to a version matching the version parameter. Fails when there are uncommited changes. On failures (also e.g. network failure) grants the checked out files are in the same state as before the call. If a timeout is specified, any pending operation will fail after the specified amount (in seconds)
- Parameters
- version -- token for identifying repository revision desired. Token might be a tagname, branchname, version-id, SHA-ID, ... depending on the VCS implementation.
- timeout -- maximum allocated time to perform operation
- Returns
True on success, False else
- vcstools.svn.canonical_svn_url_split(url)
checks url for traces of canonical svn structure, and return root, type, name (of tag or branch), subfolder, query and fragment (see urllib urlparse) This should allow creating a different url for switching to a different tag or branch
- Parameters
url -- location of central repo, str
- Returns
dict {root, type, name, subfolder, query, fragment}
with type one of "trunk", "tags", "branches"
vcstools.svn.get_remote_contents(url)
tar Module
tar vcs support.
The implementation uses the "version" argument to indicate a subfolder within a tarfile. Hence one can organize sources by creating one tarfile with a folder inside for each version.
- vcstools.tar.TARClient
alias of vcstools.tar.TarClient
- class vcstools.tar.TarClient(path)
Bases: vcstools.vcs_base.VcsClientBase
- checkout(url, version='', verbose=False, shallow=False, timeout=None)
untars tar at url to self.path. If version was given, only the subdirectory 'version' of the tar will end up in self.path. Also creates a file next to the checkout named
*
.tar which is a yaml file listing origin url and version arguments.
- export_repository(version, basepath)
Calls scm equivalent to svn export, removing scm meta information and tar gzip'ing the repository at a given version to the given basepath.
- Parameters
version -- version of the repository to export. This can
be a branch, tag, or path (svn). When specifying the version as a path for svn, the path should be relative to the root of the svn repository, i.e. 'trunk', or 'tags/1.2.3', or './' for the root. :param basepath: this is the path to the tar gzip, excluding the extension which will be .tar.gz :returns: True on success, False otherwise.
- get_current_version_label()
Find an description for the current local version. Token spec might be a branchname, version-id, SHA-ID, ... depending on the VCS implementation.
- Returns
short description of local version (e.g. branchname, tagename).
- Return type
str
- get_diff(basepath=None)
- Parameters
basepath -- diff paths will be relative to this, if any
- Returns
A string showing local differences
- Return type
str
- static get_environment_metadata()
For debugging purposes, returns a dict containing information about the environment, like the version of the SCM client, or version of libraries involved. Suggest considering keywords "version", "dependency", "features" first. :returns: a dict containing relevant information :rtype: dict
- get_remote_version(fetch=False)
Find an identifier for the current revision on remote. Token spec might be a tagname, version-id, SHA-ID, ... depending on the VCS implementation.
- Parameters
fetch -- if False, only local information may be used
- Returns
current revision number of the remote repository.
- Return type
str
- get_status(basepath=None, untracked=False)
Calls scm status command. Output must be terminated by newline unless empty.
Semantics of untracked are difficult to generalize. In SVN, this would be new files only. In git, hg, bzr, this would be changes that have not been added for commit.
Extra keyword arguments are passed along to the underlying vcs code. See the specific implementations of get_status() for extra options.
- Parameters
- basepath -- status path will be relative to this, if any
- untracked -- whether to also show changes that would not commit
- Returns
A string summarizing locally modified files
- Return type
str
- get_url()
- Returns
TAR URL of the directory path (output of tar info
command), or None if it cannot be determined
- get_version(spec=None)
Find an identifier for a the current or a specified revision. Token spec might be a tagname, branchname, version-id, SHA-ID, ... depending on the VCS implementation.
- Parameters
spec (str) -- token for identifying repository revision
- Returns
current revision number of the repository. Or if spec is provided, the respective revision number.
- Return type
str
- static static_detect_presence(path)
For auto detection
- update(version='', verbose=False, timeout=None)
Does nothing except returning true if tar exists in same "version" as checked out with vcstools.
vcs_abstraction Module
undoc-members
show-inheritance
- vcstools.vcs_abstraction.VCSClient
alias of vcstools.vcs_abstraction.VcsClient
- class vcstools.vcs_abstraction.VcsClient(vcs_type, path)
DEPRECATED API for interacting with source-controlled paths independent of actual version-control implementation.
- vcstools.vcs_abstraction.get_registered_vcs_types()
- Returns
list of valid key to use as vcs_type
- vcstools.vcs_abstraction.get_vcs(vcs_type)
Returns the class interfacing with vcs of given type
- Parameters
vcs_type -- id of the tpye, e.g. git, svn, hg, bzr
- Returns
class extending VcsClientBase
- Raises
ValueError for unknown vcs_type
- vcstools.vcs_abstraction.get_vcs_client(vcs_type, path)
Returns a client with which to interact with the vcs at given path
- Parameters
vcs_type -- id of the tpye, e.g. git, svn, hg, bzr
- Returns
instance of VcsClientBase
- Raises
ValueError for unknown vcs_type
- vcstools.vcs_abstraction.register_vcs(vcs_type, clazz)
- Parameters
- vcs_type -- id, str
- clazz -- class extending VcsClientBase
vcs_base Module
vcs support library base class.
undoc-members
show-inheritance
- class vcstools.vcs_base.VcsClientBase(vcs_type_name, path)
parent class for all vcs clients, provides their public API
- checkout(url, version=None, verbose=False, shallow=False, timeout=None)
Attempts to create a local repository given a remote url. Fails if a target path exists, unless it's an empty directory. If a version is provided, the local repository will be updated to that revision. It is possible that after a failed call to checkout, a repository still exists, e.g. if an invalid revision was given. If shallow is provided, the scm client may checkout less than the full repository history to save time / disk space. If a timeout is specified, any pending operation will fail after the specified amount (in seconds). NOTE: this parameter might or might not be honored, depending on VCS client implementation. :param url: where to checkout from :type url: str :param version: token for identifying repository revision :type version: str :param shallow: hint to checkout less than a full repository :type shallow: bool :param timeout: maximum allocated time to perform operation :type shallow: int :returns: True if successful
- detect_presence()
For auto detection
- export_repository(version, basepath)
Calls scm equivalent to svn export, removing scm meta information and tar gzip'ing the repository at a given version to the given basepath.
- Parameters
version -- version of the repository to export. This can
be a branch, tag, or path (svn). When specifying the version as a path for svn, the path should be relative to the root of the svn repository, i.e. 'trunk', or 'tags/1.2.3', or './' for the root. :param basepath: this is the path to the tar gzip, excluding the extension which will be .tar.gz :returns: True on success, False otherwise.
- get_affected_files(revision)
Get the files that were affected by a specific revision :param revision: SHA or revision number. :returns: A list of strings with the files affected by a specific commit
- get_branches(local_only=False)
Returns a list of all branches in the vcs repository.
- Parameters
local_only -- if True it will only list local branches
- Returns
list of branches in the repository, [] if none exist
- get_current_version_label()
Find an description for the current local version. Token spec might be a branchname, version-id, SHA-ID, ... depending on the VCS implementation.
- Returns
short description of local version (e.g. branchname, tagename).
- Return type
str
- get_default_remote_version_label()
Find a label for the default branch on remote, meaning the one that would be checked out on a clean checkout.
- Returns
a label or None (if not applicable)
- Return type
str
- get_diff(basepath=None)
- Parameters
basepath -- diff paths will be relative to this, if any
- Returns
A string showing local differences
- Return type
str
- static get_environment_metadata()
For debugging purposes, returns a dict containing information about the environment, like the version of the SCM client, or version of libraries involved. Suggest considering keywords "version", "dependency", "features" first. :returns: a dict containing relevant information :rtype: dict
- get_log(relpath=None, limit=None)
Calls scm log command.
- This returns a list of dictionaries with the following fields:
- id: the commit SHA or revision number
- date: the date the commit was made (python datetime)
- author: the name of the author of the commit, if available
- email: the e-mail address of the author of the commit
- message: the commit message, if any
- Parameters
relpath -- (optional) restrict logs to events on this
resource path (folder or file) relative to the root of the repository. If None (default), this is the root of the repository. :param limit: (optional) the maximum number of log entries that should be retrieved. If None (default), there is no limit.
- get_path()
returns the path this client was configured for
- get_remote_version(fetch=False)
Find an identifier for the current revision on remote. Token spec might be a tagname, version-id, SHA-ID, ... depending on the VCS implementation.
- Parameters
fetch -- if False, only local information may be used
- Returns
current revision number of the remote repository.
- Return type
str
- get_status(basepath=None, untracked=False, **kwargs)
Calls scm status command. Output must be terminated by newline unless empty.
Semantics of untracked are difficult to generalize. In SVN, this would be new files only. In git, hg, bzr, this would be changes that have not been added for commit.
Extra keyword arguments are passed along to the underlying vcs code. See the specific implementations of get_status() for extra options.
- Parameters
- basepath -- status path will be relative to this, if any
- untracked -- whether to also show changes that would not commit
- Returns
A string summarizing locally modified files
- Return type
str
- get_url()
- Returns
The source control url for the path or None if not set
- Return type
str
- get_vcs_type_name()
used when auto detected
- get_version(spec=None)
Find an identifier for a the current or a specified revision. Token spec might be a tagname, branchname, version-id, SHA-ID, ... depending on the VCS implementation.
- Parameters
spec (str) -- token for identifying repository revision
- Returns
current revision number of the repository. Or if spec is provided, the respective revision number.
- Return type
str
- path_exists()
helper function
- static static_detect_presence(path)
For auto detection
- update(version=None, verbose=False, timeout=None)
Sets the local copy of the repository to a version matching the version parameter. Fails when there are uncommited changes. On failures (also e.g. network failure) grants the checked out files are in the same state as before the call. If a timeout is specified, any pending operation will fail after the specified amount (in seconds)
- Parameters
- version -- token for identifying repository revision desired. Token might be a tagname, branchname, version-id, SHA-ID, ... depending on the VCS implementation.
- timeout -- maximum allocated time to perform operation
- Returns
True on success, False else
- url_matches(url, url_or_shortcut)
client can decide whether the url and the other url are equivalent. Checks string equality by default :param url_or_shortcut: url or shortcut (e.g. bzr launchpad url) :returns: bool if params are equivalent
- exception vcstools.vcs_base.VcsError(value)
To be thrown when an SCM Client faces a situation because of a violated assumption
Changelog
Changelog
0.1
0.1.42
- remove cosmic and disco until we have hosting for it
0.1.41
- fix git submodule error due to lack of quoting
- Fix git update failure by refreshing git index before fast-forward
- Fix python3 incompatibility due to wrong use of urlopen
- Updating get_affected_files function by removing single quotes covering format (#129)
- Fix export_upstream for git submodules with relative urls. (#130)
0.1.40
- Trivial style and testing changes
0.1.39
- Added support for git submodule in export_repository
- Add Wily Xenial Yakkety
- Add get_affected_files for all vcss
0.1.38
- Fixed test failures due to SVN 1.9.
- Added the get_default_remote_version_label() API method to support changes in wstool.
- Renamed some internal functions to have a leading _ to indicate that they are private.
0.1.37
- Fix an issue where log were restricted to the named branch (hg).
- Fixed svn to use a global revision number rather than a branch-local revision.
- Added the get_remote_version() and get_current_version_label() API calls.
- Enhanced use of no_warn in run_shell_command().
- Fix get_version() to catch stderr.
- Added get_branches() API call.
- Fix some errors and warnings to output to stderr.
- Fix output to avoid extra newlines when show_stdout=True.
0.1.36
- Updates to the release platforms (-lucid +utopic +vivid)
- Fix an issue with updating branches on git, see vcstools/wstool#25
0.1.31
- Fix submodule support on checkout #71
0.1.30
- use netrc to download tars from private repos, also will work for private rosinstall files
- Fix checks for empty repository #62
0.1.29
- fix #57 shallow checkout of non-master breaks with git >= 1.8.0
- unit test fixes
0.1.28
- test of new upload method
0.1.27
- fix #51 hg status and diff dont work if workspace is inside hg repo
- fix #47 several performance improvements by removing unecessary update actions after checkout
- fix #46 https tar download fails behind proxy
- fix #45 sometimes commands run forever
- fix #44 minor bug when checking out from repo with default branch not master
- fix #41 improvedAPI, get_vcs_client function part of vcstools module
0.1.26
- fix #38 git commands fail in local repositories with many (>2000) references
- fix #31 get_log() svn xml not available on Ubuntu Lucid (hg 1.4.2)
- fix #37 update() returns True even when fetch failed
0.1.25
- minor bugfixes
- travis-ci config file
- fix unit tests for svn diff&status ordering changes
- deprecated VcsClient Class
- added get_log function
0.1.24
- fix git update return value to False when fast-forward not possible due to diverge
- fix. svn certificate prompt invisible, svn checkout and update become verbose due to this
0.1.22
- Changed the way that git implements detect_presence to fix a bug with submodules in newer versions of git
- fix for git single quotes on Windows
- minor internal api bug where a git function always returned True
- fix gub in svn export_repository
0.1.21
- bugfix #66: hg http username prompt hidden
- add export_repository method to vcs_base and all implementations with tests
- bugfix #64: unicode decoding problems
0.1.20
- rosws update –verbose for git prints small message when rebasing
- improved python3 compatibility
0.1.19
- more python3 compatibility
- code style improved
- match_url to compare bzr shortcuts to real urls
- more unit tests
- get_status required to end with newline, to fix #55
0.1.18
- added shallow flag to API, implemented for git
0.1.17
- svn stdout output on get_version removed
0.1.16
- All SCMs show some output when update caused changes
- All SCMs have verbose option to show all changes done on update
- bugfix for bazaar getUrl() being a joined abspath
- bugfix for not all output being shown when requested
0.1.15
- Added pyyaml as a proper dependency, removed detection code.
- remove use of tar entirely, switch to tarfile module
- fix #36 allowing for tar being bsdtar on OSX
0.1.14
- Added tarball uncompression.
0.1.13
- added this changelog
- git get-version fetches only when local lookup fails
- hg get-version pulls if label not found
- Popen error message incudes cwd path
0.1.12
- py_checker clean after all refactorings since 0.1.0
0.1.11
- svn and hg update without user interaction
- bugfix #30
- minor bugfixes
0.1.10
- minor bugs
0.1.9
- safer sanitization of shell params
- git diff and stat recurse for submodules
- base class manages all calls to Popen
0.1.8
- several bugfixes
- reverted using shell commands instead of bazaar API
0.1.7
- reverted using shell commands instaed of pysvn and mercurial APIs
- protection against shell incection attempts
0.1.6
- bugfixes to svn and bzr
- unified all calls through Popen
0.1.5
- missing dependency to dateutil added
0.1.4
switched shell calls to calls to python API of mercurial, bazaar, py-svn
0.1.3
- fix #6
0.1.2
- fix #15
0.1.1
- more unit tests
- diverse bugfixes
- major change to git client behavior, based around git https://kforge.ros.org/vcstools/trac/ticket/1
0.1.0
- documentation fixes
0.0.3
- import from svn
Bug reports and feature requests
- Submit a bug report
Developer Setup
vcstools uses setuptools, which you will need to download and install in order to run the packaging. We use setuptools instead of distutils in order to be able use setup() keys like install_requires.
cd vcstools python setup.py develop
Testing
Install test dependencies
pip install nose pip install mock
vcstools uses Python nose for testing, which is a fairly simple and straightfoward test framework. The vcstools mainly use unittest to construct test fixtures, but with nose you can also just write a function that starts with the name test and use normal assert statements.
vcstools also uses mock to create mocks for testing.
You can run the tests, including coverage, as follows:
cd vcstools make test
Documentation
Sphinx is used to provide API documentation for vcstools. The documents are stored in the doc subdirectory.
- genindex
- modindex
- search
Author
Tully Foote, Thibault Kruse, Ken Conley
Copyright
2021, Willow Garage