Quickstart¶

vcspull syncs a workspace of git, mercurial, and subversion repositories from one YAML or JSON configuration file. Install it, declare your repositories, and pull everything with a single command.

Installation¶

For the latest official version:

$ pip install --user vcspull

Or using uv:

$ uv tool install vcspull

For one-time use without installation:

$ uvx vcspull

Upgrading:

$ pip install --user --upgrade vcspull

Or with uv:

$ uv tool upgrade vcspull

Configuration¶

See also

Configuration and vcspull import.

You’ll check out the source code of flask to ~/code/flask.

Prefer JSON? Create a ~/.vcspull.json file:

{
  "~/code/": {
    "flask": "git+https://github.com/mitsuhiko/flask.git"
  }
}

YAML? Create a ~/.vcspull.yaml file:

~/code/:
  "flask": "git+https://github.com/mitsuhiko/flask.git"

Already have repositories cloned locally? Use vcspull discover with ~/code --recursive to detect existing Git checkouts and append them to your configuration. See vcspull discover for more details and options such as --workspace-root and --yes for unattended runs. After editing or discovering repositories, run vcspull fmt with --write to normalize keys and keep your configuration tidy.

The git+ prefix tells vcspull the repository type. Mercurial repositories use hg+; Subversion uses svn+. Repository type and address are specified in pip VCS URL format.

Now run the command to pull all the repositories in your .vcspull.yaml / .vcspull.json:

$ vcspull sync --all

Want to manage multiple branches or tags of the same repository? See vcspull worktree for declarative worktree support.

Developmental releases¶

Most readers can stop here. If you need a prerelease, vcspull publishes alpha, beta, and release-candidate builds to PyPI with version suffixes like a1, b1, and rc1. 1.10.0b4 would mean the fourth beta of 1.10.0 before general availability.

pip:

$ pip install --user --upgrade --pre vcspull

pipx:

$ pipx install \
    --suffix=@next \
    --pip-args '\--pre' \
    --force \
    'vcspull'

The suffixed command is then available as vcspull@next sync [config].

uv tool install:

$ uv tool install --prerelease allow vcspull

uv:
```
$ uv add vcspull --prerelease allow
```

uvx:

$ uvx --from 'vcspull' --prerelease allow vcspull

Install from unreleased code¶

Installing from master is for testing unreleased changes and can break without notice.

pip:

$ pip install --user -e git+https://github.com/vcs-python/vcspull.git#egg=vcspull

pipx:

$ pipx install \
    --suffix=@master \
    --force \
    'vcspull @ git+https://github.com/vcs-python/vcspull.git@master'

uv:

$ uv tool install vcspull --from git+https://github.com/vcs-python/vcspull.git

You can also sync arbitrary projects. Let’s say you have a mercurial repository but need a git dependency — add a .deps.yaml to your project (any name works):

./vendor/:
  sdl2pp: "git+https://github.com/libSDL2pp/libSDL2pp.git"

Use -f/--file to specify a config.

$ vcspull sync --file .deps.yaml --all

You can also use fnmatch patterns to pull repositories from your config in various fashions:

$ vcspull sync django

$ vcspull sync django\*

$ vcspull sync "django*"

Filter by VCS URL:

Any repo term beginning with http, https, or git looks up repositories by their VCS URL.

Pull / update repositories you have with github in the repo url:

$ vcspull sync "git+https://github.com/yourusername/*"

Pull / update repositories you have with bitbucket in the repo url:

$ vcspull sync "git+https://*bitbucket*"

Filter by the path of the repo on your local machine:

Any repo term beginning with /, ./, ~, or $HOME matches against the project’s path on your system.

Pull all repos inside of ~/study/python:

$ vcspull sync "$HOME/study/python"

Pull all the repos in your config under directories containing “python”:

$ vcspull sync ~/*python*