Document remote-helper scheme support · Entire
Document remote-helper scheme support
68c4b44→main·
Soph·4w ago·2 files·+37 added/-0 removed
Add a "Remote-helper schemes" section to docs/usage.md and a README FAQ entry
explaining that git-sync falls back to git-remote-
schemes, with entire:// as the motivating example, and noting the --stats
throughput caveat shared with SSH.
Co-Authored-By: Claude Opus 4.8 (1M context) noreply@anthropic.com
Sessions
91460e76a6dfView transcript
[?
❯ GITSYNC_MAX_REF_UPDATES_PER_PUSH=5000 go run ./cmd/git-sync replicate --all-refs --stats --verbose \Claude Code·Opus 4.8[1m]·3 steps](/content/gh/entireio/git-sync/session/4f8f5e9b-9f90-4c22-88b9-988c55f45833#timeline-91460e76a6df/index.html)
Changes
2
MREADME.md+8
docs
Musage.md+29
136 unmodified lines
137
138
139
140
141
142
143
144
145
146
147
148
149
150
136 unmodified lines
`ssh://`, SCP-style `git@host:path.git`, and `git+ssh://` URLs. See
[docs/usage.md](docs/usage.md) for details and current caveats.
### What about other URL schemes (e.g. `entire://`)?
For any scheme it has no native transport for, `git-sync` falls back to a git
remote helper named `git-remote-<scheme>` on `PATH`, exactly as `git` does. With
`git-remote-entire` installed, `entire://` URLs work for both fetch and push and
authenticate through the helper. See
[Remote-helper schemes](docs/usage.md#remote-helper-schemes).
### Does it run as a daemon or watch for changes?
No. `git-sync` is a one-shot CLI/library operation. To sync on a schedule or in response to events, run it from cron, CI, a worker, or another service.
MREADME.md+8
144 unmodified lines
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
144 unmodified lines
If `ssh` is not available on `PATH`, `git-sync` fails early with a clear
`locate ssh binary` error before contacting either remote.
### Remote-helper schemes
For any URL scheme `git-sync` has no native transport for, it looks for a git
remote helper named `git-remote-<scheme>` on `PATH` — the same mechanism `git`
itself uses for custom schemes. If one is installed, `git-sync` delegates auth
and the network round trips to it while still driving the smart protocol over
the helper's `stateless-connect` bridge.
The motivating case is Entire's own `entire://` URLs:
```bash
git-sync replicate --all-refs \
https://github.com/source-org/source-repo.git \
entire://cluster-host/et/project/repo
```
This requires `git-remote-entire` (installed by the Entire CLI) on `PATH`.
Authentication — including the Entire context model and OAuth token refresh —
is handled entirely by the helper, so no `--target-token` is needed when you're
already logged in via the CLI. Both fetch (upload-pack, protocol v2) and push
(receive-pack) work through the helper.
`http`/`https`/`ssh` are never routed to a helper: `git-sync` always uses its
own optimized transports for those, even though `git` ships
`git-remote-http(s)`.
Like SSH, the helper bridge has no per-request byte accounting, so `--stats`
omits helper-side throughput (the other side's throughput still prints).
## Sync Behavior
`sync` picks the bootstrap relay path automatically when the target is empty. For non-empty targets, safe fast-forward updates also use a relay path that streams the source pack directly into target `receive-pack` without local materialization. Anything not relay-eligible (force, prune, deletes, tag retargets) falls back to a materialized path bounded by `--materialized-max-objects`.
Mdocs/usage.md+29