# Docs: HEAD / Default Branch

`c25015d`→[main](/content/gh/entireio/git-sync/commits/main/index.html)·

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