Documentation
¶
Overview ¶
Package git encapsulates the per-session git worktree: creation, diff stats, push, and cleanup.
Each agent session runs inside its own worktree under {configDir}/worktrees/, on a branch named "{BranchPrefix}{SessionTitle}". The worktree is torn down on pause (branch preserved) and destroyed entirely on kill. Callers interact via the GitWorktree type; a CommandRunner abstraction makes the exec layer injectable for tests.
Error handling convention: errors are wrapped with fmt.Errorf("...: %w", err) so callers can match the cause. ErrBranchGone is a sentinel returned when the underlying branch has disappeared between operations — callers typically recover by rediscovering the branch or dropping the session.
Index ¶
- Constants
- Variables
- func CleanupWorktrees(configDir string, runner CommandRunner) error
- func CurrentBranch(repoPath string, runner CommandRunner) (string, error)
- func FetchBranches(repoPath string, runner CommandRunner)
- func IsGitRepo(path string, runner CommandRunner) bool
- func SearchBranches(repoPath, filter string, runner CommandRunner) ([]string, error)
- func WorktreeTitleSidecarPath(worktreePath string) string
- type CommandRunner
- type DiffStats
- type GitWorktree
- func NewGitWorktree(repoPath string, sessionName string, configDir string) (tree *GitWorktree, branchname string, err error)
- func NewGitWorktreeFromBranch(repoPath string, branchName string, sessionName string, configDir string) (*GitWorktree, error)
- func NewGitWorktreeFromBranchWithRunner(repoPath string, branchName string, sessionName string, configDir string, ...) (*GitWorktree, error)
- func NewGitWorktreeFromStorage(repoPath string, worktreePath string, sessionName string, branchName string, ...) *GitWorktree
- func NewGitWorktreeFromStorageWithRunner(repoPath string, worktreePath string, sessionName string, branchName string, ...) *GitWorktree
- func NewGitWorktreeWithRunner(repoPath string, sessionName string, configDir string, runner CommandRunner) (tree *GitWorktree, branchname string, err error)
- func (g *GitWorktree) Cleanup() (err error)
- func (g *GitWorktree) CommitChanges(commitMessage string) error
- func (g *GitWorktree) Diff() *DiffStats
- func (g *GitWorktree) DiffShortStat() *DiffStats
- func (g *GitWorktree) GetBaseCommitSHA() string
- func (g *GitWorktree) GetBranchName() string
- func (g *GitWorktree) GetRepoName() string
- func (g *GitWorktree) GetRepoPath() string
- func (g *GitWorktree) GetWorktreePath() string
- func (g *GitWorktree) IsBranchCheckedOut() (bool, error)
- func (g *GitWorktree) IsDirty() (bool, error)
- func (g *GitWorktree) IsExistingBranch() bool
- func (g *GitWorktree) Merge(sourceBranch string) error
- func (g *GitWorktree) OpenBranchURL() error
- func (g *GitWorktree) Prune() error
- func (g *GitWorktree) PushChanges(commitMessage string, open bool) error
- func (g *GitWorktree) Remove() error
- func (g *GitWorktree) Setup() (err error)
Constants ¶
const MaxBranchSearchResults = 50
MaxBranchSearchResults is the maximum number of branches returned by SearchBranches.
Variables ¶
var ErrBranchGone = errors.New("branch not found locally or on remote")
ErrBranchGone is returned by Setup when the branch a paused instance was pointing at has disappeared both locally and on origin — typically because an operator ran `git branch -D <name>` from outside the app. Callers use errors.Is to classify the failure and surface a recovery hint (kill-to-clean-up) instead of a generic setup error.
Functions ¶
func CleanupWorktrees ¶
func CleanupWorktrees(configDir string, runner CommandRunner) error
CleanupWorktrees removes all worktrees and their associated branches. configDir is the workspace config directory; if empty, falls back to GetConfigDir(). Pass nil for runner to use the default subprocess runner.
func CurrentBranch ¶
func CurrentBranch(repoPath string, runner CommandRunner) (string, error)
CurrentBranch returns the current branch name for the given repo directory. Pass nil for runner to use the default subprocess runner.
func FetchBranches ¶
func FetchBranches(repoPath string, runner CommandRunner)
FetchBranches fetches and prunes remote-tracking branches (best-effort, won't fail if offline). Pass nil for runner to use the default subprocess runner.
func IsGitRepo ¶
func IsGitRepo(path string, runner CommandRunner) bool
IsGitRepo checks if the given path is within a git repository. Pass nil for runner to use the default subprocess runner.
func SearchBranches ¶
func SearchBranches(repoPath, filter string, runner CommandRunner) ([]string, error)
SearchBranches searches for branches whose name contains filter (case-insensitive), ordered by most recently updated first. Returns at most MaxBranchSearchResults. If filter is empty, returns all branches up to the limit. Pass nil for runner to use the default subprocess runner.
func WorktreeTitleSidecarPath ¶ added in v0.4.0
WorktreeTitleSidecarPath returns the path of the sidecar file that records a worktree's original instance title. It lives next to the worktree directory (a sibling file), NOT inside it — keeping it out of the work tree avoids polluting git status/diffs. Orphan discovery reads it to reconstruct the exact display title — and therefore the exact tmux session name — which the lossy branch-name sanitization (lowercasing, dash-collapsing) otherwise destroys.
Types ¶
type CommandRunner ¶
type CommandRunner = internalexec.Executor
CommandRunner is an alias for internal/exec.Executor. Kept as a type alias so git-package callers keep the familiar name while the concrete interface lives in a leaf package shared with cmd/.
func DefaultRunner ¶
func DefaultRunner() CommandRunner
DefaultRunner returns the production subprocess runner.
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 DiffUncommitted ¶
func DiffUncommitted(repoPath string, runner CommandRunner) *DiffStats
DiffUncommitted returns the diff of uncommitted changes in the given repo directory. Used for workspace terminals that operate on the root repo without a worktree. Only shows tracked file changes to avoid mutating the user's git index. Pass nil for runner to use the default subprocess runner.
func DiffUncommittedShortStat ¶
func DiffUncommittedShortStat(repoPath string, runner CommandRunner) *DiffStats
DiffUncommittedShortStat returns only line counts for uncommitted changes. Pass nil for runner to use the default subprocess runner.
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, configDir string) (tree *GitWorktree, branchname string, err error)
NewGitWorktree creates a new GitWorktree instance. configDir is the workspace config directory; if empty, falls back to GetConfigDir().
func NewGitWorktreeFromBranch ¶
func NewGitWorktreeFromBranch(repoPath string, branchName string, sessionName string, configDir string) (*GitWorktree, error)
NewGitWorktreeFromBranch creates a new GitWorktree that uses an existing branch. The branch will not be deleted on cleanup. configDir is the workspace config directory; if empty, falls back to GetConfigDir().
func NewGitWorktreeFromBranchWithRunner ¶
func NewGitWorktreeFromBranchWithRunner(repoPath string, branchName string, sessionName string, configDir string, runner CommandRunner) (*GitWorktree, error)
NewGitWorktreeFromBranchWithRunner is NewGitWorktreeFromBranch with an injected CommandRunner for tests. Passing nil falls back to the default subprocess runner.
func NewGitWorktreeFromStorage ¶
func NewGitWorktreeFromStorage(repoPath string, worktreePath string, sessionName string, branchName string, baseCommitSHA string, isExistingBranch bool, configDir string) *GitWorktree
NewGitWorktreeFromStorage rehydrates a GitWorktree from its persisted [session.GitWorktreeData] fields. Unlike NewGitWorktree, this constructor does no git work — it simply reattaches the in-memory wrapper to an on-disk worktree that already exists (or that needs to be rebuilt by a caller via Setup on resume).
func NewGitWorktreeFromStorageWithRunner ¶
func NewGitWorktreeFromStorageWithRunner(repoPath string, worktreePath string, sessionName string, branchName string, baseCommitSHA string, isExistingBranch bool, configDir string, runner CommandRunner) *GitWorktree
NewGitWorktreeFromStorageWithRunner is NewGitWorktreeFromStorage with an injected CommandRunner for tests. Passing nil falls back to the default subprocess runner.
func NewGitWorktreeWithRunner ¶
func NewGitWorktreeWithRunner(repoPath string, sessionName string, configDir string, runner CommandRunner) (tree *GitWorktree, branchname string, err error)
NewGitWorktreeWithRunner is NewGitWorktree with an injected CommandRunner (used by tests). Passing nil falls back to the default runner. configDir must be a concrete workspace config directory (callers thread this through via config.WorkspaceContext); passing empty string falls back to the global directory and logs a warning.
func (*GitWorktree) Cleanup ¶
func (g *GitWorktree) Cleanup() (err error)
Cleanup removes the worktree and associated branch
func (*GitWorktree) CommitChanges ¶
func (g *GitWorktree) CommitChanges(commitMessage string) error
CommitChanges commits changes locally without pushing to remote
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) DiffShortStat ¶
func (g *GitWorktree) DiffShortStat() *DiffStats
DiffShortStat returns only the line counts (Added/Removed) without full diff content. Uses git diff --shortstat which is significantly cheaper for large diffs.
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) 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) IsBranchCheckedOut ¶
func (g *GitWorktree) IsBranchCheckedOut() (bool, error)
IsBranchCheckedOut checks if the instance branch is currently checked out
func (*GitWorktree) IsDirty ¶
func (g *GitWorktree) IsDirty() (bool, error)
IsDirty checks if the worktree has uncommitted changes
func (*GitWorktree) IsExistingBranch ¶
func (g *GitWorktree) IsExistingBranch() bool
IsExistingBranch returns whether this worktree uses a pre-existing branch
func (*GitWorktree) Merge ¶ added in v0.3.0
func (g *GitWorktree) Merge(sourceBranch string) error
Merge runs `git merge <sourceBranch>` in the worktree's directory, bringing another session's branch into this one. On conflict or any other non-zero exit, the git error/output is returned as-is and the merge is left exactly as git leaves it (MERGE_HEAD + conflict markers on a real conflict) — callers must not run `merge --abort` automatically, so a conflicted merge stays available for the user (or the agent) to resolve and commit.
func (*GitWorktree) OpenBranchURL ¶
func (g *GitWorktree) OpenBranchURL() error
OpenBranchURL opens the branch URL in the default browser
func (*GitWorktree) Prune ¶
func (g *GitWorktree) Prune() error
Prune removes all working tree administrative files and directories
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
func (*GitWorktree) Setup ¶
func (g *GitWorktree) Setup() (err error)
Setup creates a new worktree for the session