git

package
v1.46.0 Latest Latest
Warning

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

 Go to latest Published: Aug 20, 2026 License: AGPL-3.0 Imports: 28 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 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 .claude/rules/prefer-go-git-over-subshells.md). 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 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 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 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 .claude/rules/prefer-go-git-over-subshells.md.

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 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 (*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 (.claude/rules/prefer-go-git-over-subshells.md).

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) (tree *GitWorktree, branchname string, err error)

NewGitWorktree creates a new GitWorktree instance

func NewGitWorktreeFromCommitSHA 

func NewGitWorktreeFromCommitSHA(repoPath, sessionName, branchName, commitSHA string) (*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) (*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, cmdExec executor.Executor) (*GitWorktree, error)

NewGitWorktreeFromExistingWithExecutor creates a GitWorktree from an existing worktree path with an optional executor.

func NewGitWorktreeFromStorage 

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

func NewGitWorktreeFromStorageWithExecutor 

func NewGitWorktreeFromStorageWithExecutor(repoPath string, worktreePath string, sessionName string, branchName string, baseCommitSHA string, cmdExec executor.Executor) *GitWorktree

NewGitWorktreeFromStorageWithExecutor creates a GitWorktree from stored data with an optional executor. If cmdExec is nil, a default executor is used.

func NewGitWorktreeWithBranch 

func NewGitWorktreeWithBranch(repoPath string, sessionName string, customBranch string) (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, cmdExec executor.Executor) (tree *GitWorktree, branchname string, err error)

NewGitWorktreeWithBranchAndExecutor creates a new GitWorktree with optional branch name and executor. If cmdExec is nil, a default executor is used.

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(title, body string) (prURL string, prNumber int, err error)

CreatePR creates a GitHub pull request for the current branch and returns the PR URL and number. Title defaults to the branch name if empty. 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 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 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 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 (.claude/rules/prefer-go-git-over-subshells.md).

func ListShippedCommits added in v1.39.0 

func ListShippedCommits(repoPath, baseSHA, headSHA string) ([]ShippedCommit, 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.

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.