jobs:

test:

runs-on: windows-latest

env:

- name: Test with pytest

run: |

Gix-backed operation, and backend timings include its Python glue and any CLI

fallbacks.

`IndexFile` queries immutable entry records; it does not retain a parsed index.

Deferred/virtual state consists of opaque file bytes, materialized before Git

operates and read back only after success. Private edits use Git because native

bindings cannot load an arbitrary existing index (GIX-3) or validate a checked

batch of paths (GIX-26). Split snapshots become standalone through Git and regain

split publication through Git. Native default-index queries, fresh v2 indexes

and verified tree construction remain supported. Backend coverage must count

these editing fallbacks.

Commit metadata uses `Repository.find_commit().decode()` plus structured

`Commit.author()`/`committer()` signatures. Tag metadata uses

`Repository.find_tag().decode()` and `Tag.tagger()`. Decoded extra headers retain

`gpgsig`. Raw Gix object bytes are used only for object streams. If repository

capabilities require CLI fallback, metadata uses `git cat-file`: general formatted

Git queries cannot faithfully expose all signature headers or arbitrary tags.

The bounded public identity helpers remain Python glue. Human date parsing uses

Git until GIX-27 is exposed; trailer extraction already uses Git.

Benchmark remeasurement on 2026-10-09 used the same fixed SHA-1/files fixture

`6ba2c0a2f9ee7feffd7e079621c4845820180c9a`. All 14 result digests match between

CLI and Gix. Gix still uses 1 CLI process for the complete read journey, 0 for

index reads and commit history, 1 for patch diffs/opening, and 3 for discovery.

The CLI journey now uses 73 launches, including 26 for the 25-commit history;

raw metadata queries preserve exact bytes. Existing Gix budgets remain valid.

The `--fast` timing samples ran alongside validation and have substantial jitter;

use their digests/counts, not their wall times, as evidence for this migration.

These read-only budgets make no claim that index editing is native.

The prepared environments in this checkout are `.venv` (CLI) and `.tox/gix`

| `Commit.iter_items`, `Repo.iter_commits` | First-parent walks and a single tip | General history ordering; GIX-8 |

| Index entry reads, `ls_files` | Stage/mode/OID/path and exposed index flags | Custom and sparse indexes; GIX-3/4 |

| `IndexFile.version`, `update_index` query | Native index version | Actual `update-index` mutations |

| Index editing and `IndexFile.write` | Opaque byte snapshots; atomic locked publication | Private-file edits always use Git: arbitrary native index loading and strict pathname validation are missing; GIX-3/4/13/26 |

| ODB `store`, managed `hash_object` | Native object hashing/writing with byte-fidelity preflight | Tags, large/nonseekable input and changed serialization; GIX-2/5/28 |

| `IndexFile.write_tree` | Native tree editor with child-kind and null-ID validation | Missing non-gitlink children, invalid entries; GIX-7/24 |

| Tree serialization, `mktree` | Native tree editor with child-kind and null-ID validation | Missing children, unsupported or invalid entries; GIX-7/24 |

| Fresh index preparation, `read_tree` | Empty index or index from one tree | Existing index, merges, non-v2 selection; GIX-13 |

| GIX-23 | Missing API | No hook lookup or execution API is bound in GixPython 0.1.0. The removed absence fast path read config through Gix but used Python `os.stat()` to declare success. | Bind native hook lookup with configured/default path, linked-worktree, missing/nonexecutable-hook and diagnostic semantics, plus execution where needed. Until then all managed hook calls use Git, including `--ignore-missing` no-ops. A Python filesystem check is not a Gix implementation. |

| GIX-24 | Bug | In both object formats, `new_commit_as()` accepts a blob as the tree or a parent where `git commit-tree` rejects it. Tree-editor `upsert()`/`write()` accepts object IDs whose actual kinds disagree with blob/tree/gitlink modes; `git mktree --missing` rejects all three tested mismatches. `edit_references_as()` accepts a blob target under `refs/heads/`, rejected by `git update-ref`. | Provide checked commit/tree construction and reference edits, at least in Git-strict mode. Match Git's kind and direct-branch target validation before writing and under the required ref locks, including its distinct handling of symbolic aliases. Existing `_commit_tree`, `_write_tree` and `_update_ref` guards query Gix headers and select CLI on invalid inputs; they do not replace Gix writes with Python. |

