1VCSTOOLS(1) vcstools VCSTOOLS(1)
2
6 vcstools - vcstools Documentation
7 The vcstools module provides a Python API for interacting with differ‐
9 ent version control systems (VCS/SCMs). The VcsClient class provides
10 an API for seamless interacting with Git, Mercurial (Hg), Bzr and SVN.
11 The focus of the API is manipulating on-disk checkouts of source-con‐
12 trolled trees. Its main use is to support the rosinstall tool.
13
15 The VcsClient class provides a generic API for
16 • Subversion (svn)
18 • Mercurial (hg)
20 • Git (git)
22 • Bazaar (bzr)
24 class vcstools.VcsClient(vcs_type, path)
26 API for interacting with source-controlled paths independent of
27 actual version-control implementation.
28 Parameters
30 • vcs_type – type of VCS to use (e.g. ‘svn’, ‘hg’, ‘bzr’,
32 ‘git’), str
33 • path – filesystem path where code is/will be checked
35 out , str
36 path_exists() -> bool
38 Returns
40 True if path exists on disk.
41 get_path() -> str
43 Returns
45 filesystem path this client is initialized with.
46 url_matches(self, url, url_or_shortcut) -> bool
48 client can decide whether the url and the other url are
49 equivalent. Checks string equality by default
50 Parameters
52 url_or_shortcut – url or shortcut (e.g. bzr
53 launchpad url)
54 Returns
56 bool if params are equivalent
57 get_version([spec=None]) -> str
59 Parameters
61 spec –
62 token for identifying repository revision desired.
64 Token might be a tagname, branchname, version-id,
65 or SHA-ID depending on the VCS implementation.
66 • svn: anything accepted by svn info --help, e.g.
68 a revnumber, {date}, HEAD, BASE, PREV, or COM‐
69 MITTED
70 • git: anything accepted by git log, e.g. a tag‐
72 name, branchname, or sha-id.
73 • hg: anything accepted by hg log -r, e.g. a tag‐
75 name, sha-ID, revision-number
76 • bzr: revisionspec as returned by bzr help revi‐
78 sionspec, e.g. a tagname or revno:<number>
79 Returns
82 current revision number of the repository. Or if
83 spec is provided, the globally unique identifier
84 (e.g. revision number, or SHA-ID) of a revision
85 specified by some token.
86 get_remote_version(self, fatch=False) -> str
88 Find an identifier for the current revision on remote.
89 Token spec might be a tagname, version-id, SHA-ID, … de‐
90 pending on the VCS implementation.
91 Parameters
93 fetch – if False, only local information may be
94 used
95 Returns
97 current revision number of the remote repository.
98 get_current_version_label() -> str
100 Find an description for the current local version. Token
101 spec might be a branchname, version-id, SHA-ID, … depend‐
102 ing on the VCS implementation.
103 returns
105 short description of local version (e.g.
106 branchname, tagename).
107 checkout(url[, version=''][, verbose=False][, shallow=False])
109 Checkout the given URL to the path associated with this
110 client.
111 Parameters
113 • url – URL of source control to check out
115 • version – specific version to check out
117 • verbose – flag to run verbosely
119 • shallow – flag to create shallow clone without
121 history
122 update(version)
124 Update the local checkout from upstream source control.
125 detect_presence() -> bool
127 Returns
129 True if path has a checkout with matching VCS
130 type, e.g. if the type of this client is ‘svn’,
131 the checkout at the path is managed by Subversion.
132 get_vcs_type_name() -> str
134 Returns
136 type of VCS this client is initialized with.
137 get_url() -> str
139 Returns
141 Upstream URL that this code was checked out from.
142 get_branch_parent()
144 (Git Only)
145 Returns
147 parent branch.
148 get_diff([basepath=None])
150 Parameters
152 basepath – compute diff relative to this path, if
153 provided
154 Returns
156 A string showing local differences
157 get_status([basepath=None[, untracked=False]])
159 Calls scm status command. semantics of untracked are dif‐
160 ficult to generalize. In SVN, this would be new files
161 only. In git, hg, bzr, this would be changes that have
162 not been added for commit.
163 Parameters
165 • basepath – status path will be relative to this,
167 if provided.
168 • untracked – If True, also show changes that
170 would not commit
171 Returns
173 A string summarizing locally modified files
174 Example:
176 import vcstools
178 # interrogate an existing tree
180 client = vcstools.VcsClient('svn', '/path/to/checkout')
181 print client.get_url()
183 print client.get_version()
184 print client.get_diff()
185 # create a new tree
187 client = vcstools.VcsClient('hg', '/path/to/new/checkout')
188 client.checkout('https://bitbucket.org/foo/bar')
189 vcstools is available on pypi and can be installed via pip
191 pip install vcstools
193 or easy_install:
195 easy_install vcstools
197 The vcstools module is meant to be used as a normal Python module. Af‐
199 ter it has been installed, you can import it normally and do not need
200 to declare as a ROS package dependency.
201
203 Code API
204 Packages
205 Changelog
206 Changelog
207 0.1
208 0.1.42
209 • remove cosmic and disco until we have hosting for it
210 0.1.41
212 • fix git submodule error due to lack of quoting
213 • Fix git update failure by refreshing git index before fast-forward
215 • Fix python3 incompatibility due to wrong use of urlopen
217 • Updating get_affected_files function by removing single quotes cover‐
219 ing format (#129)
220 • Fix export_upstream for git submodules with relative urls. (#130)
222 0.1.40
224 • Trivial style and testing changes
225 0.1.39
227 • Added support for git submodule in export_repository
228 • Add Wily Xenial Yakkety
230 • Add get_affected_files for all vcss
232 0.1.38
234 • Fixed test failures due to SVN 1.9.
235 • Added the get_default_remote_version_label() API method to support
237 changes in wstool.
238 • Renamed some internal functions to have a leading _ to indicate that
240 they are private.
241 0.1.37
243 • Fix an issue where log were restricted to the named branch (hg).
244 • Fixed svn to use a global revision number rather than a branch-local
246 revision.
247 • Added the get_remote_version() and get_current_version_label() API
249 calls.
250 • Enhanced use of no_warn in run_shell_command().
252 • Fix get_version() to catch stderr.
254 • Added get_branches() API call.
256 • Fix some errors and warnings to output to stderr.
258 • Fix output to avoid extra newlines when show_stdout=True.
260 0.1.36
262 • Updates to the release platforms (-lucid +utopic +vivid)
263 • Fix an issue with updating branches on git, see vcstools/wstool#25
265 0.1.31
267 • Fix submodule support on checkout #71
268 0.1.30
270 • use netrc to download tars from private repos, also will work for
271 private rosinstall files
272 • Fix checks for empty repository #62
274 0.1.29
276 • fix #57 shallow checkout of non-master breaks with git >= 1.8.0
277 • unit test fixes
279 0.1.28
281 • test of new upload method
282 0.1.27
284 • fix #51 hg status and diff dont work if workspace is inside hg repo
285 • fix #47 several performance improvements by removing unecessary up‐
287 date actions after checkout
288 • fix #46 https tar download fails behind proxy
290 • fix #45 sometimes commands run forever
292 • fix #44 minor bug when checking out from repo with default branch not
294 master
295 • fix #41 improvedAPI, get_vcs_client function part of vcstools module
297 0.1.26
299 • fix #38 git commands fail in local repositories with many (>2000)
300 references
301 • fix #31 get_log() svn xml not available on Ubuntu Lucid (hg 1.4.2)
303 • fix #37 update() returns True even when fetch failed
305 0.1.25
307 • minor bugfixes
308 • travis-ci config file
310 • fix unit tests for svn diff&status ordering changes
312 • deprecated VcsClient Class
314 • added get_log function
316 0.1.24
318 • fix git update return value to False when fast-forward not possible
319 due to diverge
320 • fix. svn certificate prompt invisible, svn checkout and update become
322 verbose due to this
323 0.1.22
325 • Changed the way that git implements detect_presence to fix a bug with
326 submodules in newer versions of git
327 • fix for git single quotes on Windows
329 • minor internal api bug where a git function always returned True
331 • fix gub in svn export_repository
333 0.1.21
335 • bugfix #66: hg http username prompt hidden
336 • add export_repository method to vcs_base and all implementations with
338 tests
339 • bugfix #64: unicode decoding problems
341 0.1.20
343 • rosws update --verbose for git prints small message when rebasing
344 • improved python3 compatibility
346 0.1.19
348 • more python3 compatibility
349 • code style improved
351 • match_url to compare bzr shortcuts to real urls
353 • more unit tests
355 • get_status required to end with newline, to fix #55
357 0.1.18
359 • added shallow flag to API, implemented for git
360 0.1.17
362 • svn stdout output on get_version removed
363 0.1.16
365 • All SCMs show some output when update caused changes
366 • All SCMs have verbose option to show all changes done on update
368 • bugfix for bazaar getUrl() being a joined abspath
370 • bugfix for not all output being shown when requested
372 0.1.15
374 • Added pyyaml as a proper dependency, removed detection code.
375 • remove use of tar entirely, switch to tarfile module
377 • fix #36 allowing for tar being bsdtar on OSX
379 0.1.14
381 • Added tarball uncompression.
382 0.1.13
384 • added this changelog
385 • git get-version fetches only when local lookup fails
387 • hg get-version pulls if label not found
389 • Popen error message incudes cwd path
391 0.1.12
393 • py_checker clean after all refactorings since 0.1.0
394 0.1.11
396 • svn and hg update without user interaction
397 • bugfix #30
399 • minor bugfixes
401 0.1.10
403 • minor bugs
404 0.1.9
406 • safer sanitization of shell params
407 • git diff and stat recurse for submodules
409 • base class manages all calls to Popen
411 0.1.8
413 • several bugfixes
414 • reverted using shell commands instead of bazaar API
416 0.1.7
418 • reverted using shell commands instaed of pysvn and mercurial APIs
419 • protection against shell incection attempts
421 0.1.6
423 • bugfixes to svn and bzr
424 • unified all calls through Popen
426 0.1.5
428 • missing dependency to dateutil added
429 0.1.4
431 switched shell calls to calls to python API of mercurial, bazaar,
432 py-svn
433 0.1.3
435 • fix #6
436 0.1.2
438 • fix #15
439 0.1.1
441 • more unit tests
442 • diverse bugfixes
444 • major change to git client behavior, based around git
446 https://kforge.ros.org/vcstools/trac/ticket/1
447 0.1.0
449 • documentation fixes
450 0.0.3
452 • import from svn
453 Bug reports and feature requests
455 • Submit a bug report
456 Developer Setup
458 vcstools uses setuptools, which you will need to download and install
459 in order to run the packaging. We use setuptools instead of distutils
460 in order to be able use setup() keys like install_requires.
461 cd vcstools python setup.py develop
462 Testing
464 Install test dependencies
465 pip install nose
467 pip install mock
468 vcstools uses Python nose for testing, which is a fairly simple and
470 straightfoward test framework. The vcstools mainly use unittest to
471 construct test fixtures, but with nose you can also just write a func‐
472 tion that starts with the name test and use normal assert statements.
473 vcstools also uses mock to create mocks for testing.
475 You can run the tests, including coverage, as follows:
477 cd vcstools
479 make test
480 Documentation
482 Sphinx is used to provide API documentation for vcstools. The docu‐
483 ments are stored in the doc subdirectory.
484 • Index
486 • Module Index
488 • Search Page
490
492 Tully Foote, Thibault Kruse, Ken Conley
493
495 2023, Willow Garage
4960.1.42 Jan 20, 2023 VCSTOOLS(1)