gitoxide-py

Python bindings to gitoxide (the gix Rust crate), built with PyO3 and maturin.

Status: alpha, work in progress.

Started from shenxianpeng/gitoxide (MIT OR Apache-2.0) and reworked from there: every call releases the GIL, the read surface covers diffs, reflogs, the index and submodules, and ref edits are supported. Distributed as gitoxide-py, separately from that project's gitoxide package.

Design goals

• API parity with gix. Method and function names mirror gix's own Rust API where a direct equivalent exists (open/discover/init, git_dir/workdir, head_id/head_commit, rev_parse_single, rev_walk/commits, ...), rather than mimicking GitPython's API shape.
• The GIL is released for every call. Every method wraps its gix work in Python::detach, so other Python threads keep running while a call is in flight. See the module doc comment in src/lib.rs for why Repository is backed by gix::ThreadSafeRepository rather than gix::Repository — the latter is never Sync (internal RefCell-based object cache), so it can't satisfy detach's Send bound no matter how the pyclass is annotated.
• Typed, with no hand-maintained stub file. pyo3's experimental-inspect feature embeds type introspection data into the built binary; maturin build/develop --generate-stubs extracts it and bundles the result into the wheel as a proper gitoxide_py/ package (__init__.py + .pyi + py.typed, PEP 561), so mypy/pyright resolve real types against the installed package with no extra configuration — and the stub can never drift from the actual API, since it's generated from the same binary. Requires the declarative #[pymodule] mod gitoxide_py { ... } style in src/lib.rs; introspection doesn't support the older function-style #[pymodule] fn gitoxide_py(m: &Bound<PyModule>) -> PyResult<()> { ... }.

Building

uv manages the environment — maturin and pytest are declared as a dev dependency group in pyproject.toml, locked in uv.lock.

uv sync
uv run maturin develop --release --generate-stubs

API

The generated stub (gitoxide_py/__init__.pyi in the installed package) carries the full signature and doc of every function, method and attribute, so editors and type checkers describe the API without a second copy of it living here.

Testing

uv run pytest -v

The tests build fixture repositories with the real git CLI and exercise the API against them. test_gil_release.py is the exception: it asserts that Python::detach actually lets another Python thread make progress during a call, via the _debug_detached_sleep helper (not part of the public API).

CI (.github/workflows/ci.yml) runs on a self-hosted runner: cargo fmt --check, cargo clippy -D warnings, uv run maturin develop --release --generate-stubs, then uv run pytest -v.

Scope

Alpha. Reading, plus the writes that are a ref edit and nothing more: creating and deleting branches and tags, and setting local configuration. Nothing here touches the working tree.

Covered: open/discover/init; HEAD and branch state; rev-parse and object kinds; commit walks, in graph, date or topological order; merge-base, ahead/behind and ancestry checks; tree entries and blob reads; tree-to-tree diffs, with per-file line counts on request; remotes; linked worktrees; submodules and their status; index entries and conflict stages; working-tree status; reflogs; configuration reads and writes; and branch and tag creation and deletion.

Not covered: anything over the network (fetch/push/clone need a transport feature and a TLS backend, a dependency decision of its own), and anything that writes commits, index entries or the working tree. Note that those are also where git runs hooks — it runs none for a ref edit, and neither does this.

Layout

src/lib.rs assembles the Python module out of items defined beside it: src/repository.rs holds the Repository handle and the functions that open one, src/types.rs the value objects its methods return, and src/util.rs the conversions they share.