git-sync

git-sync mirrors refs from a source remote to a target remote without creating a local checkout. It uses an in-memory go-git object store and talks smart HTTP directly:

• info/refs ref advertisement for source and target
• upload-pack fetch from source with target tip hashes advertised as have
• receive-pack push to target with explicit ref update commands and a streamed packfile

That keeps the target side incremental without fetching target objects into the local process first.

Why This Exists

Mirroring Git data between remotes usually means a local mirror clone followed by a mirror push. That's fine for small repos but turns a remote-to-remote operation into a local storage problem at scale, and shell glue around git fetch / git push tends to skip planning and structured output.

git-sync fills that gap. It streams source packs directly into target receive-pack when it can, plans every action before pushing, and emits typed JSON for automation.

For when to use it (and when not), see docs/architecture.md.

Commands

The main commands are:

• git-sync sync: mirror source refs into the target
• git-sync replicate: overwrite target refs to match source via relay, and fail rather than materialize locally

sync automatically bootstraps an empty target, so the same command covers initial seeding and ongoing sync. To preview what would happen without pushing, run git-sync plan — it takes the same flags as sync, and --mode replicate previews a replicate run.

For one-off SHA1 → SHA256 repo conversion, git-sync convert-sha256 fetches from an HTTP source and writes a new SHA256 bare repo on disk, with optional commit-message hash rewrites, an origin-notes ref, and a sidecar mapping file. See docs/convert-sha256.md.

For command examples, JSON output, auth, protocol flags, and advanced command notes, see docs/usage.md.

Library API

git-sync is also a Go library. Use entire.io/entire/git-sync for the stable embedding surface (Probe, Plan, Sync, Replicate, typed results, auth and HTTP injection). entire.io/entire/git-sync/unstable exposes advanced controls (Bootstrap, Fetch, batching knobs, heap measurement) and is not stable.

Installation

Homebrew (macOS, Linux)

brew tap entireio/tap
brew install --cask git-sync

go install

Requires Go 1.26 or newer.

go install entire.io/entire/git-sync/cmd/git-sync@latest

This drops a git-sync binary into $(go env GOPATH)/bin. Make sure that directory is on your PATH.

From source

git clone https://github.com/entireio/git-sync.git
cd git-sync
go build -o git-sync ./cmd/git-sync

Verifying a download

Release archives and checksums.txt carry signed build provenance tied to this repository and the workflow that produced them. Check a download before running it:

gh attestation verify git-sync_<version>_<os>_<arch>.tar.gz --repo entireio/git-sync

Homebrew verifies the archive checksum from the tap automatically.

Quick Start

git-sync sync \
  --source-token "$GITSYNC_SOURCE_TOKEN" \
  --target-token "$GITSYNC_TARGET_TOKEN" \
  https://github.com/source-org/source-repo.git \
  https://github.com/target-org/target-repo.git

https://github.com/user-attachments/assets/60adb873-4032-4ab7-b236-24d038e04681

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.

For branch filtering, ref mapping, tags, pruning, protocol selection, JSON output, and auth details, see docs/usage.md.

Testing

Default suite:

env GOCACHE=/tmp/go-build go test ./...

Extended and environment-specific test instructions are in docs/testing.md.

Documentation

• docs/usage.md — CLI commands, examples, sync behavior, JSON output, auth, protocol notes
• docs/architecture.md — product rationale, package layout, operation modes vs transfer modes, memory model
• docs/protocol.md — smart HTTP, pkt-line, capability negotiation, sideband, relay framing
• docs/convert-sha256.md — one-off SHA1 → SHA256 repo conversion, mapping outputs, sharp edges
• docs/testing.md — test suites and integration coverage

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. To go the other way you'd run a second invocation with the endpoints swapped.

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?

git-sync has two transfer paths:

• Relay — pack data streams from source upload-pack directly into target receive-pack. The local process holds no object graph, so memory stays bounded regardless of repo size. Used when the target supports relay.
• Materialized fallback — when relay isn't available, git-sync fetches the needed objects into an in-memory go-git store, plans, then encodes and pushes a packfile. Memory scales with the diff being pushed and is guarded by an explicit object-count limit. Bootstrap can batch large initial syncs to keep this bounded.

Planning itself is cheap: ref-only round-trips, plus a filter tree:0 fetch for ancestry checks when the source advertises filter support.

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

It depends on repository size, network speed, and whether the relay path is available. As a rule of thumb, the relay path is bounded by source pack generation + network transfer + target receive-pack time — roughly the time of a git clone from the source plus a git push of the same pack. The materialized fallback adds local memory work for objects that need inspection.

For concrete numbers on your own setup, run the included benchmark tool against a representative repo; see docs/testing.md.

Does it support SSH?

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.

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.

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.

Contributing

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