Metadata-Version: 2.4
Name: gitoxide-py
Version: 0.87.1
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Typing :: Typed
License-File: LICENSE
Summary: Typed Python bindings to the gix (gitoxide) engine that release the GIL for every call
Keywords: git,gitoxide,gix,vcs,version-control,pyo3
Author: Pol Feliu
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/feliupol/gitoxide-py
Project-URL: Repository, https://github.com/feliupol/gitoxide-py
Project-URL: gix (Rust crate), https://github.com/GitoxideLabs/gitoxide

# gitoxide-py

<p align="center">
  <strong>Fast, typed Python access to local Git repositories.</strong>
</p>

<p align="center">
  <a href="https://github.com/feliupol/gitoxide-py/actions/workflows/ci.yml">
    <img src="https://github.com/feliupol/gitoxide-py/actions/workflows/ci.yml/badge.svg?branch=main" alt="Build status">
  </a>
  <a href="https://www.python.org/">
    <img src="https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&amp;logoColor=white" alt="Python 3.9 or later">
  </a>
</p>

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:

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

```python
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

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

