Document stable gitsync result shape

322787c→main·

Soph·3mo ago·2 files·+18 added/-0 removed

Sessions

74df732fb738View transcript

Changes

2

• MREADME.md+9
• docs
  • Marchitecture.md+9

73 unmodified lines

74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

73 unmodified lines

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.

The stable `pkg/gitsync` results are shaped for workers:

- `Refs`
  - per-ref outcomes
- `Counts`
  - aggregate applied/skipped/blocked/deleted counts
- `Execution`
  - execution mode, protocol, relay summary, and batch summary

## Current scope

- Smart HTTP only

MREADME.md+9

114 unmodified lines

115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

114 unmodified lines

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

The stable result contract is also intentionally worker-oriented:

- `Refs`
  per-ref outcomes and reasons
- `Counts`
  aggregate applied/skipped/blocked/deleted counts
- `Execution`
  protocol, relay summary, execution mode, and batch summary

That split is intentional:

- external embedders should depend on `pkg/gitsync`