perf(gix): resolve revision path metadata without cat-file

`Repo.rev_parse` resolved an object natively but still launched `cat-file` to
find its tree/index mode, then probed revision prefixes to locate its path.
Use `Repository.rev_parse` to obtain the ID and path/mode together. Preserve
path normalization and the absent metadata for root-tree specifications.

Share the existing revision-grammar guard. Index revisions also check the
existing custom/sparse-index capability guard before native parsing, including
OID lookup on the fallback path, so an alternate index is never silently
replaced by the repository's default index.

The fixed `HEAD:file` probe drops from 1 CLI launch to 0. Regression assertions
compare root/directory/file, executable, symlink and index-stage results with
Git in both object formats, prohibit native CLI launches, and exercise an
alternate index. The earlier full inventory had 170 mode-query launches.

Validation: revision, backend and positional-argument tests passed with Gix
first (101 tests, 15.60s), then CLI (54 tests, one skipped, 12.65s). Ruff
lint/format, mypy, basedpyright and `git diff --check` passed.

Author: codex

doc/gix-backend.md

@@ -134,6 +134,7 @@ The historical full-suite counts above predate this correction. A constant
 | `Repo` opening/discovery | Native storage, worktree, object format and empty-tree metadata | Repository-format validation, unsupported layouts/environment and native validation gaps; GIX-1/14/19 |
 | Standalone discovery helpers | Native storage directories and gitfiles reopened at their canonical native Git directory | Rejected candidates and the same layout/environment guards as `Repo` opening; GIX-14 |
 | `Repo.rev_parse`, `rev_parse` metadata queries | Revision lookup, common directory, object format, bare flag, worktree root, fixed `modules`/`COMMIT_EDITMSG` locations | Repository-format validation, other metadata paths, symlinked metadata leaves, message searches and describe forms; GIX-1/14/17/22 |
+| Revision path/mode metadata | Native revision specification, including tree paths and index stages | Custom/sparse indexes, unsupported revision grammar or path normalization |
 | Tree enumeration, `ls_tree` | Native tree entries with modes, names, and object IDs | Other command options |
 | Reference object reads | One exact native lookup for direct, symbolic and absent references | Partial names and native decoding errors |
 | Reference-name validation | Native full-name validation without opening a repository | Standalone names outside the native grammar; GIX-20 |

git/_backend.py

@@ -194,12 +194,18 @@ def _canonical_repository(repo: Any) -> Any:
     return gix.open_opts(canonical, repo.open_options()) if path != canonical else repo
 
 
-def _oid(repo: Any, ref: Any) -> Any:
+def _check_revision_grammar(ref: str) -> None:
+    if ref.startswith(":/") or "^{/" in ref or "-dirty" in ref or re.search(r"-\d+-g[0-9a-fA-F]+", ref):
+        raise _Unsupported("revision grammar differences (GIX-17)")
+
+
+def _oid(repo: Any, ref: Any, env: Optional[Dict[str, Any]] = None) -> Any:
     ref = safe_decode(ref) if isinstance(ref, bytes) else str(ref)
     if re.fullmatch(r"[a-fA-F0-9]{40}|[a-fA-F0-9]{64}", ref):
         return gix.ObjectId(ref)
-    if ref.startswith(":/") or "^{/" in ref or "-dirty" in ref or re.search(r"-\d+-g[0-9a-fA-F]+", ref):
-        raise _Unsupported("revision grammar differences (GIX-17)")
+    _check_revision_grammar(ref)
+    if ref.startswith(":"):
+        _index(repo, {"env": env or {}})
     if not hasattr(repo, "rev_parse_single"):
         raise _Unsupported("revision feature disabled")
     return repo.rev_parse_single(ref)
@@ -212,7 +218,7 @@ def object_data(command: Any, ref: bytes, *, stream: bool = False) -> Any:
     method = "stream_object_data" if stream else "get_object_header"
     try:
         repo = _repository(command, {})
-        oid = _oid(repo, ref)
+        oid = _oid(repo, ref, command.environment())
         header = repo.try_find_header(oid)
         if header is None:
             raise ValueError("SHA %s could not be resolved" % oid)
@@ -231,6 +237,29 @@ def object_data(command: Any, ref: bytes, *, stream: bool = False) -> Any:
     return result
 
 
+def revision_info(command: Any, ref: str) -> Any:
+    """Resolve an object and its tree/index path metadata in one native parse."""
+    if gix is None:
+        return NotImplemented
+    try:
+        _check_revision_grammar(ref)
+        repo = _repository(command, {})
+        if ref.startswith(":"):
+            _index(repo, {"env": command.environment()})
+        spec = repo.rev_parse(ref)
+        oid = spec.single()
+        if oid is None:
+            raise _Unsupported("multiple revisions")
+        metadata = spec.path_and_mode()
+    except _Unsupported as exc:
+        return _fallback("Repo.rev_parse", str(exc))
+    except gix.Error as exc:
+        _logger.debug("native revision metadata: %s", exc)
+        return _fallback("Repo.rev_parse", "native read diagnostics")
+    record("Repo.rev_parse", "native")
+    return str(oid), metadata
+
+
 def _rev_parse(repo: Any, args: List[str], kwargs: Dict[str, Any]) -> bytes:
     if args[:2] == ["--path-format=absolute", "--git-path"]:
         from git.util import to_native_path_linux
