gitoxide-python

Fast, safe, pure-Rust Git for Python — bindings to the gitoxide engine, and a modern alternative to GitPython.

gitoxide (the gix crate) is a next-generation, pure-Rust implementation of Git. This project exposes that engine to Python through PyO3 and ships as pre-built wheels via maturin, so you get:

_{Nothing here shells out to the git CLI. A repository that configures a clean/smudge filter (Git LFS, say) will still have that filter program executed when blame reads such a file — exactly as git itself would.}

Status: alpha. The binding surface is small but real. It currently covers read-oriented workflows (open/discover, HEAD, history walk, refs, branches, tags, blob reads) — the operations DevOps tooling reaches for most. See Scope for what is and isn't wrapped yet.

Installation

pip install gitoxide

Pre-built wheels are published for Linux (manylinux, x86_64 + aarch64), macOS (x86_64 + Apple Silicon), and Windows — no Rust toolchain or system libgit2 required.

Quick start

import gitoxide

repo = gitoxide.open(".")            # or gitoxide.discover(".")

print(repo.git_dir)                  # .../my-project/.git
print(repo.workdir)                  # .../my-project  (None if bare)
print(repo.is_bare)                  # False
print(repo.head_name)                # 'main'  (None if detached)

# The commit at HEAD
head = repo.head_commit()
print(head.short_id, head.summary)
print(head.author.name, head.author.email, head.author.time)

# Walk history (reverse-chronological), like `git log`
for commit in repo.commits(max_count=10):
    print(commit.short_id, commit.author.name, commit.summary)

# Resolve a revspec to an object id
print(repo.rev_parse("HEAD~2"))
print(repo.rev_parse("main"))

# Branches, tags, and all references
print(repo.branches())               # ['main', 'dev', ...]
print(repo.tags())                   # ['v1.0.0', ...]
for ref in repo.references():
    print(ref.name, "->", ref.target)

# Read a file's content at a revision
readme = repo.read_blob("HEAD:README.md")
print(readme.decode())

# Blame a file: which commit last touched each line
for hunk in repo.blame("README.md"):
    print(f"{hunk.start_line}-{hunk.end_line}\t{hunk.short_id}")

Performance

Median time per operation on a full clone of python/cpython — 130,654 commits, 531 references — on an Apple M2:

Faster than GitPython on five of these seven, a tie on open, and a loss on blame — where GitPython is really git's own C implementation in a subprocess, and gix's younger blame has not caught it yet. Against pygit2 the split runs the other way: history walking and blame are several times faster here, while pygit2 still wins the single-object lookups it has spent fifteen years tuning.

The three libraries are checked against each other on every operation — same commit ids, same blob bytes, same line count — so a fast wrong answer can't win. benchmarks/ has the exact call made against each library, the caveats, and a one-command way to reproduce it on your own machine.

Migrating from GitPython

Common operations, side by side:

The key difference is what happens underneath: GitPython's iter_commits spawns a git rev-list subprocess; gitoxide-python walks the object database in-process in Rust.

API

Module functions

• gitoxide.open(path) -> Repository
• gitoxide.discover(path) -> Repository — search path and its parents
• gitoxide.init(path, bare=False) -> Repository
• gitoxide.gix_version() -> str

Repository

Properties: git_dir, workdir, is_bare, is_shallow, head_id, head_name, head_is_detached.

Note: head_name and head_is_detached access the HEAD reference and may raise GitoxideError if it is inaccessible (e.g., corrupted repository). is_shallow may raise GitoxideError if the configured shallow-file path cannot be represented on the platform. Other properties never raise.

Methods: head_commit(), rev_parse(spec), commit(rev), commits(rev=None, max_count=None), references(), branches(), tags(), read_blob(rev), blame(path, rev=None).

Commit

id, short_id, tree_id, message, summary, author, committer, parents.

Signature

name, email, time (Unix seconds), offset (UTC offset seconds).

Reference

name, shorthand, target.

BlameHunk

start_line, end_line, line_count, orig_start_line, commit_id, short_id. Line numbers are 1-based and inclusive, matching git blame. Consecutive lines from the same commit are grouped into one hunk.

All errors (from any function or method) are raised as gitoxide.GitoxideError.

Scope

This is a binding, not a reimplementation: it exposes a slice of what the gix engine already does. Today that slice is:

• Wrapped: open / discover / init, HEAD, history walk, rev-parse, references, branches, tags, blob reads, and blame.
• Not wrapped yet: diff & status, tree listing, writing commits and the index, and clone / remote operations.

The engine supports much more; these are simply the parts this binding hasn't surfaced yet. Issues and pull requests that expose more of gix are welcome — see Contributing.

Contributing

The binding layer lives in a single src/lib.rs and maps closely onto the gix API, so adding a method is usually a small, self-contained change.

Building from source requires a Rust toolchain (this is also the path used when installing the sdist on a platform without a pre-built wheel):

python -m venv .venv && source .venv/bin/activate
pip install maturin pytest

maturin develop          # build the extension into the venv
pytest -q                # run the test suite

cargo fmt --all          # format Rust
cargo clippy --all-targets -- -D warnings

The tests generate a throwaway git repository on the fly (see tests/conftest.py), so they need git on PATH but touch nothing outside a temp directory.

License

Licensed under either of Apache License 2.0 or MIT license at your option, to match the upstream gitoxide project.