Document gitsync embedding surface

9ccde3e→main·
Soph·3mo ago·2 files·+44 added/-0 removed

Sessions

5562a64d356dView transcript

Changes

2

• pkg/gitsync

• Adoc.go+14

  • Aexample_test.go+30

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// Package gitsync provides the public orchestration API for git-sync.
//
// The public surface is intentionally narrower than the internal engine:
// callers express sync intent through typed probe, plan, and sync requests,
// while relay selection, batching, and fallback strategy remain internal.
//
// The package is designed for embedders such as queue workers. Callers can:
//   - inject an HTTP client for transport, OTEL, proxy, TLS, and timeout control
//   - inject an auth provider that resolves source and target credentials
//   - inspect structured results for per-ref outcomes and aggregate counters
//
// Current advanced engine tuning such as batch sizing, max pack thresholds, and
// heap measurement remains outside this stable public surface.
package gitsync

Apkg/gitsync/doc.go+14

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

package gitsync_test

import (
    "context"
    "net/http"

"github.com/soph/git-sync/pkg/gitsync"
)

func ExampleClient_Sync() {
    client := gitsync.New(gitsync.Options{
        HTTPClient: &http.Client{},
        Auth: gitsync.StaticAuthProvider{
            Source: gitsync.EndpointAuth{Token: "source-token"},
            Target: gitsync.EndpointAuth{Token: "target-token"},
        },
    })

_, _ = client.Sync(context.Background(), gitsync.SyncRequest{
        Source: gitsync.Endpoint{URL: "https://github.example/source/repo.git"},
        Target: gitsync.Endpoint{URL: "https://git.example/target/repo.git"},
        Scope:  gitsync.RefScope{Branches: []string{"main"}},
        Policy: gitsync.SyncPolicy{
            IncludeTags: true,
            Protocol:    gitsync.ProtocolAuto,
        },
    })

// Output:
}

Apkg/gitsync/example_test.go+30