What is vcs2l?
================
Vcs2l is a fork of Dirk Thomas's `vcstool <https://github.com/dirk-thomas/vcstool/>`_ which is a version control system (VCS) tool, designed to make working with multiple repositories easier.
This fork is created to continue the development of vcstool, as it is no longer actively maintained.
The commands provided by vcs2l have the same naming structure as the original fork, so it can be used as a drop-in replacement.
Therefore, the repository is renamed to `vcs2l` while maintaining the command names to `vcstool` to ensure compatibility with existing scripts and workflows.
Note:
This tool should not be confused with `vcstools <https://github.com/vcstools/vcstools/>`_ (with a trailing ``s``) which provides a Python API for interacting with different version control systems.
The biggest differences between the two are:
* ``vcstool`` doesn't use any state beside the repository working copies available in the filesystem.
* The file format of ``vcstool export`` uses the relative paths of the repositories as keys in YAML which avoids collisions by design.
* ``vcstool`` has significantly fewer lines of code than ``vcstools`` including the command line tools built on top.
Python 3.5+ support
---------------------------
The latest version supports Python 3.5 and newer.
However, the CI is only run on Python 3.7 and newer, as there are no suitable GitHub Actions `runners <https://raw.githubusercontent.com/actions/python-versions/main/versions-manifest.json/>`_ available for Python 3.5 and 3.6.
How does it work?
-----------------
Vcs2l operates on any folder from where it recursively searches for supported repositories.
On these repositories vcs2l invokes the native VCS client with the requested command (i.e. *diff*).
Which VCS types are supported?
------------------------------
Vcs2l supports `Git <http://git-scm.com>`_, `Mercurial <https://www.mercurial-scm.org/>`_, `Subversion <http://subversion.apache.org>`_, `Bazaar <http://bazaar.canonical.com/en/>`_.
How to use vcs2l?
-------------------
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 vcs2l 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
--------------------------------------------
Vcs2l can export and import all the information required to reproduce the versions of a set of repositories.
Vcs2l uses a simple `YAML <http://www.yaml.org/>`_ 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 ``type``, ``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 (`vcs2l <https://github.com/ros-infrastructure/vcs2l>`_ cloned via Git and `rosinstall <http://github.com/vcstools/rosinstall>`_ checked out via Subversion):
.. code-block:: yaml
repositories:
vcs2l:
type: git
url: git@github.com:ros-infrastructure/vcs2l.git
version: master
old_tools/rosinstall:
type: svn
url: https://github.com/vcstools/rosinstall/trunk
version: 748
Export set of repositories
~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``vcs export`` command outputs the path, vcs type, URL and version information for all repositories in `YAML <http://www.yaml.org/>`_ 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
The ``import`` command also supports input in the `rosinstall file format <http://www.ros.org/doc/independent/api/rosinstall/html/rosinstall_file_format.html>`_.
Beside passing a file path the command also supports passing a URL.
Only for this command vcs2l supports the pseudo clients ``tar`` and ``zip`` which fetch a tarball / zipfile from a URL and unpack its content.
For those two types the ``version`` key is optional.
If specified only entries from the archive which are in the subfolder specified by the version value are being extracted.
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
The ``validate`` command also supports input in the `rosinstall file format <http://www.ros.org/doc/independent/api/rosinstall/html/rosinstall_file_format.html>`_.
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 vcs invocation.
The set of repositories to operate on can optionally be restricted by the type:
vcs custom --git --args log --oneline -n 10
If the command should work on multiple repositories make sure to pass only generic arguments which work for all of these repository types.
How to install vcs2l?
=======================
On Debian-based platforms the recommended method is to install the package *python3-vcs2l*.
On Ubuntu this is done using *apt-get*:
If you are using `ROS <https://www.ros.org/>`_ you can get the package directly from the ROS repository::
sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'
sudo apt install curl # if you haven't already installed curl
curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -
sudo apt-get update
sudo apt-get install python3-vcs2l
On other systems, use the `PyPI <https://pypi.org/project/vcs2l/>`_ package::
pip3 install vcs2l
Setup auto-completion
---------------------
For the shells *bash*, *tcsh* and *zsh* vcs2l 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/vcs2l-completion/vcs.bash
For *tcsh* append the following line to the ``~/.cshrc`` file::
source /usr/share/vcs2l-completion/vcs.tcsh
For *zsh* append the following line to the ``~/.zshrc`` file::
source /usr/share/vcs2l-completion/vcs.zsh
For *fish* append the following line to the ``~/.config/fishconfig.fish`` file::
source /usr/share/vcs2l-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 <https://github.com/ros-infrastructure/vcs2l/issues>`_ after making sure that this problem has not yet been reported.
Please make sure to include as much information, i.e. version numbers from vcs2l, 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 the ``PYTHONPATH`` and the ``scripts`` folder to the ``PATH``.
Then vcs2l can be used with the commands ``vcs-COMMAND`` (note the hyphen between ``vcs`` and ``command`` 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 .
Raw data
{
"_id": null,
"home_page": "https://github.com/ros-infrastructure/vcs2l",
"name": "vcs2l",
"maintainer": "ROS Infrastructure Team",
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "vcs, version control, git, hg, svn, bzr",
"author": "Dirk Thomas",
"author_email": "web@dirk-thomas.net",
"download_url": "https://files.pythonhosted.org/packages/32/f0/bd2937710299e32d3f57c0602f33ad9b51b41bead9d6aeefd2f24dc76ca1/vcs2l-1.1.0.tar.gz",
"platform": null,
"description": "What is vcs2l?\n================\n\nVcs2l is a fork of Dirk Thomas's `vcstool <https://github.com/dirk-thomas/vcstool/>`_ which is a version control system (VCS) tool, designed to make working with multiple repositories easier.\nThis fork is created to continue the development of vcstool, as it is no longer actively maintained.\n\nThe commands provided by vcs2l have the same naming structure as the original fork, so it can be used as a drop-in replacement.\nTherefore, the repository is renamed to `vcs2l` while maintaining the command names to `vcstool` to ensure compatibility with existing scripts and workflows.\n\nNote:\n This tool should not be confused with `vcstools <https://github.com/vcstools/vcstools/>`_ (with a trailing ``s``) which provides a Python API for interacting with different version control systems.\n The biggest differences between the two are:\n\n * ``vcstool`` doesn't use any state beside the repository working copies available in the filesystem.\n * The file format of ``vcstool export`` uses the relative paths of the repositories as keys in YAML which avoids collisions by design.\n * ``vcstool`` has significantly fewer lines of code than ``vcstools`` including the command line tools built on top.\n\nPython 3.5+ support\n---------------------------\n\nThe latest version supports Python 3.5 and newer.\nHowever, the CI is only run on Python 3.7 and newer, as there are no suitable GitHub Actions `runners <https://raw.githubusercontent.com/actions/python-versions/main/versions-manifest.json/>`_ available for Python 3.5 and 3.6.\n\n\nHow does it work?\n-----------------\n\nVcs2l operates on any folder from where it recursively searches for supported repositories.\nOn these repositories vcs2l invokes the native VCS client with the requested command (i.e. *diff*).\n\n\nWhich VCS types are supported?\n------------------------------\n\nVcs2l supports `Git <http://git-scm.com>`_, `Mercurial <https://www.mercurial-scm.org/>`_, `Subversion <http://subversion.apache.org>`_, `Bazaar <http://bazaar.canonical.com/en/>`_.\n\n\nHow to use vcs2l?\n-------------------\n\nThe script ``vcs`` can be used similarly to the VCS clients ``git``, ``hg`` etc.\nThe ``help`` command provides a list of available commands with an additional description::\n\n vcs help\n\nBy default vcs2l searches for repositories under the current folder.\nOptionally one path (or multiple paths) can be passed to search for repositories at different locations::\n\n vcs status /path/to/several/repos /path/to/other/repos /path/to/single/repo\n\n\nExporting and importing sets of repositories\n--------------------------------------------\n\nVcs2l can export and import all the information required to reproduce the versions of a set of repositories.\nVcs2l uses a simple `YAML <http://www.yaml.org/>`_ format to encode this information.\nThis format includes a root key ``repositories`` under which each local repository is described by a dictionary keyed by its relative path.\nEach of these dictionaries contains keys ``type``, ``url``, and ``version``.\nIf the ``version`` key is omitted the default branch is being used.\n\nThis results in something similar to the following for a set of two repositories (`vcs2l <https://github.com/ros-infrastructure/vcs2l>`_ cloned via Git and `rosinstall <http://github.com/vcstools/rosinstall>`_ checked out via Subversion):\n\n.. code-block:: yaml\n\n repositories:\n vcs2l:\n type: git\n url: git@github.com:ros-infrastructure/vcs2l.git\n version: master\n old_tools/rosinstall:\n type: svn\n url: https://github.com/vcstools/rosinstall/trunk\n version: 748\n\n\nExport set of repositories\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe ``vcs export`` command outputs the path, vcs type, URL and version information for all repositories in `YAML <http://www.yaml.org/>`_ format.\nThe output is usually piped to a file::\n\n vcs export > my.repos\n\nIf the repository is currently on the tip of a branch the branch is followed.\nThis implies that a later import might fetch a newer revision if the branch has evolved in the meantime.\nFurthermore if the local branch has evolved from the remote repository an import might not result in the exact same state.\n\nTo make sure to store the exact revision in the exported data use the command line argument ``--exact``.\nSince 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.\nIf it exists in multiple the remotes ``origin`` and ``upstream`` are considered before any other in alphabetical order.\n\n\nImport set of repositories\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe ``vcs import`` command clones all repositories which are passed in via ``stdin`` in YAML format.\nUsually the data of a previously exported file is piped in::\n\n vcs import < my.repos\n\nThe ``import`` command also supports input in the `rosinstall file format <http://www.ros.org/doc/independent/api/rosinstall/html/rosinstall_file_format.html>`_.\nBeside passing a file path the command also supports passing a URL.\n\nOnly for this command vcs2l supports the pseudo clients ``tar`` and ``zip`` which fetch a tarball / zipfile from a URL and unpack its content.\nFor those two types the ``version`` key is optional.\nIf specified only entries from the archive which are in the subfolder specified by the version value are being extracted.\n\n\nValidate repositories file\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe ``vcs validate`` command takes a YAML file which is passed in via ``stdin`` and validates its contents and format.\nThe data of a previously-exported file or hand-generated file are piped in::\n\n vcs validate < my.repos\n\nThe ``validate`` command also supports input in the `rosinstall file format <http://www.ros.org/doc/independent/api/rosinstall/html/rosinstall_file_format.html>`_.\n\n\nAdvanced features\n-----------------\n\nShow log since last tag\n~~~~~~~~~~~~~~~~~~~~~~~\n\nThe ``vcs log`` command supports the argument ``--limit-untagged`` which will output the log for all commits since the last tag.\n\n\nParallelization and stdin\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\nBy default ``vcs`` parallelizes the work across multiple repositories based on the number of CPU cores.\nIn the case that the invoked commands require input from ``stdin`` that parallelization is a problem.\nIn order to be able to provide input to each command separately these commands must run sequentially.\nWhen needing to e.g. interactively provide credentials all commands should be executed sequentially by passing:\n\n --workers 1\n\nIn the case repositories are using SSH ``git@`` URLs but the host is not known yet ``vcs import`` automatically falls back to a single worker.\n\n\nRun arbitrary commands\n~~~~~~~~~~~~~~~~~~~~~~\n\nThe ``vcs custom`` command enables to pass arbitrary user-specified arguments to the vcs invocation.\nThe set of repositories to operate on can optionally be restricted by the type:\n\n vcs custom --git --args log --oneline -n 10\n\nIf the command should work on multiple repositories make sure to pass only generic arguments which work for all of these repository types.\n\n\nHow to install vcs2l?\n=======================\n\nOn Debian-based platforms the recommended method is to install the package *python3-vcs2l*.\nOn Ubuntu this is done using *apt-get*:\n\nIf you are using `ROS <https://www.ros.org/>`_ you can get the package directly from the ROS repository::\n\n sudo sh -c 'echo \"deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main\" > /etc/apt/sources.list.d/ros-latest.list'\n sudo apt install curl # if you haven't already installed curl\n curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -\n sudo apt-get update\n sudo apt-get install python3-vcs2l\n\nOn other systems, use the `PyPI <https://pypi.org/project/vcs2l/>`_ package::\n\n pip3 install vcs2l\n\n\nSetup auto-completion\n---------------------\n\nFor the shells *bash*, *tcsh* and *zsh* vcs2l can provide auto-completion of the various VCS commands.\nIn order to enable that feature the shell specific completion file must be sourced.\n\nFor *bash* append the following line to the ``~/.bashrc`` file::\n\n source /usr/share/vcs2l-completion/vcs.bash\n\nFor *tcsh* append the following line to the ``~/.cshrc`` file::\n\n source /usr/share/vcs2l-completion/vcs.tcsh\n\nFor *zsh* append the following line to the ``~/.zshrc`` file::\n\n source /usr/share/vcs2l-completion/vcs.zsh\n\nFor *fish* append the following line to the ``~/.config/fishconfig.fish`` file::\n\n source /usr/share/vcs2l-completion/vcs.fish\n\nHow to contribute?\n==================\n\nHow to report problems?\n-----------------------\n\nBefore reporting a problem please make sure to use the latest version.\nIssues can be filled on `GitHub <https://github.com/ros-infrastructure/vcs2l/issues>`_ after making sure that this problem has not yet been reported.\n\nPlease make sure to include as much information, i.e. version numbers from vcs2l, operating system, Python and a reproducible example of the commands which expose the problem.\n\n\nHow to try the latest changes?\n------------------------------\n\nSourcing the ``setup.sh`` file prepends the ``src`` folder to the ``PYTHONPATH`` and the ``scripts`` folder to the ``PATH``.\nThen vcs2l can be used with the commands ``vcs-COMMAND`` (note the hyphen between ``vcs`` and ``command`` instead of a space).\n\nAlternatively the ``-e/--editable`` flag of ``pip`` can be used::\n\n # from the top level of this repo\n pip3 install --user -e .\n\n\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "vcs2l provides a command line tool to invoke vcs commands on multiple repositories.",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/ros-infrastructure/vcs2l",
"Issue tracker": "https://github.com/ros-infrastructure/vcs2l/issues",
"Source code": "https://github.com/ros-infrastructure/vcs2l"
},
"split_keywords": [
"vcs",
" version control",
" git",
" hg",
" svn",
" bzr"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f4cd5d1120a344ab1dd5face8bf63b7e8fabdcaa10ab575cebe55699e825d0d5",
"md5": "2e8a6f094247254e9b8efdc330a7cfb8",
"sha256": "0e5ac317eef9a602cdb4fa047572d4cfdd24d79e458181e7a706df3f1592be5a"
},
"downloads": -1,
"filename": "vcs2l-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2e8a6f094247254e9b8efdc330a7cfb8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 46246,
"upload_time": "2025-07-30T18:17:26",
"upload_time_iso_8601": "2025-07-30T18:17:26.066561Z",
"url": "https://files.pythonhosted.org/packages/f4/cd/5d1120a344ab1dd5face8bf63b7e8fabdcaa10ab575cebe55699e825d0d5/vcs2l-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "32f0bd2937710299e32d3f57c0602f33ad9b51b41bead9d6aeefd2f24dc76ca1",
"md5": "fa3e5d1bb17fcc620debe28d996a9b49",
"sha256": "dd7a58e95f9ee212528a0a99cf3df3ab72b527bf19cd9fa70c1d4307b8dbee5b"
},
"downloads": -1,
"filename": "vcs2l-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "fa3e5d1bb17fcc620debe28d996a9b49",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 37937,
"upload_time": "2025-07-30T18:17:27",
"upload_time_iso_8601": "2025-07-30T18:17:27.495880Z",
"url": "https://files.pythonhosted.org/packages/32/f0/bd2937710299e32d3f57c0602f33ad9b51b41bead9d6aeefd2f24dc76ca1/vcs2l-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-30 18:17:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ros-infrastructure",
"github_project": "vcs2l",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "vcs2l"
}
JSON
