index.md

(index)=

libvcs

Typed Python utilities for Git, SVN, and Mercurial. Parse URLs, execute commands, and synchronize repositories -- all with a consistent, type-friendly API.

::::{grid} 1 2 3 3 :gutter: 2 2 3 3

:::{grid-item-card} Quickstart :link: quickstart :link-type: doc Install and parse your first VCS URL in 5 minutes. :::

:::{grid-item-card} URL Parsing :link: url/index :link-type: doc Parse, validate, and normalize git/hg/svn URLs. :::

:::{grid-item-card} Commands :link: cmd/index :link-type: doc Typed wrappers for git, hg, and svn CLI operations. :::

:::{grid-item-card} Sync :link: sync/index :link-type: doc Clone and update local repositories. :::

:::{grid-item-card} pytest Plugin :link: api/pytest-plugin :link-type: doc Fixtures for isolated VCS test repos. :::

:::{grid-item-card} Project :link: project/index :link-type: doc Contributing, code style, release process. :::

::::

Install

$ pip install libvcs

$ uv add libvcs

libvcs is pre-1.0. Pin to a range: `libvcs>=0.39,<0.40`

See Quickstart for all methods and first steps.

At a glance

from libvcs.url.git import GitURL

url = GitURL(url="git@github.com:vcs-python/libvcs.git")
url.hostname  # 'github.com'
url.path      # 'vcs-python/libvcs'

GitURL.is_valid(url="https://github.com/vcs-python/libvcs.git")
# True

libvcs gives you typed dataclasses for every parsed URL, thin CLI wrappers for git / hg / svn, and high-level sync that clones or updates a local checkout in one call.

Layer	Module	Purpose
URL parsing	{mod}libvcs.url	Detect, validate, normalize VCS URLs
Commands	{mod}libvcs.cmd	Execute individual VCS CLI operations
Sync	{mod}libvcs.sync	Clone and update local repositories

Testing

libvcs ships a pytest plugin with session-scoped fixtures for Git, SVN, and Mercurial repositories:

def test_my_tool(create_git_remote_repo):
    repo_path = create_git_remote_repo()
    assert repo_path.exists()

:hidden:

quickstart
topics/index
api/index
internals/index
project/index
history
migration