Document stable and unstable library APIs

0d2e56c→main·

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.