|
2 | 2 | [](https://readthedocs.org/projects/gitpython/?badge=stable) |
3 | 3 | [](https://repology.org/metapackage/python:gitpython/versions) |
4 | 4 |
|
5 | | -## [Gitoxide](https://github.com/Byron/gitoxide): A peek into the future… |
| 5 | +## GixPython: Gitoxide for GitPython |
6 | 6 |
|
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. |
10 | 12 |
|
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. |
13 | 19 |
|
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 |
16 | 21 |
|
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: |
19 | 24 |
|
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. |
25 | 63 |
|
26 | 64 | ## GitPython |
27 | 65 |
|
|
0 commit comments