fix(gix): preserve bytes in native submodule configuration values

The dedicated Gix submodule parser returns path, URL and branch values as
bytes. Strict decoding forced valid non-UTF-8 values into the CLI fallback.
Decode those values with the shared lossless helper while preserving existing
checks for duplicate sections, implicit values and raw branch spelling.

Record the remaining native API gap: non-UTF-8 subsection names require CLI
because generic config keys require text, and the byte-capable branch getter
interprets empty/implicit values instead of exposing their raw spelling.
No Python configuration semantics or fabricated native success are introduced.

The native regression fails before the fix and passes with Git.execute blocked.
Scripted tests also verify byte subsection names through fallback and cached
field reads against Git 2.54.0. Connected tests pass: nine Gix cases, two CLI
cases and seven native-only skips. Ruff, mypy and whitespace checks pass.

Author: codex

doc/gix-backend.md

@@ -369,7 +369,7 @@ and predate the current fallback; they do not establish native coverage.
 | Managed `symbolic_ref` | Nonrecursive target lookup | Mutation, command-level missing-reference diagnostics |
 | Reference enumeration, `for_each_ref` | Sorted reference names and literal prefixes, preserving symbolic aliases | Dangling symbolic refs, root refs, glob patterns, other formats/options; GIX-25 |
 | Managed `config --get KEY` | Merged repository config snapshot | Files/streams, enumeration, mutation; GIX-12 |
-| Submodule enumeration and cached fields | Dedicated native `.gitmodules` parser over the existing worktree/blob source, with raw path/URL/branch values | Other/duplicate sections, ambiguous brackets, missing/implicit fields and parser errors; GIX-12 |
+| Submodule enumeration and cached fields | Dedicated native `.gitmodules` parser over the existing worktree/blob source, with raw path/URL/branch values | Non-UTF-8 subsection names, other/duplicate sections, ambiguous brackets, missing/implicit fields and parser errors; GIX-12 |
 | Commit hooks | No bound native lookup/execution API | All hooks, including absent hooks; GIX-23 |
 | Worktree inventory, `worktree list` | Main and linked worktree metadata, including bare main repositories and locks | Prunable entries; GIX-14 |
 | `Repo.merge_base`, `Repo.is_ancestor` | Native graph queries for two revisions | Octopus/fork-point and other options |
@@ -1088,6 +1088,16 @@ runtime validation and timings remain attributed to their measured snapshots.
 
 ### Remaining configuration reads (GIX-12)
 
+Native `.gitmodules` reads preserve arbitrary bytes in paths, URLs and branch
+values through `surrogateescape`. Non-UTF-8 subsection names use the CLI fallback:
+GixPython 0.3.0's `ConfigFile.string()` and `.boolean()` require text keys.
+Although `ModulesFile.path()` and `.url()` accept byte names, `.branch()`
+interprets the value: an empty value becomes `HEAD`, and missing and implicit
+values both become `None`. A byte-key raw configuration accessor is needed to
+retain GitPython's configuration contract natively. The scripted
+`submodule-bytes.sh` regressions cover values, names and cached-field rereads;
+the native value test prohibits CLI execution.
+
 The October 7 inventory identified 951 remote-enumeration reads, 674 actor
 lookups, 262 remote-property reads, 202 tracking-branch lookups and 111 fetch
 refspec checks. These are historical call-site counts, not additive savings.

git/_backend.py

@@ -425,7 +425,7 @@ def submodule_config(source: Any) -> Any:
                     if option != "branch" or config.boolean(key) is not None:
                         raise _Unsupported("missing or implicit submodule fields")
                 else:
-                    values[option] = value.decode(defenc)
+                    values[option] = safe_decode(value)
             result[name] = values
     except _Unsupported as exc:
         return _fallback("Submodule.config", str(exc))

test/test_submodule.py

@@ -2,6 +2,7 @@
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
 import gc
+from io import BytesIO
 import os
 import os.path as osp
 from pathlib import Path
@@ -32,6 +33,34 @@
 from test.lib.fixtures import fixture_repo, read_only_fixture, writable_fixture
 
 
+@pytest.mark.parametrize("scenario, name", [("ascii-name", "module"), ("byte-name", "module-\udcff")])
+def test_submodule_configuration_preserves_non_utf8_bytes(scenario, name):
+    with fixture_repo("submodule-bytes.sh", scenario) as repo:
+        data = repo.git.config("list", "--null", "--file", ".gitmodules", stdout_as_string=False)
+        assert b".path\npath-\xfe\0" in data
+        assert b".url\nurl-\xfd\0" in data
+        assert b".branch\nrefs/heads/branch-\xfc\0" in data
+        submodule = repo.submodules[0]
+        assert submodule.name == name
+        assert submodule.path == "path-\udcfe"
+        assert submodule.url == "url-\udcfd"
+        assert submodule.branch_path == "refs/heads/branch-\udcfc"
+        submodule._clear_cache()
+        assert (submodule.path, submodule.url, submodule.branch_path) == (
+            "path-\udcfe",
+            "url-\udcfd",
+            "refs/heads/branch-\udcfc",
+        )
+
+
+@pytest.mark.skipif(git._backend.name != "gix", reason="requires the native backend")
+def test_native_submodule_configuration_preserves_non_utf8_values():
+    path = read_only_fixture("submodule-bytes.sh", "ascii-name") / "repo" / ".gitmodules"
+    with mock.patch.object(Git, "execute", side_effect=AssertionError("Git must not run")):
+        native = git._backend.submodule_config(BytesIO(path.read_bytes()))
+    assert native == {"module": {"path": "path-\udcfe", "url": "url-\udcfd", "branch": "refs/heads/branch-\udcfc"}}
+
+
 @pytest.mark.parametrize("state", ["unborn", "untracked", "detached"])
 @pytest.mark.parametrize("remote", [None, ".", "origin"], ids=["working-tree", "local-origin", "origin"])
 @patch_git_config("protocol.file.allow", "always")

tests/fixtures/submodule-bytes.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -eu
+git init -q repo
+cd repo
+git -c user.name=fixture -c user.email=fixture@example.invalid commit --allow-empty -qm initial
+case "$1" in
+    ascii-name) name=module ;;
+    byte-name) name=$'module-\377' ;;
+    *) exit 1 ;;
+esac
+printf '[submodule "%s"]\npath = path-\376\nurl = url-\375\nbranch = refs/heads/branch-\374\n' "$name" > .gitmodules
+modules=$(git hash-object -w .gitmodules)
+commit=$(git rev-parse HEAD)
+tree=$(printf '100644 blob %s\t.gitmodules\000160000 commit %s\tpath-\376\000' "$modules" "$commit" | git mktree -z)
+commit=$(printf 'Add submodule\n' | git -c user.name=fixture -c user.email=fixture@example.invalid commit-tree "$tree" -p "$commit")
+git update-ref HEAD "$commit"