feat(gix): update supported reference targets natively

Use native reference edits for compatible unconstrained target changes and
non-dereferencing deletions. Keep strict create/CAS, active-branch HEAD logs,
symbolic detachment and unchanged-target cases on Git because the native
semantics differ (`GIX-9`/`GIX-10`).

Set each edit's message through `gix.LogChange`, including its force-log flag.
The API already provides explicit per-edit messages, but no Git-compatible
cleanup policy: a direct native write preserves leading/trailing whitespace,
tabs, and repeated spaces where Git stores `keep spaces`. Add a regression
that writes through `edit_references_as()` and reads both native and Git logs.

Pass canonical messages unchanged. Messages needing cleanup use Git before
any native mutation; Python must not repair missing native cleanup. Upstream
could provide normalization on `LogChange` or a policy applied to all ref
edits. `core.logAllRefUpdates` controls log creation, not message cleanup.
A supported update avoids one CLI call; a cleanup case retains one. This
follow-up clarifies the limitation and leaves those counts unchanged.
Per-command committer overrides also retain their `GIX-21` fallback.

Validation: reflog/history/positional selection passed with Gix first
(45 passed in 7.87s), then CLI (33 passed, 1 skipped in 7.48s).
Ruff lint/format and `git diff --check` passed. The replay resolution preserves
both `Reference` and `InvalidGitRepositoryError` imports and existing tests.

Author: codex

git/_backend.py

@@ -652,6 +652,64 @@ def _var(repo: Any, args: List[str], kwargs: Dict[str, Any]) -> bytes:
     return signature.name + b" <" + signature.email + b"> " + _date(signature) + b"\n"
 
 
+def _update_ref(repo: Any, args: List[str], kwargs: Dict[str, Any]) -> bytes:
+    if "--" not in args:
+        raise _Unsupported("reference transactions (GIX-9)")
+    split = args.index("--")
+    options, operands = args[:split], args[split + 1 :]
+    deref, force_log, delete, message = True, False, False, ""
+    cursor = iter(options)
+    for option in cursor:
+        if option == "--no-deref":
+            deref = False
+        elif option == "--create-reflog":
+            force_log = True
+        elif option == "-d":
+            delete = True
+        elif option == "-m":
+            message = next(cursor, "")
+        else:
+            raise _Unsupported("reference options")
+    # LogChange sets each edit's message, but its writer does not normalize it.
+    if re.search(r"[\t\r\n\v\f]|^ | $| {2}", message):
+        raise _Unsupported("reflog message cleanup (GIX-10)")
+    if delete:
+        if len(operands) != 1 or deref:
+            raise _Unsupported("reference deletion options")
+        edit = gix.RefEdit.delete(operands[0], gix.PreviousValue.Any).with_deref(False)
+        _write("update_ref", lambda: repo.edit_references_as([edit]))
+        return b""
+    if len(operands) != 2:
+        raise _Unsupported("strict reference creation / compare-and-swap (GIX-9)")
+    name, target = operands
+    oid = _oid(repo, target)
+    kind = repo.find_header(oid).kind()
+    if (name == "HEAD" or name.startswith("refs/heads/")) and kind != "commit":
+        raise _Unsupported("branch target validation")
+    reference = repo.try_find_reference(name)
+    if reference is not None:
+        if deref and name != "HEAD" and reference.target().try_name() is not None:
+            raise _Unsupported("symbolic reference update (GIX-10)")
+        if not deref and reference.target().try_name() is not None:
+            raise _Unsupported("detaching symbolic ref reflog (GIX-10)")
+        if reference.follow_to_object() == oid:
+            raise _Unsupported("unchanged reference reflog (GIX-10)")
+    head = repo.try_find_reference("HEAD")
+    for _ in range(5):
+        if head is None or head.target().try_name() is None:
+            break
+        if head.target().try_name() == os.fsencode(name):
+            raise _Unsupported("active branch HEAD reflog (GIX-10)")
+        head = head.follow()
+    log = gix.LogChange()
+    log.force_create_reflog = force_log
+    log.message = message
+    edit = gix.RefEdit.update_with_log(name, gix.Target.Object(oid), gix.PreviousValue.Any, log).with_deref(deref)
+    signature = _committer(repo, kwargs.get("env", {}))
+    _write("update_ref", lambda: repo.edit_references_as([edit], signature))
+    return b""
+
+
 def _commit_tree(repo: Any, args: List[str], kwargs: Dict[str, Any]) -> bytes:
     if len(args) < 2 or args[0] != "--no-gpg-sign" or args[2::2] != ["-p"] * len(args[2::2]):
         raise _Unsupported("commit options")
@@ -692,6 +750,7 @@ def _commit_tree(repo: Any, args: List[str], kwargs: Dict[str, Any]) -> bytes:
     "commit_tree": _commit_tree,
     "reflog": _reflog,
     "var": _var,
+    "update_ref": _update_ref,
     "config": _config,
     "worktree": _worktree,
 }

test/test_gix_backend.py

@@ -7,7 +7,7 @@
 
 import pytest
 
-from git import Actor, Commit, Git, Repo, _backend
+from git import Actor, Commit, Git, Reference, Repo, _backend
 from git.exc import GitCommandError, InvalidGitRepositoryError
 from gitdb import IStream
 
@@ -201,6 +201,16 @@ def test_commit_identity_cleanup_matches_git(repo):
         assert commit == Commit.create_from_tree(repo, tree, "message", **kwargs)
 
 
