Documentation
¶
Overview ¶
Package git is a simple Pusher implementation backed by a local git checkout.
On every Push call the implementation:
- Fetches the configured remote.
- Resets the checkout's HEAD to refs/remotes/<remote>/<target>.
- Cherry-picks the head SHA of every URI of every Change, in order. A pick that produces no new content (because the change is already present on the target branch) is what git surfaces as "rebased out" and is recorded as OutcomeStatusAlreadyExisted. A pick that fails to apply cleanly is treated as a conflict.
- Pushes HEAD to refs/heads/<target> on the remote.
Atomicity: nothing is published to the remote until step 4 succeeds. If any cherry-pick fails the in-progress pick is aborted and Push returns an error without ever invoking step 4.
Contention: if step 4 fails because the remote tip moved between step 2 and step 4 (typically a concurrent push from another writer), the whole fetch/reset/cherry-pick/push cycle is retried. Detection works by re-fetching the remote tip after a push failure and comparing it to the SHA we reset to in step 2: if it advanced, the failure is treated as contention. Other push failures (network, auth, hook reject without ref change) propagate immediately. Retries are capped at Params.MaxPushAttempts (default 10) to bound the worst case.
Construction takes the path to an existing checkout, the remote name, and the target branch — the implementation owns the working tree at that path for the duration of any in-flight Push call and serializes concurrent invocations.
Change URIs are parsed using the github-family URI format (see entity/github), so each URI's last segment is interpreted as the head commit SHA. The SHA must be reachable from a ref on the remote so that `git fetch` makes it available locally.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type GitRuntime ¶
type GitRuntime struct {
// Executable is the absolute path to the Git executable.
Executable string
// ExecPath is the absolute directory containing Git's helper executables.
ExecPath string
// TemplateDir is the absolute directory containing Git's repository
// templates.
TemplateDir string
}
GitRuntime identifies the explicitly provided Git runtime used by the Pusher.
type Params ¶
type Params struct {
// CheckoutPath is the absolute path to an existing git checkout that the
// Pusher will operate against. The Pusher owns this working tree.
CheckoutPath string
// Remote is the name of the git remote to fetch from and push to
// (e.g. "origin").
Remote string
// Target is the destination branch ref on the remote (e.g. "main").
Target string
// Resolver resolves each batch's changes.
Resolver changeset.Resolver
// Logger is the structured logger.
Logger *zap.SugaredLogger
// MetricsScope is the metrics scope for instrumentation.
MetricsScope tally.Scope
// Runtime is the pinned Git runtime used for every invocation.
Runtime GitRuntime
// MaxPushAttempts caps how many times Push retries the full
// fetch/reset/cherry-pick/push cycle when the remote tip moves under
// it. Defaults to defaultMaxPushAttempts when zero or negative.
MaxPushAttempts int
}
Params holds the dependencies for the git Pusher.
Source Files