Package: vcstool2
What is vcstool2?Vcstool2 is an attempt at continuing the development ofvcstoolbyDirk Thomas.Vcstool2 is a version control system (VCS) tool, designed to make working
with multiple repositories easier.Note:This tool should not be confused withvcstools(with a trailings) which
provides a Python API for interacting with different version control systems. The biggest differences between the two
are:vcstool2doesn't use any state beside the repository working copies available in the filesystem.The file format of vcstool2'sexportuses the relative paths of the repositories as keys in YAML which avoids
collisions by design.vcstool2has significantly fewer lines of code thanvcstoolsincluding the command line tools built on top.Python supportThis package supports python >= 3.5.How does it work?Vcstool2 operates on any folder from where it recursively searches for supported repositories. On these repositories
vcstool2 invokes the native VCS client with the requested command (i.e.diff).Which VCS types are supported?Vcstool2 supportsGitrepositories only.How to use vcstool2?The scriptvcscan be used similarly to the VCS clientsgit,hg, etc. Thehelpcommand provides a list of
available commands with an additional description:vcshelpBy default, vcstool2 searches for repositories under the current folder. Optionally one path (or multiple paths) can be
passed to search for repositories at different locations:vcsstatus/path/to/several/repos/path/to/other/repos/path/to/single/repoExporting and importing sets of repositoriesVcstool2 can export and import all the information required to reproduce the versions of a set of repositories. Vcstool2
uses a simpleYAMLformat to encode this information. This format includes a root
keyrepositoriesunder which each local repository is described by a dictionary keyed by its relative path. Each of
these dictionaries contains keysurl, andversion. If theversionkey is omitted the default branch is
being used.This results in something similar to the following for a set of two repositories
(vcstoolandvcstool2):repositories:vcstool:url:git@github.com:dirk-thomas/vcstool.gitversion:masterold_tools/rosinstall:url:git@github.com:MaxandreOgeret/vcstool2.gitversion:masterExport set of repositoriesThevcs exportcommand outputs the path, URL and version
information for all repositories inYAMLformat.
The output is usually piped to a file:vcsexport>my.reposIf the repository is currently on the tip of a branch the branch is followed. This implies that a later import might
fetch a newer revision if the branch has evolved in the meantime. Furthermore, if the local branch has evolved from the
remote repository an import might not result in the exact same state.To make sure to store the exact revision in the exported data use the command line argument--exact. Since a specific
revision is not tied to neither a branch nor a remote (for Git and Mercurial) the tool will check if the current hash
exists in any of the remotes. If it exists in multiple the remotesoriginandupstreamare considered before any
other in alphabetical order.Import set of repositoriesThevcs importcommand clones all repositories which are passed in viastdinin YAML format. Usually the data of a
previously exported file is piped in:vcsimport<my.reposBeside passing a file path the command also supports passing a URL.Validate repositories fileThevcs validatecommand takes a YAML file which is passed in viastdinand validates its contents and format. The
data of a previously-exported file or hand-generated file are piped in:vcsvalidate<my.reposDeleting repositoriesThevcs rmcommand takes a YAML file containing the repositories which is passed in viastdinor with its path
specified via--input.The command performs a dry run by default, to perform the deletion use the--forceoption.This command will delete all the pulled repositories if the--alloption is passed.It can also filter the repos to delete based on their cloning path with a regex pattern passed with the--patternoption, see theremoduledocumentationfor details about the syntax.To delete all:vcsrm--all--force<repos.yamlTo delete all repos paths containing "foo" or "bar":vcsrm--pattern"foo|bar"--force<repos.yamlVersion rangesVcstool2 supports version ranges in the yaml repository file, E.g.repositories:vcstool2_0:url:https://github.com/MaxandreOgeret/vcstool2.gitversion:">0.4.1,<0.4.3"vcstool2_1:url:https://github.com/MaxandreOgeret/vcstool2.gitversion:"==0.4.*"The version ranges syntax is basedPEP440, and is powered by thepackagingpackage.Advanced featuresShow log since last tagThevcs logcommand supports the argument--limit-untaggedwhich will output the log for all commits since the last
tag.Parallelization and stdinBy defaultvcsparallelizes the work across multiple repositories based on the number of CPU cores. In the case that
the invoked commands require input fromstdinthat parallelization is a problem. In order to be able to provide input
to each command separately these commands must run sequentially. When needing to e.g. interactively provide credentials
all commands should be executed sequentially by passing:--workers 1In the case repositories are using SSHgit@URLs but the host is not known yetvcs importautomatically falls back
to a single worker.Run arbitrary commandsThevcs customcommand enables to pass arbitrary user-specified arguments to the git executable.vcs custom --args log --oneline -n 10How to install vcstool2?Use thePyPIpackage:sudopipinstallvcstool2Setup auto-completionFor the shellsbash,tcshandzshvcstool2 can provide auto-completion of the various VCS commands. In order to
enable that feature the shell specific completion file must be sourced.Forbashappend the following line to the~/.bashrcfile:source/usr/share/vcstool2-completion/vcs.bashFortcshappend the following line to the~/.cshrcfile:source/usr/share/vcstool2-completion/vcs.tcshForzshappend the following line to the~/.zshrcfile:source/usr/share/vcstool2-completion/vcs.zshForfishappend the following line to the~/.config/fishconfig.fishfile:source/usr/share/vcstool2-completion/vcs.fishHow to contribute?How to report problems?Before reporting a problem please make sure to use the latest version. Issues can be filled
onGitHubafter making sure that this problem has not yet been
reported.Please make sure to include as much information, i.e. version numbers from vcstool2, operating system, Python and a
reproducible example of the commands which expose the problem.How to try the latest changes?Sourcing thesetup.shfile prepends thesrcfolder to thePYTHONPATHand thescriptsfolder to thePATH. Then
vcstool2 can be used with the commandsvcs-COMMAND(note the hyphen betweenvcsandcommandinstead of a space).Alternatively the-e/--editableflag ofpipcan be used:# from the top level of this repopip3install--user-e.