ℹ️ This project is a fork of vcstool originally created by Dirk Thomas. All credits for the original work go to Dirk Thomas. ℹ️
Vcstool2 is a version control system (VCS) tool, designed to make working with multiple repositories easier.
Note:
This tool should not be confused with vcstools (with a trailings
) which
provides a Python API for interacting with different version control systems. The biggest differences between the two
are:
- vcstool2 doesn't use any state beside the repository working copies available in the filesystem.
- The file format of vcstool2's
export
uses the relative paths of the repositories as keys in YAML which avoids collisions by design. - vcstool2 has significantly fewer lines of code than vcstools including the command line tools built on top.
This package supports Python >= 3.5, and is tested on Python (3.7 -> 3.12).
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).
Vcstool2 supports Git repositories only.
The script vcs
can be used similarly to the VCS clients git
, hg
, etc. The help
command provides a list of
available commands with an additional description:
vcs help
By 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:
vcs status /path/to/several/repos /path/to/other/repos /path/to/single/repo
Vcstool2 can export and import all the information required to reproduce the versions of a set of repositories. Vcstool2
uses a simple YAML format to encode this information. This format includes a root
key repositories
under which each local repository is described by a dictionary keyed by its relative path. Each of
these dictionaries contains keys url
, and version
. If the version
key is omitted the default branch is
being used.
This results in something similar to the following for a set of two repositories (vcstool and vcstool2):
repositories:
vcstool:
url: [email protected]:dirk-thomas/vcstool.git
version: master
old_tools/rosinstall:
url: [email protected]:MaxandreOgeret/vcstool2.git
version: master
The vcs export
command outputs the path, URL and version
information for all repositories in YAML format.
The output is usually piped to a file:
vcs export > my.repos
If 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 remotes origin
and upstream
are considered before any
other in alphabetical order.
The vcs import
command clones all repositories which are passed in via stdin
in YAML format. Usually the data of a
previously exported file is piped in:
vcs import < my.repos
Beside passing a file path the command also supports passing a URL.
The vcs validate
command takes a YAML file which is passed in via stdin
and validates its contents and format. The
data of a previously-exported file or hand-generated file are piped in:
vcs validate < my.repos
The vcs rm
command takes a YAML file containing the repositories which is passed in via stdin
or with its path
specified via --input
.
The command performs a dry run by default, to perform the deletion use the --force
option.
This command will delete all the pulled repositories if the --all
option is passed.
It can also filter the repos to delete based on their cloning path with a regex pattern passed with the --pattern
option, see the re
module documentation
for details about the syntax.
To delete all:
vcs rm --all --force < repos.yaml
To delete all repos paths containing "foo" or "bar":
vcs rm --pattern "foo|bar" --force < repos.yaml
Vcstool2 supports version ranges in the yaml repository file, E.g.
repositories:
vcstool2_0:
url: https://github.com/MaxandreOgeret/vcstool2.git
version: ">0.4.1,<0.4.3"
vcstool2_1:
url: https://github.com/MaxandreOgeret/vcstool2.git
version: "==0.4.*"
The version ranges syntax follows Python Packaging Authority Guidelines, and is powered by the packaging package.
The vcs log
command supports the argument --limit-untagged
which will output the log for all commits since the last
tag.
By default vcs
parallelizes the work across multiple repositories based on the number of CPU cores. In the case that
the invoked commands require input from stdin
that 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 1
In the case repositories are using SSH git@
URLs but the host is not known yet vcs import
automatically falls back
to a single worker.
The vcs custom
command enables to pass arbitrary user-specified arguments to the git executable.
vcs custom --args log --oneline -n 10
Use the PyPI package:
sudo pip install vcstool2
For the shells bash, tcsh and zsh vcstool2 can provide auto-completion of the various VCS commands. In order to enable that feature the shell specific completion file must be sourced.
For bash append the following line to the ~/.bashrc
file:
source /usr/share/vcstool2-completion/vcs.bash
For tcsh append the following line to the ~/.cshrc
file:
source /usr/share/vcstool2-completion/vcs.tcsh
For zsh append the following line to the ~/.zshrc
file:
source /usr/share/vcstool2-completion/vcs.zsh
For fish append the following line to the ~/.config/fishconfig.fish
file:
source /usr/share/vcstool2-completion/vcs.fish
Before reporting a problem please make sure to use the latest version. Issues can be filled on GitHub after 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.
Sourcing the setup.sh
file prepends the src
folder to thePYTHONPATH
and the scripts
folder to the PATH
. Then
vcstool2 can be used with the commands vcs-COMMAND
(note the hyphen between vcs
andcommand
instead of a space).
Alternatively the -e/--editable
flag of pip
can be used:
# from the top level of this repo
pip3 install --user -e .