1VCSTOOLS(1)                        vcstools                        VCSTOOLS(1)
2
3
4

NAME

6       vcstools - vcstools Documentation
7
8       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

GENERAL VCS/SCM API

15       The VcsClient class provides a generic API for
16
17       • Subversion (svn)
18
19       • Mercurial (hg)
20
21       • Git (git)
22
23       • Bazaar (bzr)
24
25       class vcstools.VcsClient(vcs_type, path)
26              API  for interacting with source-controlled paths independent of
27              actual version-control implementation.
28
29              Parameters
30
31vcs_type – type of VCS to use (e.g. ‘svn’, ‘hg’, ‘bzr’,
32                       ‘git’), str
33
34path  –  filesystem  path where code is/will be checked
35                       out , str
36
37              path_exists() -> bool
38
39                     Returns
40                            True if path exists on disk.
41
42              get_path() -> str
43
44                     Returns
45                            filesystem path this client is initialized with.
46
47              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
51                     Parameters
52                            url_or_shortcut   –  url  or  shortcut  (e.g.  bzr
53                            launchpad url)
54
55                     Returns
56                            bool if params are equivalent
57
58              get_version([spec=None]) -> str
59
60                     Parameters
61                            spec 
62
63                            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
67                            • svn: anything accepted by svn info --help,  e.g.
68                              a  revnumber,  {date}, HEAD, BASE, PREV, or COM‐
69                              MITTED
70
71                            • git: anything accepted by git log, e.g.  a  tag‐
72                              name, branchname, or sha-id.
73
74                            • hg:  anything accepted by hg log -r, e.g. a tag‐
75                              name, sha-ID, revision-number
76
77                            • bzr: revisionspec as returned by bzr help  revi‐
78                              sionspec, e.g. a tagname or revno:<number>
79
80
81                     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
87              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
92                     Parameters
93                            fetch – if False, only local  information  may  be
94                            used
95
96                     Returns
97                            current revision number of the remote repository.
98
99              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
104                        returns
105                               short   description   of  local  version  (e.g.
106                               branchname, tagename).
107
108              checkout(url[, version=''][, verbose=False][, shallow=False])
109                     Checkout the given URL to the path associated  with  this
110                     client.
111
112                     Parameters
113
114url – URL of source control to check out
115
116version – specific version to check out
117
118verbose – flag to run verbosely
119
120shallow  –  flag to create shallow clone without
121                              history
122
123              update(version)
124                     Update the local checkout from upstream source control.
125
126              detect_presence() -> bool
127
128                     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
133              get_vcs_type_name() -> str
134
135                     Returns
136                            type of VCS this client is initialized with.
137
138              get_url() -> str
139
140                     Returns
141                            Upstream URL that this code was checked out from.
142
143              get_branch_parent()
144                     (Git Only)
145
146                     Returns
147                            parent branch.
148
149              get_diff([basepath=None])
150
151                     Parameters
152                            basepath – compute diff relative to this path,  if
153                            provided
154
155                     Returns
156                            A string showing local differences
157
158              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
164                     Parameters
165
166basepath – status path will be relative to this,
167                              if provided.
168
169untracked  –  If  True,  also  show changes that
170                              would not commit
171
172                     Returns
173                            A string summarizing locally modified files
174
175       Example:
176
177          import vcstools
178
179          # interrogate an existing tree
180          client = vcstools.VcsClient('svn', '/path/to/checkout')
181
182          print client.get_url()
183          print client.get_version()
184          print client.get_diff()
185
186          # create a new tree
187          client = vcstools.VcsClient('hg', '/path/to/new/checkout')
188          client.checkout('https://bitbucket.org/foo/bar')
189
190       vcstools is available on pypi and can be installed via pip
191
192          pip install vcstools
193
194       or easy_install:
195
196          easy_install vcstools
197
198       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

