Skip to content

Commit 07b2eae

Browse files
codexByron
authored andcommitted
docs: explain GixPython backend activation and requirements
Replace the historical Gitoxide introduction in `README.md` with an explanation of `GixPython` as Gitoxide's Python bindings and the experimental `GitPython` backend. Describe reduced subprocess overhead and reuse of the native repository handle, with a link to the backend benchmarks. Show installation from this unreleased source checkout and selection through `GIT_PYTHON_BACKEND` before imports. Explain automatic selection, explicit CLI/Gix choices, CPython 3.11+, Git 2.52+, and the Rust 1.89+ and system linker needed for Linux and Windows source builds of `GixPython` 0.3.0. Its default hashing, compression and HTTPS dependencies use pure Rust. Retain CLI fallback and compatibility limitations, linking the backend ledger and downstream audit. Resolve replay against the introducing commit's 0.3.0 upgrade by keeping the new README structure while updating its package version and source-build prerequisites. No repository implementation changes are part of this commit. Validation: the README activation example returned the same HEAD as `git rev-parse HEAD`; local links and `git diff --check` passed. The complete fast profile passed: configured pre-commit hooks, `mypy --python-version=3.12`, `basedpyright --warnings`, `uv sync --all-extras --all-groups --dry-run`, and vendored-package CI lint. Full tests, builds, documentation builds and benchmarks were outside the requested fast profile.
1 parent 35eccc5 commit 07b2eae

1 file changed

Lines changed: 53 additions & 15 deletions

File tree

‎README.md‎

Lines changed: 53 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -2,26 +2,64 @@
22
[![Documentation Status](https://readthedocs.org/projects/gitpython/badge/?version=stable)](https://readthedocs.org/projects/gitpython/?badge=stable)
33
[![Packaging status](https://repology.org/badge/tiny-repos/python:gitpython.svg)](https://repology.org/metapackage/python:gitpython/versions)
44

5-
## [Gitoxide](https://github.com/Byron/gitoxide): A peek into the future…
5+
## GixPython: Gitoxide for GitPython
66

7-
I started working on GitPython in 2009, back in the days when Python was 'my thing' and I had great plans with it.
8-
Of course, back in the days, I didn't really know what I was doing and this shows in many places. Somewhat similar to
9-
Python this happens to be 'good enough', but at the same time is deeply flawed and broken beyond repair.
7+
[GixPython](https://github.com/GitoxideLabs/GixPython) provides the **Python bindings
8+
for [Gitoxide](https://github.com/GitoxideLabs/gitoxide)**, an implementation of Git
9+
in [Rust](https://www.rust-lang.org). GitPython's experimental Gix backend uses these
10+
bindings to execute supported operations through Gitoxide while exposing GitPython's
11+
high-level repository, commit, tree and index interfaces.
1012

11-
By now, GitPython is widely used and I am sure there is a good reason for that, it's something to be proud of and happy about.
12-
The community is maintaining the software and is keeping it relevant for which I am absolutely grateful. For the time to come I am happy to continue maintaining GitPython, remaining hopeful that one day it won't be needed anymore.
13+
Supported object reads, tree traversal, reference/index queries and commit history
14+
can run without launching Git subprocesses. GitPython also retains and reuses a Gix
15+
repository handle across operations, reducing repeated initialization work. These
16+
changes reduce subprocess overhead, particularly for repeated repository queries;
17+
the [backend benchmarks](test/performance/README.md) measure results and CLI launch
18+
counts for both backends.
1319

14-
More than 15 years after my first meeting with 'git' I am still in excited about it, and am happy to finally have the tools and
15-
probably the skills to scratch that itch of mine: implement `git` in a way that makes tool creation a piece of cake for most.
20+
### Activate the Gix backend
1621

17-
If you like the idea and want to learn more, please head over to [gitoxide](https://github.com/Byron/gitoxide), an
18-
implementation of 'git' in [Rust](https://www.rust-lang.org).
22+
This backend is currently unreleased. From this source checkout, install the
23+
optional `gix` extra in a virtual environment:
1924

20-
The experimental `GitPython[gix]` extra uses GixPython 0.3.0 from PyPI for
21-
supported operations, with Git CLI fallback. Set `GIT_PYTHON_BACKEND=cli` or
22-
`gix` to select the backend explicitly. Tests use `gix.testtools` for scripted
23-
fixtures with either backend and require Python 3.11+. See the
24-
[installation, test commands, and conversion ledger](doc/gix-backend.md).
25+
```sh
26+
python -m pip install ".[gix]"
27+
```
28+
29+
The extra installs **GixPython 0.3.0** from PyPI; its Python import name is `gix`.
30+
Set `GIT_PYTHON_BACKEND=gix` **before importing GitPython**, either in your
31+
environment or in Python:
32+
33+
```python
34+
import os
35+
36+
os.environ["GIT_PYTHON_BACKEND"] = "gix"
37+
from git import Repo
38+
39+
with Repo(".") as repo:
40+
print(repo.head.commit.hexsha)
41+
```
42+
43+
With `GIT_PYTHON_BACKEND` unset, GitPython automatically selects Gix when `gix`
44+
can be imported, otherwise CLI. Set it to `cli` to force Git subprocesses instead.
45+
Explicit `gix` selection fails if GixPython cannot be imported.
46+
47+
### Prerequisites and coverage
48+
49+
- **CPython 3.11 or newer** for GixPython. GitPython itself still supports Python
50+
3.8 or newer; on Python 3.8–3.10 the extra omits GixPython and uses CLI.
51+
- **Git 2.52 or newer**, available in `PATH` or selected with
52+
`GIT_PYTHON_GIT_EXECUTABLE`, remains required for CLI fallbacks.
53+
- GixPython 0.3.0 publishes **macOS wheels**. On **Linux and Windows**, installation
54+
builds its released source distribution and requires **Rust 1.89 or newer** and
55+
a **system linker**. Default hashing, compression and HTTPS dependencies use
56+
pure Rust and do not require a C/C++ compiler.
57+
58+
Unsupported operations and options retain the Git CLI path, including clone,
59+
fetch and push. Direct `repo.git.<command>()` calls also retain command-line
60+
behavior. Coverage and compatibility gaps are documented in the
61+
[backend ledger and installation guide](doc/gix-backend.md); the
62+
[downstream audit](test/downstream/audit.md) starts with known API incompatibilities.
2563

2664
## GitPython
2765

0 commit comments

Comments
 (0)