+def test_symbolic_alias_cannot_point_a_branch_at_a_blob(repo):
+    commit = repo.index.commit("initial", skip_hooks=True)
+    blob = repo.odb.store(IStream("blob", 1, BytesIO(b"x")))
+    repo.git.symbolic_ref("refs/aliases/main", "refs/heads/main")
+    alias = Reference(repo, "refs/aliases/main")
+    with pytest.raises(GitCommandError):
+        alias.set_object(blob.hexsha.decode())
+    assert repo.head.commit == commit
+
+
 def test_partial_native_stream_does_not_corrupt_next_read(repo):
     one = repo.odb.store(IStream("blob", 6, BytesIO(b"abcdef"))).binsha
     two = repo.odb.store(IStream("blob", 3, BytesIO(b"xyz"))).binsha
@@ -209,3 +219,65 @@ def test_partial_native_stream_does_not_corrupt_next_read(repo):
         assert stream.read(1) == b"a"
         assert repo.odb.stream(two).read() == b"xyz"
         assert stream.read() == b"bcdef"
+
+
+def test_native_history_and_references(repo, monkeypatch):
+    monkeypatch.setenv("GIT_COMMITTER_NAME", "Reflog Actor")
+    monkeypatch.setenv("GIT_COMMITTER_EMAIL", "actor@example.invalid")
+    monkeypatch.setenv("GIT_COMMITTER_DATE", "1100000000 -0430")
+    first = repo.index.commit("first", skip_hooks=True)
+    second = first.replace(message="second", parents=[first])
+    branch = repo.create_head("other", first)
+    repo.heads  # Warm the existing, Git-validated reference-name cache.
+    with patch.object(Git, "execute", side_effect=AssertionError("unexpected CLI call")):
+        repo.head.set_object(second, "through HEAD")
+        branch.set_object(second, "inactive branch")
+        assert first.count() == 1
+        assert second.count() == 2
+        assert list(repo.iter_commits(first_parent=True, skip=1)) == [first]
+        assert list(repo.iter_commits(max_count=1)) == [second]
+        assert repo.head.log_entry(-1).message == "through HEAD"
+        assert branch.log_entry(-1).newhexsha == second.hexsha
+        native_log = repo.head.log()
+        native_refs = [ref.path for ref in repo.heads]
+    with patch.object(_backend, "gix", None):
+        assert native_log == repo.head.log()
+        assert native_refs == [ref.path for ref in repo.heads]
+
+
+def test_native_refedit_message_is_verbatim(repo):
+    commit = repo.index.commit("initial", skip_hooks=True)
+    native = gix.open(repo.git_dir)
+    log = gix.LogChange()
+    log.force_create_reflog = True
+    log.message = "  keep\t  spaces  "
+    edit = gix.RefEdit.update_with_log(
+        "refs/heads/native", gix.Target.Object(gix.ObjectId(commit.hexsha)), gix.PreviousValue.Any, log
+    )
+    native.edit_references_as([edit], gix.Signature("Example", "example@example.invalid", 1100000000, 0))
+    with native.find_reference("refs/heads/native").log_iter().rev() as lines:
+        assert next(lines).message == b"  keep\t  spaces  "
+    with patch.object(_backend, "gix", None):
+        repo.git._call_process_safe(
+            "update_ref", "--create-reflog", "-m", "  keep\t  spaces  ", "--", "refs/heads/control", commit.hexsha
+        )
+    with native.find_reference("refs/heads/control").log_iter().rev() as lines:
+        assert next(lines).message == b"keep spaces"
+
+
+@pytest.mark.parametrize("message", ["through\tHEAD", " leading  spaces ", "line\nnext", "mixed\r\v\fspaces"])
+def test_reflog_message_cleanup_uses_cli_before_mutation(repo, message, monkeypatch):
+    monkeypatch.setenv("GIT_COMMITTER_DATE", "1100000000 -0430")
+    first = repo.index.commit("first", skip_hooks=True)
+    second = first.replace(message="second", parents=[first])
+    branch = repo.create_head("other", first)
+    control = repo.create_head("control", first)
+    args = ("--create-reflog", "-m", message, "--")
+    with patch.object(_backend, "_write", side_effect=AssertionError("must fall back before mutation")):
+        with patch.object(Git, "execute", autospec=True, side_effect=Git.execute) as cli:
+            repo.git._call_process_safe("update_ref", *args, branch.path, second.hexsha)
+            assert cli.call_count == 1
+    native_log = branch.log_entry(-1)
+    with patch.object(_backend, "gix", None):
+        repo.git._call_process_safe("update_ref", *args, control.path, second.hexsha)
+        assert native_log == control.log_entry(-1)

test/test_positional_args.py

@@ -4,7 +4,7 @@
 
 import pytest
 
-from git import Actor, Git, GitCommandError, Head, Remote, RemoteReference, Repo, TagReference
+from git import Actor, Git, GitCommandError, Head, Remote, RemoteReference, Repo, TagReference, _backend
 from git.exc import UnsafeOptionError
 
 
@@ -95,7 +95,10 @@ def test_remote_ref_delete_preserves_operand(tmp_path):
     commit = repo.index.commit("initial")
     ref = RemoteReference(repo, "refs/remotes/--force")
     repo.git.update_ref(ref.path, commit.hexsha)
-    with mock.patch.object(Git, "execute", autospec=True, side_effect=Git.execute) as run:
+    # Exercise the CLI fallback's option boundary even with GixPython installed.
+    with mock.patch.object(_backend, "dispatch", return_value=NotImplemented), mock.patch.object(
+        Git, "execute", autospec=True, side_effect=Git.execute
+    ) as run:
         RemoteReference.delete(repo, ref)
     argv = run.call_args.args[1]
     assert argv[argv.index("update-ref") :] == ["update-ref", "--no-deref", "-d", "--", ref.path]