Skip to main content

Lite, typed, python utilities for Git, SVN, Mercurial, etc.

Project description

libvcs · Python Package License Code Coverage

libvcs is a lite, typed, pythonic tool box for detection and parsing of URLs, commanding, and syncing with git, hg, and svn. Powers vcspull.


Supports Python 3.9 and above

Features for Git, Subversion, and Mercurial:

  • Detect and parse VCS URLs
  • Command VCS via python API
  • Sync repos locally
  • Test fixtures for temporary local repos and working copies

To get started, see the quickstart for more.

$ pip install --user libvcs

URL Parser

You can validate and parse Git, Mercurial, and Subversion URLs through libvcs.url:


>>> from libvcs.url.git import GitURL

>>> GitURL.is_valid(url='')

Parse and adjust a Git URL:

>>> from libvcs.url.git import GitURL

>>> git_location = GitURL(url='')

>>> git_location

Switch repo libvcs -> vcspull:

>>> from libvcs.url.git import GitURL

>>> git_location = GitURL(url='')

>>> git_location.path = 'vcs-python/vcspull'

>>> git_location.to_url()

# Switch them to gitlab:
>>> git_location.hostname = ''

# Export to a `git clone` compatible URL.
>>> git_location.to_url()

See more in the parser document.


Simple subprocess wrappers around git(1), hg(1), svn(1). Here is Git w/ Git.clone:

import pathlib
from libvcs.cmd.git import Git

git = Git(path=pathlib.Path.cwd() / 'my_git_repo')


Create a GitSync object of the project to inspect / checkout / update:

import pathlib
from libvcs.sync.git import GitSync

repo = GitSync(
   path=pathlib.Path().cwd() / "my_repo",
       'gitlab': ''

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

# Get revision:
>>> repo.get_revision()

Pytest plugin

libvcs also provides a test rig for local repositories. It automatically can provide clean local repositories and working copies for git, svn, and mercurial. They are automatically cleaned up after each test.

It works by bootstrapping a temporary $HOME environment in a TmpPathFactory for automatic cleanup.

import pathlib

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

def test_repo_git_remote_checkout(
    create_git_remote_repo: CreateProjectCallbackFixtureProtocol,
    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}")


    assert git_repo.get_revision() == "initial"

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

Learn more on the docs at


Your donations fund development of new features, testing and support. Your money will go directly to maintenance and development of the project. If you are an individual, feel free to give whatever feels right for the value you get out of the project.

See donation options at

More information

Docs Build Status

Project details

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

libvcs-0.29.0.tar.gz (448.3 kB view hashes)

Uploaded Source

Built Distribution

libvcs-0.29.0-py3-none-any.whl (74.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page