libvcs provides a unified, typed, and pythonic interface for managing Git, Mercurial, and Subversion repositories. Whether you're building a deployment tool, a developer utility, or just need to clone a repo in a script, libvcs handles the heavy lifting.
It powers vcspull and simplifies VCS interactions down to a few lines of code.
- 🔄 Repository Synchronization: Clone, update, and manage local repository copies with a high-level API.
- 🛠 Command Abstraction: Speak fluent
git,hg, andsvnthrough fully-typed Python objects. - 🔗 URL Parsing: Robustly validate, parse, and manipulate VCS URLs (including SCP-style).
- 🧪 Pytest Fixtures: Batteries-included fixtures for spinning up temporary repositories in your test suite.
$ pip install libvcsWith uv:
$ uv add libvcsTry it interactively:
$ uvx --with libvcs ipythonTip: libvcs is pre-1.0. Pin a version range in projects to avoid surprises:
# pyproject.tomldependencies = ["libvcs>=0.37,<0.38"]Clone and update repositories with a consistent API, regardless of the VCS.
Learn more about Synchronization
importpathlibfromlibvcs.sync.gitimportGitSync# Define your repositoryrepo=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()
ifresult.ok:
print(f"Current revision: {repo.get_revision()}")
else:
forerrorinresult.errors:
print(f"Sync failed at {error.step}: {error.message}")Traverse repository entities intuitively with ORM-like filtering, then run targeted commands against them.
Learn more about Command Abstraction
importpathlibfromlibvcs.cmd.gitimportGit# Initialize the wrappergit=Git(path=pathlib.Path.cwd() /"libvcs")
# Run commands directlygit.clone(url="https://github.com/vcs-python/libvcs.git")
git.checkout(ref="master")
# Traverse branches with ORM-like filteringgit.branches.create("feature/new-gui")
print(git.branches.ls()) # Returns QueryList for filtering# Target specific entities with contextual commandsgit.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")Stop writing regex for Git URLs. Let libvcs handle the edge cases.
fromlibvcs.url.gitimportGitURL# Validate URLsGitURL.is_valid(url="https://github.com/vcs-python/libvcs.git") # True# Parse complex URLsurl=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 URLsurl.hostname="gitlab.com"print(url.to_url()) # 'git@gitlab.com:vcs-python/libvcs.git'Writing a tool that interacts with VCS? Use our fixtures to keep your tests clean and isolated.
Learn more about Pytest Fixtures
importpathlibfromlibvcs.pytest_pluginimportCreateRepoFnfromlibvcs.sync.gitimportGitSyncdeftest_my_git_tool(create_git_remote_repo: CreateRepoFn, tmp_path: pathlib.Path):
# Spin up a real, temporary Git servergit_server=create_git_remote_repo()
# Clone it to a temporary directorycheckout_path=tmp_path/"checkout"repo=GitSync(path=checkout_path, url=f"file://{git_server}")
repo.obtain()
assertcheckout_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.