# What is vcstool2?
**ℹ️ This project is a fork of [vcstool](https://github.com/dirk-thomas/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](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:
- **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](http://git-scm.com) 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:
```bash
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:
```bash
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](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 `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](https://github.com/dirk-thomas/vcstool) and
[vcstool2](https://github.com/MaxandreOgeret/vcstool2)):
``` yaml
repositories:
vcstool:
url: git@github.com:dirk-thomas/vcstool.git
version: master
old_tools/rosinstall:
url: git@github.com: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](http://www.yaml.org/) format.
The output is usually piped to a file:
```bash
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:
```bash
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:
```bash
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](https://docs.python.org/3/library/re.html#regular-expression-syntax)
for details about the syntax.
To delete all:
```bash
vcs rm --all --force < repos.yaml
```
To delete all repos paths containing "foo" or "bar":
```bash
vcs rm --pattern "foo|bar" --force < repos.yaml
```
### Version ranges
Vcstool2 supports version ranges in the yaml repository file, E.g.
```yaml
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](https://peps.python.org/pep-0440/#version-specifiers), and is powered by the
[packaging](https://packaging.pypa.io/en/stable/specifiers.html) 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](http://pypi.python.org) package:
```bash
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:
```bash
source /usr/share/vcstool2-completion/vcs.bash
```
For *tcsh* append the following line to the `~/.cshrc` file:
```bash
source /usr/share/vcstool2-completion/vcs.tcsh
```
For *zsh* append the following line to the `~/.zshrc` file:
```bash
source /usr/share/vcstool2-completion/vcs.zsh
```
For *fish* append the following line to the `~/.config/fishconfig.fish` file:
```bash
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](https://github.com/MaxandreOgeret/vcstool2/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 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 the`PYTHONPATH` and the `scripts` folder to the `PATH`. Then
vcstool2 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:
```bash
# from the top level of this repo
pip3 install --user -e .
```
Raw data
{
"_id": null,
"home_page": "https://github.com/MaxandreOgeret/vcstool2",
"name": "vcstool2",
"maintainer": "Maxandre Ogeret",
"docs_url": null,
"requires_python": null,
"maintainer_email": "MaxandreOgeret@users.noreply.github.com",
"keywords": null,
"author": "Dirk Thomas",
"author_email": "web@dirk-thomas.net",
"download_url": "https://files.pythonhosted.org/packages/1b/22/514b5c73d95265881a0c35a7ded2d945bd16157c07e0bd4f0339f2f2e471/vcstool2-0.4.5.tar.gz",
"platform": null,
"description": "# What is vcstool2?\n\n**\u2139\ufe0f This project is a fork of [vcstool](https://github.com/dirk-thomas/vcstool) originally created by Dirk Thomas. All credits for the original work go to Dirk Thomas. \u2139\ufe0f**\n\nVcstool2 is a version control system (VCS) tool, designed to make working\nwith multiple repositories easier.\n\nNote:\n\nThis tool should not be confused with [vcstools](https://github.com/vcstools/vcstools/) (with a trailing`s`) which\nprovides a Python API for interacting with different version control systems. The biggest differences between the two\nare:\n\n- **vcstool2** doesn't use any state beside the repository working copies available in the filesystem.\n- The file format of vcstool2's `export` uses the relative paths of the repositories as keys in YAML which avoids\n collisions by design.\n- **vcstool2** has significantly fewer lines of code than **vcstools** including the command line tools built on top.\n\n## Python support\n\nThis package supports Python >= 3.5, and is tested on Python (3.7 -> 3.12).\n\n## How does it work?\n\nVcstool2 operates on any folder from where it recursively searches for supported repositories. On these repositories\nvcstool2 invokes the native VCS client with the requested command (i.e. *diff*).\n\n## Which VCS types are supported?\n\nVcstool2 supports [Git](http://git-scm.com) repositories only.\n\n## How to use vcstool2?\n\nThe script `vcs` can be used similarly to the VCS clients `git`, `hg`, etc. The `help` command provides a list of\navailable commands with an additional description:\n\n```bash\nvcs help\n```\n\nBy default, vcstool2 searches for repositories under the current folder. Optionally one path (or multiple paths) can be\npassed to search for repositories at different locations:\n\n```bash\nvcs status /path/to/several/repos /path/to/other/repos /path/to/single/repo\n```\n\n## Exporting and importing sets of repositories\n\nVcstool2 can export and import all the information required to reproduce the versions of a set of repositories. Vcstool2\nuses a simple [YAML](http://www.yaml.org/) format to encode this information. This format includes a root\nkey `repositories` under which each local repository is described by a dictionary keyed by its relative path. Each of\nthese dictionaries contains keys `url`, and `version`. If the `version` key is omitted the default branch is\nbeing used.\n\nThis results in something similar to the following for a set of two repositories\n([vcstool](https://github.com/dirk-thomas/vcstool) and\n[vcstool2](https://github.com/MaxandreOgeret/vcstool2)):\n\n``` yaml\nrepositories:\n vcstool:\n url: git@github.com:dirk-thomas/vcstool.git\n version: master\n old_tools/rosinstall:\n url: git@github.com:MaxandreOgeret/vcstool2.git\n version: master\n```\n\n### Export set of repositories\n\nThe `vcs export` command outputs the path, URL and version\ninformation for all repositories in [YAML](http://www.yaml.org/) format.\nThe output is usually piped to a file:\n\n```bash\nvcs export > my.repos\n```\n\nIf the repository is currently on the tip of a branch the branch is followed. This implies that a later import might\nfetch a newer revision if the branch has evolved in the meantime. Furthermore, if the local branch has evolved from the\nremote 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`. Since a specific\nrevision is not tied to neither a branch nor a remote (for Git and Mercurial) the tool will check if the current hash\nexists in any of the remotes. If it exists in multiple the remotes `origin` and `upstream` are considered before any\nother in alphabetical order.\n\n### Import set of repositories\n\nThe `vcs import` command clones all repositories which are passed in via `stdin` in YAML format. Usually the data of a\npreviously exported file is piped in:\n\n```bash\nvcs import < my.repos\n```\n\nBeside passing a file path the command also supports passing a URL.\n\n### Validate repositories file\n\nThe `vcs validate` command takes a YAML file which is passed in via `stdin` and validates its contents and format. The\ndata of a previously-exported file or hand-generated file are piped in:\n\n```bash\nvcs validate < my.repos\n```\n\n### Deleting repositories\n\nThe `vcs rm` command takes a YAML file containing the repositories which is passed in via `stdin` or with its path\nspecified via `--input`.\n\nThe command performs a dry run by default, to perform the deletion use the `--force` option.\n\nThis command will delete all the pulled repositories if the `--all` option is passed. \nIt can also filter the repos to delete based on their cloning path with a regex pattern passed with the `--pattern` \noption, see the `re` module [documentation](https://docs.python.org/3/library/re.html#regular-expression-syntax) \nfor details about the syntax.\n\nTo delete all:\n\n```bash\nvcs rm --all --force < repos.yaml\n```\n\nTo delete all repos paths containing \"foo\" or \"bar\":\n\n```bash\nvcs rm --pattern \"foo|bar\" --force < repos.yaml\n```\n\n### Version ranges\n\nVcstool2 supports version ranges in the yaml repository file, E.g.\n\n```yaml\nrepositories:\n vcstool2_0:\n url: https://github.com/MaxandreOgeret/vcstool2.git\n version: \">0.4.1,<0.4.3\"\n vcstool2_1:\n url: https://github.com/MaxandreOgeret/vcstool2.git\n version: \"==0.4.*\"\n```\n\nThe version ranges syntax follows [Python Packaging Authority Guidelines](https://peps.python.org/pep-0440/#version-specifiers), and is powered by the\n[packaging](https://packaging.pypa.io/en/stable/specifiers.html) package.\n\n## Advanced features\n\n### Show log since last tag\n\nThe `vcs log` command supports the argument `--limit-untagged` which will output the log for all commits since the last\ntag.\n\n### Parallelization and stdin\n\nBy default `vcs` parallelizes the work across multiple repositories based on the number of CPU cores. In the case that\nthe invoked commands require input from `stdin` that parallelization is a problem. In order to be able to provide input\nto each command separately these commands must run sequentially. When needing to e.g. interactively provide credentials\nall commands should be executed sequentially by passing:\n\n```\n--workers 1\n```\n\nIn the case repositories are using SSH `git@` URLs but the host is not known yet `vcs import` automatically falls back\nto a single worker.\n\n### Run arbitrary commands\n\nThe `vcs custom` command enables to pass arbitrary user-specified arguments to the git executable.\n\n```\nvcs custom --args log --oneline -n 10\n```\n\n\n# How to install vcstool2?\n\nUse the [PyPI](http://pypi.python.org) package:\n\n```bash\nsudo pip install vcstool2\n```\n\n## Setup auto-completion\n\nFor the shells *bash*, *tcsh* and *zsh* vcstool2 can provide auto-completion of the various VCS commands. In order to\nenable that feature the shell specific completion file must be sourced.\n\nFor *bash* append the following line to the `~/.bashrc` file:\n\n```bash\nsource /usr/share/vcstool2-completion/vcs.bash\n```\n\nFor *tcsh* append the following line to the `~/.cshrc` file:\n\n```bash\nsource /usr/share/vcstool2-completion/vcs.tcsh\n```\n\nFor *zsh* append the following line to the `~/.zshrc` file:\n\n```bash\nsource /usr/share/vcstool2-completion/vcs.zsh\n```\n\nFor *fish* append the following line to the `~/.config/fishconfig.fish` file:\n\n```bash\nsource /usr/share/vcstool2-completion/vcs.fish\n```\n\n# How to contribute?\n\n## How to report problems?\n\nBefore reporting a problem please make sure to use the latest version. Issues can be filled\non [GitHub](https://github.com/MaxandreOgeret/vcstool2/issues) after making sure that this problem has not yet been\nreported.\n\nPlease make sure to include as much information, i.e. version numbers from vcstool2, operating system, Python and a\nreproducible example of the commands which expose the problem.\n\n## How to try the latest changes?\n\nSourcing the `setup.sh` file prepends the `src` folder to the`PYTHONPATH` and the `scripts` folder to the `PATH`. Then\nvcstool2 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```bash\n# from the top level of this repo\npip3 install --user -e .\n```\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "vcstool2 provides a command line tool to invoke git commands on multiple repositories.",
"version": "0.4.5",
"project_urls": {
"Homepage": "https://github.com/MaxandreOgeret/vcstool2"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ffdf7186f8215e9dab32b146016a5fef0deaa1af3a3dc43e0936a39b42a28336",
"md5": "45f5e23ae3b164eb5d129d8b625dffe8",
"sha256": "df83770c95c9d110d4695e22ba2b6d878cb003b233e8ea7db975846f9ceb3969"
},
"downloads": -1,
"filename": "vcstool2-0.4.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "45f5e23ae3b164eb5d129d8b625dffe8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 38135,
"upload_time": "2024-08-25T12:21:08",
"upload_time_iso_8601": "2024-08-25T12:21:08.498870Z",
"url": "https://files.pythonhosted.org/packages/ff/df/7186f8215e9dab32b146016a5fef0deaa1af3a3dc43e0936a39b42a28336/vcstool2-0.4.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1b22514b5c73d95265881a0c35a7ded2d945bd16157c07e0bd4f0339f2f2e471",
"md5": "bef140e39ca0195af92bc21aa9459508",
"sha256": "d77cf32318a467395ebcba8ad98e1aaf3ea763d34c8a92c23bcb17a0d53372d1"
},
"downloads": -1,
"filename": "vcstool2-0.4.5.tar.gz",
"has_sig": false,
"md5_digest": "bef140e39ca0195af92bc21aa9459508",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 37625,
"upload_time": "2024-08-25T12:21:10",
"upload_time_iso_8601": "2024-08-25T12:21:10.399068Z",
"url": "https://files.pythonhosted.org/packages/1b/22/514b5c73d95265881a0c35a7ded2d945bd16157c07e0bd4f0339f2f2e471/vcstool2-0.4.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-25 12:21:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MaxandreOgeret",
"github_project": "vcstool2",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "vcstool2"
}
JSON
