# Expose replicate mode in API and CLI

`3486c1b`→[main](/content/gh/entireio/git-sync/commits/main/index.html)·

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:

```bash
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:

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