| GIX-25 | Bug; missing API | After `git symbolic-ref refs/heads/dangling refs/heads/missing`, `Repository.references().all()` enumerates the dangling name, while `git for-each-ref --format=%(refname)` omits it. Valid symbolic aliases must remain present. Both SHA-1 and SHA-256 probes reproduce this difference. | Expose Git-compatible enumeration with the same dangling-reference and diagnostic behavior, retaining the raw iterator for callers that need it. `_for_each_ref` forces Gix to resolve symbolic targets and falls back to Git on failure; keep that fallback until a compatible Gix API/mode is verified. |

| GIX-26 | Bug; missing API | `dangerously_push_entry(IndexStat(), oid, 0, 0o120000, b".gitmodules")`, followed by `sort_entries()`, `verify_entries()` and `write()`, succeeds and retains the unsafe symlink. Protected Git `update-index -z --index-info` ignores it with exit 0 and `Ignoring path .gitmodules`; protected `read-tree` rejects it. The native fresh `index_from_tree` also rejects it. | A Git-strict checked index batch editor that validates names/modes, preserves metadata and reports rejected records. `verify_entries()` verifies ordering, not pathname safety. All private-index edits use Git with `core.protectHFS=true` and `core.protectNTFS=true`, followed by requested-entry readback; no Python dictionary reconstruction or native dangerous insertion remains. |

| GIX-27 | Missing API | `gix.Time` exposes seconds/offset but no human date parser in GixPython 0.1.0. | Bind Git-compatible textual date parsing with timezone semantics. `parse_date()` uses `git var GIT_AUTHOR_IDENT` with fixed identity and per-command date, then adapts the normalized timestamp/offset. |

| GIX-28 | Bug; missing API | GixPython 0.1.0 on Gitoxide `f819565c2c4c56619c4888acef6cf3b8144cbccb` stores `object <blob>\ntype blob\ntag invalid\n\nmessage\n` through `write_object("tag", data)`. Git 2.54.0 rejects the same payload through `hash-object -t tag -w --stdin` with `missingTaggerEntry`. Byte-preserving native readback does not establish Git's validation. | Expose a Git-strict tag writer or validation API. Managed tag hashing/storage uses Git before any native write; `test_tag_storage_rejects_missing_tagger` verifies failure and absence from storage. Keep the bug open until upstream validation is verified. |

Windows reproduction for GIX-14 uses CPython 3.12.13, Git

2.55.0.windows.3 and the released GixPython 0.1.0 source distribution with

* ``GitCmdObjectDB`` no longer inherits ``LooseObjectDB``. Its object reads,

writes, existence checks, and enumeration use Git, including packed objects.

Precompressed input streams and custom object-output writers are unsupported.

``GitDB`` exports and backend selection are removed. ``odbt`` accepts only

``GitCmdObjectDB`` and its subclasses, rejecting unsupported types before

initialization or cloning. Remove ``odbt=GitDB`` or select ``GitCmdObjectDB``.

``gitdb`` remains a dependency for shared types and utilities.

* ``Repo.object_format`` and ``Repo.ref_format`` report Git's storage formats.

``Repo.alternates`` is read-only and reports effective absolute alternate

directories, including environment and transitive alternates. Direct editing

Fetch/pull results are derived from command output rather than ``FETCH_HEAD``

file parsing. Revision strings follow Git's native revision grammar.

* ``IndexFile.entries`` is removed. Use ``iter_entries()`` for immutable query

records, ``entry(path, stage=0)`` for exact lookup (missing entries raise

``KeyError``), ``add()``, and ``remove()`` for edits. Python retains only opaque

index-file bytes for deferred/virtual indexes. Git edits private files and

validates readback before atomic publication. ``add(write=False)`` and

``resolve_blobs()`` retain deferred edits; ``remove(..., write=False)`` now does

too, unless ``working_tree=True``. ``write(file_path)`` publishes to an alternate

path. Checkout and diff use pending bytes. Git owns versions, flags, sparse and

