gitoxide-py

Fast, typed Python access to local Git repositories.

Explore repositories, inspect history and working-tree state, and manage refs from Python without blocking other threads.

Quick start

Build from a checkout of this repository:

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

import gitoxide_py as gix

repo = gix.discover(".")

print(repo.git_dir)
print(repo.head_name)
print(repo.head_commit().summary)

for commit in repo.commits(max_count=10):
    print(commit.short_id, commit.author.name, commit.summary)

print(repo.branches())
print(repo.tags())
print(repo.read_blob("HEAD:README.md").decode())

The generated API snapshot used by the Griffe CI check lives in stubs/gitoxide_py/__init__.pyi. Regenerate it after changing the PyO3 API by building a wheel with uv run maturin build --generate-stubs, then replace the tracked stub with the wheel's gitoxide_py/__init__.pyi.

What it covers

• Repository and history: HEAD and branch state, revisions, commit walks, merge bases, ahead/behind counts, ancestry, references, branches, tags, and reflogs.
• Content inspection: object kinds, tree entries, blob reads, tree-to-tree diffs with line hunks, and blame.
• Working repository state: remotes, linked worktrees, submodules, local configuration, index entries and conflicts, and working-tree status.
• Focused changes: create or delete branches and tags, and update local configuration. These operations do not modify the working tree.
• Python-friendly: every Git operation releases the GIL, and generated type information is available to mypy and pyright.

Network operations (clone, fetch, and push) and changes to commits, index entries, or working-tree files are not part of the API.

Development

uv run pytest -v
uv run maturin build --generate-stubs