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, 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.
$ pip install libvcsWith uv:
$ uv add libvcsTry it interactively:
$ uvx --with libvcs ipythonlibvcs 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="[email protected]: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.
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="[email protected]: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()) # '[email protected]: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.11+
- 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.