split indexes; deferred split snapshots are made standalone through Git.

Ordinary failed index edits preserve pending and published state. Worktree,

object storage and hook side effects are not rolled back. Commit hooks see the

materialized index; their index edits survive failures without advancing HEAD.

Binary-parser tests and duplicate filename-rejection matrices are replaced by

happy paths, Python glue failures and representative compatibility regressions.

Historical timing-only tests are removed; the maintained backend benchmark

checks result parity and CLI budgets.

* Commit/tag metadata uses structured Gix decoders when the Gix backend supports

the repository. The CLI backend retains raw decoding because Git has no faithful

formatted query for all commit headers or arbitrary tag objects. ``gpgsig``

remains readable. The small ``Actor.from_string()`` and

``parse_actor_and_date()`` identity helpers remain supported.

* ``parse_date()`` delegates text syntax and timezone interpretation to Git;

aware datetimes retain direct conversion and invalid inputs raise ``ValueError``.

ISO/RFC dates now apply their timezone to the UTC timestamp, correcting the

previous behavior. Dates without a zone use Git's local timezone, and accepted

date syntax follows the installed Git version. Use an explicit timezone for

reproducible results. ``co_authors`` now uses Git's final trailer block rather

than scanning arbitrary message lines; use a valid trailer block after a blank

line.

* Removed deprecated APIs: ``Git.USE_SHELL`` (explicit ``Git.execute(shell=...)``

remains), ``Diff.renamed`` (use ``renamed_file``), ``Commit.trailers`` (use

``trailers_list`` or ``trailers_dict``), ``Actor.name_email_regex`` (use

``Actor.from_string``), ``git.util.Iterable`` (use ``IterableObj``),

``git.compat.is_win/is_posix/is_darwin`` (use ``os.name``/``sys.platform``), and

``git.types.Lit_commit_ish`` (use ``Literal["commit", "tag"]`` or

``GitObjectTypeString``). Top-level typing exports and private module aliases

are removed; import from ``typing`` or the owning module. ``git.util`` now

exposes the actual utility module. Abstract ``Traversable.traverse`` and

``list_traverse`` raise ``NotImplementedError``; use concrete implementations.

* Paths and URLs no longer expand ``$VAR``/``%VAR%`` automatically. Removed

``expand_vars`` switches from ``Repo``, ``Repo.init``, ``expand_path``,

``cygpath`` and ``Git.polish_url``. Expand explicitly with

``os.path.expandvars`` if wanted; initial ``~`` expansion remains.

``HIDE_WINDOWS_KNOWN_ERRORS`` and ``HIDE_WINDOWS_FREEZE_ERRORS`` are removed.

``rmtree`` propagates filesystem errors rather than raising ``SkipTest``.

3.2.1

GitPython is a python library used to interact with git repositories, high-level like git-porcelain, or low-level like git-plumbing.

It provides Python objects for repository data and delegates Git operations to the Git executable. The default backend supports both SHA-1 and SHA-256 object IDs and both files and reftable reference storage. The legacy pure-Python GitDB backend is removed.

The object database implementation is optimized for handling large quantities of objects and large datasets, which is achieved by using low-level structures and data streaming.

* `Python`_ >= 3.8

* `Git`_ 2.52 or newer

* `GitDB`_ - shared data types and utilities

* `typing_extensions`_ >= 3.7.3.4 (if python < 3.10)

.. _Python: https://www.python.org

The Index Object

The git index is the stage containing changes to be written with the next commit or where merges finally have to take place. Use :meth:`IndexFile.iter_entries <git.index.base.IndexFile.iter_entries>` and :meth:`IndexFile.entry <git.index.base.IndexFile.entry>` to query immutable entry records (mode, object ID, path, and stage); use ``add`` and ``remove`` to edit them. Deferred edits retain opaque index-file bytes. Git reads and writes the underlying index; raw stat fields and binary index extensions are not exposed.

Modify the index with ease

.. literalinclude:: ../../test/test_docs.py

Only ``GitCmdObjectDB`` and subclasses can be selected through ``odbt``. The

legacy ``GitDB`` backend is removed. The ``gitdb`` package remains a dependency

for shared types and utilities.

Git Command Debugging and Customization