Documentation
¶
Index ¶
- Variables
- func CanonicalRemoteKey(remote string) (string, error)
- func IsRepo(path string) bool
- func SafeBranchName(branch string) bool
- func UsesLFS(ctx context.Context, dir string) (bool, error)
- func ValidateRemote(remote string) error
- type BaseDrift
- type CloneOptions
- type CommandError
- type DefaultBranchSource
- type DirtyState
- type Runner
- func (r Runner) BaseDrift(ctx context.Context, dir, baseRef, recordedSHA string) (BaseDrift, error)
- func (r Runner) Clone(ctx context.Context, remote, dest string, partial bool) error
- func (r Runner) CloneWithOptions(ctx context.Context, remote, dest string, opts CloneOptions) error
- func (r Runner) DefaultBranch(ctx context.Context, dir, fallback string) (string, error)
- func (r Runner) DirtyState(ctx context.Context, dir string) (DirtyState, error)
- func (r Runner) Fetch(ctx context.Context, dir, remote, branch string) error
- func (r Runner) LFSInstallLocal(ctx context.Context, dir string) error
- func (r Runner) LFSPull(ctx context.Context, dir string) error
- func (r Runner) LocalDefaultBranch(ctx context.Context, dir, fallback string) (string, DefaultBranchSource, error)
- func (r Runner) MaintenanceRun(ctx context.Context, dir string) error
- func (r Runner) PushBranch(ctx context.Context, dir, remote, branch string) error
- func (r Runner) RemoteDefaultBranch(ctx context.Context, dir, remote string) (string, error)
- func (r Runner) RemoteURL(ctx context.Context, dir string) (string, error)
- func (r Runner) ResolveDefaultBranch(ctx context.Context, dir, fallback string) (string, DefaultBranchSource, error)
- func (r Runner) RevParse(ctx context.Context, dir, ref string) (string, error)
- func (r Runner) Run(ctx context.Context, dir string, args ...string) (string, error)
- func (r Runner) WorktreeAdd(ctx context.Context, dir, path, branch, base string) error
- func (r Runner) WorktreePrune(ctx context.Context, dir string) error
- func (r Runner) WorktreeRemove(ctx context.Context, dir, path string, force bool) error
Constants ¶
This section is empty.
Variables ¶
var ( ErrNetwork = errors.New("git network error") ErrTimeout = errors.New("git timeout") ErrAuth = errors.New("git authentication error") ErrBranchNotFound = errors.New("git branch not found") ErrRemoteMissing = errors.New("git remote missing") // ErrNonFastForward classifies a push rejected because the remote ref // advanced past the local view (someone else pushed first). It is the // retryable outcome of the git-carrier hub's optimistic write loop: // refetch, re-apply, push again — never a terminal failure. ErrNonFastForward = errors.New("git non-fast-forward push") )
Functions ¶
func CanonicalRemoteKey ¶
func SafeBranchName ¶
SafeBranchName reports whether branch is a plain, option-injection-free git branch name (the git-carrier hub validates its configured branch with it).
func ValidateRemote ¶
Types ¶
type CloneOptions ¶
type CloneOptions struct {
Partial bool // --filter=blob:none (blobless clone)
Submodules bool // --recurse-submodules so the tree is fully present
AlsoFilterSubmodules bool // --also-filter-submodules (keep submodules blobless too; only meaningful with Partial)
}
CloneOptions controls git clone behavior (GIT-06).
type CommandError ¶
func (CommandError) Error ¶
func (e CommandError) Error() string
func (CommandError) Unwrap ¶
func (e CommandError) Unwrap() error
type DefaultBranchSource ¶
type DefaultBranchSource string
DefaultBranchSource records how ResolveDefaultBranch determined the branch, from most to least authoritative.
const ( // DefaultBranchRemote means the value came from the remote (origin/HEAD or // a set-head --auto query). DefaultBranchRemote DefaultBranchSource = "remote" // DefaultBranchStored means origin/HEAD was unavailable and a previously // stored fallback branch was verified to exist on the remote. DefaultBranchStored DefaultBranchSource = "stored" )
type DirtyState ¶
type DirtyState string
const ( DirtyUnknown DirtyState = "unknown" DirtyClean DirtyState = "clean" DirtyDirty DirtyState = "dirty" DirtyAhead DirtyState = "ahead" DirtyBehind DirtyState = "behind" DirtyDiverged DirtyState = "diverged" DirtyConflicted DirtyState = "conflicted" )
type Runner ¶
type Runner struct {
Bin string
Timeout time.Duration
// LongTimeout is the per-attempt deadline for network-transfer commands
// that legitimately run for tens of minutes on large repositories: clone,
// fetch, and git lfs pull. Other git commands use Timeout.
LongTimeout time.Duration
RetryAttempts int
RetryBackoff time.Duration
// RetryCap bounds the per-sleep backoff so exponential growth cannot exceed
// a sane ceiling (QUAL-06).
RetryCap time.Duration
// MaxElapsed bounds the total wall-clock time of a single operation's
// retry loop (across all attempts). Zero means no aggregate budget (bounded
// only by RetryAttempts and the per-command Timeout). Set by callers that
// need a hung operation to fail fast instead of wedging a worker slot
// (QUAL-06).
MaxElapsed time.Duration
}
func (Runner) CloneWithOptions ¶
CloneWithOptions runs a git clone with the given options and the GIT-02 clean-destination retry. When Submodules is set the clone initializes submodules so the working tree is structurally complete (GIT-06); with Partial + AlsoFilterSubmodules the submodules are blobless too.
func (Runner) DefaultBranch ¶
DefaultBranch resolves the remote default branch, returning only the branch name. Prefer ResolveDefaultBranch when the caller wants to know how authoritative the answer is.
func (Runner) DirtyState ¶
func (Runner) LFSInstallLocal ¶
LFSInstallLocal installs the LFS smudge/clean filters into the repo's own .git/config. It is required on the materialize path because gitEnv sets GIT_CONFIG_GLOBAL=/dev/null, hiding any global `git lfs install` (P6-GIT-04). This is a local operation (no network); it uses the default Timeout.
func (Runner) LocalDefaultBranch ¶
func (r Runner) LocalDefaultBranch(ctx context.Context, dir, fallback string) (string, DefaultBranchSource, error)
LocalDefaultBranch resolves the default branch using only local refs — it never touches the network (no set-head/ls-remote/fetch). Scan-time onboarding must stay offline (P6-XP-05); authoritative set-head --auto repair is deferred to hydrate/worktree materialization, which calls ResolveDefaultBranch at use time. It returns the branch and how authoritative the answer is.
func (Runner) MaintenanceRun ¶
MaintenanceRun runs a one-time `git maintenance run --auto` (commit-graph + prefetch) so common history ops (blame, log -p) do not trigger per-object lazy fetches on a blobless clone (GIT-06). It is best-effort: older git or a missing promisor makes this a no-op or error, and the caller should not fail materialization on it.
func (Runner) PushBranch ¶
PushBranch pushes branch to remote with -u under the long transfer deadline (P6-GIT-01): a large branch push is the same network-transfer class as clone/fetch. No retry loop — the wrapper cannot know a failed push is safe to repeat, so the caller decides.
func (Runner) RemoteDefaultBranch ¶
RemoteDefaultBranch queries the remote authoritatively with `git ls-remote --symref <remote> HEAD`, returning the branch HEAD points at. This works even when no local refs/remotes/origin/HEAD exists. It is a network operation.
func (Runner) ResolveDefaultBranch ¶
func (r Runner) ResolveDefaultBranch(ctx context.Context, dir, fallback string) (string, DefaultBranchSource, error)
ResolveDefaultBranch resolves the remote default branch in layers, never silently falling back to a hardcoded "main": (1) read refs/remotes/origin/HEAD; (2) on failure, repair it with `remote set-head origin --auto` (which queries the remote) and retry; (3) verify the caller's stored fallback exists on the remote. It returns the branch and the source so callers can warn when the answer is not authoritative.
Source Files