Expose replicate mode in API and CLI

3486c1b→main·

Soph·3mo ago·11 files·+244 added/-19 removed

Sessions

ce4b384e68ddView transcript

Changes

11

• MREADME.md+25/-2

• cmd/git-sync

• Mmain.go+39/-5

• Mmain_test.go+87/-3

• docs

• Marchitecture.md+14/-7

• pkg/gitsync

• Mclient.go+22

• Mclient_test.go+11

• internalbridge

• Mconfig.go+13

• Mmodel.go+5/-1

• Mmodel_test.go+2/-1

• Mtypes.go+9

• unstable

• Mclient.go+17

Commands

• git-sync probe: inspect a source remote, and optionally a target remote
• git-sync fetch: exercise source-side fetch negotiation without pushing
• git-sync bootstrap: seed an empty target with create-only relay behavior
• git-sync plan: compute source-to-target ref actions without pushing
• git-sync plan: compute source-to-target ref actions without pushing, with --mode sync|replicate
• git-sync sync: execute the planned changes against the target
• git-sync replicate: execute source-authoritative relay-only replication against the target
• git-sync-bench: run repeatable benchmark scenarios against fresh empty targets

Library API

• pkg/gitsync
  • stable embedding surface for queue workers and other external callers
  • typed Probe, Plan, and Sync requests/results
  • injected auth and HTTP client support
• pkg/gitsync/unstable
  • explicitly non-stable surface for first-party tooling and advanced controls

Features

• Optional exact ref mapping with --map
• Fast-forward safety by default
• Optional forced retargeting with --force
• Optional source-authoritative relay-only replication with replicate / plan --mode replicate
• Optional managed-ref deletion with --prune
• Optional transfer stats output with --stats
• Optional machine-readable output with --json

Examples

Plan a source-authoritative replication without pushing anything:

go run ./cmd/git-sync plan \
  --mode replicate \
  --stats \
  https://github.com/source-org/source-repo.git \
  https://github.com/target-org/target-repo.git

Execute relay-only replication that overwrites differing managed refs and fails instead of materializing locally:

go run ./cmd/git-sync replicate \
  --stats \
  https://github.com/source-org/source-repo.git \
  https://github.com/target-org/target-repo.git

When To Use git-sync

Explicit Strategy Split

The current execution modes are:

• bootstrap
  • empty-target relay
• sync
  • planning plus reconciliation
• replicate
  • source-authoritative overwrite planning
  • relay-only execution
  • no materialized fallback; incompatible targets fail and should use sync

The current transfer modes are:

• bootstrap
  • empty-target relay
• incremental relay
  • narrow fast path for safe updates
• materialized fallback

The project now separates embedding concerns from first-party tooling concerns:

• pkg/gitsync is the stable library boundary. Callers express orchestration intent through typed probe, plan, and sync requests. Auth and transport are injected. Execution strategy remains internal.
• pkg/gitsync/unstable is the escape hatch for advanced controls. It exists so the CLI and benchmark tool can use batching limits, memory measurement, verbose progress, bootstrap, and fetch without widening the stable API prematurely.