DEVELOPER’S GUIDE

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
210       vcstools.setup_logger()
211              creates a logger 'vcstools'
212
213   bzr Module
214       bzr vcs support.
215
216       vcstools.bzr.BZRClient
217              alias of vcstools.bzr.BzrClient
218
219       class vcstools.bzr.BzrClient(path)
220              Bases: vcstools.vcs_base.VcsClientBase
221
222              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
242              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
247                     Parameters
248                            version -- version of the  repository  to  export.
249                            This can
250
251                     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
259              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
265              get_branches(local_only=False)
266                     Returns a list of all branches in the vcs repository.
267
268                     Parameters
269                            local_only -- if True  it  will  only  list  local
270                            branches
271
272                     Returns
273                            list of branches in the repository, [] if none ex‐
274                            ist
275
276              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
281                     Returns
282                            short description of local version  (e.g.  branch‐
283                            name, tagename).
284
285                     Return type
286                            str
287
288              get_diff(basepath=None)
289
290                     Parameters
291                            basepath  --  diff paths will be relative to this,
292                            if any
293
294                     Returns
295                            A string showing local differences
296
297                     Return type
298                            str
299
300              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
308              get_log(relpath=None, limit=None)
309                     Calls scm log command.
310
311                     This  returns  a  list of dictionaries with the following
312                     fields:
313
314                            • id: the commit SHA or revision number
315
316                            • date: the date the commit was made (python date‐
317                              time)
318
319                            • author: the name of the author of the commit, if
320                              available
321
322                            • email: the e-mail address of the author  of  the
323                              commit
324
325                            • message: the commit message, if any
326
327                     Parameters
328                            relpath  --  (optional) restrict logs to events on
329                            this
330
331                     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
337              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
342                     Parameters
343                            fetch -- if False, only local information  may  be
344                            used
345
346                     Returns
347                            current revision number of the remote repository.
348
349                     Return type
350                            str
351
352              get_status(basepath=None, untracked=False)
353                     Calls  scm  status  command. Output must be terminated by
354                     newline unless empty.
355
356                     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
360                     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
364                     Parameters
365
366basepath -- status  path  will  be  relative  to
367                              this, if any
368
369untracked  --  whether to also show changes that
370                              would not commit
371
372                     Returns
373                            A string summarizing locally modified files
374
375                     Return type
376                            str
377
378              get_url()
379
380                     Returns
381                            BZR URL of the branch (output  of  bzr  info  com‐
382                            mand),
383
384                     or None if it cannot be determined
385
386              get_version(spec=None)
387
388                     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
394                     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
399              static static_detect_presence(path)
400                     For auto detection
401
402              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
411                     Parameters
412
413version -- 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
418timeout -- maximum allocated time to perform op‐
419                              eration
420
421                     Returns
422                            True on success, False else
423
424              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
430   git Module
431       git vcs support.
432
433       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
437       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
442       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
450       vcstools.git.GITClient
451              alias of vcstools.git.GitClient
452
453       class vcstools.git.GitClient(path)
454              Bases: vcstools.vcs_base.VcsClientBase
455
456              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
461              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
466                     Parameters
467                            version -- version of the  repository  to  export.
468                            This can
469
470                     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
478              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
484              get_branches(local_only=False)
485                     Returns a list of all branches in the vcs repository.
486
487                     Parameters
488                            local_only -- if True  it  will  only  list  local
489                            branches
490
491                     Returns
492                            list of branches in the repository, [] if none ex‐
493                            ist
494
495              get_current_version_label()
496                     For git we change the label to clarify when  a  different
497                     remote is configured.
498
499              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
503                     Returns
504                            a label or None (if not applicable)
505
506                     Return type
507                            str
508
509              get_diff(basepath=None)
510
511                     Parameters
512                            basepath -- diff paths will be relative  to  this,
513                            if any
514
515                     Returns
516                            A string showing local differences
517
518                     Return type
519                            str
520
521              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
529              get_log(relpath=None, limit=None)
530                     Calls scm log command.
531
532                     This returns a list of dictionaries  with  the  following
533                     fields:
534
535                            • id: the commit SHA or revision number
536
537                            • date: the date the commit was made (python date‐
538                              time)
539
540                            • author: the name of the author of the commit, if
541                              available
542
543                            • email:  the  e-mail address of the author of the
544                              commit
545
546                            • message: the commit message, if any
547
548                     Parameters
549                            relpath -- (optional) restrict logs to  events  on
550                            this
551
552                     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
558              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
563                     Parameters
564                            fetch  --  if False, only local information may be
565                            used
566
567                     Returns
568                            current revision number of the remote repository.
569
570                     Return type
571                            str
572
573              get_status(basepath=None, untracked=False, porcelain=False)
574                     Calls scm status command. Output must  be  terminated  by
575                     newline unless empty.
576
577                     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
581                     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
585                     Parameters
586
587basepath  --  status  path  will  be relative to
588                              this, if any
589
590untracked -- whether to also show  changes  that
591                              would not commit
592
593                     Returns
594                            A string summarizing locally modified files
595
596                     Return type
597                            str
598
599              get_url()
600
601                     Returns
602                            git  URL of the directory path (output of git info
603                            command), or None if it cannot be determined
604
605              get_version(spec=None)
606
607                     Parameters
608
609spec -- (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
614fetch -- When spec is given, can be used to sup‐
615                              press git fetch call
616
617                     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
622              is_tag(tag_name, fetch=True)
623                     checks list of tags for match.  Set fetch to False if you
624                     just fetched already.
625
626                     Returns
627                            True if tag_name among known tags
628
629                     Raises GitError when call to git fetch fails
630
631              static static_detect_presence(path)
632                     For auto detection
633
634              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
639                     Else interprets version as a local branch, remote branch,
640                     tagname, hash, etc.
641
642                     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
647                     Returns
648                            True  if  already  up-to-date with remote or after
649                            successful fast_foward
650
651       exception vcstools.git.GitError
652              Bases: Exception
653
654   hg Module
655       hg vcs support.
656
657       using ui object to redirect output into a string
658
659       vcstools.hg.HGClient
660              alias of vcstools.hg.HgClient
661
662       class vcstools.hg.HgClient(path)
663              Bases: vcstools.vcs_base.VcsClientBase
664
665              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
685              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
690                     Parameters
691                            version  --  version  of the repository to export.
692                            This can
693
694                     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
702              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
708              get_branch()
709
710              get_branches(local_only=False)
711                     Returns a list of all branches in the vcs repository.
712
713                     Parameters
714                            local_only  --  if  True  it  will only list local
715                            branches
716
717                     Returns
718                            list of branches in the repository, [] if none ex‐
719                            ist
720
721              get_current_version_label()
722
723                     Parameters
724                            spec  --  (optional)  spec  can  be what 'svn info
725                            --help' allows, meaning a revnumber, {date}, HEAD,
726                            BASE, PREV, or COMMITTED.
727
728                     Returns
729                            current  revision  number of the repository. Or if
730                            spec provided, the number of a revision  specified
731                            by some token.
732
733              get_diff(basepath=None)
734
735                     Parameters
736                            basepath  --  diff paths will be relative to this,
737                            if any
738
739                     Returns
740                            A string showing local differences
741
742                     Return type
743                            str
744
745              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
753              get_log(relpath=None, limit=None)
754                     Calls scm log command.
755
756                     This  returns  a  list of dictionaries with the following
757                     fields:
758
759                            • id: the commit SHA or revision number
760
761                            • date: the date the commit was made (python date‐
762                              time)
763
764                            • author: the name of the author of the commit, if
765                              available
766
767                            • email: the e-mail address of the author  of  the
768                              commit
769
770                            • message: the commit message, if any
771
772                     Parameters
773                            relpath  --  (optional) restrict logs to events on
774                            this
775
776                     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
782              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
787                     Parameters
788                            fetch -- if False, only local information  may  be
789                            used
790
791                     Returns
792                            current revision number of the remote repository.
793
794                     Return type
795                            str
796
797              get_status(basepath=None, untracked=False)
798                     Calls  scm  status  command. Output must be terminated by
799                     newline unless empty.
800
801                     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
805                     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
809                     Parameters
810
811basepath -- status  path  will  be  relative  to
812                              this, if any
813
814untracked  --  whether to also show changes that
815                              would not commit
816
817                     Returns
818                            A string summarizing locally modified files
819
820                     Return type
821                            str
822
823              get_url()
824
825                     Returns
826                            HG URL of the directory path. (output of hg paths
827
828                     command), or None if it cannot be determined
829
830              get_version(spec=None)
831
832                     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
837                     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
842              static static_detect_presence(path)
843                     For auto detection
844
845              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
854                     Parameters
855
856version -- 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
861timeout -- maximum allocated time to perform op‐
862                              eration
863
864                     Returns
865                            True on success, False else
866
867   svn Module
868       svn vcs support.
869
870       vcstools.svn.SVNClient
871              alias of vcstools.svn.SvnClient
872
873       class vcstools.svn.SvnClient(path)
874              Bases: vcstools.vcs_base.VcsClientBase
875
876              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
896              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
901                     Parameters
902                            version  --  version  of the repository to export.
903                            This can
904
905                     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
913              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
919              get_branches(local_only=False)
920                     Returns a list of all branches in the vcs repository.
921
922                     Parameters
923                            local_only  --  if  True  it  will only list local
924                            branches
925
926                     Returns
927                            list of branches in the repository, [] if none ex‐
928                            ist
929
930              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
935                     Returns
936                            short  description  of local version (e.g. branch‐
937                            name, tagename).
938
939                     Return type
940                            str
941
942              get_diff(basepath=None)
943
944                     Parameters
945                            basepath -- diff paths will be relative  to  this,
946                            if any
947
948                     Returns
949                            A string showing local differences
950
951                     Return type
952                            str
953
954              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
962              get_log(relpath=None, limit=None)
963                     Calls scm log command.
964
965                     This returns a list of dictionaries  with  the  following
966                     fields:
967
968                            • id: the commit SHA or revision number
969
970                            • date: the date the commit was made (python date‐
971                              time)
972
973                            • author: the name of the author of the commit, if
974                              available
975
976                            • email:  the  e-mail address of the author of the
977                              commit
978
979                            • message: the commit message, if any
980
981                     Parameters
982                            relpath -- (optional) restrict logs to  events  on
983                            this
984
985                     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
991              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
996                     Parameters
997                            fetch  --  if False, only local information may be
998                            used
999
1000                     Returns
1001                            current revision number of the remote repository.
1002
1003                     Return type
1004                            str
1005
1006              get_status(basepath=None, untracked=False)
1007                     Calls scm status command. Output must  be  terminated  by
1008                     newline unless empty.
1009
1010                     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
1014                     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
1018                     Parameters
1019
1020basepath  --  status  path  will  be relative to
1021                              this, if any
1022
1023untracked -- whether to also show  changes  that
1024                              would not commit
1025
1026                     Returns
1027                            A string summarizing locally modified files
1028
1029                     Return type
1030                            str
1031
1032              get_url()
1033
1034                     Returns
1035                            SVN  URL of the directory path (output of svn info
1036                            command), or None if it cannot be determined
1037
1038              get_version(spec=None)
1039
1040                     Parameters
1041
1042spec -- (optional) spec can be  what  'svn  info
1043                              --help'  allows,  meaning  a  revnumber, {date},
1044                              HEAD, BASE, PREV, or COMMITTED.
1045
1046path -- the url to use, default is for this repo
1047
1048                     Returns
1049                            current revision number of the repository.  Or  if
1050                            spec  provided, the number of a revision specified
1051                            by some token.
1052
1053              static static_detect_presence(path)
1054                     For auto detection
1055
1056              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
1065                     Parameters
1066
1067version -- 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
1072timeout -- maximum allocated time to perform op‐
1073                              eration
1074
1075                     Returns
1076                            True on success, False else
1077
1078       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
1084              Parameters
1085                     url -- location of central repo, str
1086
1087              Returns
1088                     dict {root, type, name, subfolder, query, fragment}
1089
1090              with type one of "trunk", "tags", "branches"
1091
1092       vcstools.svn.get_remote_contents(url)
1093
1094   tar Module
1095       tar vcs support.
1096
1097       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
1101       vcstools.tar.TARClient
1102              alias of vcstools.tar.TarClient
1103
1104       class vcstools.tar.TarClient(path)
1105              Bases: vcstools.vcs_base.VcsClientBase
1106
1107              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
1117              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
1122                     Parameters
1123                            version -- version of the  repository  to  export.
1124                            This can
1125
1126                     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
1134              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
1139                     Returns
1140                            short  description  of local version (e.g. branch‐
1141                            name, tagename).
1142
1143                     Return type
1144                            str
1145
1146              get_diff(basepath=None)
1147
1148                     Parameters
1149                            basepath -- diff paths will be relative  to  this,
1150                            if any
1151
1152                     Returns
1153                            A string showing local differences
1154
1155                     Return type
1156                            str
1157
1158              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
1166              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
1171                     Parameters
1172                            fetch -- if False, only local information  may  be
1173                            used
1174
1175                     Returns
1176                            current revision number of the remote repository.
1177
1178                     Return type
1179                            str
1180
1181              get_status(basepath=None, untracked=False)
1182                     Calls  scm  status  command. Output must be terminated by
1183                     newline unless empty.
1184
1185                     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
1189                     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
1193                     Parameters
1194
1195basepath -- status  path  will  be  relative  to
1196                              this, if any
1197
1198untracked  --  whether to also show changes that
1199                              would not commit
1200
1201                     Returns
1202                            A string summarizing locally modified files
1203
1204                     Return type
1205                            str
1206
1207              get_url()
1208
1209                     Returns
1210                            TAR URL of the directory path (output of tar info
1211
1212                     command), or None if it cannot be determined
1213
1214              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
1219                     Parameters
1220                            spec (str) -- token for identifying repository re‐
1221                            vision
1222
1223                     Returns
1224                            current  revision number of the repository.  Or if
1225                            spec is provided, the respective revision number.
1226
1227                     Return type
1228                            str
1229
1230              static static_detect_presence(path)
1231                     For auto detection
1232
1233              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
1237   vcs_abstraction Module
1238       undoc-members
1239
1240       show-inheritance
1241
1242       vcstools.vcs_abstraction.VCSClient
1243              alias of vcstools.vcs_abstraction.VcsClient
1244
1245       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
1249       vcstools.vcs_abstraction.get_registered_vcs_types()
1250
1251              Returns
1252                     list of valid key to use as vcs_type
1253
1254       vcstools.vcs_abstraction.get_vcs(vcs_type)
1255              Returns the class interfacing with vcs of given type
1256
1257              Parameters
1258                     vcs_type -- id of the tpye, e.g. git, svn, hg, bzr
1259
1260              Returns
1261                     class extending VcsClientBase
1262
1263              Raises ValueError for unknown vcs_type
1264
1265       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
1269              Parameters
1270                     vcs_type -- id of the tpye, e.g. git, svn, hg, bzr
1271
1272              Returns
1273                     instance of VcsClientBase
1274
1275              Raises ValueError for unknown vcs_type
1276
1277       vcstools.vcs_abstraction.register_vcs(vcs_type, clazz)
1278
1279              Parameters
1280
1281vcs_type -- id, str
1282
1283clazz -- class extending VcsClientBase
1284
1285   vcs_base Module
1286       vcs support library base class.
1287
1288       undoc-members
1289
1290       show-inheritance
1291
1292       class vcstools.vcs_base.VcsClientBase(vcs_type_name, path)
1293              parent class for all vcs clients, provides their public API
1294
1295              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
1315              detect_presence()
1316                     For auto detection
1317
1318              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
1323                     Parameters
1324                            version -- version of the  repository  to  export.
1325                            This can
1326
1327                     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
1335              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
1341              get_branches(local_only=False)
1342                     Returns a list of all branches in the vcs repository.
1343
1344                     Parameters
1345                            local_only -- if True  it  will  only  list  local
1346                            branches
1347
1348                     Returns
1349                            list of branches in the repository, [] if none ex‐
1350                            ist
1351
1352              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
1357                     Returns
1358                            short description of local version  (e.g.  branch‐
1359                            name, tagename).
1360
1361                     Return type
1362                            str
1363
1364              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
1368                     Returns
1369                            a label or None (if not applicable)
1370
1371                     Return type
1372                            str
1373
1374              get_diff(basepath=None)
1375
1376                     Parameters
1377                            basepath -- diff paths will be relative  to  this,
1378                            if any
1379
1380                     Returns
1381                            A string showing local differences
1382
1383                     Return type
1384                            str
1385
1386              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
1394              get_log(relpath=None, limit=None)
1395                     Calls scm log command.
1396
1397                     This returns a list of dictionaries  with  the  following
1398                     fields:
1399
1400                            • id: the commit SHA or revision number
1401
1402                            • date: the date the commit was made (python date‐
1403                              time)
1404
1405                            • author: the name of the author of the commit, if
1406                              available
1407
1408                            • email:  the  e-mail address of the author of the
1409                              commit
1410
1411                            • message: the commit message, if any
1412
1413                     Parameters
1414                            relpath -- (optional) restrict logs to  events  on
1415                            this
1416
1417                     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
1423              get_path()
1424                     returns the path this client was configured for
1425
1426              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
1431                     Parameters
1432                            fetch  --  if False, only local information may be
1433                            used
1434
1435                     Returns
1436                            current revision number of the remote repository.
1437
1438                     Return type
1439                            str
1440
1441              get_status(basepath=None, untracked=False, **kwargs)
1442                     Calls scm status command. Output must  be  terminated  by
1443                     newline unless empty.
1444
1445                     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
1449                     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
1453                     Parameters
1454
1455basepath  --  status  path  will  be relative to
1456                              this, if any
1457
1458untracked -- whether to also show  changes  that
1459                              would not commit
1460
1461                     Returns
1462                            A string summarizing locally modified files
1463
1464                     Return type
1465                            str
1466
1467              get_url()
1468
1469                     Returns
1470                            The source control url for the path or None if not
1471                            set
1472
1473                     Return type
1474                            str
1475
1476              get_vcs_type_name()
1477                     used when auto detected
1478
1479              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
1484                     Parameters
1485                            spec (str) -- token for identifying repository re‐
1486                            vision
1487
1488                     Returns
1489                            current  revision number of the repository.  Or if
1490                            spec is provided, the respective revision number.
1491
1492                     Return type
1493                            str
1494
1495              path_exists()
1496                     helper function
1497
1498              static static_detect_presence(path)
1499                     For auto detection
1500
1501              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
1510                     Parameters
1511
1512version -- 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
1517timeout -- maximum allocated time to perform op‐
1518                              eration
1519
1520                     Returns
1521                            True on success, False else
1522
1523              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
1529       exception vcstools.vcs_base.VcsError(value)
1530              To  be  thrown when an SCM Client faces a situation because of a
1531              violated assumption
1532
1533   Changelog
1534   Changelog
1535   0.1
1536   0.1.42
1537       • remove cosmic and disco until we have hosting for it
1538
1539   0.1.41
1540       • fix git submodule error due to lack of quoting
1541
1542       • Fix git update failure by refreshing git index before fast-forward
1543
1544       • Fix python3 incompatibility due to wrong use of urlopen
1545
1546       • Updating get_affected_files function by removing single quotes cover‐
1547         ing format (#129)
1548
1549       • Fix export_upstream for git submodules with relative urls. (#130)
1550
1551   0.1.40
1552       • Trivial style and testing changes
1553
1554   0.1.39
1555       • Added support for git submodule in export_repository
1556
1557       • Add Wily Xenial Yakkety
1558
1559       • Add get_affected_files for all vcss
1560
1561   0.1.38
1562       • Fixed test failures due to SVN 1.9.
1563
1564       • Added  the  get_default_remote_version_label()  API method to support
1565         changes in wstool.
1566
1567       • Renamed some internal functions to have a leading _ to indicate  that
1568         they are private.
1569
1570   0.1.37
1571       • Fix an issue where log were restricted to the named branch (hg).
1572
1573       • Fixed  svn to use a global revision number rather than a branch-local
1574         revision.
1575
1576       • Added the get_remote_version()  and  get_current_version_label()  API
1577         calls.
1578
1579       • Enhanced use of no_warn in run_shell_command().
1580
1581       • Fix get_version() to catch stderr.
1582
1583       • Added get_branches() API call.
1584
1585       • Fix some errors and warnings to output to stderr.
1586
1587       • Fix output to avoid extra newlines when show_stdout=True.
1588
1589   0.1.36
1590       • Updates to the release platforms (-lucid +utopic +vivid)
1591
1592       • Fix an issue with updating branches on git, see vcstools/wstool#25
1593
1594   0.1.31
1595       • Fix submodule support on checkout #71
1596
1597   0.1.30
1598       • use  netrc  to  download  tars from private repos, also will work for
1599         private rosinstall files
1600
1601       • Fix checks for empty repository #62
1602
1603   0.1.29
1604       • fix #57 shallow checkout of non-master breaks with git >= 1.8.0
1605
1606       • unit test fixes
1607
1608   0.1.28
1609       • test of new upload method
1610
1611   0.1.27
1612       • fix #51 hg status and diff dont work if workspace is inside hg repo
1613
1614       • fix #47 several performance improvements by removing  unecessary  up‐
1615         date actions after checkout
1616
1617       • fix #46 https tar download fails behind proxy
1618
1619       • fix #45 sometimes commands run forever
1620
1621       • fix #44 minor bug when checking out from repo with default branch not
1622         master
1623
1624       • fix #41 improvedAPI, get_vcs_client function part of vcstools module
1625
1626   0.1.26
1627       • fix #38 git commands fail in local  repositories  with  many  (>2000)
1628         references
1629
1630       • fix #31 get_log() svn xml not available on Ubuntu Lucid (hg 1.4.2)
1631
1632       • fix #37 update() returns True even when fetch failed
1633
1634   0.1.25
1635       • minor bugfixes
1636
1637       • travis-ci config file
1638
1639       • fix unit tests for svn diff&status ordering changes
1640
1641       • deprecated VcsClient Class
1642
1643       • added get_log function
1644
1645   0.1.24
1646       • fix  git  update return value to False when fast-forward not possible
1647         due to diverge
1648
1649       • fix. svn certificate prompt invisible, svn checkout and update become
1650         verbose due to this
1651
1652   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
1656       • fix for git single quotes on Windows
1657
1658       • minor internal api bug where a git function always returned True
1659
1660       • fix gub in svn export_repository
1661
1662   0.1.21
1663       • bugfix #66: hg http username prompt hidden
1664
1665       • add export_repository method to vcs_base and all implementations with
1666         tests
1667
1668       • bugfix #64: unicode decoding problems
1669
1670   0.1.20
1671       • rosws update –verbose for git prints small message when rebasing
1672
1673       • improved python3 compatibility
1674
1675   0.1.19
1676       • more python3 compatibility
1677
1678       • code style improved
1679
1680       • match_url to compare bzr shortcuts to real urls
1681
1682       • more unit tests
1683
1684       • get_status required to end with newline, to fix #55
1685
1686   0.1.18
1687       • added shallow flag to API, implemented for git
1688
1689   0.1.17
1690       • svn stdout output on get_version removed
1691
1692   0.1.16
1693       • All SCMs show some output when update caused changes
1694
1695       • All SCMs have verbose option to show all changes done on update
1696
1697       • bugfix for bazaar getUrl() being a joined abspath
1698
1699       • bugfix for not all output being shown when requested
1700
1701   0.1.15
1702       • Added pyyaml as a proper dependency, removed detection code.
1703
1704       • remove use of tar entirely, switch to tarfile module
1705
1706       • fix #36 allowing for tar being bsdtar on OSX
1707
1708   0.1.14
1709       • Added tarball uncompression.
1710
1711   0.1.13
1712       • added this changelog
1713
1714       • git get-version fetches only when local lookup fails
1715
1716       • hg get-version pulls if label not found
1717
1718       • Popen error message incudes cwd path
1719
1720   0.1.12
1721       • py_checker clean after all refactorings since 0.1.0
1722
1723   0.1.11
1724       • svn and hg update without user interaction
1725
1726       • bugfix #30
1727
1728       • minor bugfixes
1729
1730   0.1.10
1731       • minor bugs
1732
1733   0.1.9
1734       • safer sanitization of shell params
1735
1736       • git diff and stat recurse for submodules
1737
1738       • base class manages all calls to Popen
1739
1740   0.1.8
1741       • several bugfixes
1742
1743       • reverted using shell commands instead of bazaar API
1744
1745   0.1.7
1746       • reverted using shell commands instaed of pysvn and mercurial APIs
1747
1748       • protection against shell incection attempts
1749
1750   0.1.6
1751       • bugfixes to svn and bzr
1752
1753       • unified all calls through Popen
1754
1755   0.1.5
1756       • missing dependency to dateutil added
1757
1758   0.1.4
1759       switched  shell  calls  to  calls  to  python API of mercurial, bazaar,
1760       py-svn
1761
1762   0.1.3
1763       • fix #6
1764
1765   0.1.2
1766       • fix #15
1767
1768   0.1.1
1769       • more unit tests
1770
1771       • diverse bugfixes
1772
1773       • major   change   to   git   client   behavior,   based   around   git
1774         https://kforge.ros.org/vcstools/trac/ticket/1
1775
1776   0.1.0
1777       • documentation fixes
1778
1779   0.0.3
1780       • import from svn
1781
1782   Bug reports and feature requests
1783Submit a bug report
1784
1785   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
1791   Testing
1792       Install test dependencies
1793
1794          pip install nose
1795          pip install mock
1796
1797       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
1802       vcstools also uses mock to create mocks for testing.
1803
1804       You can run the tests, including coverage, as follows:
1805
1806          cd vcstools
1807          make test
1808
1809   Documentation
1810       Sphinx is used to provide API documentation for  vcstools.   The  docu‐
1811       ments are stored in the doc subdirectory.
1812
1813       • genindex
1814
1815       • modindex
1816
1817       • search
1818

AUTHOR

1820       Tully Foote, Thibault Kruse, Ken Conley
1821
1823       2021, Willow Garage
1824
1825
1826
1827
18280.1.42                           Jul 27, 2021                      VCSTOOLS(1)
Impressum