vcstool2 0.4.5

vcstool2 provides a command line tool to invoke git commands on multiple repositories.

What is vcstool2?

ℹ️ 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.

Python support

This package supports Python >= 3.5, and is tested on Python (3.7 -> 3.12).

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 supports Git repositories only.

How to use vcstool2?

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

Exporting and importing sets of repositories

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: [e-mail]:dirk-thomas/vcstool.git
    version: master
  old_tools/rosinstall:
    url: [e-mail]:MaxandreOgeret/vcstool2.git
    version: master

Export set of repositories

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.

Import set of repositories

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.

Validate repositories file

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

Deleting repositories

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

Version ranges

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.

Advanced features

Show log since last tag

The vcs log command supports the argument --limit-untagged which will output the log for all commits since the last tag.

Parallelization and stdin

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.

Run arbitrary commands

The vcs custom command enables to pass arbitrary user-specified arguments to the git executable.

vcs custom --args log --oneline -n 10

How to install vcstool2?

Use the PyPI package:

sudo pip install vcstool2

Setup auto-completion

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

How to contribute?

How to report problems?

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.

How to try the latest changes?

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 .