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, …
90 depending 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.
199 After 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
226 directory. If a version is provided, the local reposi‐
227 tory will be updated to that revision. It is possible
228 that after a failed call to checkout, a repository still
229 exists, e.g. if an invalid revision was given. If shal‐
230 low is provided, the scm client may checkout less than
231 the full repository history to save time / disk space.
232 If a timeout is specified, any pending operation will
233 fail after the specified amount (in seconds). NOTE: this
234 parameter might or might not be honored, depending on VCS
235 client implementation. :param url: where to checkout
236 from :type url: str :param version: token for identifying
237 repository revision :type version: str :param shallow:
238 hint to checkout less than a full repository :type shal‐
239 low: bool :param timeout: maximum allocated time to per‐
240 form operation :type shallow: int :returns: True if suc‐
241 cessful
242 export_repository(version, basepath)
244 Calls scm equivalent to svn export, removing scm meta
245 information and tar gzip'ing the repository at a given
246 version to the given basepath.
247 Parameters
249 version -- version of the repository to export.
250 This can
251 be a branch, tag, or path (svn). When specifying the
253 version as a path for svn, the path should be relative to
254 the root of the svn repository, i.e. 'trunk', or
255 'tags/1.2.3', or './' for the root. :param basepath:
256 this is the path to the tar gzip, excluding the extension
257 which will be .tar.gz :returns: True on success, False
258 otherwise.
259 get_affected_files(revision)
261 Get the files that were affected by a specific revision
262 :param revision: SHA or revision number. :returns: A
263 list of strings with the files affected by a specific
264 commit
265 get_branches(local_only=False)
267 Returns a list of all branches in the vcs repository.
268 Parameters
270 local_only -- if True it will only list local
271 branches
272 Returns
274 list of branches in the repository, [] if none
275 exist
276 get_current_version_label()
278 Find an description for the current local version. Token
279 spec might be a branchname, version-id, SHA-ID, ...
280 depending on the VCS implementation.
281 Returns
283 short description of local version (e.g. branch‐
284 name, tagename).
285 Return type
287 str
288 get_diff(basepath=None)
290 Parameters
292 basepath -- diff paths will be relative to this,
293 if any
294 Returns
296 A string showing local differences
297 Return type
299 str
300 static get_environment_metadata()
302 For debugging purposes, returns a dict containing infor‐
303 mation about the environment, like the version of the SCM
304 client, or version of libraries involved. Suggest con‐
305 sidering keywords "version", "dependency", "features"
306 first. :returns: a dict containing relevant information
307 :rtype: dict
308 get_log(relpath=None, limit=None)
310 Calls scm log command.
311 This returns a list of dictionaries with the following
313 fields:
314 · id: the commit SHA or revision number
316 · date: the date the commit was made (python date‐
318 time)
319 · author: the name of the author of the commit, if
321 available
322 · email: the e-mail address of the author of the
324 commit
325 · message: the commit message, if any
327 Parameters
329 relpath -- (optional) restrict logs to events on
330 this
331 resource path (folder or file) relative to the root of
333 the repository. If None (default), this is the root of
334 the repository. :param limit: (optional) the maximum
335 number of log entries that should be retrieved. If None
336 (default), there is no limit.
337 get_remote_version(fetch=False)
339 Find an identifier for the current revision on remote.
340 Token spec might be a tagname, version-id, SHA-ID, ...
341 depending on the VCS implementation.
342 Parameters
344 fetch -- if False, only local information may be
345 used
346 Returns
348 current revision number of the remote repository.
349 Return type
351 str
352 get_status(basepath=None, untracked=False)
354 Calls scm status command. Output must be terminated by
355 newline unless empty.
356 Semantics of untracked are difficult to generalize. In
358 SVN, this would be new files only. In git, hg, bzr, this
359 would be changes that have not been added for commit.
360 Extra keyword arguments are passed along to the underly‐
362 ing vcs code. See the specific implementations of
363 get_status() for extra options.
364 Parameters
366 · basepath -- status path will be relative to
368 this, if any
369 · untracked -- whether to also show changes that
371 would not commit
372 Returns
374 A string summarizing locally modified files
375 Return type
377 str
378 get_url()
380 Returns
382 BZR URL of the branch (output of bzr info com‐
383 mand),
384 or None if it cannot be determined
386 get_version(spec=None)
388 Parameters
390 spec -- (optional) revisionspec of desired ver‐
391 sion. May be any revisionspec as returned by 'bzr
392 help revisionspec', e.g. a tagname or 'revno:<num‐
393 ber>'
394 Returns
396 the current revision number of the repository. Or
397 if spec is provided, the number of a revision
398 specified by some token.
399 static static_detect_presence(path)
401 For auto detection
402 update(version='', verbose=False, timeout=None)
404 Sets the local copy of the repository to a version match‐
405 ing the version parameter. Fails when there are uncom‐
406 mited changes. On failures (also e.g. network failure)
407 grants the checked out files are in the same state as
408 before the call. If a timeout is specified, any pending
409 operation will fail after the specified amount (in sec‐
410 onds)
411 Parameters
413 · version -- token for identifying repository
415 revision desired. Token might be a tagname,
416 branchname, version-id, SHA-ID, ... depending on
417 the VCS implementation.
418 · timeout -- maximum allocated time to perform
420 operation
421 Returns
423 True on success, False else
424 url_matches(url, url_or_shortcut)
426 client can decide whether the url and the other url are
427 equivalent. Checks string equality by default :param
428 url_or_shortcut: url or shortcut (e.g. bzr launchpad url)
429 :returns: bool if params are equivalent
430 git Module
432 git vcs support.
433 refnames in git can be branchnames, hashes, partial hashes, tags. On
435 checkout, git will disambiguate by checking them in that order, taking
436 the first that applies
437 This class aims to provide git for linear centralized workflows. This
439 means in case of ambiguity, we assume that the only relevant remote is
440 the one named "origin", and we assume that commits once on origin
441 remain on origin.
442 A challenge with git is that it has strong reasonable conventions, but
444 is very allowing for breaking them. E.g. it is possible to name remotes
445 and branches with names like "refs/heads/master", give branches and
446 tags the same name, or a valid SHA-ID as name, etc. Similarly git
447 allows plenty of ways to reference any object, in case of ambiguities,
448 git attempts to take the most reasonable disambiguation, and in some
449 cases warns.
450 vcstools.git.GITClient
452 alias of vcstools.git.GitClient
453 class vcstools.git.GitClient(path)
455 Bases: vcstools.vcs_base.VcsClientBase
456 checkout(url, version=None, verbose=False, shallow=False, time‐
458 out=None)
459 calls git clone and then, if version was given,
460 update(version)
461 export_repository(version, basepath)
463 Calls scm equivalent to svn export, removing scm meta
464 information and tar gzip'ing the repository at a given
465 version to the given basepath.
466 Parameters
468 version -- version of the repository to export.
469 This can
470 be a branch, tag, or path (svn). When specifying the
472 version as a path for svn, the path should be relative to
473 the root of the svn repository, i.e. 'trunk', or
474 'tags/1.2.3', or './' for the root. :param basepath:
475 this is the path to the tar gzip, excluding the extension
476 which will be .tar.gz :returns: True on success, False
477 otherwise.
478 get_affected_files(revision)
480 Get the files that were affected by a specific revision
481 :param revision: SHA or revision number. :returns: A
482 list of strings with the files affected by a specific
483 commit
484 get_branches(local_only=False)
486 Returns a list of all branches in the vcs repository.
487 Parameters
489 local_only -- if True it will only list local
490 branches
491 Returns
493 list of branches in the repository, [] if none
494 exist
495 get_current_version_label()
497 For git we change the label to clarify when a different
498 remote is configured.
499 get_default_remote_version_label()
501 Find a label for the default branch on remote, meaning
502 the one that would be checked out on a clean checkout.
503 Returns
505 a label or None (if not applicable)
506 Return type
508 str
509 get_diff(basepath=None)
511 Parameters
513 basepath -- diff paths will be relative to this,
514 if any
515 Returns
517 A string showing local differences
518 Return type
520 str
521 static get_environment_metadata()
523 For debugging purposes, returns a dict containing infor‐
524 mation about the environment, like the version of the SCM
525 client, or version of libraries involved. Suggest con‐
526 sidering keywords "version", "dependency", "features"
527 first. :returns: a dict containing relevant information
528 :rtype: dict
529 get_log(relpath=None, limit=None)
531 Calls scm log command.
532 This returns a list of dictionaries with the following
534 fields:
535 · id: the commit SHA or revision number
537 · date: the date the commit was made (python date‐
539 time)
540 · author: the name of the author of the commit, if
542 available
543 · email: the e-mail address of the author of the
545 commit
546 · message: the commit message, if any
548 Parameters
550 relpath -- (optional) restrict logs to events on
551 this
552 resource path (folder or file) relative to the root of
554 the repository. If None (default), this is the root of
555 the repository. :param limit: (optional) the maximum
556 number of log entries that should be retrieved. If None
557 (default), there is no limit.
558 get_remote_version(fetch=False)
560 Find an identifier for the current revision on remote.
561 Token spec might be a tagname, version-id, SHA-ID, ...
562 depending on the VCS implementation.
563 Parameters
565 fetch -- if False, only local information may be
566 used
567 Returns
569 current revision number of the remote repository.
570 Return type
572 str
573 get_status(basepath=None, untracked=False, porcelain=False)
575 Calls scm status command. Output must be terminated by
576 newline unless empty.
577 Semantics of untracked are difficult to generalize. In
579 SVN, this would be new files only. In git, hg, bzr, this
580 would be changes that have not been added for commit.
581 Extra keyword arguments are passed along to the underly‐
583 ing vcs code. See the specific implementations of
584 get_status() for extra options.
585 Parameters
587 · basepath -- status path will be relative to
589 this, if any
590 · untracked -- whether to also show changes that
592 would not commit
593 Returns
595 A string summarizing locally modified files
596 Return type
598 str
599 get_url()
601 Returns
603 git URL of the directory path (output of git info
604 command), or None if it cannot be determined
605 get_version(spec=None)
607 Parameters
609 · spec -- (optional) token to identify desired
611 version. For git, this may be anything accepted
612 by git log, e.g. a tagname, branchname, or
613 sha-id.
614 · fetch -- When spec is given, can be used to sup‐
616 press git fetch call
617 Returns
619 current SHA-ID of the repository. Or if spec is
620 provided, the SHA-ID of a commit specified by some
621 token if found, else None
622 is_tag(tag_name, fetch=True)
624 checks list of tags for match. Set fetch to False if you
625 just fetched already.
626 Returns
628 True if tag_name among known tags
629 Raises GitError when call to git fetch fails
631 static static_detect_presence(path)
633 For auto detection
634 update(version=None, verbose=False, force_fetch=False, time‐
636 out=None)
637 if version is None, attempts fast-forwarding current
638 branch, if any.
639 Else interprets version as a local branch, remote branch,
641 tagname, hash, etc.
642 If it is a branch, attempts to move to it unless already
644 on it, and to fast-forward, unless not a tracking branch.
645 Else go untracked on tag or whatever version is. Does not
646 leave if current commit would become dangling.
647 Returns
649 True if already up-to-date with remote or after
650 successful fast_foward
651 exception vcstools.git.GitError
653 Bases: Exception
654 hg Module
656 hg vcs support.
657 using ui object to redirect output into a string
659 vcstools.hg.HGClient
661 alias of vcstools.hg.HgClient
662 class vcstools.hg.HgClient(path)
664 Bases: vcstools.vcs_base.VcsClientBase
665 checkout(url, version='', verbose=False, shallow=False, time‐
667 out=None)
668 Attempts to create a local repository given a remote url.
669 Fails if a target path exists, unless it's an empty
670 directory. If a version is provided, the local reposi‐
671 tory will be updated to that revision. It is possible
672 that after a failed call to checkout, a repository still
673 exists, e.g. if an invalid revision was given. If shal‐
674 low is provided, the scm client may checkout less than
675 the full repository history to save time / disk space.
676 If a timeout is specified, any pending operation will
677 fail after the specified amount (in seconds). NOTE: this
678 parameter might or might not be honored, depending on VCS
679 client implementation. :param url: where to checkout
680 from :type url: str :param version: token for identifying
681 repository revision :type version: str :param shallow:
682 hint to checkout less than a full repository :type shal‐
683 low: bool :param timeout: maximum allocated time to per‐
684 form operation :type shallow: int :returns: True if suc‐
685 cessful
686 export_repository(version, basepath)
688 Calls scm equivalent to svn export, removing scm meta
689 information and tar gzip'ing the repository at a given
690 version to the given basepath.
691 Parameters
693 version -- version of the repository to export.
694 This can
695 be a branch, tag, or path (svn). When specifying the
697 version as a path for svn, the path should be relative to
698 the root of the svn repository, i.e. 'trunk', or
699 'tags/1.2.3', or './' for the root. :param basepath:
700 this is the path to the tar gzip, excluding the extension
701 which will be .tar.gz :returns: True on success, False
702 otherwise.
703 get_affected_files(revision)
705 Get the files that were affected by a specific revision
706 :param revision: SHA or revision number. :returns: A
707 list of strings with the files affected by a specific
708 commit
709 get_branch()
711 get_branches(local_only=False)
713 Returns a list of all branches in the vcs repository.
714 Parameters
716 local_only -- if True it will only list local
717 branches
718 Returns
720 list of branches in the repository, [] if none
721 exist
722 get_current_version_label()
724 Parameters
726 spec -- (optional) spec can be what 'svn info
727 --help' allows, meaning a revnumber, {date}, HEAD,
728 BASE, PREV, or COMMITTED.
729 Returns
731 current revision number of the repository. Or if
732 spec provided, the number of a revision specified
733 by some token.
734 get_diff(basepath=None)
736 Parameters
738 basepath -- diff paths will be relative to this,
739 if any
740 Returns
742 A string showing local differences
743 Return type
745 str
746 static get_environment_metadata()
748 For debugging purposes, returns a dict containing infor‐
749 mation about the environment, like the version of the SCM
750 client, or version of libraries involved. Suggest con‐
751 sidering keywords "version", "dependency", "features"
752 first. :returns: a dict containing relevant information
753 :rtype: dict
754 get_log(relpath=None, limit=None)
756 Calls scm log command.
757 This returns a list of dictionaries with the following
759 fields:
760 · id: the commit SHA or revision number
762 · date: the date the commit was made (python date‐
764 time)
765 · author: the name of the author of the commit, if
767 available
768 · email: the e-mail address of the author of the
770 commit
771 · message: the commit message, if any
773 Parameters
775 relpath -- (optional) restrict logs to events on
776 this
777 resource path (folder or file) relative to the root of
779 the repository. If None (default), this is the root of
780 the repository. :param limit: (optional) the maximum
781 number of log entries that should be retrieved. If None
782 (default), there is no limit.
783 get_remote_version(fetch=False)
785 Find an identifier for the current revision on remote.
786 Token spec might be a tagname, version-id, SHA-ID, ...
787 depending on the VCS implementation.
788 Parameters
790 fetch -- if False, only local information may be
791 used
792 Returns
794 current revision number of the remote repository.
795 Return type
797 str
798 get_status(basepath=None, untracked=False)
800 Calls scm status command. Output must be terminated by
801 newline unless empty.
802 Semantics of untracked are difficult to generalize. In
804 SVN, this would be new files only. In git, hg, bzr, this
805 would be changes that have not been added for commit.
806 Extra keyword arguments are passed along to the underly‐
808 ing vcs code. See the specific implementations of
809 get_status() for extra options.
810 Parameters
812 · basepath -- status path will be relative to
814 this, if any
815 · untracked -- whether to also show changes that
817 would not commit
818 Returns
820 A string summarizing locally modified files
821 Return type
823 str
824 get_url()
826 Returns
828 HG URL of the directory path. (output of hg paths
829 command), or None if it cannot be determined
831 get_version(spec=None)
833 Parameters
835 spec -- (optional) token for identifying version.
836 spec can be a whatever is allowed by 'hg log -r',
837 e.g. a tagname, sha-ID, revision-number
838 Returns
840 the current SHA-ID of the repository. Or if spec
841 is provided, the SHA-ID of a revision specified by
842 some token.
843 static static_detect_presence(path)
845 For auto detection
846 update(version='', verbose=False, timeout=None)
848 Sets the local copy of the repository to a version match‐
849 ing the version parameter. Fails when there are uncom‐
850 mited changes. On failures (also e.g. network failure)
851 grants the checked out files are in the same state as
852 before the call. If a timeout is specified, any pending
853 operation will fail after the specified amount (in sec‐
854 onds)
855 Parameters
857 · version -- token for identifying repository
859 revision desired. Token might be a tagname,
860 branchname, version-id, SHA-ID, ... depending on
861 the VCS implementation.
862 · timeout -- maximum allocated time to perform
864 operation
865 Returns
867 True on success, False else
868 svn Module
870 svn vcs support.
871 vcstools.svn.SVNClient
873 alias of vcstools.svn.SvnClient
874 class vcstools.svn.SvnClient(path)
876 Bases: vcstools.vcs_base.VcsClientBase
877 checkout(url, version='', verbose=False, shallow=False, time‐
879 out=None)
880 Attempts to create a local repository given a remote url.
881 Fails if a target path exists, unless it's an empty
882 directory. If a version is provided, the local reposi‐
883 tory will be updated to that revision. It is possible
884 that after a failed call to checkout, a repository still
885 exists, e.g. if an invalid revision was given. If shal‐
886 low is provided, the scm client may checkout less than
887 the full repository history to save time / disk space.
888 If a timeout is specified, any pending operation will
889 fail after the specified amount (in seconds). NOTE: this
890 parameter might or might not be honored, depending on VCS
891 client implementation. :param url: where to checkout
892 from :type url: str :param version: token for identifying
893 repository revision :type version: str :param shallow:
894 hint to checkout less than a full repository :type shal‐
895 low: bool :param timeout: maximum allocated time to per‐
896 form operation :type shallow: int :returns: True if suc‐
897 cessful
898 export_repository(version, basepath)
900 Calls scm equivalent to svn export, removing scm meta
901 information and tar gzip'ing the repository at a given
902 version to the given basepath.
903 Parameters
905 version -- version of the repository to export.
906 This can
907 be a branch, tag, or path (svn). When specifying the
909 version as a path for svn, the path should be relative to
910 the root of the svn repository, i.e. 'trunk', or
911 'tags/1.2.3', or './' for the root. :param basepath:
912 this is the path to the tar gzip, excluding the extension
913 which will be .tar.gz :returns: True on success, False
914 otherwise.
915 get_affected_files(revision)
917 Get the files that were affected by a specific revision
918 :param revision: SHA or revision number. :returns: A
919 list of strings with the files affected by a specific
920 commit
921 get_branches(local_only=False)
923 Returns a list of all branches in the vcs repository.
924 Parameters
926 local_only -- if True it will only list local
927 branches
928 Returns
930 list of branches in the repository, [] if none
931 exist
932 get_current_version_label()
934 Find an description for the current local version. Token
935 spec might be a branchname, version-id, SHA-ID, ...
936 depending on the VCS implementation.
937 Returns
939 short description of local version (e.g. branch‐
940 name, tagename).
941 Return type
943 str
944 get_diff(basepath=None)
946 Parameters
948 basepath -- diff paths will be relative to this,
949 if any
950 Returns
952 A string showing local differences
953 Return type
955 str
956 static get_environment_metadata()
958 For debugging purposes, returns a dict containing infor‐
959 mation about the environment, like the version of the SCM
960 client, or version of libraries involved. Suggest con‐
961 sidering keywords "version", "dependency", "features"
962 first. :returns: a dict containing relevant information
963 :rtype: dict
964 get_log(relpath=None, limit=None)
966 Calls scm log command.
967 This returns a list of dictionaries with the following
969 fields:
970 · id: the commit SHA or revision number
972 · date: the date the commit was made (python date‐
974 time)
975 · author: the name of the author of the commit, if
977 available
978 · email: the e-mail address of the author of the
980 commit
981 · message: the commit message, if any
983 Parameters
985 relpath -- (optional) restrict logs to events on
986 this
987 resource path (folder or file) relative to the root of
989 the repository. If None (default), this is the root of
990 the repository. :param limit: (optional) the maximum
991 number of log entries that should be retrieved. If None
992 (default), there is no limit.
993 get_remote_version(fetch=False)
995 Find an identifier for the current revision on remote.
996 Token spec might be a tagname, version-id, SHA-ID, ...
997 depending on the VCS implementation.
998 Parameters
1000 fetch -- if False, only local information may be
1001 used
1002 Returns
1004 current revision number of the remote repository.
1005 Return type
1007 str
1008 get_status(basepath=None, untracked=False)
1010 Calls scm status command. Output must be terminated by
1011 newline unless empty.
1012 Semantics of untracked are difficult to generalize. In
1014 SVN, this would be new files only. In git, hg, bzr, this
1015 would be changes that have not been added for commit.
1016 Extra keyword arguments are passed along to the underly‐
1018 ing vcs code. See the specific implementations of
1019 get_status() for extra options.
1020 Parameters
1022 · basepath -- status path will be relative to
1024 this, if any
1025 · untracked -- whether to also show changes that
1027 would not commit
1028 Returns
1030 A string summarizing locally modified files
1031 Return type
1033 str
1034 get_url()
1036 Returns
1038 SVN URL of the directory path (output of svn info
1039 command), or None if it cannot be determined
1040 get_version(spec=None)
1042 Parameters
1044 · spec -- (optional) spec can be what 'svn info
1046 --help' allows, meaning a revnumber, {date},
1047 HEAD, BASE, PREV, or COMMITTED.
1048 · path -- the url to use, default is for this repo
1050 Returns
1052 current revision number of the repository. Or if
1053 spec provided, the number of a revision specified
1054 by some token.
1055 static static_detect_presence(path)
1057 For auto detection
1058 update(version=None, verbose=False, timeout=None)
1060 Sets the local copy of the repository to a version match‐
1061 ing the version parameter. Fails when there are uncom‐
1062 mited changes. On failures (also e.g. network failure)
1063 grants the checked out files are in the same state as
1064 before the call. If a timeout is specified, any pending
1065 operation will fail after the specified amount (in sec‐
1066 onds)
1067 Parameters
1069 · version -- token for identifying repository
1071 revision desired. Token might be a tagname,
1072 branchname, version-id, SHA-ID, ... depending on
1073 the VCS implementation.
1074 · timeout -- maximum allocated time to perform
1076 operation
1077 Returns
1079 True on success, False else
1080 vcstools.svn.canonical_svn_url_split(url)
1082 checks url for traces of canonical svn structure, and return
1083 root, type, name (of tag or branch), subfolder, query and frag‐
1084 ment (see urllib urlparse) This should allow creating a differ‐
1085 ent url for switching to a different tag or branch
1086 Parameters
1088 url -- location of central repo, str
1089 Returns
1091 dict {root, type, name, subfolder, query, fragment}
1092 with type one of "trunk", "tags", "branches"
1094 vcstools.svn.get_remote_contents(url)
1096 tar Module
1098 tar vcs support.
1099 The implementation uses the "version" argument to indicate a subfolder
1101 within a tarfile. Hence one can organize sources by creating one
1102 tarfile with a folder inside for each version.
1103 vcstools.tar.TARClient
1105 alias of vcstools.tar.TarClient
1106 class vcstools.tar.TarClient(path)
1108 Bases: vcstools.vcs_base.VcsClientBase
1109 checkout(url, version='', verbose=False, shallow=False, time‐
1111 out=None)
1112 untars tar at url to self.path. If version was given,
1113 only the subdirectory 'version' of the tar will end up in
1114 self.path. Also creates a file next to the checkout
1115 named
1116 *
1117 .tar which is a yaml file listing origin url and version
1118 arguments.
1119 export_repository(version, basepath)
1121 Calls scm equivalent to svn export, removing scm meta
1122 information and tar gzip'ing the repository at a given
1123 version to the given basepath.
1124 Parameters
1126 version -- version of the repository to export.
1127 This can
1128 be a branch, tag, or path (svn). When specifying the
1130 version as a path for svn, the path should be relative to
1131 the root of the svn repository, i.e. 'trunk', or
1132 'tags/1.2.3', or './' for the root. :param basepath:
1133 this is the path to the tar gzip, excluding the extension
1134 which will be .tar.gz :returns: True on success, False
1135 otherwise.
1136 get_current_version_label()
1138 Find an description for the current local version. Token
1139 spec might be a branchname, version-id, SHA-ID, ...
1140 depending on the VCS implementation.
1141 Returns
1143 short description of local version (e.g. branch‐
1144 name, tagename).
1145 Return type
1147 str
1148 get_diff(basepath=None)
1150 Parameters
1152 basepath -- diff paths will be relative to this,
1153 if any
1154 Returns
1156 A string showing local differences
1157 Return type
1159 str
1160 static get_environment_metadata()
1162 For debugging purposes, returns a dict containing infor‐
1163 mation about the environment, like the version of the SCM
1164 client, or version of libraries involved. Suggest con‐
1165 sidering keywords "version", "dependency", "features"
1166 first. :returns: a dict containing relevant information
1167 :rtype: dict
1168 get_remote_version(fetch=False)
1170 Find an identifier for the current revision on remote.
1171 Token spec might be a tagname, version-id, SHA-ID, ...
1172 depending on the VCS implementation.
1173 Parameters
1175 fetch -- if False, only local information may be
1176 used
1177 Returns
1179 current revision number of the remote repository.
1180 Return type
1182 str
1183 get_status(basepath=None, untracked=False)
1185 Calls scm status command. Output must be terminated by
1186 newline unless empty.
1187 Semantics of untracked are difficult to generalize. In
1189 SVN, this would be new files only. In git, hg, bzr, this
1190 would be changes that have not been added for commit.
1191 Extra keyword arguments are passed along to the underly‐
1193 ing vcs code. See the specific implementations of
1194 get_status() for extra options.
1195 Parameters
1197 · basepath -- status path will be relative to
1199 this, if any
1200 · untracked -- whether to also show changes that
1202 would not commit
1203 Returns
1205 A string summarizing locally modified files
1206 Return type
1208 str
1209 get_url()
1211 Returns
1213 TAR URL of the directory path (output of tar info
1214 command), or None if it cannot be determined
1216 get_version(spec=None)
1218 Find an identifier for a the current or a specified revi‐
1219 sion. Token spec might be a tagname, branchname, ver‐
1220 sion-id, SHA-ID, ... depending on the VCS implementation.
1221 Parameters
1223 spec (str) -- token for identifying repository
1224 revision
1225 Returns
1227 current revision number of the repository. Or if
1228 spec is provided, the respective revision number.
1229 Return type
1231 str
1232 static static_detect_presence(path)
1234 For auto detection
1235 update(version='', verbose=False, timeout=None)
1237 Does nothing except returning true if tar exists in same
1238 "version" as checked out with vcstools.
1239 vcs_abstraction Module
1241 undoc-members
1242 show-inheritance
1244 vcstools.vcs_abstraction.VCSClient
1246 alias of vcstools.vcs_abstraction.VcsClient
1247 class vcstools.vcs_abstraction.VcsClient(vcs_type, path)
1249 DEPRECATED API for interacting with source-controlled paths
1250 independent of actual version-control implementation.
1251 vcstools.vcs_abstraction.get_registered_vcs_types()
1253 Returns
1255 list of valid key to use as vcs_type
1256 vcstools.vcs_abstraction.get_vcs(vcs_type)
1258 Returns the class interfacing with vcs of given type
1259 Parameters
1261 vcs_type -- id of the tpye, e.g. git, svn, hg, bzr
1262 Returns
1264 class extending VcsClientBase
1265 Raises ValueError for unknown vcs_type
1267 vcstools.vcs_abstraction.get_vcs_client(vcs_type, path)
1269 Returns a client with which to interact with the vcs at given
1270 path
1271 Parameters
1273 vcs_type -- id of the tpye, e.g. git, svn, hg, bzr
1274 Returns
1276 instance of VcsClientBase
1277 Raises ValueError for unknown vcs_type
1279 vcstools.vcs_abstraction.register_vcs(vcs_type, clazz)
1281 Parameters
1283 · vcs_type -- id, str
1285 · clazz -- class extending VcsClientBase
1287 vcs_base Module
1289 vcs support library base class.
1290 undoc-members
1292 show-inheritance
1294 class vcstools.vcs_base.VcsClientBase(vcs_type_name, path)
1296 parent class for all vcs clients, provides their public API
1297 checkout(url, version=None, verbose=False, shallow=False, time‐
1299 out=None)
1300 Attempts to create a local repository given a remote url.
1301 Fails if a target path exists, unless it's an empty
1302 directory. If a version is provided, the local reposi‐
1303 tory will be updated to that revision. It is possible
1304 that after a failed call to checkout, a repository still
1305 exists, e.g. if an invalid revision was given. If shal‐
1306 low is provided, the scm client may checkout less than
1307 the full repository history to save time / disk space.
1308 If a timeout is specified, any pending operation will
1309 fail after the specified amount (in seconds). NOTE: this
1310 parameter might or might not be honored, depending on VCS
1311 client implementation. :param url: where to checkout
1312 from :type url: str :param version: token for identifying
1313 repository revision :type version: str :param shallow:
1314 hint to checkout less than a full repository :type shal‐
1315 low: bool :param timeout: maximum allocated time to per‐
1316 form operation :type shallow: int :returns: True if suc‐
1317 cessful
1318 detect_presence()
1320 For auto detection
1321 export_repository(version, basepath)
1323 Calls scm equivalent to svn export, removing scm meta
1324 information and tar gzip'ing the repository at a given
1325 version to the given basepath.
1326 Parameters
1328 version -- version of the repository to export.
1329 This can
1330 be a branch, tag, or path (svn). When specifying the
1332 version as a path for svn, the path should be relative to
1333 the root of the svn repository, i.e. 'trunk', or
1334 'tags/1.2.3', or './' for the root. :param basepath:
1335 this is the path to the tar gzip, excluding the extension
1336 which will be .tar.gz :returns: True on success, False
1337 otherwise.
1338 get_affected_files(revision)
1340 Get the files that were affected by a specific revision
1341 :param revision: SHA or revision number. :returns: A
1342 list of strings with the files affected by a specific
1343 commit
1344 get_branches(local_only=False)
1346 Returns a list of all branches in the vcs repository.
1347 Parameters
1349 local_only -- if True it will only list local
1350 branches
1351 Returns
1353 list of branches in the repository, [] if none
1354 exist
1355 get_current_version_label()
1357 Find an description for the current local version. Token
1358 spec might be a branchname, version-id, SHA-ID, ...
1359 depending on the VCS implementation.
1360 Returns
1362 short description of local version (e.g. branch‐
1363 name, tagename).
1364 Return type
1366 str
1367 get_default_remote_version_label()
1369 Find a label for the default branch on remote, meaning
1370 the one that would be checked out on a clean checkout.
1371 Returns
1373 a label or None (if not applicable)
1374 Return type
1376 str
1377 get_diff(basepath=None)
1379 Parameters
1381 basepath -- diff paths will be relative to this,
1382 if any
1383 Returns
1385 A string showing local differences
1386 Return type
1388 str
1389 static get_environment_metadata()
1391 For debugging purposes, returns a dict containing infor‐
1392 mation about the environment, like the version of the SCM
1393 client, or version of libraries involved. Suggest con‐
1394 sidering keywords "version", "dependency", "features"
1395 first. :returns: a dict containing relevant information
1396 :rtype: dict
1397 get_log(relpath=None, limit=None)
1399 Calls scm log command.
1400 This returns a list of dictionaries with the following
1402 fields:
1403 · id: the commit SHA or revision number
1405 · date: the date the commit was made (python date‐
1407 time)
1408 · author: the name of the author of the commit, if
1410 available
1411 · email: the e-mail address of the author of the
1413 commit
1414 · message: the commit message, if any
1416 Parameters
1418 relpath -- (optional) restrict logs to events on
1419 this
1420 resource path (folder or file) relative to the root of
1422 the repository. If None (default), this is the root of
1423 the repository. :param limit: (optional) the maximum
1424 number of log entries that should be retrieved. If None
1425 (default), there is no limit.
1426 get_path()
1428 returns the path this client was configured for
1429 get_remote_version(fetch=False)
1431 Find an identifier for the current revision on remote.
1432 Token spec might be a tagname, version-id, SHA-ID, ...
1433 depending on the VCS implementation.
1434 Parameters
1436 fetch -- if False, only local information may be
1437 used
1438 Returns
1440 current revision number of the remote repository.
1441 Return type
1443 str
1444 get_status(basepath=None, untracked=False, **kwargs)
1446 Calls scm status command. Output must be terminated by
1447 newline unless empty.
1448 Semantics of untracked are difficult to generalize. In
1450 SVN, this would be new files only. In git, hg, bzr, this
1451 would be changes that have not been added for commit.
1452 Extra keyword arguments are passed along to the underly‐
1454 ing vcs code. See the specific implementations of
1455 get_status() for extra options.
1456 Parameters
1458 · basepath -- status path will be relative to
1460 this, if any
1461 · untracked -- whether to also show changes that
1463 would not commit
1464 Returns
1466 A string summarizing locally modified files
1467 Return type
1469 str
1470 get_url()
1472 Returns
1474 The source control url for the path or None if not
1475 set
1476 Return type
1478 str
1479 get_vcs_type_name()
1481 used when auto detected
1482 get_version(spec=None)
1484 Find an identifier for a the current or a specified revi‐
1485 sion. Token spec might be a tagname, branchname, ver‐
1486 sion-id, SHA-ID, ... depending on the VCS implementation.
1487 Parameters
1489 spec (str) -- token for identifying repository
1490 revision
1491 Returns
1493 current revision number of the repository. Or if
1494 spec is provided, the respective revision number.
1495 Return type
1497 str
1498 path_exists()
1500 helper function
1501 static static_detect_presence(path)
1503 For auto detection
1504 update(version=None, verbose=False, timeout=None)
1506 Sets the local copy of the repository to a version match‐
1507 ing the version parameter. Fails when there are uncom‐
1508 mited changes. On failures (also e.g. network failure)
1509 grants the checked out files are in the same state as
1510 before the call. If a timeout is specified, any pending
1511 operation will fail after the specified amount (in sec‐
1512 onds)
1513 Parameters
1515 · version -- token for identifying repository
1517 revision desired. Token might be a tagname,
1518 branchname, version-id, SHA-ID, ... depending on
1519 the VCS implementation.
1520 · timeout -- maximum allocated time to perform
1522 operation
1523 Returns
1525 True on success, False else
1526 url_matches(url, url_or_shortcut)
1528 client can decide whether the url and the other url are
1529 equivalent. Checks string equality by default :param
1530 url_or_shortcut: url or shortcut (e.g. bzr launchpad url)
1531 :returns: bool if params are equivalent
1532 exception vcstools.vcs_base.VcsError(value)
1534 To be thrown when an SCM Client faces a situation because of a
1535 violated assumption
1536 Changelog
1538 Changelog
1539 0.1
1540 0.1.42
1541 · remove cosmic and disco until we have hosting for it
1542 0.1.41
1544 · fix git submodule error due to lack of quoting
1545 · Fix git update failure by refreshing git index before fast-forward
1547 · Fix python3 incompatibility due to wrong use of urlopen
1549 · Updating get_affected_files function by removing single quotes cover‐
1551 ing format (#129)
1552 · Fix export_upstream for git submodules with relative urls. (#130)
1554 0.1.40
1556 · Trivial style and testing changes
1557 0.1.39
1559 · Added support for git submodule in export_repository
1560 · Add Wily Xenial Yakkety
1562 · Add get_affected_files for all vcss
1564 0.1.38
1566 · Fixed test failures due to SVN 1.9.
1567 · Added the get_default_remote_version_label() API method to support
1569 changes in wstool.
1570 · Renamed some internal functions to have a leading _ to indicate that
1572 they are private.
1573 0.1.37
1575 · Fix an issue where log were restricted to the named branch (hg).
1576 · Fixed svn to use a global revision number rather than a branch-local
1578 revision.
1579 · Added the get_remote_version() and get_current_version_label() API
1581 calls.
1582 · Enhanced use of no_warn in run_shell_command().
1584 · Fix get_version() to catch stderr.
1586 · Added get_branches() API call.
1588 · Fix some errors and warnings to output to stderr.
1590 · Fix output to avoid extra newlines when show_stdout=True.
1592 0.1.36
1594 · Updates to the release platforms (-lucid +utopic +vivid)
1595 · Fix an issue with updating branches on git, see vcstools/wstool#25
1597 0.1.31
1599 · Fix submodule support on checkout #71
1600 0.1.30
1602 · use netrc to download tars from private repos, also will work for
1603 private rosinstall files
1604 · Fix checks for empty repository #62
1606 0.1.29
1608 · fix #57 shallow checkout of non-master breaks with git >= 1.8.0
1609 · unit test fixes
1611 0.1.28
1613 · test of new upload method
1614 0.1.27
1616 · fix #51 hg status and diff dont work if workspace is inside hg repo
1617 · fix #47 several performance improvements by removing unecessary
1619 update actions after checkout
1620 · fix #46 https tar download fails behind proxy
1622 · fix #45 sometimes commands run forever
1624 · fix #44 minor bug when checking out from repo with default branch not
1626 master
1627 · fix #41 improvedAPI, get_vcs_client function part of vcstools module
1629 0.1.26
1631 · fix #38 git commands fail in local repositories with many (>2000)
1632 references
1633 · fix #31 get_log() svn xml not available on Ubuntu Lucid (hg 1.4.2)
1635 · fix #37 update() returns True even when fetch failed
1637 0.1.25
1639 · minor bugfixes
1640 · travis-ci config file
1642 · fix unit tests for svn diff&status ordering changes
1644 · deprecated VcsClient Class
1646 · added get_log function
1648 0.1.24
1650 · fix git update return value to False when fast-forward not possible
1651 due to diverge
1652 · fix. svn certificate prompt invisible, svn checkout and update become
1654 verbose due to this
1655 0.1.22
1657 · Changed the way that git implements detect_presence to fix a bug with
1658 submodules in newer versions of git
1659 · fix for git single quotes on Windows
1661 · minor internal api bug where a git function always returned True
1663 · fix gub in svn export_repository
1665 0.1.21
1667 · bugfix #66: hg http username prompt hidden
1668 · add export_repository method to vcs_base and all implementations with
1670 tests
1671 · bugfix #64: unicode decoding problems
1673 0.1.20
1675 · rosws update –verbose for git prints small message when rebasing
1676 · improved python3 compatibility
1678 0.1.19
1680 · more python3 compatibility
1681 · code style improved
1683 · match_url to compare bzr shortcuts to real urls
1685 · more unit tests
1687 · get_status required to end with newline, to fix #55
1689 0.1.18
1691 · added shallow flag to API, implemented for git
1692 0.1.17
1694 · svn stdout output on get_version removed
1695 0.1.16
1697 · All SCMs show some output when update caused changes
1698 · All SCMs have verbose option to show all changes done on update
1700 · bugfix for bazaar getUrl() being a joined abspath
1702 · bugfix for not all output being shown when requested
1704 0.1.15
1706 · Added pyyaml as a proper dependency, removed detection code.
1707 · remove use of tar entirely, switch to tarfile module
1709 · fix #36 allowing for tar being bsdtar on OSX
1711 0.1.14
1713 · Added tarball uncompression.
1714 0.1.13
1716 · added this changelog
1717 · git get-version fetches only when local lookup fails
1719 · hg get-version pulls if label not found
1721 · Popen error message incudes cwd path
1723 0.1.12
1725 · py_checker clean after all refactorings since 0.1.0
1726 0.1.11
1728 · svn and hg update without user interaction
1729 · bugfix #30
1731 · minor bugfixes
1733 0.1.10
1735 · minor bugs
1736 0.1.9
1738 · safer sanitization of shell params
1739 · git diff and stat recurse for submodules
1741 · base class manages all calls to Popen
1743 0.1.8
1745 · several bugfixes
1746 · reverted using shell commands instead of bazaar API
1748 0.1.7
1750 · reverted using shell commands instaed of pysvn and mercurial APIs
1751 · protection against shell incection attempts
1753 0.1.6
1755 · bugfixes to svn and bzr
1756 · unified all calls through Popen
1758 0.1.5
1760 · missing dependency to dateutil added
1761 0.1.4
1763 switched shell calls to calls to python API of mercurial, bazaar,
1764 py-svn
1765 0.1.3
1767 · fix #6
1768 0.1.2
1770 · fix #15
1771 0.1.1
1773 · more unit tests
1774 · diverse bugfixes
1776 · major change to git client behavior, based around git
1778 https://kforge.ros.org/vcstools/trac/ticket/1
1779 0.1.0
1781 · documentation fixes
1782 0.0.3
1784 · import from svn
1785 Bug reports and feature requests
1787 · Submit a bug report
1788 Developer Setup
1790 vcstools uses setuptools, which you will need to download and install
1791 in order to run the packaging. We use setuptools instead of distutils
1792 in order to be able use setup() keys like install_requires.
1793 cd vcstools python setup.py develop
1794 Testing
1796 Install test dependencies
1797 pip install nose
1799 pip install mock
1800 vcstools uses Python nose for testing, which is a fairly simple and
1802 straightfoward test framework. The vcstools mainly use unittest to
1803 construct test fixtures, but with nose you can also just write a func‐
1804 tion that starts with the name test and use normal assert statements.
1805 vcstools also uses mock to create mocks for testing.
1807 You can run the tests, including coverage, as follows:
1809 cd vcstools
1811 make test
1812 Documentation
1814 Sphinx is used to provide API documentation for vcstools. The docu‐
1815 ments are stored in the doc subdirectory.
1816 · genindex
1818 · modindex
1820 · search
1822
1824 Tully Foote, Thibault Kruse, Ken Conley
1825
1827 2020, Willow Garage
18280.1.42 Jul 29, 2020 VCSTOOLS(1)