docs: document SSH support and caveats

557221c→main·

Soph·2mo ago·3 files·+25 added/-2 removed

Sessions

5f03021cd910View transcript

[?
yes, start implementing, make a new branch, make meaningful commits, and add tests as you go, when it makes sense create tests firstCodex·GPT-5.4·1 step](/content/gh/entireio/git-sync/session/019e260b-71e8-73a1-9e68-5857379ffab6#timeline-5f03021cd910/index.html)

Changes

3

• MREADME.md+3/-1
• docs
  • Mprotocol.md+2/-1
  • Musage.md+20

129 unmodified lines

130
131
132
133
133
134
135
136
137
138

129 unmodified lines

Does it support SSH?

No. git-sync supports smart HTTP/HTTPS only.
Yes. git-sync supports SSH remotes through the local ssh binary, including ssh://, SCP-style git@host:path.git, and git+ssh:// URLs. See docs/usage.md for details and current caveats.

Does it run as a daemon or watch for changes?

MREADME.md+3/-1

19 unmodified lines

20
21
22
23
23
24
25
26
27

19 unmodified lines
- The pack format itself (object types, deltas, index format) — see [Git's pack-format docs](https://git-scm.com/docs/pack-format)
- Dumb HTTP — `git-sync` does not support it
- SSH transport — `git-sync` is HTTPS-only
- Full SSH transport details — `git-sync` supports SSH, but this document is focused on the Smart HTTP wire flow
- Bundle URI, partial clones, and other newer extensions

## Smart HTTP Overview

Mdocs/protocol.md+2/-1

```  
120 unmodified lines

121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

120 unmodified lines

<target-url>
```

### SSH remotes

`git-sync` also supports SSH remotes. Accepted forms include:

- `ssh://git@example.com/org/repo.git`
- `git@example.com:org/repo.git`
- `git+ssh://example.com/org/repo.git`

SSH transport shells out to the local `ssh` binary, so host aliases,
`IdentityFile`, agent-backed keys, and other `~/.ssh/config` behavior come
from your existing SSH setup rather than separate `git-sync` flags.

`git-sync` runs SSH with `BatchMode=yes`, which avoids interactive password or
host-key prompts during syncs. On first contact with a host, add it to
`known_hosts` ahead of time or configure `StrictHostKeyChecking=accept-new`
for that host in your SSH config.

Current limitation: `--progress` and `--show-stats` do not yet include
byte-counted SSH transfer metrics, so those views omit SSH-side throughput.

## 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`.
```