# Explain product rationale in docs

## Sessions

ace64d1131b3View transcript

## Changes

- MREADME.md+35
- docs
  - Marchitecture.md+23

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

## Why This Exists

Git already has pieces of this problem, but not this exact tool shape.

What usually exists today:
- a full local `git clone --mirror` followed by `git push --mirror`
- host-specific import or migration features
- CI jobs or shell scripts that glue fetch and push steps together
- one-off migration tooling tied to a specific platform

What those approaches usually do not give you:
- direct remote-to-remote relay behavior
- a small standalone CLI with explicit sync semantics
- front-loaded validation and planning
- machine-readable output for automation
- one tool that covers empty-target bootstrap, normal sync, and large-repo bootstrap fallback

That is the gap `git-sync` is trying to fill.

The main value is operational:
- avoid requiring a full local mirror checkout just to move refs between remotes
- make initial seeding of large repositories cheaper and more predictable
- keep incremental sync behavior explicit and safe
- give operators and automation a stable way to inspect, plan, execute, and benchmark the same workflows

This is especially useful when:
- the target is a new hosted Git service or internal Git endpoint
- bootstrap size matters more than local developer ergonomics
- you want a repeatable machine-oriented sync primitive rather than an ad hoc migration script
- you need clearer control over mapping, pruning, force rules, and relay behavior than generic shell glue usually provides

The command surface is:
- `git-sync probe`: inspect a source remote, and optionally a target remote

`git-sync` is a remote-to-remote Git mirroring CLI over smart HTTP.

## Product Rationale

The point of `git-sync` is not that Git mirroring is impossible without it. The point is that the usual alternatives are awkward at the exact layer operators often need:
- a full local mirror clone and mirror push is simple, but it turn remote-to-remote movement into a local storage and local bandwidth problem
- host-specific migration tools are useful, but they are not portable and they usually do not expose one consistent sync primitive across providers
- scripts around `git fetch` and `git push` can work, but they usually lack planning, explicit policy checks, stable machine-readable output, and a clean distinction between bootstrap and incremental sync

`git-sync` is meant to be that missing middle layer:
- provider-agnostic
- remote-to-remote
- automation-friendly
- explicit about safety and relay eligibility
- capable of handling both first-time seeding and repeat syncs

That is why the design leans so heavily on:
- relay-first strategies
- front-loaded validation
- typed results and JSON output
- explicit execution modes instead of a single opaque "mirror" operation

## Core Decisions

### Relay First