# Document stable and unstable library APIs

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

Soph·3mo ago·2 files·+37 added/-1 removed

## Sessions

ff6143165562View transcript

## Changes

2

- MREADME.md+14
- docs

- Marchitecture.md+23/-1

```
59 unmodified lines
```

- `git-sync sync`: execute the planned changes against the target
- `git-sync-bench`: run repeatable benchmark scenarios against fresh empty targets

## Library API

`git-sync` now has a two-tier Go 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
  - includes `Bootstrap`, `Fetch`, batching and measurement knobs, and CLI-oriented execution options

If you are embedding `git-sync` outside this repo, prefer `pkg/gitsync`. The CLI and benchmark command use `pkg/gitsync/unstable` because they still need direct access to advanced engine controls that are intentionally not part of the stable API.

## Current scope

- Smart HTTP only

## Architecture

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

## Product Rationale

## Package Model

- `pkg/gitsync`
  - stable public embedding API
  - typed `Probe`, `Plan`, and `Sync` requests/results
  - auth and HTTP client injection for worker-style callers
- `pkg/gitsync/unstable`
  - explicitly non-stable first-party tooling surface
  - advanced controls, `Bootstrap`, `Fetch`, and CLI-oriented knobs
- `internal/gitproto`
  - smart HTTP, pkt-line, fetch/push request handling, capability negotiation
- `internal/planner`
- `internal/syncertest`
  - shared in-memory test fixtures

## Public API Boundary

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.

That split is intentional:

- external embedders should depend on `pkg/gitsync`
- first-party tools inside this repo may use `pkg/gitsync/unstable`
- strategy selection, batching heuristics, and materialized fallback controls are not yet treated as stable product contracts

## Protocol Boundaries

- Source discovery and source fetch can use protocol v2 when supported.