Suggest reftable migration when HEAD can't be read

[Jorge-Polanco-Roque]

Fixes #1743.

Problem

On a repository that uses git's reftable backend, onefetch crashes with an opaque error:

The reference at "HEAD" could not be instantiated
  → The path "refs/heads/.invalid" ... is invalid
  → Reference name cannot start with a dot

Root cause

Git's reftable backend intentionally points HEAD at the sentinel refs/heads/.invalid so older clients fail early. gitoxide cannot read the reftable format yet, so every HEAD resolution fails.

Approach

Detect that specific case and turn the crash into an actionable message suggesting git refs migrate --ref-format=files. Detection matches the git-hardcoded sentinel refs/heads/.invalid (not a gix message), so it stays stable across gitoxide versions. Applied via .map_err(...) at the traversal call — the earliest, user-facing HEAD failure.

Testing

• reftable_sentinel_error_gets_migration_hint and unrelated_error_is_left_untouched (the latter guards against over-matching). Verified the hint test fails without the fix.
• cargo fmt --check clean · cargo clippy --all-targets zero warnings · cargo test --lib 102 passed.

Note: this is the graceful-error fix (as suggested in the thread); reading reftable itself belongs upstream in gitoxide.

[spenserblack]

Duplicate of #1755, but the solution here looks a bit cleaner, so I'll leave this open.

Is there any chance that, rather than pattern matching on a string generated by to_string(), you could check the actual error type that the gix utilities return in traverse_commit_graph? Let me know if you feel that this would be overly complex, and I'll approve.

[Jorge-Polanco-Roque]

Good call — switched to checking the typed error instead of the message string. reftable_head_hint now downcasts the error chain to gix::refs::file::loose::reference::decode::Error and matches the RefnameValidation variant (an invalid symbolic-ref target), which is exactly what gitoxide raises when it resolves HEAD → refs/heads/.invalid on a reftable repo — independent of the message wording.

The unit test builds the real typed error via gix::validate::reference::name(...), and I re-verified end-to-end on a git init --ref-format=reftable repo. Thanks for keeping this open!

[spenserblack]

I suspect that this PR violates the AI policy since the replies have been very LLM-like, but overall the code is still decent I suppose.

I'm curious if the user is copying and pasting comments and LLM responses, or if the account is a fully autonomous AI agent. If you are a fully autonomous AI agent, you must disclose.