docs: add README FAQ

Sessions

e0af21de41fbView transcript

Changes

1

• MREADME.md+38

FAQ

Does it sync complete Git history or only perform a shallow/partial sync?

git-sync syncs the complete Git object history required for the selected refs. It does not create a shallow clone. Some planning paths may use filtered fetches, but the target receives the full objects needed for valid refs.

Is it just refs, or objects as well?

Objects as well. Refs are what git-sync plans and updates, but it also transfers the commits, trees, blobs, and tags needed for those refs to exist on the target.

Is it bidirectional?

No. git-sync is one-way: source remote to target remote.

Does it support create, update, and delete actions?

Yes. It supports creating refs, updating refs, force updates with --force, and deleting managed refs with --prune. replicate can overwrite target refs, but it is relay-only and more restrictive than sync.

How does it scale?

The scalable path streams pack data from the source directly into the target without materializing the full object graph locally. The in-memory go-git store is used for planning, ancestry checks, and fallback materialized pushes. In fallback mode, git-sync fetches objects into memory, computes what must be pushed, then encodes and sends a pack to the target.

How long does it take for a medium-sized repo?

There is no fixed runtime. It depends on repository size, pack size, network latency, provider speed, and whether relay is used. On the relay path, time is mostly source pack generation plus network transfer plus target receive time.

How does it deal with partial successes? Is it atomic?

git-sync plans before pushing and blocks unsafe refs before starting. A single target receive-pack push is atomic in the normal Git sense for that push. Across multiple batches or separate push requests, especially batched bootstrap, it is not globally atomic; batched bootstrap uses temporary refs and resume behavior.

Does it support SSH?

No. git-sync supports smart HTTP/HTTPS only.

Is this one-time or does it run in the background?

git-sync is a one-shot CLI/library operation. It does not run as a daemon or background watcher. Run it manually, from CI, cron, a worker, or another service.

Contributing

See CONTRIBUTING.md, SECURITY.md, and CODE_OF_CONDUCT.md.