libvcs
A typed Python interface for Git, Mercurial, and Subversion repositories.
libvcs parses and validates Git, Mercurial, and Subversion URLs, wraps each VCS's command-line tool in a typed Python object, and synchronizes a local checkout against a remote — cloning it if it does not exist, fetching and updating it if it does. It also ships a pytest plugin for creating disposable repositories in your own test suite.
It powers vcspull, which uses it to sync many repositories from a single config file.
Features at a Glance
- Repository synchronization: One
obtain()/update_repo()call clones a repository if it is missing and fetches it if it already exists, the same way for git, hg, and svn. - Command abstraction: Call
git,hg, andsvnthrough typed Python objects instead of shelling out and parsing text yourself. - URL parsing: Parse, validate, and transform VCS URLs, including
SCP-style
git@host:pathremotes. - Pytest fixtures: Create disposable local git, hg, and svn repositories for your own tests, with per-test isolation.
Installation
$ pip install libvcs
With uv:
$ uv add libvcs
Try it interactively:
$ uvx --with libvcs ipython
libvcs is pre-1.0: a minor version bump (0.45 to 0.46) may change the public API. Pin a version range in projects to avoid surprises:
# pyproject.toml
dependencies = ["libvcs>=0.45,<0.46"]
Usage
1. Synchronize Repositories
GitSync, HgSync, and SvnSync give the same two calls regardless of the
underlying VCS: obtain() clones if the path does not exist yet, and
update_repo() does that or fetches and updates an existing checkout — call
it either way and let libvcs decide.
Learn more about Synchronization
import pathlib
from libvcs.sync.git import GitSync
# Define your repository
repo = GitSync(
url="https://github.com/vcs-python/libvcs",
path=pathlib.Path.cwd() / "libvcs",
remotes={"gitlab": "https://gitlab.com/vcs-python/libvcs"},
)
# Clone (if not exists) or fetch & update (if exists)
result = repo.update_repo()
if result.ok:
print(f"Current revision: {repo.get_revision()}")
else:
for error in result.errors:
print(f"Sync failed at {error.step}: {error.message}")
2. Command Abstraction
Git, Hg, and Svn wrap the binary directly — each call maps to one
subprocess invocation of the real VCS tool, so there is no divergent
reimplementation to trust. Branches, remotes, and tags are also reachable
through QueryList, which filters like a Django ORM queryset.
Learn more about Command Abstraction
import pathlib
from libvcs.cmd.git import Git
# Initialize the wrapper
git = Git(path=pathlib.Path.cwd() / "libvcs")
# Run commands directly
git.clone(url="https://github.com/vcs-python/libvcs.git")
git.checkout(ref="master")
# Traverse branches with ORM-like filtering
git.branches.create("feature/new-gui")
print(git.branches.ls()) # Returns QueryList for filtering
# Target specific entities with contextual commands
git.remotes.set_url(name="origin", url="git@github.com:vcs-python/libvcs.git")
git.tags.create(name="v1.0.0", message="Release version 1.0.0")
3. URL Parsing
GitURL, HgURL, and SvnURL parse and validate VCS URLs — including
SCP-style git remotes — without hand-written regular expressions, and let
you rewrite a parsed URL's parts back into a valid URL string.
from libvcs.url.git import GitURL
# Validate URLs
GitURL.is_valid(url="https://github.com/vcs-python/libvcs.git") # True
# Parse complex URLs
url = GitURL(url="git@github.com:vcs-python/libvcs.git")
print(url.user) # 'git'
print(url.hostname) # 'github.com'
print(url.path) # 'vcs-python/libvcs'
# Transform URLs
url.hostname = "gitlab.com"
print(url.to_url()) # 'git@gitlab.com:vcs-python/libvcs.git'
4. Testing with Pytest
The bundled pytest plugin builds a real, temporary VCS repository per test and tears it down after — no network access, no shared state between tests. A VCS's fixtures are only available when its binary is installed.
Learn more about Pytest Fixtures
import pathlib
from libvcs.pytest_plugin import CreateRepoFn
from libvcs.sync.git import GitSync
def test_my_git_tool(create_git_remote_repo: CreateRepoFn, tmp_path: pathlib.Path):
# Spin up a real, temporary Git server
git_server = create_git_remote_repo()
# Clone it to a temporary directory
checkout_path = tmp_path / "checkout"
repo = GitSync(path=checkout_path, url=f"file://{git_server}")
repo.obtain()
assert checkout_path.exists()
assert (checkout_path / ".git").is_dir()
Project Information
- Python Support: 3.10+
- VCS Support: Git (including AWS CodeCommit), Mercurial (hg), Subversion (svn)
- License: MIT
Links & Resources
- Documentation: libvcs.git-pull.com
- Source Code: github.com/vcs-python/libvcs
- Issue Tracker: GitHub Issues
- Changelog: History
- PyPI: pypi.org/project/libvcs
Support
Your donations fund development of new features, testing, and support.
Release files for libvcs 0.46.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| libvcs-0.46.0.tar.gz | 689.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| libvcs-0.46.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 797.9 kB
Release files / libvcs-0.46.0.tar.gz
| Download URL | libvcs-0.46.0.tar.gz |
|---|---|
| Size | 689.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
044736940c9c7db30ca070c87c681249933667eae603e46e75ac7519a3f4414c
|
|
BLAKE2b-256 checksum How to use checksums |
a2156a18d8dc2c44ce4f11fac06d03a2ea307c216deb32b4dbfc1cf3b986fb9b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 30, 2026.
Transparency logRelease files / libvcs-0.46.0-py3-none-any.whl
| Download URL | libvcs-0.46.0-py3-none-any.whl |
|---|---|
| Size | 108.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
285f4e4c87db31922dd7ab523a306492a4618fd7c50274c14cd7229d3a634e9b
|
|
BLAKE2b-256 checksum How to use checksums |
bd4e004f622d8b2865ebcb00870b0254ccc20de177b7fd35fca26f6afbb04056
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 30, 2026.
Transparency log
