reduced docs amount · Entire

Reduced Docs Amount

522e51d → main · Soph · 2mo ago · 11 files · +39 added/-594 removed

Sessions

Transcript data is unavailable for this checkpoint.

Changes

11

154 unmodified lines
155
156
157
158
158
159
160
161

154 unmodified lines

- **Formatting**: Code must pass `gofmt` (run `mise run fmt`)
- **Linting**: Code must pass `golangci-lint` (run `mise run lint`)
- **Naming**: Use meaningful, descriptive names following Go conventions
- **Public API**: `entire.io/entire/gitsync` is the stable embedding surface. Additions there should be reviewed carefully. `entire.io/entire/gitsync/unstable` is for advanced controls and may change. See [docs/embedding.md](docs/embedding.md).
- **Public API**: `entire.io/entire/gitsync` is the stable embedding surface. Additions there should be reviewed carefully. `entire.io/entire/gitsync/unstable` is for advanced controls and may change.

---

MCONTRIBUTING.md +1/-1

24 unmodified lines

25
26
27
28
28
29
30
31
32
32
33
34
35
41 unmodified lines

77
78
79
80
80
81
82
83
94 unmodified lines

178
179
180
181
182
183
184
185
186
181
182
183

24 unmodified lines

`sync` automatically bootstraps an empty target, so the same command covers initial seeding and ongoing sync. To preview what would happen without pushing, run `git-sync plan` — it takes the same flags as `sync`, and `--mode replicate` previews a `replicate` run.

Additional commands (`bootstrap`, `probe`, `fetch`) and advanced flags are available through `git-sync --help` and the [unstable library surface](docs/embedding.md). They are not part of the recommended public surface.

## Library API

`git-sync` is also a Go library. Use `entire.io/entire/gitsync` for the stable embedding surface (`Probe`, `Plan`, `Sync`, `Replicate`, typed results, auth and HTTP injection). `entire.io/entire/gitsync/unstable` exposes advanced controls (`Bootstrap`, `Fetch`, batching knobs, heap measurement) and is not stable. See [docs/embedding.md](docs/embedding.md) for the worker-oriented guide.

`git-sync` is also a Go library. Use `entire.io/entire/gitsync` for the stable embedding surface (`Probe`, `Plan`, `Sync`, `Replicate`, typed results, auth and HTTP injection). `entire.io/entire/gitsync/unstable` exposes advanced controls (`Bootstrap`, `Fetch`, batching knobs, heap measurement) and is not stable.

## Quick Start

41 unmodified lines

## Sync Behavior

`sync` picks the bootstrap relay path automatically when the target is empty. For non-empty targets, safe fast-forward updates also use a relay path that streams the source pack directly into target `receive-pack` without local materialization. Anything not relay-eligible (force, prune, deletes, tag retargets) falls back to a materialized path bounded by `--materialized-max-objects`. See [docs/incremental-relay.md](docs/incremental-relay.md) and [docs/bootstrap.md](docs/bootstrap.md) for details.

`sync` picks the bootstrap relay path automatically when the target is empty. For non-empty targets, safe fast-forward updates also use a relay path that streams the source pack directly into target `receive-pack` without local materialization. Anything not relay-eligible (force, prune, deletes, tag retargets) falls back to a materialized path bounded by `--materialized-max-objects`.

Sync specific branches:

94 unmodified lines

- [docs/architecture.md](docs/architecture.md) — product rationale, package layout, operation modes vs transfer modes, memory model
- [docs/protocol.md](docs/protocol.md) — smart HTTP, pkt-line, capability negotiation, sideband, relay framing
- [docs/bootstrap.md](docs/bootstrap.md) — empty-target relay
- [docs/bootstrap-batching.md](docs/bootstrap-batching.md) — checkpoint batching for very large initial migrations
- [docs/incremental-relay.md](docs/incremental-relay.md) — narrow relay fast path inside `sync`
- [docs/replicate.md](docs/replicate.md) — source-authoritative relay-only overwrite mode
- [docs/embedding.md](docs/embedding.md) — using `git-sync` as a Go library
- [docs/benchmarking.md](docs/benchmarking.md) — `git-sync-bench` usage
- [docs/testing.md](docs/testing.md) — test suites and integration coverage

## Contributing

MREADME.md +3/-9

192 unmodified lines

193
194
195
196
197
198
199
196
197

192 unmodified lines

## Related Notes

- [bootstrap.md](bootstrap.md)
- [bootstrap-batching.md](bootstrap-batching.md)
- [benchmarking.md](benchmarking.md)
- [embedding.md](embedding.md)
- [protocol.md](protocol.md)
- [testing.md](testing.md)

## Incremental Relay

`sync` has a narrow relay fast path for safe incremental updates. When eligible, it streams a fetched source pack directly into target `receive-pack` instead of decoding the object graph into the local in-memory store and re-encoding a push pack. This keeps the in-memory cost near zero for the common case where a sync run only needs to forward a small amount of new history.

This document describes when the fast path applies, what it covers, and when `sync` falls back to the materialized path.

## Eligibility

The incremental relay path is selected only when **all** of the following hold:

- no `--force`
- no `--prune`
- no managed-ref deletes
- no tag retargeting (creating a new tag at a new tip is allowed; moving an existing tag is not)
- target does **not** advertise `no-thin` on `receive-pack`

The `no-thin` check is conservative: when a target advertises `no-thin`, it is signalling that it does not support thin packs. `git-sync`'s source fetch never requests the `thin-pack` capability, so the relayed pack is always self-contained and would in fact be safe for a `no-thin` target — but the incremental relay planner skips this case as a safety margin and falls back to the materialized path instead. (`replicate` is less conservative and tolerates `no-thin` targets explicitly; see [replicate.md](replicate.md).)

## What the fast path covers

When the eligibility conditions hold, the relay path covers:

- multi-branch fast-forward branch updates
- branch-to-branch ref mappings (`--map src:dst`)
- create-only tag pushes that fit alongside the branch updates

In other words: the everyday "mirror these branches and any new tags forward" case is fully covered.

## What still falls back to materialized

The materialized path (decode source objects into the local store, plan the push set, encode a target pack) still handles:

- `--force` and any non-fast-forward update
- `--prune` and managed-ref deletes
- tag retargeting (an existing tag pointing at a new object)
- runs against targets that advertise `no-thin`

The materialized path is bounded by `--materialized-max-objects` as a safety guardrail. See [architecture.md](architecture.md#memory-assumptions) for the memory model.

## Implementation

The execution path lives in `internal/strategy/incremental`. The shared relay framing, sideband stripping, and PACK header handling live in `internal/gitproto`. See [protocol.md](protocol.md) for protocol-level details and [architecture.md](architecture.md) for where this fits in the overall package layout.