Code Style

Formatting and linting

libvcs uses ruff for formatting and linting in a single tool. The full rule set is declared in pyproject.toml under [tool.ruff].

$ uv run ruff format .

$ uv run ruff check . --fix --show-fixes

Type checking

mypy runs in strict mode:

$ uv run mypy src tests

Docstrings

All public APIs use NumPy-style docstrings:

def fetch(url: str, *, branch: str | None = None) -> str:
    """Fetch a remote branch.

    Parameters
    ----------
    url : str
        Repository URL.
    branch : str or None
        Branch name. ``None`` means the default branch.

    Returns
    -------
    str
        The fetched commit hash.
    """

Imports

• from __future__ import annotations at the top of every file.

• Standard-library modules use namespace imports: import pathlib, not from pathlib import Path.

• Typing: import typing as t, then t.Optional, t.Any, etc.