git

package
v0.1.2-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 13, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
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 CanonicalRemoteKey(remote string) (string, error)

func IsRepo 

func IsRepo(path string) bool

func SafeBranchName 

func SafeBranchName(branch string) bool

SafeBranchName reports whether branch is a plain, option-injection-free git branch name (the git-carrier hub validates its configured branch with it).

func UsesLFS 

func UsesLFS(ctx context.Context, dir string) (bool, error)

func ValidateRemote 

func ValidateRemote(remote string) error

Types

type BaseDrift 

type BaseDrift struct {
	CurrentSHA string `json:"current_sha"`
	Behind     int    `json:"behind"`
	Fresh      bool   `json:"fresh"`
}

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 

type CommandError struct {
	Kind    error
	Args    string
	Message string
	Code    int
}

func (CommandError) Error 

func (e CommandError) Error() string

func (CommandError) ExitCode added in v0.1.2 

func (e CommandError) ExitCode() int

ExitCode returns the git subprocess exit status, or -1 when the process did not report one (for example when it could not be started). Callers that rely on git's documented tri-state commands must distinguish an expected status such as merge-base's 1 from operational failures.

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 NewRunner 

func NewRunner() Runner

func (Runner) BaseDrift 

func (r Runner) BaseDrift(ctx context.Context, dir, baseRef, recordedSHA string) (BaseDrift, error)

func (Runner) Clone 

func (r Runner) Clone(ctx context.Context, remote, dest string, partial bool) error

func (Runner) CloneWithOptions 

func (r Runner) CloneWithOptions(ctx context.Context, remote, dest string, opts CloneOptions) error

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 

func (r Runner) DefaultBranch(ctx context.Context, dir, fallback string) (string, error)

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 (r Runner) DirtyState(ctx context.Context, dir string) (DirtyState, error)

func (Runner) Fetch 

func (r Runner) Fetch(ctx context.Context, dir, remote, branch string) error

func (Runner) IsSquashMerged added in v0.1.2 

func (r Runner) IsSquashMerged(ctx context.Context, dir, branch, baseRef string) (bool, error)

IsSquashMerged reports whether branch's content is already contained in the CURRENT baseRef tree — the content-equivalence test behind `worktree cleanup --merged`'s squash/rebase detection (P4-GIT-04). It simulates the merge (`git merge-tree --write-tree <baseRef> <branch>`, git >= 2.38): when the resulting tree is identical to baseRef's own tree, merging the branch would contribute nothing — every change the branch carries is already present in base, which is exactly the effect of a squash- or rebase-merge. Comparing against the CURRENT tree (rather than patch-id history) means a change that was merged and then REVERTED on base correctly reads as NOT merged (dual-review finding: historical patch-id equivalence would have deleted genuinely-unmerged work).

Conservative by construction: a conflicting simulated merge (content diverged), an invalid ref, or an older git without --write-tree all report false — doubt is never grounds to reap.

Documented accepted limitation (inherent to ANY content-equivalence test): a branch whose net change ALSO landed via an unrelated identical commit is indistinguishable from a squash-merge and reads as merged; the reap breadcrumb (the printed branch tip SHA) is the recovery path. Pinned by TestIsSquashMergedMatchesCoincidentallyIdenticalDiff.

func (Runner) LFSInstallLocal 

func (r Runner) LFSInstallLocal(ctx context.Context, dir string) error

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) LFSPull 

func (r Runner) LFSPull(ctx context.Context, dir string) error

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 

func (r Runner) MaintenanceRun(ctx context.Context, dir string) error

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 

func (r Runner) PushBranch(ctx context.Context, dir, remote, branch string) error

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 

func (r Runner) RemoteDefaultBranch(ctx context.Context, dir, remote string) (string, error)

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) RemoteURL 

func (r Runner) RemoteURL(ctx context.Context, dir string) (string, error)

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.

func (Runner) RevParse 

func (r Runner) RevParse(ctx context.Context, dir, ref string) (string, error)

func (Runner) Run 

func (r Runner) Run(ctx context.Context, dir string, args ...string) (string, error)

func (Runner) WorktreeAdd 

func (r Runner) WorktreeAdd(ctx context.Context, dir, path, branch, base string) error

func (Runner) WorktreePrune 

func (r Runner) WorktreePrune(ctx context.Context, dir string) error

func (Runner) WorktreeRemove 

func (r Runner) WorktreeRemove(ctx context.Context, dir, path string, force bool) error

func (Runner) WorktreeSandboxWriteDirs added in v0.1.2 

func (r Runner) WorktreeSandboxWriteDirs(ctx context.Context, dir string) ([]string, error)

WorktreeSandboxWriteDirs returns the absolute git storage paths a linked worktree must be able to WRITE for `git add`/`git commit` to succeed under an OS sandbox: the shared object store, refs, and reflogs in the git-common-dir, plus the per-worktree admin dir (index/HEAD/COMMIT_EDITMSG/logs). It deliberately EXCLUDES the common dir itself (and thus hooks/ and config) — granting those would let a sandboxed agent plant a hook or config that executes UNSANDBOXED on a later git operation (P7-SANDBOX-01). Paths are symlink-resolved. A nil slice with no error is returned when dir is not inside a git worktree, so callers can grant nothing without special-casing.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.