fix(refs): resolve locally tracked branches through Git

angr 10.0.4.post1's repository report cannot describe a branch configured to
track another local branch. `Head.tracking_branch()` treats Git's special
`branch.<name>.remote=.` value as a remote name and constructs the nonexistent
`refs/remotes/./<branch>` reference. The helper prints a generic tracking error
instead of its intended local-branch message. Released GitPython 3.2.1 exhibits
the same bug; a valid local-upstream fixture reproduces it independently.

For the local-repository selector, ask `git rev-parse --symbolic-full-name
<branch>@{upstream}` to resolve the configured location and return a `Head` for
that result. Keep existing remote-reference behavior for ordinary remote
tracking. Update the annotated return type and documentation for local heads.
This delegates Git configuration and upstream validation to Git rather than
reconstructing their semantics in Python. GixPython does not expose this resolver,
so the operation retains an explicit documented CLI fallback.

Add a Bash fixture and regressions across SHA-1/SHA-256 and files/reftable
storage. All four cases fail before the correction. The full reference suite
and downstream regressions pass 61 tests and 24 subtests on each backend, CLI
first. All five unchanged angr supplemental tests now pass on both backends;
the initial and released baseline failures are retained in the audit evidence.
Ruff lint/format, ShellCheck for the fixture, mypy for `git/refs/head.py` and
`git diff --check` pass with Python 3.12.15, Git 2.53.0 and GixPython 0.2.0.

Author: codex

doc/gix-backend.md

@@ -53,6 +53,14 @@ Object queries continue through `object_data()` and the supported
 `Repository.try_find_header()`/`find_object()` APIs, with the existing large-object
 and diagnostic CLI fallbacks. Storage uses the existing `hash_object` dispatch.
 
+`Head.tracking_branch()` asks Git's `rev-parse --symbolic-full-name` to resolve
+local upstreams configured with `branch.<name>.remote=.`. GixPython does not
+expose the corresponding Git-compatible upstream configuration resolver; this
+path retains CLI. Without it, both released GitPython 3.2.1 and the initial
+adapter return an invalid remote reference, preventing angr 10.0.4.post1 from
+reporting a valid local tracking branch. A native replacement must expose Git's
+local-upstream resolution, including its validation and diagnostics.
+
 `IndexFile` queries immutable entry records; it does not retain a parsed index.
 The compatibility `entries` property projects those queries into a read-only
 snapshot keyed by path and stage, preserving readers in dlt and Renku. It uses

doc/source/changes.rst

@@ -51,6 +51,10 @@ Git executable and safety
 API changes
 -----------
 
+* ``Head.tracking_branch()`` returns a local ``Head`` when Git configures the
+  current repository (``branch.<name>.remote=.``) as the upstream, instead of
+  constructing an invalid ``refs/remotes/./...`` reference. Git resolves the
+  upstream location; remote tracking branches retain their existing behavior.
 * ``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.

git/refs/head.py

@@ -202,16 +202,23 @@ def set_tracking_branch(self, remote_reference: Union["RemoteReference", None])
 
         return self
 
-    def tracking_branch(self) -> Union["RemoteReference", None]:
+    def tracking_branch(self) -> Union["RemoteReference", "Head", None]:
         """
         :return:
-            The remote reference we are tracking, or ``None`` if we are not a tracking
-            branch.
+            The remote reference or local head we are tracking, or ``None`` if we
+            are not a tracking branch.
         """
         from .remote import RemoteReference
 
         reader = self.config_reader()
         if reader.has_option(self.k_config_remote) and reader.has_option(self.k_config_remote_ref):
+            if reader.get_value(self.k_config_remote) == ".":
+                # Git resolves local-upstream configuration; do not construct a
+                # remote reference for the special local-repository selector.
+                path = self.repo.git._call_process_safe(
+                    "rev_parse", "--symbolic-full-name", f"{self.name}@{{upstream}}"
+                )
+                return Head(self.repo, path)
             ref = Head(
                 self.repo,
                 Head.to_full_path(strip_quotes(reader.get_value(self.k_config_remote_ref))),

test/test_downstream_compatibility.py

@@ -10,6 +10,18 @@
 from test.lib.fixtures import fixture_repo
 
 
+@pytest.mark.parametrize("object_format", ["sha1", "sha256"])
+@pytest.mark.parametrize("ref_format", ["files", "reftable"])
+def test_local_tracking_branch_uses_gits_upstream_location(object_format, ref_format):
+    with fixture_repo("downstream-local-upstream.sh", object_format, ref_format) as repo:
+        upstream = repo.head.reference.tracking_branch()
+        assert isinstance(upstream, git.Head)
+        assert upstream.path == repo.git.rev_parse("--symbolic-full-name", "@{upstream}")
+        assert upstream.name == "upstream"
+        assert not upstream.is_remote()
+        assert upstream.commit == repo.head.commit
+
+
 @pytest.mark.parametrize("object_format", ["sha1", "sha256"])
 @pytest.mark.parametrize("ref_format", ["files", "reftable"])
 def test_legacy_gitdb_selector_uses_the_managed_object_backend(object_format, ref_format):

tests/fixtures/downstream-local-upstream.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -eu
+git init -q --object-format="$1" --ref-format="$2" repo
+cd repo
+printf tracked > tracked
+git add tracked
+git commit -qm initial
+git branch upstream
+branch=$(git symbolic-ref --short HEAD)
+git config "branch.$branch.remote" .
+git config "branch.$branch.merge" refs/heads/upstream