Docs: HEAD / Default Branch

c25015d→main·

Adds a "HEAD / Default Branch" section to usage.md covering:

• where the source HEAD shows up (JSON and human output)
• bootstrap's first-pushed-wins ordering (the new behavior) and which hosts benefit from it (GitHub, GitLab on fresh repos)
• the wire-protocol limit ("no command for updating a remote symref") and the manual workarounds for hosts that don't infer from first push:
  • match the default at init time, or set HEAD post-sync via the host API or git symbolic-ref

JSON Output section adds sourceHead to the documented keys.

Refs #45.

Changes

1

• docs

• Musage.md+26

HEAD / Default Branch

git-sync surfaces the source's symref HEAD target — the source's default branch — in result output:

• JSON: execution.sourceHead (sync / plan / replicate / bootstrap); sourceHead (probe).
• Human: a source-head: <ref> line.

$ git-sync probe --json <source-url> | jq .sourceHead
"refs/heads/main"

Bootstrap pushes the source HEAD's branch first. On hosts that pick the default branch from the first push to a fresh repo (GitHub, GitLab, others), this makes the mirror's default branch match the source without any manual step. No flag needed — the ordering is always applied.

git's wire protocol has no command for updating a remote symref, so for hosts that don't infer the default from first-push (raw bare repos, some self-hosted setups), the default branch has to be set out of band:

1. Match the default at init time — git init --bare --initial-branch=<source-default> on the target before the first sync.
2. Set HEAD post-sync — git symbolic-ref HEAD refs/heads/<source-default> on the bare repo, or the host's API/UI (GitHub PATCH /repos/{owner}/{repo} with default_branch; GitLab PUT /projects/:id with default_branch).

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