Quickstart¶

Installation¶

For 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

Developmental releases¶

New versions of vcspull are published to PyPI as alpha, beta, or release candidates. In their versions you will see notification like a1, b1, and rc1, respectively. 1.10.0b4 would mean the 4th beta release of 1.10.0 before general availability.

pip:

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

pipx:

$ pipx install --suffix=@next 'vcspull' --pip-args '\--pre' --force
// Usage: 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

via trunk (can break easily):

pip:

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

pipx:

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

uv:

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

Configuration¶

See also

Configuration and Config generation.

We will 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 ~/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 --write (documented in vcspull fmt) to normalize keys and keep your configuration tidy.

The git+ in front of the repository URL. Mercurial repositories use hg+ and Subversion will use svn+. Repo type and address is specified in pip vcs url format.

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

$ vcspull sync

Also, you can sync arbitrary projects, lets assume you have a mercurial repo but need a git dependency, in your project add .deps.yaml (can be any name):

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

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

$ vcspull sync -f .deps.yaml

You can also use fnmatch to pull repositories from your config in various fashions, e.g.:

$ vcspull sync django

$ vcspull sync django\*

$ vcspull sync "django*"

Filter by VCS URL:

Any repo beginning with http, https or git will be look up repos by the 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 beginning with /, ./, ~ or $HOME will scan for patterns of where the project is on your system:

Pull all repos inside of ~/study/python:

$ vcspull sync "$HOME/study/python"

Pull all the repos you have in directories in my config with “python”:

$ vcspull sync ~/*python*