libvcs ·

Stop struggling with VCS command-line tools in Python. libvcs gives you a clean, typed API to work with Git, Mercurial, and SVN repositories - parse URLs, run commands, and sync repos with just a few lines of code.

Why Use libvcs?

• 🔄 Manage multiple repos without shell scripts or subprocess calls
• 🔍 Parse and transform VCS URLs between different formats
• 🧪 Test code that interacts with repositories using included pytest fixtures
• 🔒 Type-safe operations with full typing support

Supports Python 3.9 and above, Git (including AWS CodeCommit), Subversion, and Mercurial.

$ pip install --user libvcs

---

Quick Examples

Parse and transform Git URLs

>>> from libvcs.url.git import GitURL
>>> # Transform a GitHub URL to GitLab with one line
>>> git_location = GitURL(url='git@github.com:vcs-python/libvcs.git')
>>> git_location.hostname = 'gitlab.com'  # Change is this simple!
>>> git_location.to_url()
'git@gitlab.com:vcs-python/libvcs.git'

Clone and update repositories

>>> from libvcs.sync.git import GitSync
>>> import pathlib
>>> # Set up our repository with options
>>> repo = GitSync(
...    url="https://github.com/vcs-python/libvcs",
...    path=pathlib.Path.cwd() / "my_repo",
...    remotes={
...        'gitlab': 'https://gitlab.com/vcs-python/libvcs'
...    }
... )
>>> # Operations are simple to understand
>>> # repo.obtain()  # Clone if needed
>>> # repo.update_repo()  # Pull latest changes
>>> # repo.get_revision()
>>> # '5c227e6ab4aab44bf097da2e088b0ff947370ab8'

Validate repository URLs

>>> from libvcs.url.git import GitURL
>>> # Quickly validate if a URL is a proper Git URL
>>> GitURL.is_valid(url='https://github.com/vcs-python/libvcs.git')
True

---

Core Features

1. URL Detection and Parsing

Easily validate and parse VCS URLs using the libvcs.url module:

Parse URLs and modify them programmatically:

>>> from libvcs.url.git import GitURL
>>> git_location = GitURL(url='git@github.com:vcs-python/libvcs.git')
>>> git_location.path = 'vcs-python/vcspull'
>>> git_location.to_url()
'git@github.com:vcs-python/vcspull.git'

See more in the parser documentation.

2. Command Abstraction

Abstracts CLI commands for git(1), hg(1), svn(1) via a lightweight subprocess wrapper.

import pathlib
from libvcs.cmd.git import Git

git = Git(path=pathlib.Path.cwd() / 'my_git_repo')
git.clone(url='https://github.com/vcs-python/libvcs.git')

Above: libvcs.cmd.git.Git using Git.clone().

3. Repository Synchronization

Synchronize repositories using the libvcs.sync module.

import pathlib
from libvcs.sync.git import GitSync

repo = GitSync(
   url="https://github.com/vcs-python/libvcs",
   path=pathlib.Path().cwd() / "my_repo",
   remotes={
       'gitlab': 'https://gitlab.com/vcs-python/libvcs'
   }
)

# Update / clone repo:
# repo.update_repo()

# Get revision:
# repo.get_revision()
# '5c227e6ab4aab44bf097da2e088b0ff947370ab8'

4. Pytest Fixtures for Testing

libvcs pytest plugin provides py.test fixtures to create temporary VCS repositories for testing. Repositories are automatically cleaned on test teardown.

import pathlib

from libvcs.pytest_plugin import CreateRepoPytestFixtureFn
from libvcs.sync.git import GitSync


def test_repo_git_remote_checkout(
    create_git_remote_repo: CreateRepoPytestFixtureFn,
    tmp_path: pathlib.Path,
    projects_path: pathlib.Path,
) -> None:
    git_server = create_git_remote_repo()
    git_repo_checkout_dir = projects_path / "my_git_checkout"
    git_repo = GitSync(path=str(git_repo_checkout_dir), url=f"file://{git_server!s}")

    git_repo.obtain()
    git_repo.update_repo()

    assert git_repo.get_revision() == "initial"

    assert git_repo_checkout_dir.exists()
    assert pathlib.Path(git_repo_checkout_dir / ".git").exists()

Under the hood: fixtures bootstrap a temporary $HOME environment in a TempPathFactory for automatic cleanup and pytest-xdist compatibility.

---

Documentation & Resources

• Getting Started: Quickstart Guide
• Full Documentation: libvcs.git-pull.com
• Changelog: History
• Source Code: GitHub
• PyPI Package: libvcs

API References

• libvcs.url: URL Parser
• libvcs.cmd: Commands
• libvcs.sync: Clone and update

Support

Your donations fund development of new features, testing and support. Your money will go directly to maintenance and development of the project.

See donation options at https://www.git-pull.com/support.html.

About

• Python support: 3.9+, pypy
• VCS supported: git(1), svn(1), hg(1)
• Issues: https://github.com/vcs-python/libvcs/issues
• Test Coverage: https://codecov.io/gh/vcs-python/libvcs
• License: MIT