@@ -259,7 +288,7 @@ def _rev_parse(repo: Any, args: List[str], kwargs: Dict[str, Any]) -> bytes:
         raise _Unsupported("discovery or revision options")
     if args[:-2] not in (["--verify"], ["--verify", "--quiet"]):
         raise _Unsupported("revision options")
-    return str(_oid(repo, args[-1])).encode("ascii") + b"\n"
+    return str(_oid(repo, args[-1], kwargs.get("env"))).encode("ascii") + b"\n"
 
 
 def _ls_tree(repo: Any, args: List[str], kwargs: Dict[str, Any]) -> bytes:

git/repo/fun.py

@@ -129,8 +129,13 @@ def rev_parse(repo: "Repo", rev: str) -> AnyGitObject:
     revisions and embedded command delimiters are rejected before invoking Git.
     """
     rev = Git._check_operand(rev, "revision")
+    native = _backend.revision_info(repo.git, rev) if ":" in rev else NotImplemented
     try:
-        oid = repo.git._call_process_safe("rev_parse", "--verify", "--quiet", "--end-of-options", rev)
+        oid = (
+            native[0]
+            if native is not NotImplemented
+            else repo.git._call_process_safe("rev_parse", "--verify", "--quiet", "--end-of-options", rev)
+        )
     except GitCommandError as exc:
         if exc.status != 1 and "Invalid regular expression" not in exc.stderr:
             raise
@@ -139,6 +144,12 @@ def rev_parse(repo: "Repo", rev: str) -> AnyGitObject:
         raise BadName(rev)
     obj = Object.new_from_sha(repo, hex_to_bin(oid))
     if isinstance(obj, IndexObject) and ":" in rev:
+        if native is not NotImplemented:
+            if native[1] is not None:
+                path_bytes, obj.mode = native[1]
+                path = path_bytes.decode(defenc, "surrogateescape")
+                obj.path = posixpath.normpath(path) if path else ""
+            return obj
         # Git resolves the mode, including index stages and executable/symlink
         # entries. No object storage or revision grammar is decoded in Python.
         with tempfile.TemporaryFile() as stream:

test/test_gix_backend.py

@@ -11,6 +11,7 @@
 
 from git import Actor, Commit, Git, Reference, Repo, SymbolicReference, _backend
 from git.exc import GitCommandError, InvalidGitRepositoryError
+from git.index.typ import BaseIndexEntry
 from git.repo.fun import find_submodule_git_dir, find_worktree_git_dir, is_git_dir
 from gitdb import IStream
 
@@ -306,6 +307,35 @@ def test_native_tree_and_commit_bytes_match_cli(repo):
         assert commit.replace(message="a changed message").hexsha == native.hexsha
 
 
+def test_native_revision_path_and_mode_match_cli(repo, tmp_path):
+    blob = repo.odb.store(IStream("blob", 4, BytesIO(b"data")))
+    index = repo.index
+    index.add(
+        [
+            BaseIndexEntry((mode, blob.binsha, 0, path))
+            for mode, path in ((0o100644, "dir/file"), (0o100755, "executable"), (0o120000, "link"))
+        ]
+    )
+    index.commit("paths", skip_hooks=True)
+    revisions = ["HEAD:", "HEAD:dir/", "HEAD:dir/file", "HEAD:executable", "HEAD:link", ":executable", ":0:link"]
+
+    def resolve(revision):
+        obj = repo.rev_parse(revision)
+        return obj.hexsha, getattr(obj, "path", None), getattr(obj, "mode", None)
+
+    with patch.object(_backend, "gix", None):
+        expected = [resolve(rev) for rev in revisions]
+    count = _backend.statistics().get(("Git.execute", "CLI process"), 0)
+    with patch.object(Git, "execute", side_effect=AssertionError("unexpected revision metadata CLI call")):
+        assert [resolve(rev) for rev in revisions] == expected
+    assert _backend.statistics().get(("Git.execute", "CLI process"), 0) == count
+
+    with repo.git.custom_environment(GIT_INDEX_FILE=str(tmp_path / "alternate-index")):
+        repo.git.read_tree("--empty")
+        repo.git.update_index("--add", "--cacheinfo", "100755", blob.binsha.hex(), "alternate")
+        assert resolve(":alternate") == (blob.binsha.hex(), "alternate", 0o100755)
+
+
 def test_native_reference_name_validation_without_repository():
     SymbolicReference._check_ref_name_native.cache_clear()
     count = _backend.statistics().get(("Git.execute", "CLI process"), 0)