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.

• 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, and svn through typed Python objects instead of shelling out and parsing text yourself.
• URL parsing: Parse, validate, and transform VCS URLs, including SCP-style git@host:path remotes.
• Pytest fixtures: Create disposable local git, hg, and svn repositories for your own tests, with per-test isolation.

$ 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"]

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}")

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")

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.

Learn more about URL Parsing

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'

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()

• Python Support: 3.10+
• VCS Support: Git (including AWS CodeCommit), Mercurial (hg), Subversion (svn)
• License: MIT

• Documentation: libvcs.git-pull.com
• Source Code: github.com/vcs-python/libvcs
• Issue Tracker: GitHub Issues
• Changelog: History
• PyPI: pypi.org/project/libvcs

Your donations fund development of new features, testing, and support.

• Donation Options