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

__init__(path)¶

Raises:	VcsError if bzr not detected

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

vcstools.bzr._get_bzr_version()¶: Looks up bzr version by calling bzr –version. :raises: VcsError if bzr is not installed

`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

__init__(path)¶

Raises:	VcsError if git not detected

_do_checkout(refname, fetch=True, verbose=False)¶

meaning git checkout, not vcstools checkout. This works for local branches, remote branches, tagnames, hashes, etc. git will create local branch of same name when no such local branch exists, and also setup tracking. Git decides with own rules whether local changes would cause conflicts, and refuses to checkout else.

Raises:	GitError – when checkout fails

_do_fast_forward(branch_parent, fetch=True, verbose=False)¶

Execute git fetch if necessary, and if we can fast-foward, do so to the last fetched version using git rebase.

Parameters:	branch_parent – name of branch we track fetch – whether fetch should be done first for remote refs
Returns:	True if up-to-date or after succesful fast-forward
Raises:	GitError when git fetch fails

_do_fetch(timeout=None)¶: calls git fetch :raises: GitError when call fails

_do_update(refname=None, verbose=False, fast_foward=True, timeout=None, update_submodules=True)¶

updates without fetching, thus any necessary fetching must be done before allows arguments to reduce unnecessary steps after checkout

Parameters:	fast_foward – if false, does not perform fast-forward update_submodules – if false, does not attempt to update submodules

_get_branch()¶

_get_branch_parent(fetch=False, current_branch=None)¶

Parameters:	fetch – if true, performs git fetch first current_branch – if not None, this is used as current branch (else extra shell call)
Returns:	(branch, remote) the name of the branch this branch tracks and its remote
Raises:	GitError if fetch fails

_get_default_remote()¶: in order to support users who name their default origin something else than origin, read remote name.

_is_commit_in_orphaned_subtree(version, mask_self=False, fetch=True)¶

checks git log –all (the list of all commits reached by references, meaning branches or tags) for version. If it shows up, that means git garbage collection will not remove the commit. Else it would eventually be deleted.

Parameters:	version – SHA IDs (if partial, caller is responsible for mismatch) mask_self – whether to consider direct references to this commit (rather than only references on descendants) as well fetch – whether fetch should be done first for remote refs
Returns:	True if version is not recursively referenced by a branch or tag
Raises:	GitError if git fetch fails

_is_local_branch(branch_name)¶

_is_remote_branch(branch_name, remote_name=None, fetch=True)¶

checks list of remote branches for match. Set fetch to False if you just fetched already.

Returns:	True if branch_name exists for remote <remote_name> (or ‘origin’ if None)
Raises:	GitError when git fetch fails

_rev_list_contains(refname, version, fetch=True)¶

calls git rev-list with refname and returns True if version can be found in rev-list result

Parameters:	refname – a git refname version – an SHA IDs (if partial, caller is responsible for mismatch)
Returns:	True if version is an ancestor commit from refname
Raises:	GitError when call to git fetch fails

_update_submodules(verbose=False, timeout=None)¶

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

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

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

vcstools.git._get_git_version()¶

Looks up git version by calling git –version.

Raises:	VcsError if git is not installed or returns

something unexpected

vcstools.git._git_diff_path_submodule_change(diff, rel_path_prefix)¶: Parses git diff result and changes the filename prefixes.

`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

__init__(path)¶

Raises:	VcsError if hg not detected

_do_pull(filter=False)¶

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

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

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)¶

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.hg._get_hg_version()¶: Looks up hg version by calling hg –version. :raises: VcsError if hg is not installed

vcstools.hg._hg_diff_path_change(diff, path)¶: Parses hg diff result and changes the filename prefixes.

`svn` Module¶

svn vcs support.

vcstools.svn.SVNClient¶: alias of vcstools.svn.SvnClient

class vcstools.svn.SvnClient(path)¶

Bases: vcstools.vcs_base.VcsClientBase

__init__(path)¶

Raises:	VcsError if python-svn not detected

_get_version_from_path(spec=None, path=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.

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

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

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)¶

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._get_svn_version()¶: Looks up svn version by calling svn –version. :raises: VcsError if svn is not installed

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

__init__(path)¶: @raise VcsError if tar not detected

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

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¶

vcstools.vcs_abstraction.VCSClient¶: alias of vcstools.vcs_abstraction.VcsClient

class vcstools.vcs_abstraction.VcsClient(vcs_type, path)¶

Bases: object

DEPRECATED API for interacting with source-controlled paths independent of actual version-control implementation.

__init__(vcs_type, path)¶: Initialize self. See help(type(self)) for accurate signature.

checkout(url, version='', verbose=False, shallow=False)¶

detect_presence()¶

export_repository(version, basepath)¶

get_branches(local_only=False)¶

get_current_version_label()¶

get_default_remote_version_label()¶

get_diff(basepath=None)¶

get_log(relpath=None, limit=None)¶

get_path()¶

get_remote_version(fetch=False)¶

get_status(basepath=None, untracked=False, **kwargs)¶

get_url()¶

get_vcs_type_name()¶

get_version(spec=None)¶

path_exists()¶

update(version='', verbose=False)¶

url_matches(url, url_or_shortcut)¶

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.

class vcstools.vcs_base.VcsClientBase(vcs_type_name, path)¶

Bases: object

parent class for all vcs clients, provides their public API

__init__(vcs_type_name, path)¶: subclasses may raise VcsError when a dependency is missing

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

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

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)¶

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)¶

Bases: Exception

To be thrown when an SCM Client faces a situation because of a violated assumption

__init__(value)¶: Initialize self. See help(type(self)) for accurate signature.

__str__()¶: Return str(self).

vcstools Package¶