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. arevnumber
,{date}
,HEAD
,BASE
,PREV
, orCOMMITTED
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-numberbzr: revisionspec as returned by
bzr help revisionspec
, e.g. a tagname orrevno:<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