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 __init__(path)
223 Raises VcsError if bzr not detected
225 checkout(url, version=None, verbose=False, shallow=False, time‐
227 out=None)
228 export_repository(version, basepath)
230 get_affected_files(revision)
232 get_branches(local_only=False)
234 get_current_version_label()
236 get_diff(basepath=None)
238 static get_environment_metadata()
240 get_log(relpath=None, limit=None)
242 get_remote_version(fetch=False)
244 get_status(basepath=None, untracked=False)
246 get_url()
248 Returns
250 BZR URL of the branch (output of bzr info com‐
251 mand),
252 or None if it cannot be determined
254 get_version(spec=None)
256 Parameters
258 spec -- (optional) revisionspec of desired ver‐
259 sion. May be any revisionspec as returned by 'bzr
260 help revisionspec', e.g. a tagname or 'revno:<num‐
261 ber>'
262 Returns
264 the current revision number of the repository. Or
265 if spec is provided, the number of a revision
266 specified by some token.
267 static static_detect_presence(path)
269 update(version=u'', verbose=False, timeout=None)
271 url_matches(url, url_or_shortcut)
273 vcstools.bzr._get_bzr_version()
275 Looks up bzr version by calling bzr --version. :raises: VcsEr‐
276 ror if bzr is not installed
277 git Module
279 git vcs support.
280 refnames in git can be branchnames, hashes, partial hashes, tags. On
282 checkout, git will disambiguate by checking them in that order, taking
283 the first that applies
284 This class aims to provide git for linear centralized workflows. This
286 means in case of ambiguity, we assume that the only relevant remote is
287 the one named "origin", and we assume that commits once on origin
288 remain on origin.
289 A challenge with git is that it has strong reasonable conventions, but
291 is very allowing for breaking them. E.g. it is possible to name remotes
292 and branches with names like "refs/heads/master", give branches and
293 tags the same name, or a valid SHA-ID as name, etc. Similarly git
294 allows plenty of ways to reference any object, in case of ambiguities,
295 git attempts to take the most reasonable disambiguation, and in some
296 cases warns.
297 vcstools.git.GITClient
299 alias of vcstools.git.GitClient
300 class vcstools.git.GitClient(path)
302 Bases: vcstools.vcs_base.VcsClientBase
303 __init__(path)
305 Raises VcsError if git not detected
307 _do_checkout(refname, fetch=True, verbose=False)
309 meaning git checkout, not vcstools checkout. This works
310 for local branches, remote branches, tagnames, hashes,
311 etc. git will create local branch of same name when no
312 such local branch exists, and also setup tracking. Git
313 decides with own rules whether local changes would cause
314 conflicts, and refuses to checkout else.
315 Raises GitError -- when checkout fails
317 _do_fast_forward(branch_parent, fetch=True, verbose=False)
319 Execute git fetch if necessary, and if we can
320 fast-foward, do so to the last fetched version using git
321 rebase.
322 Parameters
324 · branch_parent -- name of branch we track
326 · fetch -- whether fetch should be done first for
328 remote refs
329 Returns
331 True if up-to-date or after succesful fast-forward
332 Raises GitError when git fetch fails
334 _do_fetch(timeout=None)
336 calls git fetch :raises: GitError when call fails
337 _do_update(refname=None, verbose=False, fast_foward=True, time‐
339 out=None, update_submodules=True)
340 updates without fetching, thus any necessary fetching
341 must be done before allows arguments to reduce unneces‐
342 sary steps after checkout
343 Parameters
345 · fast_foward -- if false, does not perform
347 fast-forward
348 · update_submodules -- if false, does not attempt
350 to update submodules
351 _get_branch()
353 _get_branch_parent(fetch=False, current_branch=None)
355 Parameters
357 · fetch -- if true, performs git fetch first
359 · current_branch -- if not None, this is used as
361 current branch (else extra shell call)
362 Returns
364 (branch, remote) the name of the branch this
365 branch tracks and its remote
366 Raises GitError if fetch fails
368 _get_default_remote()
370 in order to support users who name their default origin
371 something else than origin, read remote name.
372 _is_commit_in_orphaned_subtree(version, mask_self=False,
374 fetch=True)
375 checks git log --all (the list of all commits reached by
376 references, meaning branches or tags) for version. If it
377 shows up, that means git garbage collection will not
378 remove the commit. Else it would eventually be deleted.
379 Parameters
381 · version -- SHA IDs (if partial, caller is
383 responsible for mismatch)
384 · mask_self -- whether to consider direct refer‐
386 ences to this commit (rather than only refer‐
387 ences on descendants) as well
388 · fetch -- whether fetch should be done first for
390 remote refs
391 Returns
393 True if version is not recursively referenced by a
394 branch or tag
395 Raises GitError if git fetch fails
397 _is_local_branch(branch_name)
399 _is_remote_branch(branch_name, remote_name=None, fetch=True)
401 checks list of remote branches for match. Set fetch to
402 False if you just fetched already.
403 Returns
405 True if branch_name exists for remote
406 <remote_name> (or 'origin' if None)
407 Raises GitError when git fetch fails
409 _rev_list_contains(refname, version, fetch=True)
411 calls git rev-list with refname and returns True if ver‐
412 sion can be found in rev-list result
413 Parameters
415 · refname -- a git refname
417 · version -- an SHA IDs (if partial, caller is
419 responsible for mismatch)
420 Returns
422 True if version is an ancestor commit from refname
423 Raises GitError when call to git fetch fails
425 _update_submodules(verbose=False, timeout=None)
427 checkout(url, version=None, verbose=False, shallow=False, time‐
429 out=None)
430 calls git clone and then, if version was given,
431 update(version)
432 export_repository(version, basepath)
434 get_affected_files(revision)
436 get_branches(local_only=False)
438 get_current_version_label()
440 For git we change the label to clarify when a different
441 remote is configured.
442 get_default_remote_version_label()
444 get_diff(basepath=None)
446 static get_environment_metadata()
448 get_log(relpath=None, limit=None)
450 get_remote_version(fetch=False)
452 get_status(basepath=None, untracked=False, porcelain=False)
454 get_url()
456 Returns
458 git URL of the directory path (output of git info
459 command), or None if it cannot be determined
460 get_version(spec=None)
462 Parameters
464 · spec -- (optional) token to identify desired
466 version. For git, this may be anything accepted
467 by git log, e.g. a tagname, branchname, or
468 sha-id.
469 · fetch -- When spec is given, can be used to sup‐
471 press git fetch call
472 Returns
474 current SHA-ID of the repository. Or if spec is
475 provided, the SHA-ID of a commit specified by some
476 token if found, else None
477 is_tag(tag_name, fetch=True)
479 checks list of tags for match. Set fetch to False if you
480 just fetched already.
481 Returns
483 True if tag_name among known tags
484 Raises GitError when call to git fetch fails
486 static static_detect_presence(path)
488 update(version=None, verbose=False, force_fetch=False, time‐
490 out=None)
491 if version is None, attempts fast-forwarding current
492 branch, if any.
493 Else interprets version as a local branch, remote branch,
495 tagname, hash, etc.
496 If it is a branch, attempts to move to it unless already
498 on it, and to fast-forward, unless not a tracking branch.
499 Else go untracked on tag or whatever version is. Does not
500 leave if current commit would become dangling.
501 Returns
503 True if already up-to-date with remote or after
504 successful fast_foward
505 exception vcstools.git.GitError
507 Bases: exceptions.Exception
508 vcstools.git._get_git_version()
510 Looks up git version by calling git --version.
511 Raises VcsError if git is not installed or returns
513 something unexpected
515 vcstools.git._git_diff_path_submodule_change(diff, rel_path_prefix)
517 Parses git diff result and changes the filename prefixes.
518 hg Module
520 hg vcs support.
521 using ui object to redirect output into a string
523 vcstools.hg.HGClient
525 alias of vcstools.hg.HgClient
526 class vcstools.hg.HgClient(path)
528 Bases: vcstools.vcs_base.VcsClientBase
529 __init__(path)
531 Raises VcsError if hg not detected
533 _do_pull(filter=False)
535 checkout(url, version=u'', verbose=False, shallow=False, time‐
537 out=None)
538 export_repository(version, basepath)
540 get_affected_files(revision)
542 get_branch()
544 get_branches(local_only=False)
546 get_current_version_label()
548 Parameters
550 spec -- (optional) spec can be what 'svn info
551 --help' allows, meaning a revnumber, {date}, HEAD,
552 BASE, PREV, or COMMITTED.
553 Returns
555 current revision number of the repository. Or if
556 spec provided, the number of a revision specified
557 by some token.
558 get_diff(basepath=None)
560 static get_environment_metadata()
562 get_log(relpath=None, limit=None)
564 get_remote_version(fetch=False)
566 get_status(basepath=None, untracked=False)
568 get_url()
570 Returns
572 HG URL of the directory path. (output of hg paths
573 command), or None if it cannot be determined
575 get_version(spec=None)
577 Parameters
579 spec -- (optional) token for identifying version.
580 spec can be a whatever is allowed by 'hg log -r',
581 e.g. a tagname, sha-ID, revision-number
582 Returns
584 the current SHA-ID of the repository. Or if spec
585 is provided, the SHA-ID of a revision specified by
586 some token.
587 static static_detect_presence(path)
589 update(version=u'', verbose=False, timeout=None)
591 vcstools.hg._get_hg_version()
593 Looks up hg version by calling hg --version. :raises: VcsError
594 if hg is not installed
595 vcstools.hg._hg_diff_path_change(diff, path)
597 Parses hg diff result and changes the filename prefixes.
598 svn Module
600 svn vcs support.
601 vcstools.svn.SVNClient
603 alias of vcstools.svn.SvnClient
604 class vcstools.svn.SvnClient(path)
606 Bases: vcstools.vcs_base.VcsClientBase
607 __init__(path)
609 Raises VcsError if python-svn not detected
611 _get_version_from_path(spec=None, path=None)
613 Parameters
615 · spec -- (optional) spec can be what 'svn info
617 --help' allows, meaning a revnumber, {date},
618 HEAD, BASE, PREV, or COMMITTED.
619 · path -- the url to use, default is for this repo
621 Returns
623 current revision number of the repository. Or if
624 spec provided, the number of a revision specified
625 by some token.
626 checkout(url, version=u'', verbose=False, shallow=False, time‐
628 out=None)
629 export_repository(version, basepath)
631 get_affected_files(revision)
633 get_branches(local_only=False)
635 get_current_version_label()
637 get_diff(basepath=None)
639 static get_environment_metadata()
641 get_log(relpath=None, limit=None)
643 get_remote_version(fetch=False)
645 get_status(basepath=None, untracked=False)
647 get_url()
649 Returns
651 SVN URL of the directory path (output of svn info
652 command), or None if it cannot be determined
653 get_version(spec=None)
655 Parameters
657 · spec -- (optional) spec can be what 'svn info
659 --help' allows, meaning a revnumber, {date},
660 HEAD, BASE, PREV, or COMMITTED.
661 · path -- the url to use, default is for this repo
663 Returns
665 current revision number of the repository. Or if
666 spec provided, the number of a revision specified
667 by some token.
668 static static_detect_presence(path)
670 update(version=None, verbose=False, timeout=None)
672 vcstools.svn._get_svn_version()
674 Looks up svn version by calling svn --version. :raises: VcsEr‐
675 ror if svn is not installed
676 vcstools.svn.canonical_svn_url_split(url)
678 checks url for traces of canonical svn structure, and return
679 root, type, name (of tag or branch), subfolder, query and frag‐
680 ment (see urllib urlparse) This should allow creating a differ‐
681 ent url for switching to a different tag or branch
682 Parameters
684 url -- location of central repo, str
685 Returns
687 dict {root, type, name, subfolder, query, fragment}
688 with type one of "trunk", "tags", "branches"
690 vcstools.svn.get_remote_contents(url)
692 tar Module
694 tar vcs support.
695 The implementation uses the "version" argument to indicate a subfolder
697 within a tarfile. Hence one can organize sources by creating one
698 tarfile with a folder inside for each version.
699 vcstools.tar.TARClient
701 alias of vcstools.tar.TarClient
702 class vcstools.tar.TarClient(path)
704 Bases: vcstools.vcs_base.VcsClientBase
705 __init__(path)
707 @raise VcsError if tar not detected
708 checkout(url, version=u'', verbose=False, shallow=False, time‐
710 out=None)
711 untars tar at url to self.path. If version was given,
712 only the subdirectory 'version' of the tar will end up in
713 self.path. Also creates a file next to the checkout
714 named
715 *
716 .tar which is a yaml file listing origin url and version
717 arguments.
718 export_repository(version, basepath)
720 get_current_version_label()
722 get_diff(basepath=None)
724 static get_environment_metadata()
726 get_remote_version(fetch=False)
728 get_status(basepath=None, untracked=False)
730 get_url()
732 Returns
734 TAR URL of the directory path (output of tar info
735 command), or None if it cannot be determined
737 get_version(spec=None)
739 static static_detect_presence(path)
741 update(version=u'', verbose=False, timeout=None)
743 Does nothing except returning true if tar exists in same
744 "version" as checked out with vcstools.
745 vcs_abstraction Module
747 undoc-members
748 show-inheritance
750 vcstools.vcs_abstraction.VCSClient
752 alias of vcstools.vcs_abstraction.VcsClient
753 class vcstools.vcs_abstraction.VcsClient(vcs_type, path)
755 Bases: object
756 DEPRECATED API for interacting with source-controlled paths
758 independent of actual version-control implementation.
759 __init__(vcs_type, path)
761 x.__init__(...) initializes x; see help(type(x)) for sig‐
762 nature
763 vcstools.vcs_abstraction.get_registered_vcs_types()
765 Returns
767 list of valid key to use as vcs_type
768 vcstools.vcs_abstraction.get_vcs(vcs_type)
770 Returns the class interfacing with vcs of given type
771 Parameters
773 vcs_type -- id of the tpye, e.g. git, svn, hg, bzr
774 Returns
776 class extending VcsClientBase
777 Raises ValueError for unknown vcs_type
779 vcstools.vcs_abstraction.get_vcs_client(vcs_type, path)
781 Returns a client with which to interact with the vcs at given
782 path
783 Parameters
785 vcs_type -- id of the tpye, e.g. git, svn, hg, bzr
786 Returns
788 instance of VcsClientBase
789 Raises ValueError for unknown vcs_type
791 vcstools.vcs_abstraction.register_vcs(vcs_type, clazz)
793 Parameters
795 · vcs_type -- id, str
797 · clazz -- class extending VcsClientBase
799 vcs_base Module
801 vcs support library base class.
802 undoc-members
804 show-inheritance
806 class vcstools.vcs_base.VcsClientBase(vcs_type_name, path)
808 Bases: object
809 parent class for all vcs clients, provides their public API
811 __init__(vcs_type_name, path)
813 subclasses may raise VcsError when a dependency is miss‐
814 ing
815 checkout(url, version=None, verbose=False, shallow=False, time‐
817 out=None)
818 Attempts to create a local repository given a remote url.
819 Fails if a target path exists, unless it's an empty
820 directory. If a version is provided, the local reposi‐
821 tory will be updated to that revision. It is possible
822 that after a failed call to checkout, a repository still
823 exists, e.g. if an invalid revision was given. If shal‐
824 low is provided, the scm client may checkout less than
825 the full repository history to save time / disk space.
826 If a timeout is specified, any pending operation will
827 fail after the specified amount (in seconds). NOTE: this
828 parameter might or might not be honored, depending on VCS
829 client implementation. :param url: where to checkout
830 from :type url: str :param version: token for identifying
831 repository revision :type version: str :param shallow:
832 hint to checkout less than a full repository :type shal‐
833 low: bool :param timeout: maximum allocated time to per‐
834 form operation :type shallow: int :returns: True if suc‐
835 cessful
836 detect_presence()
838 For auto detection
839 export_repository(version, basepath)
841 Calls scm equivalent to svn export, removing scm meta
842 information and tar gzip'ing the repository at a given
843 version to the given basepath.
844 Parameters
846 version -- version of the repository to export.
847 This can
848 be a branch, tag, or path (svn). When specifying the
850 version as a path for svn, the path should be relative to
851 the root of the svn repository, i.e. 'trunk', or
852 'tags/1.2.3', or './' for the root. :param basepath:
853 this is the path to the tar gzip, excluding the extension
854 which will be .tar.gz :returns: True on success, False
855 otherwise.
856 get_affected_files(revision)
858 Get the files that were affected by a specific revision
859 :param revision: SHA or revision number. :returns: A
860 list of strings with the files affected by a specific
861 commit
862 get_branches(local_only=False)
864 Returns a list of all branches in the vcs repository.
865 Parameters
867 local_only -- if True it will only list local
868 branches
869 Returns
871 list of branches in the repository, [] if none
872 exist
873 get_current_version_label()
875 Find an description for the current local version. Token
876 spec might be a branchname, version-id, SHA-ID, ...
877 depending on the VCS implementation.
878 Returns
880 short description of local version (e.g. branch‐
881 name, tagename).
882 Return type
884 str
885 get_default_remote_version_label()
887 Find a label for the default branch on remote, meaning
888 the one that would be checked out on a clean checkout.
889 Returns
891 a label or None (if not applicable)
892 Return type
894 str
895 get_diff(basepath=None)
897 Parameters
899 basepath -- diff paths will be relative to this,
900 if any
901 Returns
903 A string showing local differences
904 Return type
906 str
907 static get_environment_metadata()
909 For debugging purposes, returns a dict containing infor‐
910 mation about the environment, like the version of the SCM
911 client, or version of libraries involved. Suggest con‐
912 sidering keywords "version", "dependency", "features"
913 first. :returns: a dict containing relevant information
914 :rtype: dict
915 get_log(relpath=None, limit=None)
917 Calls scm log command.
918 This returns a list of dictionaries with the following
920 fields:
921 · id: the commit SHA or revision number
923 · date: the date the commit was made (python date‐
925 time)
926 · author: the name of the author of the commit, if
928 available
929 · email: the e-mail address of the author of the
931 commit
932 · message: the commit message, if any
934 Parameters
936 relpath -- (optional) restrict logs to events on
937 this
938 resource path (folder or file) relative to the root of
940 the repository. If None (default), this is the root of
941 the repository. :param limit: (optional) the maximum
942 number of log entries that should be retrieved. If None
943 (default), there is no limit.
944 get_path()
946 returns the path this client was configured for
947 get_remote_version(fetch=False)
949 Find an identifier for the current revision on remote.
950 Token spec might be a tagname, version-id, SHA-ID, ...
951 depending on the VCS implementation.
952 Parameters
954 fetch -- if False, only local information may be
955 used
956 Returns
958 current revision number of the remote repository.
959 Return type
961 str
962 get_status(basepath=None, untracked=False, **kwargs)
964 Calls scm status command. Output must be terminated by
965 newline unless empty.
966 Semantics of untracked are difficult to generalize. In
968 SVN, this would be new files only. In git, hg, bzr, this
969 would be changes that have not been added for commit.
970 Extra keyword arguments are passed along to the underly‐
972 ing vcs code. See the specific implementations of
973 get_status() for extra options.
974 Parameters
976 · basepath -- status path will be relative to
978 this, if any
979 · untracked -- whether to also show changes that
981 would not commit
982 Returns
984 A string summarizing locally modified files
985 Return type
987 str
988 get_url()
990 Returns
992 The source control url for the path or None if not
993 set
994 Return type
996 str
997 get_vcs_type_name()
999 used when auto detected
1000 get_version(spec=None)
1002 Find an identifier for a the current or a specified revi‐
1003 sion. Token spec might be a tagname, branchname, ver‐
1004 sion-id, SHA-ID, ... depending on the VCS implementation.
1005 Parameters
1007 spec (str) -- token for identifying repository
1008 revision
1009 Returns
1011 current revision number of the repository. Or if
1012 spec is provided, the respective revision number.
1013 Return type
1015 str
1016 path_exists()
1018 helper function
1019 static static_detect_presence(path)
1021 For auto detection
1022 update(version=None, verbose=False, timeout=None)
1024 Sets the local copy of the repository to a version match‐
1025 ing the version parameter. Fails when there are uncom‐
1026 mited changes. On failures (also e.g. network failure)
1027 grants the checked out files are in the same state as
1028 before the call. If a timeout is specified, any pending
1029 operation will fail after the specified amount (in sec‐
1030 onds)
1031 Parameters
1033 · version -- token for identifying repository
1035 revision desired. Token might be a tagname,
1036 branchname, version-id, SHA-ID, ... depending on
1037 the VCS implementation.
1038 · timeout -- maximum allocated time to perform
1040 operation
1041 Returns
1043 True on success, False else
1044 url_matches(url, url_or_shortcut)
1046 client can decide whether the url and the other url are
1047 equivalent. Checks string equality by default :param
1048 url_or_shortcut: url or shortcut (e.g. bzr launchpad url)
1049 :returns: bool if params are equivalent
1050 exception vcstools.vcs_base.VcsError(value)
1052 Bases: exceptions.Exception
1053 To be thrown when an SCM Client faces a situation because of a
1055 violated assumption
1056 __init__(value)
1058 x.__init__(...) initializes x; see help(type(x)) for sig‐
1059 nature
1060 __str__() <==> str(x)
1062 Changelog
1064 Changelog
1065 0.1
1066 0.1.40
1067 · Trivial style and testing changes
1068 0.1.39
1070 · Added support for git submodule in export_repository
1071 · Add Wily Xenial Yakkety
1073 · Add get_affected_files for all vcss
1075 0.1.38
1077 · Fixed test failures due to SVN 1.9.
1078 · Added the get_default_remote_version_label() API method to support
1080 changes in wstool.
1081 · Renamed some internal functions to have a leading _ to indicate that
1083 they are private.
1084 0.1.37
1086 · Fix an issue where log were restricted to the named branch (hg).
1087 · Fixed svn to use a global revision number rather than a branch-local
1089 revision.
1090 · Added the get_remote_version() and get_current_version_label() API
1092 calls.
1093 · Enhanced use of no_warn in run_shell_command().
1095 · Fix get_version() to catch stderr.
1097 · Added get_branches() API call.
1099 · Fix some errors and warnings to output to stderr.
1101 · Fix output to avoid extra newlines when show_stdout=True.
1103 0.1.36
1105 · Updates to the release platforms (-lucid +utopic +vivid)
1106 · Fix an issue with updating branches on git, see vcstools/wstool#25
1108 0.1.31
1110 · Fix submodule support on checkout #71
1111 0.1.30
1113 · use netrc to download tars from private repos, also will work for
1114 private rosinstall files
1115 · Fix checks for empty repository #62
1117 0.1.29
1119 · fix #57 shallow checkout of non-master breaks with git >= 1.8.0
1120 · unit test fixes
1122 0.1.28
1124 · test of new upload method
1125 0.1.27
1127 · fix #51 hg status and diff dont work if workspace is inside hg repo
1128 · fix #47 several performance improvements by removing unecessary
1130 update actions after checkout
1131 · fix #46 https tar download fails behind proxy
1133 · fix #45 sometimes commands run forever
1135 · fix #44 minor bug when checking out from repo with default branch not
1137 master
1138 · fix #41 improvedAPI, get_vcs_client function part of vcstools module
1140 0.1.26
1142 · fix #38 git commands fail in local repositories with many (>2000)
1143 references
1144 · fix #31 get_log() svn xml not available on Ubuntu Lucid (hg 1.4.2)
1146 · fix #37 update() returns True even when fetch failed
1148 0.1.25
1150 · minor bugfixes
1151 · travis-ci config file
1153 · fix unit tests for svn diff&status ordering changes
1155 · deprecated VcsClient Class
1157 · added get_log function
1159 0.1.24
1161 · fix git update return value to False when fast-forward not possible
1162 due to diverge
1163 · fix. svn certificate prompt invisible, svn checkout and update become
1165 verbose due to this
1166 0.1.22
1168 · Changed the way that git implements detect_presence to fix a bug with
1169 submodules in newer versions of git
1170 · fix for git single quotes on Windows
1172 · minor internal api bug where a git function always returned True
1174 · fix gub in svn export_repository
1176 0.1.21
1178 · bugfix #66: hg http username prompt hidden
1179 · add export_repository method to vcs_base and all implementations with
1181 tests
1182 · bugfix #64: unicode decoding problems
1184 0.1.20
1186 · rosws update –verbose for git prints small message when rebasing
1187 · improved python3 compatibility
1189 0.1.19
1191 · more python3 compatibility
1192 · code style improved
1194 · match_url to compare bzr shortcuts to real urls
1196 · more unit tests
1198 · get_status required to end with newline, to fix #55
1200 0.1.18
1202 · added shallow flag to API, implemented for git
1203 0.1.17
1205 · svn stdout output on get_version removed
1206 0.1.16
1208 · All SCMs show some output when update caused changes
1209 · All SCMs have verbose option to show all changes done on update
1211 · bugfix for bazaar getUrl() being a joined abspath
1213 · bugfix for not all output being shown when requested
1215 0.1.15
1217 · Added pyyaml as a proper dependency, removed detection code.
1218 · remove use of tar entirely, switch to tarfile module
1220 · fix #36 allowing for tar being bsdtar on OSX
1222 0.1.14
1224 · Added tarball uncompression.
1225 0.1.13
1227 · added this changelog
1228 · git get-version fetches only when local lookup fails
1230 · hg get-version pulls if label not found
1232 · Popen error message incudes cwd path
1234 0.1.12
1236 · py_checker clean after all refactorings since 0.1.0
1237 0.1.11
1239 · svn and hg update without user interaction
1240 · bugfix #30
1242 · minor bugfixes
1244 0.1.10
1246 · minor bugs
1247 0.1.9
1249 · safer sanitization of shell params
1250 · git diff and stat recurse for submodules
1252 · base class manages all calls to Popen
1254 0.1.8
1256 · several bugfixes
1257 · reverted using shell commands instead of bazaar API
1259 0.1.7
1261 · reverted using shell commands instaed of pysvn and mercurial APIs
1262 · protection against shell incection attempts
1264 0.1.6
1266 · bugfixes to svn and bzr
1267 · unified all calls through Popen
1269 0.1.5
1271 · missing dependency to dateutil added
1272 0.1.4
1274 switched shell calls to calls to python API of mercurial, bazaar,
1275 py-svn
1276 0.1.3
1278 · fix #6
1279 0.1.2
1281 · fix #15
1282 0.1.1
1284 · more unit tests
1285 · diverse bugfixes
1287 · major change to git client behavior, based around git
1289 https://kforge.ros.org/vcstools/trac/ticket/1
1290 0.1.0
1292 · documentation fixes
1293 0.0.3
1295 · import from svn
1296 Bug reports and feature requests
1298 · Submit a bug report
1299 Developer Setup
1301 vcstools uses setuptools, which you will need to download and install
1302 in order to run the packaging. We use setuptools instead of distutils
1303 in order to be able use setup() keys like install_requires.
1304 cd vcstools python setup.py develop
1305 Testing
1307 Install test dependencies
1308 pip install nose
1310 pip install mock
1311 vcstools uses Python nose for testing, which is a fairly simple and
1313 straightfoward test framework. The vcstools mainly use unittest to
1314 construct test fixtures, but with nose you can also just write a func‐
1315 tion that starts with the name test and use normal assert statements.
1316 vcstools also uses mock to create mocks for testing.
1318 You can run the tests, including coverage, as follows:
1320 cd vcstools
1322 make test
1323 Documentation
1325 Sphinx is used to provide API documentation for vcstools. The docu‐
1326 ments are stored in the doc subdirectory.
1327 · genindex
1329 · modindex
1331 · search
1333
1335 Tully Foote, Thibault Kruse, Ken Conley
1336
1338 2010, Willow Garage
13390.1.40 Feb 13, 2019 VCSTOOLS(1)