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 vcstools Package
206 vcstools Package
207 Library for tools that need to interact with ROS-support version con‐
208 trol systems.
209 vcstools.setup_logger()
211 creates a logger 'vcstools'
212 bzr Module
214 bzr vcs support.
215 vcstools.bzr.BZRClient
217 alias of vcstools.bzr.BzrClient
218 class vcstools.bzr.BzrClient(path)
220 Bases: vcstools.vcs_base.VcsClientBase
221 checkout(url, version=None, verbose=False, shallow=False, time‐
223 out=None)
224 Attempts to create a local repository given a remote url.
225 Fails if a target path exists, unless it's an empty di‐
226 rectory. If a version is provided, the local repository
227 will be updated to that revision. It is possible that af‐
228 ter a failed call to checkout, a repository still exists,
229 e.g. if an invalid revision was given. If shallow is
230 provided, the scm client may checkout less than the full
231 repository history to save time / disk space. If a time‐
232 out is specified, any pending operation will fail after
233 the specified amount (in seconds). NOTE: this parameter
234 might or might not be honored, depending on VCS client
235 implementation. :param url: where to checkout from :type
236 url: str :param version: token for identifying repository
237 revision :type version: str :param shallow: hint to
238 checkout less than a full repository :type shallow: bool
239 :param timeout: maximum allocated time to perform opera‐
240 tion :type shallow: int :returns: True if successful
241 export_repository(version, basepath)
243 Calls scm equivalent to svn export, removing scm meta in‐
244 formation and tar gzip'ing the repository at a given ver‐
245 sion to the given basepath.
246 Parameters
248 version -- version of the repository to export.
249 This can
250 be a branch, tag, or path (svn). When specifying the
252 version as a path for svn, the path should be relative to
253 the root of the svn repository, i.e. 'trunk', or
254 'tags/1.2.3', or './' for the root. :param basepath:
255 this is the path to the tar gzip, excluding the extension
256 which will be .tar.gz :returns: True on success, False
257 otherwise.
258 get_affected_files(revision)
260 Get the files that were affected by a specific revision
261 :param revision: SHA or revision number. :returns: A
262 list of strings with the files affected by a specific
263 commit
264 get_branches(local_only=False)
266 Returns a list of all branches in the vcs repository.
267 Parameters
269 local_only -- if True it will only list local
270 branches
271 Returns
273 list of branches in the repository, [] if none ex‐
274 ist
275 get_current_version_label()
277 Find an description for the current local version. Token
278 spec might be a branchname, version-id, SHA-ID, ... de‐
279 pending on the VCS implementation.
280 Returns
282 short description of local version (e.g. branch‐
283 name, tagename).
284 Return type
286 str
287 get_diff(basepath=None)
289 Parameters
291 basepath -- diff paths will be relative to this,
292 if any
293 Returns
295 A string showing local differences
296 Return type
298 str
299 static get_environment_metadata()
301 For debugging purposes, returns a dict containing infor‐
302 mation about the environment, like the version of the SCM
303 client, or version of libraries involved. Suggest con‐
304 sidering keywords "version", "dependency", "features"
305 first. :returns: a dict containing relevant information
306 :rtype: dict
307 get_log(relpath=None, limit=None)
309 Calls scm log command.
310 This returns a list of dictionaries with the following
312 fields:
313 • id: the commit SHA or revision number
315 • date: the date the commit was made (python date‐
317 time)
318 • author: the name of the author of the commit, if
320 available
321 • email: the e-mail address of the author of the
323 commit
324 • message: the commit message, if any
326 Parameters
328 relpath -- (optional) restrict logs to events on
329 this
330 resource path (folder or file) relative to the root of
332 the repository. If None (default), this is the root of
333 the repository. :param limit: (optional) the maximum
334 number of log entries that should be retrieved. If None
335 (default), there is no limit.
336 get_remote_version(fetch=False)
338 Find an identifier for the current revision on remote.
339 Token spec might be a tagname, version-id, SHA-ID, ...
340 depending on the VCS implementation.
341 Parameters
343 fetch -- if False, only local information may be
344 used
345 Returns
347 current revision number of the remote repository.
348 Return type
350 str
351 get_status(basepath=None, untracked=False)
353 Calls scm status command. Output must be terminated by
354 newline unless empty.
355 Semantics of untracked are difficult to generalize. In
357 SVN, this would be new files only. In git, hg, bzr, this
358 would be changes that have not been added for commit.
359 Extra keyword arguments are passed along to the underly‐
361 ing vcs code. See the specific implementations of
362 get_status() for extra options.
363 Parameters
365 • basepath -- status path will be relative to
367 this, if any
368 • untracked -- whether to also show changes that
370 would not commit
371 Returns
373 A string summarizing locally modified files
374 Return type
376 str
377 get_url()
379 Returns
381 BZR URL of the branch (output of bzr info com‐
382 mand),
383 or None if it cannot be determined
385 get_version(spec=None)
387 Parameters
389 spec -- (optional) revisionspec of desired ver‐
390 sion. May be any revisionspec as returned by 'bzr
391 help revisionspec', e.g. a tagname or 'revno:<num‐
392 ber>'
393 Returns
395 the current revision number of the repository. Or
396 if spec is provided, the number of a revision
397 specified by some token.
398 static static_detect_presence(path)
400 For auto detection
401 update(version='', verbose=False, timeout=None)
403 Sets the local copy of the repository to a version match‐
404 ing the version parameter. Fails when there are uncom‐
405 mited changes. On failures (also e.g. network failure)
406 grants the checked out files are in the same state as be‐
407 fore the call. If a timeout is specified, any pending
408 operation will fail after the specified amount (in sec‐
409 onds)
410 Parameters
412 • version -- token for identifying repository re‐
414 vision desired. Token might be a tagname,
415 branchname, version-id, SHA-ID, ... depending on
416 the VCS implementation.
417 • timeout -- maximum allocated time to perform op‐
419 eration
420 Returns
422 True on success, False else
423 url_matches(url, url_or_shortcut)
425 client can decide whether the url and the other url are
426 equivalent. Checks string equality by default :param
427 url_or_shortcut: url or shortcut (e.g. bzr launchpad url)
428 :returns: bool if params are equivalent
429 git Module
431 git vcs support.
432 refnames in git can be branchnames, hashes, partial hashes, tags. On
434 checkout, git will disambiguate by checking them in that order, taking
435 the first that applies
436 This class aims to provide git for linear centralized workflows. This
438 means in case of ambiguity, we assume that the only relevant remote is
439 the one named "origin", and we assume that commits once on origin re‐
440 main on origin.
441 A challenge with git is that it has strong reasonable conventions, but
443 is very allowing for breaking them. E.g. it is possible to name remotes
444 and branches with names like "refs/heads/master", give branches and
445 tags the same name, or a valid SHA-ID as name, etc. Similarly git al‐
446 lows plenty of ways to reference any object, in case of ambiguities,
447 git attempts to take the most reasonable disambiguation, and in some
448 cases warns.
449 vcstools.git.GITClient
451 alias of vcstools.git.GitClient
452 class vcstools.git.GitClient(path)
454 Bases: vcstools.vcs_base.VcsClientBase
455 checkout(url, version=None, verbose=False, shallow=False, time‐
457 out=None)
458 calls git clone and then, if version was given, up‐
459 date(version)
460 export_repository(version, basepath)
462 Calls scm equivalent to svn export, removing scm meta in‐
463 formation and tar gzip'ing the repository at a given ver‐
464 sion to the given basepath.
465 Parameters
467 version -- version of the repository to export.
468 This can
469 be a branch, tag, or path (svn). When specifying the
471 version as a path for svn, the path should be relative to
472 the root of the svn repository, i.e. 'trunk', or
473 'tags/1.2.3', or './' for the root. :param basepath:
474 this is the path to the tar gzip, excluding the extension
475 which will be .tar.gz :returns: True on success, False
476 otherwise.
477 get_affected_files(revision)
479 Get the files that were affected by a specific revision
480 :param revision: SHA or revision number. :returns: A
481 list of strings with the files affected by a specific
482 commit
483 get_branches(local_only=False)
485 Returns a list of all branches in the vcs repository.
486 Parameters
488 local_only -- if True it will only list local
489 branches
490 Returns
492 list of branches in the repository, [] if none ex‐
493 ist
494 get_current_version_label()
496 For git we change the label to clarify when a different
497 remote is configured.
498 get_default_remote_version_label()
500 Find a label for the default branch on remote, meaning
501 the one that would be checked out on a clean checkout.
502 Returns
504 a label or None (if not applicable)
505 Return type
507 str
508 get_diff(basepath=None)
510 Parameters
512 basepath -- diff paths will be relative to this,
513 if any
514 Returns
516 A string showing local differences
517 Return type
519 str
520 static get_environment_metadata()
522 For debugging purposes, returns a dict containing infor‐
523 mation about the environment, like the version of the SCM
524 client, or version of libraries involved. Suggest con‐
525 sidering keywords "version", "dependency", "features"
526 first. :returns: a dict containing relevant information
527 :rtype: dict
528 get_log(relpath=None, limit=None)
530 Calls scm log command.
531 This returns a list of dictionaries with the following
533 fields:
534 • id: the commit SHA or revision number
536 • date: the date the commit was made (python date‐
538 time)
539 • author: the name of the author of the commit, if
541 available
542 • email: the e-mail address of the author of the
544 commit
545 • message: the commit message, if any
547 Parameters
549 relpath -- (optional) restrict logs to events on
550 this
551 resource path (folder or file) relative to the root of
553 the repository. If None (default), this is the root of
554 the repository. :param limit: (optional) the maximum
555 number of log entries that should be retrieved. If None
556 (default), there is no limit.
557 get_remote_version(fetch=False)
559 Find an identifier for the current revision on remote.
560 Token spec might be a tagname, version-id, SHA-ID, ...
561 depending on the VCS implementation.
562 Parameters
564 fetch -- if False, only local information may be
565 used
566 Returns
568 current revision number of the remote repository.
569 Return type
571 str
572 get_status(basepath=None, untracked=False, porcelain=False)
574 Calls scm status command. Output must be terminated by
575 newline unless empty.
576 Semantics of untracked are difficult to generalize. In
578 SVN, this would be new files only. In git, hg, bzr, this
579 would be changes that have not been added for commit.
580 Extra keyword arguments are passed along to the underly‐
582 ing vcs code. See the specific implementations of
583 get_status() for extra options.
584 Parameters
586 • basepath -- status path will be relative to
588 this, if any
589 • untracked -- whether to also show changes that
591 would not commit
592 Returns
594 A string summarizing locally modified files
595 Return type
597 str
598 get_url()
600 Returns
602 git URL of the directory path (output of git info
603 command), or None if it cannot be determined
604 get_version(spec=None)
606 Parameters
608 • spec -- (optional) token to identify desired
610 version. For git, this may be anything accepted
611 by git log, e.g. a tagname, branchname, or
612 sha-id.
613 • fetch -- When spec is given, can be used to sup‐
615 press git fetch call
616 Returns
618 current SHA-ID of the repository. Or if spec is
619 provided, the SHA-ID of a commit specified by some
620 token if found, else None
621 is_tag(tag_name, fetch=True)
623 checks list of tags for match. Set fetch to False if you
624 just fetched already.
625 Returns
627 True if tag_name among known tags
628 Raises GitError when call to git fetch fails
630 static static_detect_presence(path)
632 For auto detection
633 update(version=None, verbose=False, force_fetch=False, time‐
635 out=None)
636 if version is None, attempts fast-forwarding current
637 branch, if any.
638 Else interprets version as a local branch, remote branch,
640 tagname, hash, etc.
641 If it is a branch, attempts to move to it unless already
643 on it, and to fast-forward, unless not a tracking branch.
644 Else go untracked on tag or whatever version is. Does not
645 leave if current commit would become dangling.
646 Returns
648 True if already up-to-date with remote or after
649 successful fast_foward
650 exception vcstools.git.GitError
652 Bases: Exception
653 hg Module
655 hg vcs support.
656 using ui object to redirect output into a string
658 vcstools.hg.HGClient
660 alias of vcstools.hg.HgClient
661 class vcstools.hg.HgClient(path)
663 Bases: vcstools.vcs_base.VcsClientBase
664 checkout(url, version='', verbose=False, shallow=False, time‐
666 out=None)
667 Attempts to create a local repository given a remote url.
668 Fails if a target path exists, unless it's an empty di‐
669 rectory. If a version is provided, the local repository
670 will be updated to that revision. It is possible that af‐
671 ter a failed call to checkout, a repository still exists,
672 e.g. if an invalid revision was given. If shallow is
673 provided, the scm client may checkout less than the full
674 repository history to save time / disk space. If a time‐
675 out is specified, any pending operation will fail after
676 the specified amount (in seconds). NOTE: this parameter
677 might or might not be honored, depending on VCS client
678 implementation. :param url: where to checkout from :type
679 url: str :param version: token for identifying repository
680 revision :type version: str :param shallow: hint to
681 checkout less than a full repository :type shallow: bool
682 :param timeout: maximum allocated time to perform opera‐
683 tion :type shallow: int :returns: True if successful
684 export_repository(version, basepath)
686 Calls scm equivalent to svn export, removing scm meta in‐
687 formation and tar gzip'ing the repository at a given ver‐
688 sion to the given basepath.
689 Parameters
691 version -- version of the repository to export.
692 This can
693 be a branch, tag, or path (svn). When specifying the
695 version as a path for svn, the path should be relative to
696 the root of the svn repository, i.e. 'trunk', or
697 'tags/1.2.3', or './' for the root. :param basepath:
698 this is the path to the tar gzip, excluding the extension
699 which will be .tar.gz :returns: True on success, False
700 otherwise.
701 get_affected_files(revision)
703 Get the files that were affected by a specific revision
704 :param revision: SHA or revision number. :returns: A
705 list of strings with the files affected by a specific
706 commit
707 get_branch()
709 get_branches(local_only=False)
711 Returns a list of all branches in the vcs repository.
712 Parameters
714 local_only -- if True it will only list local
715 branches
716 Returns
718 list of branches in the repository, [] if none ex‐
719 ist
720 get_current_version_label()
722 Parameters
724 spec -- (optional) spec can be what 'svn info
725 --help' allows, meaning a revnumber, {date}, HEAD,
726 BASE, PREV, or COMMITTED.
727 Returns
729 current revision number of the repository. Or if
730 spec provided, the number of a revision specified
731 by some token.
732 get_diff(basepath=None)
734 Parameters
736 basepath -- diff paths will be relative to this,
737 if any
738 Returns
740 A string showing local differences
741 Return type
743 str
744 static get_environment_metadata()
746 For debugging purposes, returns a dict containing infor‐
747 mation about the environment, like the version of the SCM
748 client, or version of libraries involved. Suggest con‐
749 sidering keywords "version", "dependency", "features"
750 first. :returns: a dict containing relevant information
751 :rtype: dict
752 get_log(relpath=None, limit=None)
754 Calls scm log command.
755 This returns a list of dictionaries with the following
757 fields:
758 • id: the commit SHA or revision number
760 • date: the date the commit was made (python date‐
762 time)
763 • author: the name of the author of the commit, if
765 available
766 • email: the e-mail address of the author of the
768 commit
769 • message: the commit message, if any
771 Parameters
773 relpath -- (optional) restrict logs to events on
774 this
775 resource path (folder or file) relative to the root of
777 the repository. If None (default), this is the root of
778 the repository. :param limit: (optional) the maximum
779 number of log entries that should be retrieved. If None
780 (default), there is no limit.
781 get_remote_version(fetch=False)
783 Find an identifier for the current revision on remote.
784 Token spec might be a tagname, version-id, SHA-ID, ...
785 depending on the VCS implementation.
786 Parameters
788 fetch -- if False, only local information may be
789 used
790 Returns
792 current revision number of the remote repository.
793 Return type
795 str
796 get_status(basepath=None, untracked=False)
798 Calls scm status command. Output must be terminated by
799 newline unless empty.
800 Semantics of untracked are difficult to generalize. In
802 SVN, this would be new files only. In git, hg, bzr, this
803 would be changes that have not been added for commit.
804 Extra keyword arguments are passed along to the underly‐
806 ing vcs code. See the specific implementations of
807 get_status() for extra options.
808 Parameters
810 • basepath -- status path will be relative to
812 this, if any
813 • untracked -- whether to also show changes that
815 would not commit
816 Returns
818 A string summarizing locally modified files
819 Return type
821 str
822 get_url()
824 Returns
826 HG URL of the directory path. (output of hg paths
827 command), or None if it cannot be determined
829 get_version(spec=None)
831 Parameters
833 spec -- (optional) token for identifying version.
834 spec can be a whatever is allowed by 'hg log -r',
835 e.g. a tagname, sha-ID, revision-number
836 Returns
838 the current SHA-ID of the repository. Or if spec
839 is provided, the SHA-ID of a revision specified by
840 some token.
841 static static_detect_presence(path)
843 For auto detection
844 update(version='', verbose=False, timeout=None)
846 Sets the local copy of the repository to a version match‐
847 ing the version parameter. Fails when there are uncom‐
848 mited changes. On failures (also e.g. network failure)
849 grants the checked out files are in the same state as be‐
850 fore the call. If a timeout is specified, any pending
851 operation will fail after the specified amount (in sec‐
852 onds)
853 Parameters
855 • version -- token for identifying repository re‐
857 vision desired. Token might be a tagname,
858 branchname, version-id, SHA-ID, ... depending on
859 the VCS implementation.
860 • timeout -- maximum allocated time to perform op‐
862 eration
863 Returns
865 True on success, False else
866 svn Module
868 svn vcs support.
869 vcstools.svn.SVNClient
871 alias of vcstools.svn.SvnClient
872 class vcstools.svn.SvnClient(path)
874 Bases: vcstools.vcs_base.VcsClientBase
875 checkout(url, version='', verbose=False, shallow=False, time‐
877 out=None)
878 Attempts to create a local repository given a remote url.
879 Fails if a target path exists, unless it's an empty di‐
880 rectory. If a version is provided, the local repository
881 will be updated to that revision. It is possible that af‐
882 ter a failed call to checkout, a repository still exists,
883 e.g. if an invalid revision was given. If shallow is
884 provided, the scm client may checkout less than the full
885 repository history to save time / disk space. If a time‐
886 out is specified, any pending operation will fail after
887 the specified amount (in seconds). NOTE: this parameter
888 might or might not be honored, depending on VCS client
889 implementation. :param url: where to checkout from :type
890 url: str :param version: token for identifying repository
891 revision :type version: str :param shallow: hint to
892 checkout less than a full repository :type shallow: bool
893 :param timeout: maximum allocated time to perform opera‐
894 tion :type shallow: int :returns: True if successful
895 export_repository(version, basepath)
897 Calls scm equivalent to svn export, removing scm meta in‐
898 formation and tar gzip'ing the repository at a given ver‐
899 sion to the given basepath.
900 Parameters
902 version -- version of the repository to export.
903 This can
904 be a branch, tag, or path (svn). When specifying the
906 version as a path for svn, the path should be relative to
907 the root of the svn repository, i.e. 'trunk', or
908 'tags/1.2.3', or './' for the root. :param basepath:
909 this is the path to the tar gzip, excluding the extension
910 which will be .tar.gz :returns: True on success, False
911 otherwise.
912 get_affected_files(revision)
914 Get the files that were affected by a specific revision
915 :param revision: SHA or revision number. :returns: A
916 list of strings with the files affected by a specific
917 commit
918 get_branches(local_only=False)
920 Returns a list of all branches in the vcs repository.
921 Parameters
923 local_only -- if True it will only list local
924 branches
925 Returns
927 list of branches in the repository, [] if none ex‐
928 ist
929 get_current_version_label()
931 Find an description for the current local version. Token
932 spec might be a branchname, version-id, SHA-ID, ... de‐
933 pending on the VCS implementation.
934 Returns
936 short description of local version (e.g. branch‐
937 name, tagename).
938 Return type
940 str
941 get_diff(basepath=None)
943 Parameters
945 basepath -- diff paths will be relative to this,
946 if any
947 Returns
949 A string showing local differences
950 Return type
952 str
953 static get_environment_metadata()
955 For debugging purposes, returns a dict containing infor‐
956 mation about the environment, like the version of the SCM
957 client, or version of libraries involved. Suggest con‐
958 sidering keywords "version", "dependency", "features"
959 first. :returns: a dict containing relevant information
960 :rtype: dict
961 get_log(relpath=None, limit=None)
963 Calls scm log command.
964 This returns a list of dictionaries with the following
966 fields:
967 • id: the commit SHA or revision number
969 • date: the date the commit was made (python date‐
971 time)
972 • author: the name of the author of the commit, if
974 available
975 • email: the e-mail address of the author of the
977 commit
978 • message: the commit message, if any
980 Parameters
982 relpath -- (optional) restrict logs to events on
983 this
984 resource path (folder or file) relative to the root of
986 the repository. If None (default), this is the root of
987 the repository. :param limit: (optional) the maximum
988 number of log entries that should be retrieved. If None
989 (default), there is no limit.
990 get_remote_version(fetch=False)
992 Find an identifier for the current revision on remote.
993 Token spec might be a tagname, version-id, SHA-ID, ...
994 depending on the VCS implementation.
995 Parameters
997 fetch -- if False, only local information may be
998 used
999 Returns
1001 current revision number of the remote repository.
1002 Return type
1004 str
1005 get_status(basepath=None, untracked=False)
1007 Calls scm status command. Output must be terminated by
1008 newline unless empty.
1009 Semantics of untracked are difficult to generalize. In
1011 SVN, this would be new files only. In git, hg, bzr, this
1012 would be changes that have not been added for commit.
1013 Extra keyword arguments are passed along to the underly‐
1015 ing vcs code. See the specific implementations of
1016 get_status() for extra options.
1017 Parameters
1019 • basepath -- status path will be relative to
1021 this, if any
1022 • untracked -- whether to also show changes that
1024 would not commit
1025 Returns
1027 A string summarizing locally modified files
1028 Return type
1030 str
1031 get_url()
1033 Returns
1035 SVN URL of the directory path (output of svn info
1036 command), or None if it cannot be determined
1037 get_version(spec=None)
1039 Parameters
1041 • spec -- (optional) spec can be what 'svn info
1043 --help' allows, meaning a revnumber, {date},
1044 HEAD, BASE, PREV, or COMMITTED.
1045 • path -- the url to use, default is for this repo
1047 Returns
1049 current revision number of the repository. Or if
1050 spec provided, the number of a revision specified
1051 by some token.
1052 static static_detect_presence(path)
1054 For auto detection
1055 update(version=None, verbose=False, timeout=None)
1057 Sets the local copy of the repository to a version match‐
1058 ing the version parameter. Fails when there are uncom‐
1059 mited changes. On failures (also e.g. network failure)
1060 grants the checked out files are in the same state as be‐
1061 fore the call. If a timeout is specified, any pending
1062 operation will fail after the specified amount (in sec‐
1063 onds)
1064 Parameters
1066 • version -- token for identifying repository re‐
1068 vision desired. Token might be a tagname,
1069 branchname, version-id, SHA-ID, ... depending on
1070 the VCS implementation.
1071 • timeout -- maximum allocated time to perform op‐
1073 eration
1074 Returns
1076 True on success, False else
1077 vcstools.svn.canonical_svn_url_split(url)
1079 checks url for traces of canonical svn structure, and return
1080 root, type, name (of tag or branch), subfolder, query and frag‐
1081 ment (see urllib urlparse) This should allow creating a differ‐
1082 ent url for switching to a different tag or branch
1083 Parameters
1085 url -- location of central repo, str
1086 Returns
1088 dict {root, type, name, subfolder, query, fragment}
1089 with type one of "trunk", "tags", "branches"
1091 vcstools.svn.get_remote_contents(url)
1093 tar Module
1095 tar vcs support.
1096 The implementation uses the "version" argument to indicate a subfolder
1098 within a tarfile. Hence one can organize sources by creating one
1099 tarfile with a folder inside for each version.
1100 vcstools.tar.TARClient
1102 alias of vcstools.tar.TarClient
1103 class vcstools.tar.TarClient(path)
1105 Bases: vcstools.vcs_base.VcsClientBase
1106 checkout(url, version='', verbose=False, shallow=False, time‐
1108 out=None)
1109 untars tar at url to self.path. If version was given,
1110 only the subdirectory 'version' of the tar will end up in
1111 self.path. Also creates a file next to the checkout
1112 named
1113 *
1114 .tar which is a yaml file listing origin url and version
1115 arguments.
1116 export_repository(version, basepath)
1118 Calls scm equivalent to svn export, removing scm meta in‐
1119 formation and tar gzip'ing the repository at a given ver‐
1120 sion to the given basepath.
1121 Parameters
1123 version -- version of the repository to export.
1124 This can
1125 be a branch, tag, or path (svn). When specifying the
1127 version as a path for svn, the path should be relative to
1128 the root of the svn repository, i.e. 'trunk', or
1129 'tags/1.2.3', or './' for the root. :param basepath:
1130 this is the path to the tar gzip, excluding the extension
1131 which will be .tar.gz :returns: True on success, False
1132 otherwise.
1133 get_current_version_label()
1135 Find an description for the current local version. Token
1136 spec might be a branchname, version-id, SHA-ID, ... de‐
1137 pending on the VCS implementation.
1138 Returns
1140 short description of local version (e.g. branch‐
1141 name, tagename).
1142 Return type
1144 str
1145 get_diff(basepath=None)
1147 Parameters
1149 basepath -- diff paths will be relative to this,
1150 if any
1151 Returns
1153 A string showing local differences
1154 Return type
1156 str
1157 static get_environment_metadata()
1159 For debugging purposes, returns a dict containing infor‐
1160 mation about the environment, like the version of the SCM
1161 client, or version of libraries involved. Suggest con‐
1162 sidering keywords "version", "dependency", "features"
1163 first. :returns: a dict containing relevant information
1164 :rtype: dict
1165 get_remote_version(fetch=False)
1167 Find an identifier for the current revision on remote.
1168 Token spec might be a tagname, version-id, SHA-ID, ...
1169 depending on the VCS implementation.
1170 Parameters
1172 fetch -- if False, only local information may be
1173 used
1174 Returns
1176 current revision number of the remote repository.
1177 Return type
1179 str
1180 get_status(basepath=None, untracked=False)
1182 Calls scm status command. Output must be terminated by
1183 newline unless empty.
1184 Semantics of untracked are difficult to generalize. In
1186 SVN, this would be new files only. In git, hg, bzr, this
1187 would be changes that have not been added for commit.
1188 Extra keyword arguments are passed along to the underly‐
1190 ing vcs code. See the specific implementations of
1191 get_status() for extra options.
1192 Parameters
1194 • basepath -- status path will be relative to
1196 this, if any
1197 • untracked -- whether to also show changes that
1199 would not commit
1200 Returns
1202 A string summarizing locally modified files
1203 Return type
1205 str
1206 get_url()
1208 Returns
1210 TAR URL of the directory path (output of tar info
1211 command), or None if it cannot be determined
1213 get_version(spec=None)
1215 Find an identifier for a the current or a specified revi‐
1216 sion. Token spec might be a tagname, branchname, ver‐
1217 sion-id, SHA-ID, ... depending on the VCS implementation.
1218 Parameters
1220 spec (str) -- token for identifying repository re‐
1221 vision
1222 Returns
1224 current revision number of the repository. Or if
1225 spec is provided, the respective revision number.
1226 Return type
1228 str
1229 static static_detect_presence(path)
1231 For auto detection
1232 update(version='', verbose=False, timeout=None)
1234 Does nothing except returning true if tar exists in same
1235 "version" as checked out with vcstools.
1236 vcs_abstraction Module
1238 undoc-members
1239 show-inheritance
1241 vcstools.vcs_abstraction.VCSClient
1243 alias of vcstools.vcs_abstraction.VcsClient
1244 class vcstools.vcs_abstraction.VcsClient(vcs_type, path)
1246 DEPRECATED API for interacting with source-controlled paths in‐
1247 dependent of actual version-control implementation.
1248 vcstools.vcs_abstraction.get_registered_vcs_types()
1250 Returns
1252 list of valid key to use as vcs_type
1253 vcstools.vcs_abstraction.get_vcs(vcs_type)
1255 Returns the class interfacing with vcs of given type
1256 Parameters
1258 vcs_type -- id of the tpye, e.g. git, svn, hg, bzr
1259 Returns
1261 class extending VcsClientBase
1262 Raises ValueError for unknown vcs_type
1264 vcstools.vcs_abstraction.get_vcs_client(vcs_type, path)
1266 Returns a client with which to interact with the vcs at given
1267 path
1268 Parameters
1270 vcs_type -- id of the tpye, e.g. git, svn, hg, bzr
1271 Returns
1273 instance of VcsClientBase
1274 Raises ValueError for unknown vcs_type
1276 vcstools.vcs_abstraction.register_vcs(vcs_type, clazz)
1278 Parameters
1280 • vcs_type -- id, str
1282 • clazz -- class extending VcsClientBase
1284 vcs_base Module
1286 vcs support library base class.
1287 undoc-members
1289 show-inheritance
1291 class vcstools.vcs_base.VcsClientBase(vcs_type_name, path)
1293 parent class for all vcs clients, provides their public API
1294 checkout(url, version=None, verbose=False, shallow=False, time‐
1296 out=None)
1297 Attempts to create a local repository given a remote url.
1298 Fails if a target path exists, unless it's an empty di‐
1299 rectory. If a version is provided, the local repository
1300 will be updated to that revision. It is possible that af‐
1301 ter a failed call to checkout, a repository still exists,
1302 e.g. if an invalid revision was given. If shallow is
1303 provided, the scm client may checkout less than the full
1304 repository history to save time / disk space. If a time‐
1305 out is specified, any pending operation will fail after
1306 the specified amount (in seconds). NOTE: this parameter
1307 might or might not be honored, depending on VCS client
1308 implementation. :param url: where to checkout from :type
1309 url: str :param version: token for identifying repository
1310 revision :type version: str :param shallow: hint to
1311 checkout less than a full repository :type shallow: bool
1312 :param timeout: maximum allocated time to perform opera‐
1313 tion :type shallow: int :returns: True if successful
1314 detect_presence()
1316 For auto detection
1317 export_repository(version, basepath)
1319 Calls scm equivalent to svn export, removing scm meta in‐
1320 formation and tar gzip'ing the repository at a given ver‐
1321 sion to the given basepath.
1322 Parameters
1324 version -- version of the repository to export.
1325 This can
1326 be a branch, tag, or path (svn). When specifying the
1328 version as a path for svn, the path should be relative to
1329 the root of the svn repository, i.e. 'trunk', or
1330 'tags/1.2.3', or './' for the root. :param basepath:
1331 this is the path to the tar gzip, excluding the extension
1332 which will be .tar.gz :returns: True on success, False
1333 otherwise.
1334 get_affected_files(revision)
1336 Get the files that were affected by a specific revision
1337 :param revision: SHA or revision number. :returns: A
1338 list of strings with the files affected by a specific
1339 commit
1340 get_branches(local_only=False)
1342 Returns a list of all branches in the vcs repository.
1343 Parameters
1345 local_only -- if True it will only list local
1346 branches
1347 Returns
1349 list of branches in the repository, [] if none ex‐
1350 ist
1351 get_current_version_label()
1353 Find an description for the current local version. Token
1354 spec might be a branchname, version-id, SHA-ID, ... de‐
1355 pending on the VCS implementation.
1356 Returns
1358 short description of local version (e.g. branch‐
1359 name, tagename).
1360 Return type
1362 str
1363 get_default_remote_version_label()
1365 Find a label for the default branch on remote, meaning
1366 the one that would be checked out on a clean checkout.
1367 Returns
1369 a label or None (if not applicable)
1370 Return type
1372 str
1373 get_diff(basepath=None)
1375 Parameters
1377 basepath -- diff paths will be relative to this,
1378 if any
1379 Returns
1381 A string showing local differences
1382 Return type
1384 str
1385 static get_environment_metadata()
1387 For debugging purposes, returns a dict containing infor‐
1388 mation about the environment, like the version of the SCM
1389 client, or version of libraries involved. Suggest con‐
1390 sidering keywords "version", "dependency", "features"
1391 first. :returns: a dict containing relevant information
1392 :rtype: dict
1393 get_log(relpath=None, limit=None)
1395 Calls scm log command.
1396 This returns a list of dictionaries with the following
1398 fields:
1399 • id: the commit SHA or revision number
1401 • date: the date the commit was made (python date‐
1403 time)
1404 • author: the name of the author of the commit, if
1406 available
1407 • email: the e-mail address of the author of the
1409 commit
1410 • message: the commit message, if any
1412 Parameters
1414 relpath -- (optional) restrict logs to events on
1415 this
1416 resource path (folder or file) relative to the root of
1418 the repository. If None (default), this is the root of
1419 the repository. :param limit: (optional) the maximum
1420 number of log entries that should be retrieved. If None
1421 (default), there is no limit.
1422 get_path()
1424 returns the path this client was configured for
1425 get_remote_version(fetch=False)
1427 Find an identifier for the current revision on remote.
1428 Token spec might be a tagname, version-id, SHA-ID, ...
1429 depending on the VCS implementation.
1430 Parameters
1432 fetch -- if False, only local information may be
1433 used
1434 Returns
1436 current revision number of the remote repository.
1437 Return type
1439 str
1440 get_status(basepath=None, untracked=False, **kwargs)
1442 Calls scm status command. Output must be terminated by
1443 newline unless empty.
1444 Semantics of untracked are difficult to generalize. In
1446 SVN, this would be new files only. In git, hg, bzr, this
1447 would be changes that have not been added for commit.
1448 Extra keyword arguments are passed along to the underly‐
1450 ing vcs code. See the specific implementations of
1451 get_status() for extra options.
1452 Parameters
1454 • basepath -- status path will be relative to
1456 this, if any
1457 • untracked -- whether to also show changes that
1459 would not commit
1460 Returns
1462 A string summarizing locally modified files
1463 Return type
1465 str
1466 get_url()
1468 Returns
1470 The source control url for the path or None if not
1471 set
1472 Return type
1474 str
1475 get_vcs_type_name()
1477 used when auto detected
1478 get_version(spec=None)
1480 Find an identifier for a the current or a specified revi‐
1481 sion. Token spec might be a tagname, branchname, ver‐
1482 sion-id, SHA-ID, ... depending on the VCS implementation.
1483 Parameters
1485 spec (str) -- token for identifying repository re‐
1486 vision
1487 Returns
1489 current revision number of the repository. Or if
1490 spec is provided, the respective revision number.
1491 Return type
1493 str
1494 path_exists()
1496 helper function
1497 static static_detect_presence(path)
1499 For auto detection
1500 update(version=None, verbose=False, timeout=None)
1502 Sets the local copy of the repository to a version match‐
1503 ing the version parameter. Fails when there are uncom‐
1504 mited changes. On failures (also e.g. network failure)
1505 grants the checked out files are in the same state as be‐
1506 fore the call. If a timeout is specified, any pending
1507 operation will fail after the specified amount (in sec‐
1508 onds)
1509 Parameters
1511 • version -- token for identifying repository re‐
1513 vision desired. Token might be a tagname,
1514 branchname, version-id, SHA-ID, ... depending on
1515 the VCS implementation.
1516 • timeout -- maximum allocated time to perform op‐
1518 eration
1519 Returns
1521 True on success, False else
1522 url_matches(url, url_or_shortcut)
1524 client can decide whether the url and the other url are
1525 equivalent. Checks string equality by default :param
1526 url_or_shortcut: url or shortcut (e.g. bzr launchpad url)
1527 :returns: bool if params are equivalent
1528 exception vcstools.vcs_base.VcsError(value)
1530 To be thrown when an SCM Client faces a situation because of a
1531 violated assumption
1532 Changelog
1534 Changelog
1535 0.1
1536 0.1.42
1537 • remove cosmic and disco until we have hosting for it
1538 0.1.41
1540 • fix git submodule error due to lack of quoting
1541 • Fix git update failure by refreshing git index before fast-forward
1543 • Fix python3 incompatibility due to wrong use of urlopen
1545 • Updating get_affected_files function by removing single quotes cover‐
1547 ing format (#129)
1548 • Fix export_upstream for git submodules with relative urls. (#130)
1550 0.1.40
1552 • Trivial style and testing changes
1553 0.1.39
1555 • Added support for git submodule in export_repository
1556 • Add Wily Xenial Yakkety
1558 • Add get_affected_files for all vcss
1560 0.1.38
1562 • Fixed test failures due to SVN 1.9.
1563 • Added the get_default_remote_version_label() API method to support
1565 changes in wstool.
1566 • Renamed some internal functions to have a leading _ to indicate that
1568 they are private.
1569 0.1.37
1571 • Fix an issue where log were restricted to the named branch (hg).
1572 • Fixed svn to use a global revision number rather than a branch-local
1574 revision.
1575 • Added the get_remote_version() and get_current_version_label() API
1577 calls.
1578 • Enhanced use of no_warn in run_shell_command().
1580 • Fix get_version() to catch stderr.
1582 • Added get_branches() API call.
1584 • Fix some errors and warnings to output to stderr.
1586 • Fix output to avoid extra newlines when show_stdout=True.
1588 0.1.36
1590 • Updates to the release platforms (-lucid +utopic +vivid)
1591 • Fix an issue with updating branches on git, see vcstools/wstool#25
1593 0.1.31
1595 • Fix submodule support on checkout #71
1596 0.1.30
1598 • use netrc to download tars from private repos, also will work for
1599 private rosinstall files
1600 • Fix checks for empty repository #62
1602 0.1.29
1604 • fix #57 shallow checkout of non-master breaks with git >= 1.8.0
1605 • unit test fixes
1607 0.1.28
1609 • test of new upload method
1610 0.1.27
1612 • fix #51 hg status and diff dont work if workspace is inside hg repo
1613 • fix #47 several performance improvements by removing unecessary up‐
1615 date actions after checkout
1616 • fix #46 https tar download fails behind proxy
1618 • fix #45 sometimes commands run forever
1620 • fix #44 minor bug when checking out from repo with default branch not
1622 master
1623 • fix #41 improvedAPI, get_vcs_client function part of vcstools module
1625 0.1.26
1627 • fix #38 git commands fail in local repositories with many (>2000)
1628 references
1629 • fix #31 get_log() svn xml not available on Ubuntu Lucid (hg 1.4.2)
1631 • fix #37 update() returns True even when fetch failed
1633 0.1.25
1635 • minor bugfixes
1636 • travis-ci config file
1638 • fix unit tests for svn diff&status ordering changes
1640 • deprecated VcsClient Class
1642 • added get_log function
1644 0.1.24
1646 • fix git update return value to False when fast-forward not possible
1647 due to diverge
1648 • fix. svn certificate prompt invisible, svn checkout and update become
1650 verbose due to this
1651 0.1.22
1653 • Changed the way that git implements detect_presence to fix a bug with
1654 submodules in newer versions of git
1655 • fix for git single quotes on Windows
1657 • minor internal api bug where a git function always returned True
1659 • fix gub in svn export_repository
1661 0.1.21
1663 • bugfix #66: hg http username prompt hidden
1664 • add export_repository method to vcs_base and all implementations with
1666 tests
1667 • bugfix #64: unicode decoding problems
1669 0.1.20
1671 • rosws update –verbose for git prints small message when rebasing
1672 • improved python3 compatibility
1674 0.1.19
1676 • more python3 compatibility
1677 • code style improved
1679 • match_url to compare bzr shortcuts to real urls
1681 • more unit tests
1683 • get_status required to end with newline, to fix #55
1685 0.1.18
1687 • added shallow flag to API, implemented for git
1688 0.1.17
1690 • svn stdout output on get_version removed
1691 0.1.16
1693 • All SCMs show some output when update caused changes
1694 • All SCMs have verbose option to show all changes done on update
1696 • bugfix for bazaar getUrl() being a joined abspath
1698 • bugfix for not all output being shown when requested
1700 0.1.15
1702 • Added pyyaml as a proper dependency, removed detection code.
1703 • remove use of tar entirely, switch to tarfile module
1705 • fix #36 allowing for tar being bsdtar on OSX
1707 0.1.14
1709 • Added tarball uncompression.
1710 0.1.13
1712 • added this changelog
1713 • git get-version fetches only when local lookup fails
1715 • hg get-version pulls if label not found
1717 • Popen error message incudes cwd path
1719 0.1.12
1721 • py_checker clean after all refactorings since 0.1.0
1722 0.1.11
1724 • svn and hg update without user interaction
1725 • bugfix #30
1727 • minor bugfixes
1729 0.1.10
1731 • minor bugs
1732 0.1.9
1734 • safer sanitization of shell params
1735 • git diff and stat recurse for submodules
1737 • base class manages all calls to Popen
1739 0.1.8
1741 • several bugfixes
1742 • reverted using shell commands instead of bazaar API
1744 0.1.7
1746 • reverted using shell commands instaed of pysvn and mercurial APIs
1747 • protection against shell incection attempts
1749 0.1.6
1751 • bugfixes to svn and bzr
1752 • unified all calls through Popen
1754 0.1.5
1756 • missing dependency to dateutil added
1757 0.1.4
1759 switched shell calls to calls to python API of mercurial, bazaar,
1760 py-svn
1761 0.1.3
1763 • fix #6
1764 0.1.2
1766 • fix #15
1767 0.1.1
1769 • more unit tests
1770 • diverse bugfixes
1772 • major change to git client behavior, based around git
1774 https://kforge.ros.org/vcstools/trac/ticket/1
1775 0.1.0
1777 • documentation fixes
1778 0.0.3
1780 • import from svn
1781 Bug reports and feature requests
1783 • Submit a bug report
1784 Developer Setup
1786 vcstools uses setuptools, which you will need to download and install
1787 in order to run the packaging. We use setuptools instead of distutils
1788 in order to be able use setup() keys like install_requires.
1789 cd vcstools python setup.py develop
1790 Testing
1792 Install test dependencies
1793 pip install nose
1795 pip install mock
1796 vcstools uses Python nose for testing, which is a fairly simple and
1798 straightfoward test framework. The vcstools mainly use unittest to
1799 construct test fixtures, but with nose you can also just write a func‐
1800 tion that starts with the name test and use normal assert statements.
1801 vcstools also uses mock to create mocks for testing.
1803 You can run the tests, including coverage, as follows:
1805 cd vcstools
1807 make test
1808 Documentation
1810 Sphinx is used to provide API documentation for vcstools. The docu‐
1811 ments are stored in the doc subdirectory.
1812 • genindex
1814 • modindex
1816 • search
1818
1820 Tully Foote, Thibault Kruse, Ken Conley
1821
1823 2021, Willow Garage
18240.1.42 Jul 27, 2021 VCSTOOLS(1)