git

package
v1.51.0 Latest Latest
Warning

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

 Go to latest Published: Sep 3, 2026 License: AGPL-3.0 Imports: 30 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultBranchDriftThreshold = 50

DefaultBranchDriftThreshold is how many commits a work session's branch can fall behind main before EnsureBranchSyncedWithMain treats it as drifted and attempts a proactive resync before review. See BUG-044: a branch left to drift unbounded across a multi-day item lifecycle eventually produces a review/PR diff dominated by unrelated upstream commits rather than the item's own work, which review then (correctly, given what it's shown) reports as unrelated — misdiagnosing branch staleness as bad work. 50 commits is comfortably past "a few days of normal repo activity" while still catching drift well before it reaches the hundreds-of-commits scale that made backlog item 693c2700's diff unreviewable (289 commits behind).

View Source 
const IsDirtyCacheTTL = 30 * time.Second

IsDirtyCacheTTL is the duration for which a dirty (has changes) result is considered fresh. 30s keeps the review queue responsive when uncommitted changes are present. InvalidateDirtyCache() is called after commits/pushes so critical paths remain snappy.

View Source 
const IsDirtyCleanCacheTTL = 5 * time.Minute

IsDirtyCleanCacheTTL is the TTL when the worktree is known to be clean. Clean worktrees won't change unless Claude commits or a user modifies files; InvalidateDirtyCache() is called on those code paths, so 5 min is safe and cuts subprocess calls by ~10x vs dirty-path TTL for quiescent sessions.

View Source 
const IsDirtyErrorCacheTTL = 60 * time.Second

IsDirtyErrorCacheTTL is the TTL applied when `git status` itself fails (e.g. the worktree directory is missing — a stale path left behind by a rework/reopen cycle). Without a backoff, a broken worktree gets re-checked on every poller tick (every few seconds), burning a subprocess spawn per tick indefinitely; 60s keeps failure visible in logs at a sane rate while still recovering quickly once the worktree is fixed.

View Source 
const SteeringBranchDriftThreshold = 20

SteeringBranchDriftThreshold is the lower drift threshold used by the PostToolUse steering hook (server/services/hook_receiver_drift.go) that fires after every git commit/push inside an autonomous backlog work session. Deliberately smaller than DefaultBranchDriftThreshold: that threshold governs when review itself blocks and is calibrated to "comfortably past normal multi-day activity"; this one governs when the *agent still doing the work* gets nudged, so it can self-correct well before drift ever reaches review-blocking scale. 20 is roughly a day or so of normal upstream activity — enough headroom that this doesn't fire on ordinary same-session commits, while leaving a wide margin before DefaultBranchDriftThreshold (50) so the agent has room to act on the nudge before review would block. See BUG-044.

Variables

View Source 
var CandidateDefaultBranches = []string{"main", "master", "develop", "trunk"} //nolint:gochecknoglobals

CandidateDefaultBranches are tried, in order, by ResolveDefaultBranchSHA when the caller doesn't know the repo's actual default branch name. Mirrors the candidate list session/unfinished's GoGitVCSReader.ResolveDefaultBranch already uses. "main" stays first so the common case costs exactly one fetch. Exported so other packages needing the same candidate list (session.RecoverBaseCommitSHA, GitWorktree.initBaseCommitSHA) share one definition instead of re-declaring the literal.

View Source 
var ErrRemoteBasePathMissing = errors.New("remote worktree base path does not exist")

ErrRemoteBasePathMissing is returned by RemoteWorktreeOps.CreateWorktree when the remote directory a new worktree would be created under does not exist. Distinct from a connection/transport failure (an unreachable host, a dead SSH channel) so callers can tell "host is fine, path is wrong" apart from "host is unreachable" — see Task 2.2.1a and adversarial-review.md Blocker 3's TOCTOU note (this check is advisory only; the real error surfaces from `git worktree add` itself if the directory is removed/unmounted between this check and the add).

View Source 
var ScaffoldingExcludePatterns = []string{
	".backlog-context.md",
	".claude/commands/backlog/",
	"web-app/.next/",
}

ScaffoldingExcludePatterns are the git exclude patterns for files stapler-squad writes into worktrees (backlog automation scaffolding, build output) that must never be committed to the target repo, even if they were already tracked in that branch's history. This is the single source of truth: consumed by the worktree-write side (session.addWorktreeExcludes, session.selfHealWorktreeScaffolding), the commit/push staging guard (StageAllExceptScaffolding below), and QuickCommitPush (server/services/unfinished_work_service.go). Keep in sync with .gitignore — session/git/scaffolding_test.go asserts they match.

Functions

func BehindOriginMain added in v1.41.0 

func BehindOriginMain(worktreePath, mainBranch string) (int, error)

BehindOriginMain fetches mainBranch from origin into worktreePath and reports how many commits origin/mainBranch has that worktreePath's currently checked-out HEAD does not — i.e. how far the checked-out branch has drifted behind main. Unlike BranchAheadBehind (which reads repoPath's LOCAL mainBranch ref and does no fetch of its own — fine for a UI badge computed against a repo some other process keeps fresh, but silently stale otherwise), this always fetches first, so the count can never be stale the way a check against an unfetched local branch ref would be. MergeMainIntoWorktree already fetches and merges against this exact origin/mainBranch ref, so this reuses the same reference point rather than introducing a second, possibly inconsistent notion of "how far behind" (BUG-044).

func CanonicalizeWorktreePath added in v1.45.1 

func CanonicalizeWorktreePath(path string) string

