Document the HEAD propagation limitation and the workarounds · Entire

Document the HEAD propagation limitation and the workarounds

d5bc3f5·

Soph·2mo ago·1 file·+29 added/-0 removed

usage.md gains a "HEAD / Default Branch" section explaining:

where to find the source's HEAD in JSON/human output
why the target's HEAD isn't reconciled (no portable receive-pack symref-update; go-git alpha doesn't ship the capability anyway)
two mitigations: match the default at init time (preferred), or set HEAD manually post-sync via git symbolic-ref or the host's API

The JSON Output section lists the new execution.sourceHead / sourceHead fields.

Refs #45.

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

Sessions

bd2959cd5c8aView transcript

Changes

docs
Musage.md+29

221 unmodified lines

...
260
261
262
263
264
265
266

221 unmodified lines
  <target-url>

HEAD / Default Branch

git-sync surfaces the source's symref HEAD target — the source's default branch — in the result's execution.sourceHead field (JSON) and as a source-head: <ref> line in human output. probe exposes the same field.

$ git-sync sync --json … | jq .execution.sourceHead
"refs/heads/main"

The target's default branch is not automatically reconciled. git's push --mirror doesn't propagate HEAD either; standard receive-pack has no portable mechanism for setting a remote symref's target (only newer git versions support a symref-update capability, and go-git's current alpha doesn't send it). The result: if you git init --bare your target with a default branch that differs from the source's, the mirror's HEAD will dangle even after a successful sync.

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. Compare against git-sync probe <source-url>'s sourceHead to know 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.

Detecting the mismatch automatically is tracked as a follow-up; doing so requires a separate upload-pack round-trip against the target since the receive-pack advertisement we already query doesn't include HEAD.

JSON Output

Add --json to any command to emit machine-readable output instead of the default text format.

refs and hashes are serialized as strings, not raw byte arrays
top-level keys include plans, pushed, skipped, blocked, deleted, warned, dryRun, protocol, and stats, plus relay, relayMode, relayReason, batching, batchCount, plannedBatchCount, and tempRefs
each item in plans includes stable string fields such as branch, sourceRef, targetRef, sourceHash, targetHash, kind, action, and reason
execution.sourceHead (sync/plan/replicate/bootstrap) and sourceHead (probe) carry the source's symref HEAD target when advertised