refactor!: delegate index state and metadata decoding to Git and Gix

Python previously retained mutable index dictionaries and reconstructed index
files from those entries. That duplicated Git semantics and allowed validation
and publication to diverge. Keep deferred and virtual indexes as opaque bytes;
materialize a private file before Git edits it, verify requested entries survived,
and publish through the existing atomic lock. Replace `IndexFile.entries` with
`iter_entries()` and `entry()` and migrate submodule, tutorial and test callers.

Preserve deferred add/remove and conflict resolution, alternate publication,
index versions and flags, split snapshots, checkout/diff visibility and hook
edits. Failed ordinary edits retain pending and published state. Reject NULs
before encoding stdin records. Keep source containment checks because Python
reads those paths before Git validates the recorded destination.

Use GixPython's structured commit/tag decoders, including signature headers and
encoding, instead of parsing native object bytes. Retain raw CLI commit/tag
metadata decoding where formatted Git output cannot preserve those fields.
Delegate textual date syntax and trailer discovery to Git. Record Gix's unsafe
index insertion, missing date parser and missing strict tag validation as
`GIX-26` through `GIX-28`; private index edits and tag storage use CLI fallbacks.
A native byte round trip alone does not prove Git-compatible validation.

Remove the deprecated `GitDB` selection, API aliases, global shell switch,
automatic environment expansion and Windows error-hiding switches. Keep explicit
shell selection and tilde expansion. Document replacements and changed timezone
and trailer behavior in `doc/source/changes.rst`.

Delete obsolete parser/deprecation tests, repeated rejection matrices and
historical timing-only tests. Retain happy paths, Python glue/security failures,
atomicity and demonstrated compatibility regressions. The maintained benchmark
continues to check parity and CLI process budgets.

Validation on macOS with Git 2.54.0 and GixPython 0.1.0:

- Final retained Gix suite: 1,767 passed, 51 skipped, one expected failure,
  and 44 subtests passed. CLI suite: 1,672 passed, 52 skipped, one expected
  failure, and 44 subtests passed. The new tag rejection test passed separately
  on CLI after that suite collected; final framing/fixture checks passed on
  both backends (17 tests each).
- All five cached downstream profiles passed on both backends: Bandit,
  DataHub, LangChain, MLflow and SWE-bench.
- All 14 benchmark result digests matched and existing Gix CLI ceilings passed.
  Fast timings ran alongside validation and do not establish a speed change.
- `pre-commit`, `ruff`, `mypy`, `basedpyright`, the warnings-as-errors Sphinx
  build, and `git diff --check` passed.

Windows/Cygwin and the minimum Git 2.52 were not exercised for this migration.
Removed APIs and corrected date/trailer behavior require caller migration.

Author: codex

.basedpyright/baseline.json

@@ -228,24 +228,6 @@
         }
       }
     ],
-    "./git/remote.py": [
-      {
-        "code": "reportAttributeAccessIssue",
-        "range": {
-          "startColumn": 26,
-          "endColumn": 38,
-          "lineCount": 1
-        }
-      },
-      {
-        "code": "reportAttributeAccessIssue",
-        "range": {
-          "startColumn": 26,
-          "endColumn": 38,
-          "lineCount": 1
-        }
-      }
-    ],
     "./git/repo/base.py": [
       {
         "code": "reportTypedDictNotRequiredAccess",
@@ -311,16 +293,6 @@
           "lineCount": 1
         }
       }
-    ],
-    "./test/deprecation/test_basic.py": [
-      {
-        "code": "reportUnusedExpression",
-        "range": {
-          "startColumn": 12,
-          "endColumn": 62,
-          "lineCount": 1
-        }
-      }
     ]
   }
 }

doc/gix-backend.md

@@ -42,6 +42,36 @@ provide general Git-path resolution. A `native` counter must represent a
 Gix-backed operation, and backend timings include its Python glue and any CLI
 fallbacks.
 
+## Index and object metadata lifecycle
+
+`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.
+
 ## Install and test without package indexes
 
 The prepared environments in this checkout are `.venv` (CLI) and `.tox/gix`
@@ -186,8 +216,8 @@ repository-format validation gap.
 | `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 |
-| `IndexFile.write` and index persistence | Edit a private native index, publish through the existing lock | Custom, sparse, split, non-v2, unmerged, overlapping, or null-ID entries; GIX-3/4/13 |
-| ODB `store`, managed `hash_object` | Native object hashing/writing with byte-fidelity preflight | Large/nonseekable input and changed serialization; GIX-2/5 |
+| 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 |
@@ -738,6 +768,10 @@ identify the historical fixture where needed.
 | 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

doc/source/changes.rst

@@ -51,8 +51,10 @@ API changes
 * ``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.
-  The deprecated ``GitDB`` remains explicitly selectable with its existing
-  warning and limitations; ``gitdb`` remains a dependency for shared types.
+  ``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
@@ -99,6 +101,52 @@ API changes
   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
 =====
 

doc/source/intro.rst

@@ -6,7 +6,7 @@ Overview / Install
 
 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 remains available but is deprecated.
+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.
 
@@ -15,7 +15,7 @@ Requirements
 
 * `Python`_ >= 3.8
 * `Git`_ 2.52 or newer
-* `GitDB`_ - shared data types and the deprecated legacy object database
+* `GitDB`_ - shared data types and utilities
 * `typing_extensions`_ >= 3.7.3.4 (if python < 3.10)
 
 .. _Python: https://www.python.org

doc/source/tutorial.rst

@@ -341,7 +341,7 @@ As trees allow direct access to their intermediate child entries only, use the t
 
 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. You may access and manipulate semantic entries (mode, object ID, path, and stage) using the :class:`IndexFile <git.index.base.IndexFile>` object. Git reads and writes the underlying index; raw stat fields and binary index extensions are not exposed.
+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
@@ -522,20 +522,9 @@ resolves abbreviated object IDs through persistent ``git cat-file`` processes::
     # Equivalent explicit selection:
     repo = Repo("path/to/repo", odbt=GitCmdObjectDB)
 
-GitDB
-=====
-.. warning::
-   The pure-Python ``GitDB`` backend is deprecated due to security and performance
-   issues. Its object parsers can exhaust resources or return incorrect object
-   data when processing untrusted repositories. Do not use it for untrusted data.
-
-Selecting ``odbt=GitDB`` (including a subclass) emits a ``DeprecationWarning``.
-To migrate, remove ``odbt=GitDB`` or replace it with ``odbt=GitCmdObjectDB`` when
-opening, initializing, or cloning a repository. The deprecated backend remains
-available for compatibility; deprecation does not fix its parsing issues.
-
-The ``gitdb`` package remains a dependency because GitPython still uses its shared
-types and utilities.
+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
 ***************************************