Docs: correct the "active HEAD propagation needs symref-update" claim · Entire

Docs: correct the "active HEAD propagation needs symref-update" claim

eb10e26·

Earlier docs framed active HEAD propagation as blocked on a future go-git change for the symref-update receive-pack capability. That capability doesn't exist in git's wire protocol — gitprotocol-pack.adoc defines receive-pack commands as create/delete/update only, and receive-pack's command parser rejects anything else. The symref-update that exists in git is in update-ref --stdin, a local CLI for the ref backend.

There is no portable wire-level mechanism for updating a remote symref, which is why git push --mirror doesn't either. Reframe the docs to match: detection is the ceiling for any git-protocol client, and manual reconciliation (provider REST API or git symbolic-ref over SSH) is the supported path, not a v1 placeholder.

Refs #45.

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com

Changes

  1. Practical mitigations, in order of preference:
    • Match the default at init time. git init --bare --initial-branch=<source-default> (or the equivalent on your host) avoids the problem entirely. git-sync probe <source-url>'s sourceHead field tells you what to pass.
    • Set HEAD manually post-sync. On a self-hosted bare repo: git symbolic-ref HEAD refs/heads/<source-default>. On hosted providers (GitHub, GitLab, etc.), use the provider's API or web UI to set the default branch.
    • Set HEAD out-of-band post-sync. On a self-hosted bare repo accessible over SSH: git symbolic-ref HEAD refs/heads/<source-default>. On hosted providers, use the provider's API (GitHub: PATCH /repos/{owner}/{repo} with default_branch; GitLab: PUT /projects/:id with default_branch) or web UI.
    • Compare the fields. A wrapper script that runs git-sync probe ... and compares sourceHead against targetHead will catch mismatches before they bite.

JSON Output

Mdocs/usage.md+8/-6