CanonicalizeWorktreePath resolves path to its symlink-free (realpath'd) form, matching what `git worktree list --porcelain` reports and what getWorktreeDirectory already produces for freshly-created worktree parents. On macOS /var (and /tmp) is itself a symlink to /private/var, so two code paths that construct the "same" worktree path differently — one via filepath.Join on an unresolved parent, the other by reading git's already-resolved output — end up as different strings for the identical directory (see TestBacklogFullLifecycle_SDDTriageWorktreeIsReusedBySpawnedWorkSession). EvalSymlinks requires the path to exist, which doesn't hold for the pre-creation/rehydration cases this is also used in; falling back to filepath.Clean on ANY error (not just ENOENT) keeps this a pure, non-failing normalizer, matching the established pattern in session/history_detector.go, session/import_correlate.go, and session/unfinished/gogitstore/open.go.

func CheckoutBranch added in v1.37.0 

func CheckoutBranch(repoPath, branchName string) error

CheckoutBranch checks out a branch in an existing repository.

func CleanupWorktrees 

func CleanupWorktrees() error

CleanupWorktrees removes all worktree directories under the configured worktrees dir. It deliberately does NOT delete the associated branches: a branch can hold commits that exist nowhere else (never pushed, never merged), and this function has no way to know whether that's true for any given one. See GitWorktree.Cleanup's doc comment — same fix, same root cause (docs/tasks/backlog-feature-improvement.md).

func DiffHashBetween added in v1.42.0 

func DiffHashBetween(repoPath, baseSHA, headSHA string) (string, error)

DiffHashBetween returns a stable content hash of the diff between baseSHA and headSHA in the repo at repoPath — the actual added/removed line content per file, not just per-file counts (a per-file path+status+addition-count+deletion-count tuple can collide across two genuinely different edits, e.g. two different single-line replacements on the same file both show as one addition and one deletion; hashing the actual line text avoids that false-collision shape). Feeds session.IsFlakyVerdictFlipFlop's DiffHash comparison: the same code reviewed twice must hash identically; any real change to the diff must not. Unlike a hash of the (possibly token-capped) prompt text sent to a reviewer, this is computed from the full, untruncated diff, so two different diffs that happen to share a truncated prefix can never collide here.

func EnsureBranchSyncedWithMain added in v1.41.0 

func EnsureBranchSyncedWithMain(worktreePath, branchName, mainBranch string, driftThreshold int) (ok bool, blockedSummary string)

EnsureBranchSyncedWithMain checks how far worktreePath's checked-out branch has drifted behind origin/mainBranch (via BehindOriginMain, always freshly fetched) and, once past driftThreshold commits, proactively merges main in and pushes the result — the same sync backlog_service_triage.go's syncPRBranchWithMain performs reactively after a PR-fix cycle, offered here as a precondition any review caller can run before trusting a diff computed against this worktree (BUG-044 suggested fix direction #1: "make the main-sync a precondition of review, not a best-effort side effect of the fix-retry path").

ok=true means the branch is fine to review as-is — either it wasn't drifted past driftThreshold, or a sync just resolved it cleanly (merged and pushed, or found already up to date). ok=false means the caller must not proceed to review yet; blockedSummary explains why in language written for both a human operator and a follow-up fix session's prompt context, naming the exact conflicted files (or push failure) rather than leaving the cause to be inferred from a confusing diff later.

Fails OPEN on any error determining or acting on drift (bad repo, fetch failure, merge error unrelated to a real conflict): returns ok=true so a broken detector never itself blocks review — matches every other best-effort git check in this codebase (see syncPRBranchWithMain's "never blocks the spawn" doc comment for the identical rationale). branchName is used only to build the operator-facing/fix-session message; the merge and push themselves act on whatever is currently checked out at worktreePath.

func FetchBranch added in v1.37.0 

func FetchBranch(repoPath, branchName string) error

FetchBranch fetches a specific branch from the origin remote.

func GetCurrentBranchName added in v1.35.0 

func GetCurrentBranchName(path string) (string, error)

GetCurrentBranchName returns the current branch name for a git repository or worktree. Returns an error if the repo is in detached HEAD state.

func GetHeadCommitSHA added in v1.37.0 

func GetHeadCommitSHA(path string) (string, error)

GetHeadCommitSHA returns the SHA of the HEAD commit for a git repository or worktree.

func InitializeProjectDirectory added in v1.35.0 

func InitializeProjectDirectory(path string) error

InitializeProjectDirectory creates a directory and initializes it as a git repository. Behavior by pre-existing state:

  • Path does not exist: creates with os.MkdirAll(path, 0755), runs git init, commits.
  • Path exists, no .git: runs git init in place, commits.
  • Path exists, already a git repo: no-op, returns nil.
  • Path exists but is a regular file: returns an error.

On partial failure (dir created, git init failed): attempts os.RemoveAll to roll back the newly created directory. Logs a warning if rollback also fails.

func IsCommitOnMain added in v1.39.0 

func IsCommitOnMain(repoPath, mainBranch, sha string) (bool, error)

IsCommitOnMain reports whether sha has actually landed on mainBranch — either the local branch (a commit merged directly to main without ever going through a PR) or origin's copy (a PR merged remotely on GitHub that hasn't been pulled locally yet). Approval (a passing review verdict) and shipping are different questions; this answers only the second one, and does so by checking ancestry rather than trusting any cached "PR merged" flag, since that flag can be stale, absent (no PR was ever opened), or simply wrong for a manually-merged branch.

Uses go-git rather than shelling out (repo convention — see the `prefer-go-git-over-subshells` skill). The origin fetch is best-effort: a failure (offline, no such remote, nothing new) does not fail the whole check, since the local-main check alone still answers the "merged directly to main locally" case.

func IsGitRepo 

func IsGitRepo(path string) bool

IsGitRepo checks if the given path is within a git repository

func IsUnbornRepo added in v1.48.0 

func IsUnbornRepo(repoPath string) bool

IsUnbornRepo reports whether repoPath is a git repository with zero commits (HEAD points at a branch ref that doesn't exist yet, e.g. right after `git init`). Distinct from "no candidate default branch found": that can also mean a repo with real commit history whose default branch just isn't named main/master/develop/trunk, which is not safe to fall back to ambient HEAD for (see CreateBacklogWorktree). An unborn repo has no commit history at all, so there is nothing to misattribute either way.

func OpenRepo added in v1.51.0 

func OpenRepo(path string) (*git.Repository, error)

OpenRepo opens the git repository or worktree at path using defaultPlainOpenOptions. Every git repository open in this codebase must go through this function rather than a bare git.PlainOpen/PlainOpenWithOptions call — see tools/lint's norawgitopen analyzer, which enforces this.

func PreviewWorktreePath added in v1.41.0 

func PreviewWorktreePath(repoPath, sessionName string) (string, error)

PreviewWorktreePath returns the directory PREFIX a new worktree would be created under - the same filepath.Join(worktreeDir, sanitizeBranchName(sessionName)) that NewGitWorktreeWithBranchAndExecutor computes, WITHOUT the "_<random-suffix>" it appends at actual creation time (that suffix can't be predicted ahead of the call). Performs no git subprocess calls (deliberately skips the existing-worktree-for-branch lookup, which shells out to "git worktree list") and, unlike findGitRepoRoot, never mutates the filesystem: it only walks up from repoPath looking for an existing git repo. A preview is called on every Omnibar keystroke, so it must be a pure read - it must not create directories, run `git init`, or create commits the way findGitRepoRoot's create-if-missing fallback does for the real creation path.

func RemoteURL added in v1.37.0 

func RemoteURL(repoPath, remote string) (string, error)

RemoteURL returns the URL of the named remote (usually "origin") for a local repo.

func ResolveDefaultBranchSHA added in v1.48.0 

func ResolveDefaultBranchSHA(repoPath string) (branch, sha string, err error)

ResolveDefaultBranchSHA finds repoPath's real default branch and returns its freshly- fetched origin tip SHA, trying CandidateDefaultBranches in order via ResolveOriginBranchSHA until one exists on origin. Exists because a repo's default branch can be named anything (this repo's own sibling dotfiles project uses "master", not "main") — a caller that hardcodes "main" gets a fetch failure on every single call against such a repo, which used to silently fall through to branching from the caller's ambient HEAD instead. Querying each candidate by fetch (rather than inspecting locally-cached remote-tracking refs) works even when the repo has never been fetched before, since a nonexistent branch fails fast at the fetch step itself.

func ResolveDefaultLocalBranchSHA added in v1.48.0 

func ResolveDefaultLocalBranchSHA(repoPath string) (branch, sha string, err error)

ResolveDefaultLocalBranchSHA is ResolveDefaultBranchSHA's fully-offline counterpart: tries CandidateDefaultBranches against repoPath's own local refs (no fetch), for use when every origin candidate fetch has already failed.

func ResolveLocalBranchSHA added in v1.48.0 

func ResolveLocalBranchSHA(repoPath, branchName string) (string, error)

ResolveLocalBranchSHA returns the tip commit SHA of the local branch (refs/heads/<branchName>) in repoPath, without fetching. Used as a same-branch-only fallback when ResolveOriginBranchSHA's fetch fails (offline, no origin remote) — still guarantees the caller branches from branchName itself, just not guaranteed fresh, unlike falling back to repoPath's ambient HEAD which could be checked out to any branch a concurrent process last left it on.

func ResolveOriginBranchSHA added in v1.42.0 

func ResolveOriginBranchSHA(repoPath, mainBranch string) (string, error)

ResolveOriginBranchSHA fetches mainBranch from origin into repoPath and returns the resulting origin/mainBranch tip commit SHA. Unlike a bare `rev-parse HEAD` against repoPath's own checkout, this always fetches first, so the returned SHA reflects origin's true current tip rather than whatever repoPath happened to have checked out last — the gap that let a new backlog work session's worktree branch from a days-stale local checkout instead of the real main tip (see setupNewWorktree's "branch from current HEAD" comment, and CreateBacklogWorktree's use of this func).

func SanitizeBranchName added in v1.47.0 

func SanitizeBranchName(s string) string

SanitizeBranchName exports sanitizeBranchName for callers outside this package that need the same safe-subset transform for a remote worktree directory name (server/services/session_service.go's CreateSession mode-specific block, ssh-remote-workspaces Phase 4 Epic 4.2) as this package already applies to local branch/directory names -- including its path-traversal-segment stripping, which matters just as much for a remote `path.Join(base_path, name)` as it does for the local filepath.Join call sites in this file.

func UntrackScaffolding added in v1.41.0 

func UntrackScaffolding(worktreePath string, patterns []string) ([]string, error)

UntrackScaffolding removes any git index entry matching patterns (git-rm-cached semantics: the working-tree file is left alone, only the index entry is dropped) and returns the list of paths it untracked. Uses go-git directly against the index rather than shelling out to `git rm --cached`, per the `prefer-go-git-over-subshells` skill.

Returns (nil, nil) — not an error — when worktreePath isn't a git repository at all (e.g. a directory-mode session with no git backing), matching the best-effort, non-fatal handling the rest of this package uses for that case.

func WithRepoWorktreeLock added in v1.43.0 

func WithRepoWorktreeLock(repoPath string, fn func() error) error

WithRepoWorktreeLock serializes fn against every other goroutine and OS process (on this machine) operating on repoPath's git worktree metadata. See repoWorktreeLock's doc comment for why both mu and flock are required.

Exported so callers outside this package that need to run other repoPath-mutating work (e.g. session.RepairCorruptedGitRepo's destructive re-clone) in the same critical section as a GitWorktree.Setup()/Remove() can do so via GitWorktree.SetupLocked() — see that method's doc comment for the race this closes.

Types

type AggregateDiffStat added in v1.49.0 

type AggregateDiffStat struct {
	FilesChanged int
	Additions    int
	Deletions    int
}

AggregateDiffStat is the files-changed/additions/deletions summary returned by DiffStatBetween — a DiffShortstat-equivalent for a branch's range vs. its base. Distinct from DiffStats (session/git/diff.go), which holds working-tree diff content, not a committed-range summary.

func DiffStatBetween added in v1.49.0 

func DiffStatBetween(ctx context.Context, repoPath, baseSHA, headSHA string) (AggregateDiffStat, error)

DiffStatBetween returns the aggregate files-changed/additions/deletions between baseSHA and headSHA, summing FileStatsBetween's per-file counts. ctx only guards against starting once the caller's deadline has passed — FileStatsBetween's go-git patch computation takes no ctx, so this can't bound a hang mid-computation.

type BranchStatus added in v1.39.0 

type BranchStatus struct {
	// BranchExists is false once the branch has been deleted (e.g. after a
	// "delete branch on merge" or manual cleanup). AheadOfMain/BehindMain are
	// only meaningful when true.
	BranchExists bool
	AheadOfMain  int
	BehindMain   int
}

BranchStatus describes branchName's position relative to mainBranch.

func BranchAheadBehind added in v1.39.0 

func BranchAheadBehind(repoPath, branchName, mainBranch string) (BranchStatus, error)

BranchAheadBehind reports branchName's commit position relative to mainBranch: how many commits are on the branch but not on main (ahead), and vice versa (behind) — mirroring `git rev-list --left-right --count branch...main`. Checks the local branch ref only; a branch already deleted locally reports BranchExists=false rather than an error, since that's the expected state for a shipped, cleaned-up item, not a failure.

type DiffStats 

type DiffStats struct {
	// Content is the full diff content
	Content string
	// Added is the number of added lines
	Added int
	// Removed is the number of removed lines
	Removed int
	// Error holds any error that occurred during diff computation
	// This allows propagating setup errors (like missing base commit) without breaking the flow
	Error error
}

DiffStats holds statistics about the changes in a diff

func DiffContentBetween added in v1.51.0 

func DiffContentBetween(repoPath, baseSHA, headSHA string) (*DiffStats, error)

DiffContentBetween returns the unified-diff text and added/removed line counts between baseSHA and headSHA (both resolved as commits, not the working tree — equivalent to `git diff baseSHA..headSHA`), using go-git's typed diff API instead of a safeexec shell-out (the `prefer-go-git-over-subshells` skill). Distinct from GitWorktree.Diff (session/git/diff.go), which diffs the working tree against a single ref (via `git add -N .` + `git diff <sha>`) and has no go-git equivalent — see that function's doc comment for why the shell-out stays there.

func (*DiffStats) IsEmpty 

func (d *DiffStats) IsEmpty() bool

type FileStat added in v1.39.0 

type FileStat struct {
	Path      string
	Status    string
	Additions int
	Deletions int
}

FileStat describes one file's change between two commits, as returned by FileStatsBetween. Path is the file's path as of headSHA — for a rename this is the new path, not the old one. Status is one of "added", "deleted", "renamed", or "modified".

func FileStatsBetween added in v1.39.0 

func FileStatsBetween(repoPath, baseSHA, headSHA string) ([]FileStat, error)

FileStatsBetween returns the per-file diff-stat summary (path, status, additions, deletions) for every file that changed between baseSHA and headSHA in the repo at repoPath, using go-git's typed diff API — no safeexec shell-out (the `prefer-go-git-over-subshells` skill).

Renames are reported as a single entry keyed by the file's new path, not a delete+add pair: go-git's FilePatch.Files() already exposes the from/to path pair needed to detect this directly, so unlike object.Patch.Stats() (whose FileStat.Name collapses a rename into a single "old => new" display string) this walks Patch.FilePatches() itself to keep the old and new paths distinct. Binary files are silently omitted — go-git produces zero diff chunks for them (the same signal it uses to skip submodule-ref-only changes), so there is no meaningful addition/deletion count to report; this mirrors go-git's own Stats() behavior rather than the "0/0 entry" shape one might expect, a discrepancy confirmed against go-git v5.14.0's source (getFileStatsFromFilePatches in plumbing/object/patch.go) and a throwaway spike before this function was written.

type GitWorktree 

type GitWorktree struct {
	// contains filtered or unexported fields
}

GitWorktree manages git worktree operations for a session

func NewGitWorktree 

func NewGitWorktree(repoPath string, sessionName string, opts ...GitWorktreeOption) (tree *GitWorktree, branchname string, err error)

NewGitWorktree creates a new GitWorktree instance

func NewGitWorktreeFromCommitSHA 

func NewGitWorktreeFromCommitSHA(repoPath, sessionName, branchName, commitSHA string, opts ...GitWorktreeOption) (*GitWorktree, string, error)

NewGitWorktreeFromCommitSHA creates a new GitWorktree that will branch from the given commitSHA when Setup() is called, instead of branching from the current HEAD. This is used by ForkFromCheckpoint to recreate the exact git state at checkpoint time.

func NewGitWorktreeFromExisting 

func NewGitWorktreeFromExisting(existingWorktreePath string, sessionName string, opts ...GitWorktreeOption) (*GitWorktree, error)

NewGitWorktreeFromExisting creates a GitWorktree from an existing worktree path This is used when connecting to worktrees that were created manually or by deleted sessions

func NewGitWorktreeFromExistingWithExecutor 

func NewGitWorktreeFromExistingWithExecutor(existingWorktreePath string, sessionName string, opts ...GitWorktreeOption) (*GitWorktree, error)

NewGitWorktreeFromExistingWithExecutor creates a GitWorktree from an existing worktree path. The "WithExecutor" name predates CommandRunner (ADR-002) — see NewGitWorktreeFromStorageWithExecutor's doc comment; use WithCommandRunner to override how this worktree's subprocesses run.

func NewGitWorktreeFromStorage 

func NewGitWorktreeFromStorage(repoPath string, worktreePath string, sessionName string, branchName string, baseCommitSHA string, opts ...GitWorktreeOption) *GitWorktree

func NewGitWorktreeFromStorageWithExecutor 

func NewGitWorktreeFromStorageWithExecutor(repoPath string, worktreePath string, sessionName string, branchName string, baseCommitSHA string, opts ...GitWorktreeOption) *GitWorktree

NewGitWorktreeFromStorageWithExecutor creates a GitWorktree from stored data. The "WithExecutor" name predates CommandRunner (ADR-002): this used to also accept an optional executor.Executor parameter, removed once runGitCommand's last executor.Executor-gated branch was migrated onto CommandRunner and nothing else in the package read it (see ADR-002's addendum) — use WithCommandRunner instead to override how this worktree's subprocesses run.

func NewGitWorktreeWithBranch 

func NewGitWorktreeWithBranch(repoPath string, sessionName string, customBranch string, opts ...GitWorktreeOption) (tree *GitWorktree, branchname string, err error)

NewGitWorktreeWithBranch creates a new GitWorktree instance with an optional custom branch name

func NewGitWorktreeWithBranchAndExecutor 

func NewGitWorktreeWithBranchAndExecutor(repoPath string, sessionName string, customBranch string, opts ...GitWorktreeOption) (tree *GitWorktree, branchname string, err error)

NewGitWorktreeWithBranchAndExecutor creates a new GitWorktree with an optional branch name. The "WithExecutor" name predates CommandRunner (ADR-002) — see NewGitWorktreeFromStorageWithExecutor's doc comment; use WithCommandRunner to override how this worktree's subprocesses run.

func (*GitWorktree) Cleanup 

func (g *GitWorktree) Cleanup() error

Cleanup removes the worktree. It deliberately does NOT delete the branch: branch deletion via go-git's RemoveReference is not a "safe if merged" check, it is unconditional, and a branch can hold commits that exist nowhere else (never pushed, never merged). Silently destroying those on session teardown was a live bug — see docs/tasks/backlog-feature-improvement.md ("stop_session silently deletes the git branch"). A leftover local branch ref costs nothing; a lost commit is not recoverable through this code path. Equivalent to Remove() — kept as a separate method so callers don't need to know the two used to differ.

func (*GitWorktree) ClosePR added in v1.41.0 

func (g *GitWorktree) ClosePR(prNumber int, comment string) error

ClosePR closes prNumber without merging, posting comment as an explanatory PR comment first. Used when a PR is discovered to be superseded (its branch's work already landed on main through a different path) rather than genuinely broken — see BUG-032.

func (*GitWorktree) CommitChanges 

func (g *GitWorktree) CommitChanges(commitMessage string) error

CommitChanges commits changes locally without pushing to remote

func (*GitWorktree) CreatePR added in v1.37.0 

func (g *GitWorktree) CreatePR(opts PRCreateOptions) (prURL string, prNumber int, err error)

CreatePR creates a GitHub pull request for the current branch and returns the PR URL and number. If a PR already exists for the branch it is returned without creating a new one.

func (*GitWorktree) Diff 

func (g *GitWorktree) Diff() *DiffStats

Diff returns the git diff between the worktree and the base branch along with statistics

func (*GitWorktree) EnablePRAutoMerge added in v1.37.0 

func (g *GitWorktree) EnablePRAutoMerge(prNumber int) error

EnablePRAutoMerge enables GitHub auto-merge on the given PR so it merges automatically once required CI checks pass. Best-effort: fails silently when the repo does not have auto-merge enabled in its branch protection rules.

func (*GitWorktree) GetBaseCommitSHA 

func (g *GitWorktree) GetBaseCommitSHA() string

GetBaseCommitSHA returns the base commit SHA for the worktree

func (*GitWorktree) GetBranchName 

func (g *GitWorktree) GetBranchName() string

GetBranchName returns the name of the branch associated with this worktree

func (*GitWorktree) GetPRStatus added in v1.37.0 

func (g *GitWorktree) GetPRStatus(prNumber int) (*PRStatus, error)

GetPRStatus fetches the combined CI check status, reviewer decisions, mergeability, and PR comments for the given pull request number.

func (*GitWorktree) GetRepoName 

func (g *GitWorktree) GetRepoName() string

GetRepoName returns the name of the repository (last part of the repoPath).

func (*GitWorktree) GetRepoPath 

func (g *GitWorktree) GetRepoPath() string

GetRepoPath returns the path to the repository

func (*GitWorktree) GetWorktreePath 

func (g *GitWorktree) GetWorktreePath() string

GetWorktreePath returns the path to the worktree

func (*GitWorktree) HasCommitsAheadOfMain added in v1.41.0 

func (g *GitWorktree) HasCommitsAheadOfMain(mainBranch string) (bool, error)

HasCommitsAheadOfMain reports whether this worktree's branch has at least one commit not present on mainBranch — i.e. whether there is genuinely anything to ship. Used as a pre-flight check before attempting CreatePR: a branch with zero commits ahead of main makes `gh pr create` fail with "No commits between X and Y", which is not a retryable push/PR failure (see BUG-063) but a signal that the item was already fully addressed elsewhere. Returns true (the safe, existing default: attempt PR creation as before) if the check itself is inconclusive — an error opening the repo, or the branch not existing locally — so a check failure never causes a caller to skip PR creation for a branch that may well need it.

func (*GitWorktree) HasStagedChanges added in v1.41.0 

func (g *GitWorktree) HasStagedChanges() (bool, error)

HasStagedChanges reports whether the git index differs from HEAD — i.e. whether a commit right now would actually record anything. Used after StageAllExceptScaffolding so a commit whose only staged change was a just-untracked scaffolding file is skipped gracefully instead of failing on "nothing to commit".

func (*GitWorktree) InvalidateDirtyCache added in v1.22.0 

func (g *GitWorktree) InvalidateDirtyCache()

InvalidateDirtyCache clears the IsDirty cache so the next call re-runs git status. Call this whenever worktree state changes outside of Claude's control (e.g. after a manual commit, after running git operations, or in tests after writing files directly).

func (*GitWorktree) IsBranchCheckedOut 

func (g *GitWorktree) IsBranchCheckedOut() (bool, error)

IsBranchCheckedOut checks if the instance branch is currently checked out. Uses go-git to read HEAD directly (no subprocess).

func (*GitWorktree) IsDirty 

func (g *GitWorktree) IsDirty() (bool, error)

IsDirty checks if the worktree has uncommitted changes. Results are cached for IsDirtyCacheTTL (dirty) or IsDirtyCleanCacheTTL (clean).

func (*GitWorktree) IsDirtyWithHint added in v1.22.0 

func (g *GitWorktree) IsDirtyWithHint(claudeActive bool) (bool, error)

IsDirtyWithHint checks if the worktree has uncommitted changes. When claudeActive is true the subprocess is skipped entirely and the cached value is returned (or false if no cached value is available yet), because Claude never modifies worktree state while it is actively generating output.

func (*GitWorktree) IsPRMerged added in v1.37.0 

func (g *GitWorktree) IsPRMerged(prNumber int) (bool, error)

IsPRMerged reports whether the given PR number has been merged.

func (*GitWorktree) OpenBranchURL 

func (g *GitWorktree) OpenBranchURL() error

OpenBranchURL opens the branch URL in the default browser

func (*GitWorktree) PrimeDirtyCacheAt added in v1.35.0 

func (g *GitWorktree) PrimeDirtyCacheAt(t time.Time)

PrimeDirtyCacheAt sets the dirty-cache timestamp to t without running git status. Use this to stagger per-session cache expiry so sessions added to the poller within a short window don't all expire simultaneously and burst-launch git subprocesses.

func (*GitWorktree) Prune 

func (g *GitWorktree) Prune() error

Prune removes all working tree administrative files and directories. Serialized per-repoPath like Setup/Remove — it rewrites the same shared .git/worktrees/ metadata.

func (*GitWorktree) PushBranch added in v1.37.0 

func (g *GitWorktree) PushBranch() error

func (*GitWorktree) PushChanges 

func (g *GitWorktree) PushChanges(commitMessage string, open bool) error

PushChanges commits and pushes changes in the worktree to the remote branch

func (*GitWorktree) Remove 

func (g *GitWorktree) Remove() error

Remove removes the worktree but keeps the branch. Serialized per-repoPath like Setup — it prunes and removes shared .git/worktrees/ administrative metadata, the same resource Setup's branch-check + add dispatch touches.

func (*GitWorktree) RenameBranch added in v1.42.0 

func (g *GitWorktree) RenameBranch(newBranchName string) error

RenameBranch renames the worktree's current branch in place (git branch -m) and updates g.branchName to match. Used to move a worktree created under a provisional name onto the final branch name once it's known, without losing the worktree's existing content or commits — e.g. TriggerTriage names its worktree before the LLM call reveals the item's slug, then renames it afterward to the same "backlog/<item>" branch a later SpawnSessionFromItem will look for.

func (*GitWorktree) RequestCopilotReview added in v1.41.0 

func (g *GitWorktree) RequestCopilotReview(prNumber int) error

RequestCopilotReview requests a GitHub Copilot code review on prNumber. Best-effort: fails when Copilot code review isn't enabled for the org/repo, or on any other gh error — callers must not fail PR creation on this error. Uses the legacy bot-login form (copilot-pull-request-reviewer[bot]) via --add-reviewer rather than the newer @copilot alias, since the literal login is accepted by every gh version this repo targets while the alias is version-gated (see plan.md's Pattern Decisions table).

func (*GitWorktree) Setup 

func (g *GitWorktree) Setup() error

Setup creates a new worktree for the session. The entire branch-check + add/reuse dispatch is serialized per-repoPath (across goroutines and OS processes) because git worktree add mutates shared .git/worktrees/ administrative metadata that is not safe under concurrent access -- see WithRepoWorktreeLock.

func (*GitWorktree) SetupLocked added in v1.43.0 

func (g *GitWorktree) SetupLocked() error

SetupLocked runs the same setup logic as Setup but assumes the caller already holds repoPath's worktree lock (via WithRepoWorktreeLock) -- e.g. because the caller needs to run other repoPath-mutating work (like a corrupted-repo repair/re-clone) in the very same critical section, immediately before the worktree add. Calling this without already holding the lock defeats the cross-process guarantee Setup() normally provides. See session.CreateBacklogWorktree for the motivating caller and the race this closes: without it, one process's unlocked repo repair (os.RemoveAll + re-clone) could delete/recreate repoPath's working tree while a concurrent process was mid-way through the locked `git worktree add` for the same repoPath, plausibly surfacing as git's generic "fatal: failed to resolve HEAD as a valid ref".

func (*GitWorktree) StageAllExceptScaffolding added in v1.41.0 

func (g *GitWorktree) StageAllExceptScaffolding() error

StageAllExceptScaffolding stages all worktree changes (`git add .`) and then untracks any staged path matching ScaffoldingExcludePatterns, so backlog automation scaffolding files (.backlog-context.md, .claude/commands/backlog/*) don't get (re)committed even if they were already tracked in this branch's history — gitignore/info-exclude rules only stop a NEW path from being staged, not one that's already in the index (see UntrackScaffolding's doc comment). Deliberately fails open on the untrack step (logs and continues rather than blocking a real commit) — the CI backstop workflow (.github/workflows/backlog-scaffolding-guard.yml) is the second, independent layer for the rare case where the untrack step itself errors.

type GitWorktreeOption added in v1.47.0 

type GitWorktreeOption func(*GitWorktree)

GitWorktreeOption is a functional option for GitWorktree construction, mirroring session/tmux's TmuxSessionOption. Trailing/variadic on every constructor that builds a *GitWorktree, so existing call sites are unaffected.

func WithCommandRunner added in v1.47.0 

func WithCommandRunner(r tmux.CommandRunner) GitWorktreeOption

WithCommandRunner injects a CommandRunner, overriding the tmux.LocalRunner{} default every constructor otherwise applies. Used to swap in a remote-backed CommandRunner (Phase 2 of ssh-remote-workspaces) or a test spy that records/controls what the worktree's git/gh subprocess calls do.

type MergeMainResult added in v1.39.0 

type MergeMainResult struct {
	// UpToDate is true when the worktree's branch already contained everything
	// from mainBranch — nothing was merged in.
	UpToDate bool
	// Merged is true when the merge (including a fast-forward) brought in new
	// commits from mainBranch.
	Merged bool
	// Conflicted is true when merging mainBranch produced conflicts. The merge is
	// always aborted before returning, so the worktree is left clean either way —
	// callers never have to clean up a half-merged tree.
	Conflicted bool
	// ConflictedFiles lists the paths that conflicted. Populated only when
	// Conflicted is true.
	ConflictedFiles []string
}

MergeMainResult describes the outcome of MergeMainIntoWorktree.

func MergeMainIntoWorktree added in v1.39.0 

func MergeMainIntoWorktree(worktreePath, mainBranch string) (*MergeMainResult, error)

MergeMainIntoWorktree fetches mainBranch from origin and merges it into whatever branch is currently checked out in worktreePath. It never leaves the worktree in a conflicted state: on conflict it aborts the merge immediately (via `git merge --abort`) and reports the conflicting paths, so the caller can hand that context to whoever resolves it rather than leaving a half-merged working tree behind for the next thing that touches it.

type PRCreateOptions added in v1.47.0 

type PRCreateOptions struct {
	// Title defaults to the branch name (with hyphens replaced by spaces) if empty.
	Title string
	Body  string
	// BaseBranch, if non-empty, is passed to `gh pr create --base`; if empty,
	// gh's own default-branch resolution is used (preserves pre-existing
	// behavior for every caller that doesn't care which branch it targets).
	BaseBranch string
}

PRCreateOptions bundles CreatePR's arguments. Title, Body, and BaseBranch are all plain strings with no compiler-enforced distinction between them, so a transposed call (e.g. body and baseBranch swapped) would previously compile silently wrong — the exact smell the `primitive-obsession-checklist` skill exists to catch. A named field wins that transposition back at every call site.

type PRStatus added in v1.37.0 

type PRStatus struct {
	// CIFailing is true when at least one CI check has a terminal failure.
	CIFailing bool
	// HasBlockingReviews is true when a reviewer has requested changes.
	HasBlockingReviews bool
	// HasConflicts is true when GitHub reports mergeStateStatus == "DIRTY" or
	// mergeable == "CONFLICTING" — its branch cannot be merged as-is and needs
	// a rebase. Both fields are checked (see Task 1.1.1d) because gh's
	// mergeable field has been observed returning stale data (cli/cli#9583).
	HasConflicts bool
	// IsClosed is true when the PR's state is CLOSED (rejected by a human without
	// merging) rather than OPEN or MERGED. Callers must check this before treating
	// "not merged" as "still open and healthy" — a closed PR will never merge on
	// its own no matter how long ReconcilePRPending keeps polling it.
	IsClosed bool
	// IsDraft is true when the PR is still marked draft on GitHub. Captured from
	// the same gh pr view call as everything else on this struct (no second API
	// call) so callers such as the backlog stuck-item detector (prReadyToMergeSolo)
	// can gate on it without an extra fetch.
	IsDraft bool
	// Mergeable is the raw upper-cased GitHub `mergeable` field ("MERGEABLE",
	// "CONFLICTING", or "UNKNOWN"). HasConflicts is the belt-and-suspenders
	// bool derived from this plus mergeStateStatus (see above); Mergeable is
	// exposed separately for callers (prReadyToMergeSolo) that want the literal
	// "MERGEABLE" check called out in ADR-001 rather than the inverse-of-conflict
	// approximation.
	Mergeable string
	// ApprovedCount is the number of current non-dismissed APPROVED reviews.
	ApprovedCount int
	// ChangesRequestedCount is the number of current non-dismissed
	// CHANGES_REQUESTED reviews (equivalently, len of the reviews backing
	// HasBlockingReviews — exposed as a count so callers building a
	// github.PRInfo-shaped value don't need to re-derive it from the bool).
	ChangesRequestedCount int
	// HasReviewFeedback is true when at least one substantive COMMENTED-state
	// review or substantive plain PR comment exists (Copilot's typical review
	// posture is COMMENTED, not CHANGES_REQUESTED, so this is a distinct signal
	// from HasBlockingReviews). Non-substantive feedback (bare "lgtm", empty,
	// or whitespace-only bodies) never sets this.
	HasReviewFeedback bool
	// LatestFeedbackAt is the newest GitHub-assigned submittedAt/createdAt
	// timestamp among all substantive feedback captured this call; the zero
	// value when HasReviewFeedback is false. Callers use this as the dedup
	// watermark comparison point (see ReconcilePRPending's hasNewFeedback).
	LatestFeedbackAt time.Time
	// FeedbackText is a combined human-readable summary for the fix agent.
	FeedbackText string
	// contains filtered or unexported fields
}

PRStatus holds the CI, review, and conflict state for a pull request.

func ParsePRStatusPayload added in v1.41.0 

func ParsePRStatusPayload(raw []byte) (*PRStatus, error)

ParsePRStatusPayload parses gh pr view's combined JSON output into a PRStatus. Exported so callers outside this package (e.g. session/backlog_lifecycle_test.go's ReconcilePRPending fixtures) can build a *PRStatus with commentReviews/generalComments genuinely populated — FeedbackAuthors() depends on those unexported fields, which a struct literal from another package cannot set directly.

func (*PRStatus) FeedbackAuthors added in v1.41.0 

func (s *PRStatus) FeedbackAuthors() []string

FeedbackAuthors returns one author login per countable feedback item (COMMENTED reviews plus countableGeneralComments) captured this call — NOT deduplicated, so the same login appears once per item they authored. Callers use len() of this slice as an item count and the logins as an author list for a single hasNewFeedback-triggered dispatch, since a partially-addressed multi-item batch is otherwise silently unresolved forever once the dedup watermark advances past the whole batch.

type RemoteWorktree added in v1.47.0 

type RemoteWorktree struct {
	// RepoPath is the existing repository on the remote host that `git worktree
	// add`/`remove` runs against (the CommandRunner.Run "dir" argument).
	RepoPath string
	// WorktreePath is the new worktree's own directory. Its parent directory is
	// the "base_path" CreateWorktree existence-checks before creating anything.
	WorktreePath string
	// Branch is the (already-existing) branch CreateWorktree checks out into the
	// new worktree. CreateWorktree does not create the branch itself — mirroring
	// GitWorktree's setupFromExistingBranch `git worktree add <path> <branch>`
	// shape (worktree_ops.go), not the `-b <branch>` new-branch shape.
	Branch string
}

RemoteWorktree identifies one git worktree on a remote host: the existing repository it is attached to (RepoPath — what `git worktree add`/`remove` runs against, mirroring GitWorktree.repoPath) and the worktree's own directory (WorktreePath — mirroring GitWorktree.worktreePath). Branch is the branch CreateWorktree checks out into the new worktree; it is ignored by RemoveWorktree. RepoPath and WorktreePath are bundled into this single value object rather than passed as separate positional string parameters so a caller can't silently transpose them at the call site (the `primitive-obsession-checklist` skill).

type RemoteWorktreeOps added in v1.47.0 

type RemoteWorktreeOps struct {
	// contains filtered or unexported fields
}

RemoteWorktreeOps performs git worktree creation, removal, and new-project initialization on a remote host, executed entirely through an injected tmux.CommandRunner (session/tmux, reused here per ADR-002 — see session/git/worktree.go's runner field doc comment for the same pattern applied to GitWorktree). It mirrors ops.go's free-function shape (explicit path/branch parameters, no persisted per-worktree state) rather than GitWorktree's stateful builder shape, since — unlike GitWorktree, which owns exactly one worktree's lifecycle — a single RemoteWorktreeOps is meant to be reused across many worktrees on the same remote CommandRunner.

func NewRemoteWorktreeOps added in v1.47.0 

func NewRemoteWorktreeOps(runner tmux.CommandRunner) *RemoteWorktreeOps

NewRemoteWorktreeOps constructs a RemoteWorktreeOps that runs every command through runner (a *tmux.SSHRunner in production, tmux.LocalRunner{} or a test spy in tests).

func (*RemoteWorktreeOps) CreateWorktree added in v1.47.0 

func (r *RemoteWorktreeOps) CreateWorktree(ctx context.Context, w RemoteWorktree) error

CreateWorktree runs `git worktree add <WorktreePath> <Branch>` on the remote host via the injected CommandRunner, mirroring GitWorktree.setupFromExistingBranch's argument construction (worktree_ops.go's `g.runGitCommand(g.repoPath, "worktree", "add", g.worktreePath, g.branchName)`) and returning the same result shape (an error only — the worktree's path is already known to the caller via w.WorktreePath, exactly as GitWorktree.Setup() returns only an error since the path is already stored on the receiver).

Before running `git worktree add`, this checks that w.WorktreePath's parent directory ("base_path") exists via `test -d <base_path>`, returning ErrRemoteBasePathMissing (not a generic git error) if it does not. This check is advisory only, not atomic with the add that follows (see ErrRemoteBasePathMissing's doc comment) — it exists to give a fast, distinguishable error for the common case (base_path never existed / was never mounted), not as a guarantee against a race with something removing it in between.

func (*RemoteWorktreeOps) InitializeProjectDirectory added in v1.47.0 

func (r *RemoteWorktreeOps) InitializeProjectDirectory(ctx context.Context, projectPath string) error

InitializeProjectDirectory mirrors session.SessionTypeNewProject's local init flow (InitializeProjectDirectory in util.go, driven by session/instance_worktree.go's setupFirstTimeWorktree) on a remote host: a no-op if projectPath is already a git repo, otherwise create the directory, `git init`, and make an initial commit (git worktrees need at least one commit to exist before a worktree can be added against them).

The whole flow is shelled as a single `sh -c <script>` CommandRunner.Run call rather than several separate Run calls, for two reasons: (1) writing .gitignore's content requires shell output redirection ('> .gitignore'), which CommandRunner.Run cannot express directly — Run has no stdin parameter to pipe content through (see command_runner.go's doc comment: only Start is piped, and only for the one long-lived control-mode case), and buildRemoteCommand shell-quotes each argument individually, so passing '>' as a bare Run argument would reach the remote as a literal, inert string rather than a shell operator; (2) it keeps this to one round trip against what may be a slow remote link, rather than five.

The already-a-repo check tests for a ".git" entry directly under projectPath (`[ -e .git ]` after cd, not `-d`: a git worktree's ".git" is a *file* containing a `gitdir:` pointer, not a directory) rather than `git rev-parse --is-inside-work-tree`, which walks UP the directory tree looking for the nearest .git — that would wrongly report "already a repo" for a projectPath nested inside some unrelated ancestor repository. This matches go-git's PlainOpen(path) semantics (no DetectDotGit, so no upward search; and PlainOpen itself accepts either a .git directory or a .git file), which is what the local InitializeProjectDirectory uses for its own no-op check.

Deliberately simpler than the local flow's rollback-on-failure behavior (which os.RemoveAll's the directory it created if `git init` or the initial commit fails): there is no local os.RemoveAll equivalent here cheap enough to add safely — embedding an `rm -rf` in a remote script is exactly the kind of command this package should be conservative about — and there is no production caller of this method yet (Epic 2.2 wires no caller; Phase 4 is where remote SessionTypeNewProject support would consume it). A failed remote init can leave a partially-initialized directory behind for a caller/operator to inspect or retry against.

func (*RemoteWorktreeOps) RemoveWorktree added in v1.47.0 

func (r *RemoteWorktreeOps) RemoveWorktree(ctx context.Context, w RemoteWorktree) error

RemoveWorktree runs `git worktree remove <WorktreePath> --force` on the remote host via the injected CommandRunner, mirroring CreateWorktree's argument construction. Callers use this as best-effort compensating cleanup (Task 4.2.1e's partial-failure handling, adversarial-review.md Blocker 3: if remote tmux setup fails after CreateWorktree already succeeded, or the SSH connection drops between the two steps, the orchestrating caller attempts this before surfacing the *original* error) — "best-effort" describes how a caller should treat this method's return value (log and continue, don't let a cleanup failure mask the real error), not behavior internal to this method itself, which always reports its own failures rather than swallowing them.

type ShippedCommit added in v1.39.0 

type ShippedCommit struct {
	SHA        string
	Summary    string // first line of the commit message
	AuthorAt   time.Time
	AuthorName string
}

ShippedCommit describes one commit in the range shipped by a work session.

func CommitInfo added in v1.41.0 

func CommitInfo(repoPath, sha string) (ShippedCommit, error)

CommitInfo returns the summary line, author and author timestamp for a single resolved commit hash in the repo at repoPath, read via go-git — no subshell (the `prefer-go-git-over-subshells` skill).

func ListShippedCommits added in v1.39.0 

func ListShippedCommits(ctx context.Context, repoPath, baseSHA, headSHA string) (commits []ShippedCommit, truncated bool, err error)

ListShippedCommits returns the commits reachable from headSHA but not from baseSHA — i.e. what a work session's commit range actually shipped — newest first, like a PR's "Commits" tab. Both SHAs must already be resolved commit hashes (not branch names): the caller typically has these directly from GitWorktreeData.BaseCommitSHA and the work session's LastCommitSha, which remain valid even after the branch itself has been deleted post-merge. truncated reports whether the walk hit listShippedCommitsCap before exhausting the range — the caller may want to surface that a longer list exists than what's returned.

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.