git

func BranchExists ¶

func BranchExists(repoDir, branchName string) bool

BranchExists checks if a branch exists in the repository

func CreateWorktree ¶

func CreateWorktree(repoDir, worktreePath, branchName string) error

CreateWorktree creates a new git worktree at worktreePath for the given branch If the branch doesn't exist, it will be created

func CreateWorktreeWithSetup ¶ added in v1.3.1

func CreateWorktreeWithSetup(repoDir, worktreePath, branchName string, stdout, stderr io.Writer, setupTimeout time.Duration) (setupErr error, err error)

CreateWorktreeWithSetup creates a worktree and runs the setup script if present. Setup script failure is non-fatal: the worktree is still valid. Output is streamed to the provided writers. A non-positive setupTimeout means "no deadline" — see RunWorktreeSetupScript for the full semantic.

User-visible progress (#768): the start preamble, an explicit completion line on success, and an explicit failure line on error are written to stderr so callers (CLI streaming directly, TUI capturing into a buffer for later display) can show the user what happened. Without these, users couldn't tell whether the script had run, finished, or finished cleanly before claude started.

func DeleteBranch ¶ added in v0.10.20

func DeleteBranch(repoDir, branchName string, force bool) error

DeleteBranch deletes a local branch. If force is true, uses -D (force delete).

func FindWorktreeSetupScript ¶ added in v1.3.1

func FindWorktreeSetupScript(repoDir string) (string, os.FileMode)

FindWorktreeSetupScript returns the path to the worktree setup script if one exists at <repoDir>/.agent-deck/worktree-setup.sh, or empty string. The returned os.FileMode captures the file's permission bits at discovery time, eliminating a TOCTOU race between finding and dispatching the script.

func GeneratePathID ¶ added in v0.10.10

func GeneratePathID() string

GeneratePathID returns an 8-character random hex string for path uniqueness. Used to provide a unique identifier in worktree path templates via {session-id}.

func GenerateWorktreePath ¶

func GenerateWorktreePath(repoDir, branchName, location string) string

GenerateWorktreePath generates a worktree directory path based on the repository directory, branch name, and location strategy. Location "subdirectory" places worktrees under <repo>/.worktrees/<branch>. Location "sibling" (or empty) places worktrees as <repo>-<branch> alongside the repo. A custom path (containing "/" or starting with "~") places worktrees at <path>/<repo_name>/<branch>.

func GetCurrentBranch ¶

func GetCurrentBranch(dir string) (string, error)

GetCurrentBranch returns the current branch name for the repository at dir

func GetDefaultBranch ¶ added in v0.10.20

func GetDefaultBranch(repoDir string) (string, error)

GetDefaultBranch returns the default branch name (e.g. "main" or "master") for the repo

func GetMainWorktreePath ¶

func GetMainWorktreePath(dir string) (string, error)

GetMainWorktreePath returns the path to the "project root" — the directory that hosts shared config like .agent-deck/.

• Normal repo: the repo root (parent of .git/).
• Linked worktree of a normal repo: the main worktree (parent of .git/).
• Bare-repo layout (issue #715): the parent of .bare/. In this layout there is no "main" worktree; every linked worktree is equal, and shared config lives next to .bare/ in the project root.

func GetRepoRoot ¶

func GetRepoRoot(dir string) (string, error)

GetRepoRoot returns the root directory of the git repository containing dir

func GetWorktreeBaseRoot ¶ added in v0.17.0

func GetWorktreeBaseRoot(dir string) (string, error)

GetWorktreeBaseRoot returns the "project root" suitable for locating shared config (.agent-deck/, setup scripts, etc.). Accepts:

• A normal repo dir → repo root.
• A linked worktree → the main worktree (or, for bare-repo layouts, the parent of .bare/).
• A bare-repo project root (no .git but contains a nested bare repo) → the project root itself.

This guarantees that downstream .agent-deck/ lookups resolve to a single stable location regardless of which worktree (or the project root) the caller started from.

func GetWorktreeForBranch ¶

func GetWorktreeForBranch(repoDir, branchName string) (string, error)

GetWorktreeForBranch returns the worktree path for a given branch, if any

func HasUncommittedChanges ¶ added in v0.10.20

func HasUncommittedChanges(dir string) (bool, error)

HasUncommittedChanges checks if the repository at dir has uncommitted changes

func IsBareRepo ¶ added in v1.7.58

func IsBareRepo(dir string) bool

IsBareRepo returns true if dir itself is a bare git repository. For a linked worktree checkout, this returns false — use IsBareRepoWorktree for that case.

func IsBareRepoWorktree ¶ added in v1.7.58

func IsBareRepoWorktree(dir string) bool

IsBareRepoWorktree returns true if dir is a linked worktree whose shared git-common-dir is itself a bare repository — the ".bare/" pattern from issue #715. In this layout there is no "main" worktree; every linked worktree is equal.

func IsGitRepo ¶

func IsGitRepo(dir string) bool

IsGitRepo checks if the given directory is inside a git repository

func IsGitRepoOrBareProjectRoot ¶ added in v1.7.58

func IsGitRepoOrBareProjectRoot(dir string) bool

IsGitRepoOrBareProjectRoot returns true if dir is either a regular git directory (normal repo, linked worktree, or a bare repo) or the project root of a bare-repo layout (contains a nested bare repo such as .bare/). Callers that need to validate "is this a path agent-deck can launch a session from?" should prefer this over IsGitRepo.

func IsWorktree ¶

func IsWorktree(dir string) bool

IsWorktree checks if the given directory is a git worktree (not the main repo)

func ListBranchCandidates ¶ added in v0.27.0

func ListBranchCandidates(repoDir string) ([]string, error)

ListBranchCandidates returns unique branch names from local branches and the default remote, normalized to plain branch names without a remote prefix.

func MergeBack ¶ added in v1.9.6

func MergeBack(projectRoot, sourceBranch, targetBranch string) error

MergeBack merges sourceBranch into targetBranch, handling both regular and bare-repository layouts.

In a regular layout, projectRoot is a working tree: this is the historical path — `git checkout targetBranch` then `git merge sourceBranch`.

In a bare-repo layout (issue #715/#891), projectRoot is the parent of a nested bare repo (typically `.bare/`). The bare dir has no working tree, so `checkout`/`merge` cannot run there directly. Instead:

• If targetBranch is an ancestor of sourceBranch (fast-forward case), advance targetBranch via `update-ref` on the bare dir.
• Otherwise, create a throwaway worktree of targetBranch, perform the merge there, then remove the worktree.

Regression test: TestWorktree_MergeBack_BareRepo_RegressionFor891.

func MergeBranch ¶ added in v0.10.20

func MergeBranch(repoDir, branchName string) error

MergeBranch merges the given branch into the current branch of the repository

func ProcessWorktreeInclude ¶ added in v1.9.2

func ProcessWorktreeInclude(repoDir, worktreePath string, stderr io.Writer) error

ProcessWorktreeInclude copies gitignored files matching patterns in .worktreeinclude from repoDir into worktreePath. Returns nil if no .worktreeinclude exists.

Matches Claude Code Desktop behavior: https://code.claude.com/docs/en/worktrees#copy-gitignored-files-into-worktrees

func PruneWorktrees ¶ added in v0.10.20

func PruneWorktrees(repoDir string) error

PruneWorktrees removes stale worktree references

func RemoveWorktree ¶

func RemoveWorktree(repoDir, worktreePath string, force bool) error

RemoveWorktree removes a worktree from the repository. If force is true, it will remove even if there are uncommitted changes. When force is true and git fails (e.g. "Directory not empty" due to untracked files like node_modules), falls back to removing the directory directly and pruning stale worktree references.

func RunWorktreeSetupScript ¶ added in v1.3.1

func RunWorktreeSetupScript(scriptPath string, scriptMode os.FileMode, repoDir, worktreePath string, stdout, stderr io.Writer, timeout time.Duration) error

RunWorktreeSetupScript executes the setup script with AGENT_DECK_REPO_ROOT and AGENT_DECK_WORKTREE_PATH environment variables set. Working directory is set to worktreePath. Output is streamed to the provided writers.

Dispatch (#773):

• If scriptPath has the user-executable bit set, the script is invoked directly so the kernel honors its shebang line (e.g. #!/usr/bin/env bash, #!/usr/bin/env python3). This lets users write the setup script in any language they like.
• Otherwise (legacy 0644 setups predating #773), fall back to `sh -e <path>` so existing repos keep working without a chmod.

Timeout semantics (post-#727 follow-up):

• timeout > 0 → bounded by context.WithTimeout
• timeout <= 0 → unlimited (context.Background, no deadline)

The session layer resolves the legacy 60s default before calling here; callers that want bounded runs must pass a positive duration explicitly.

func SanitizeBranchName ¶

func SanitizeBranchName(name string) string

SanitizeBranchName converts a string to a valid branch name

func ValidateBranchName ¶

func ValidateBranchName(name string) error

ValidateBranchName validates that a branch name follows git's naming rules

func WorktreePath ¶ added in v0.10.10

func WorktreePath(opts WorktreePathOptions) string

WorktreePath generates a worktree path. If opts.Template is set, it expands the template with variables:

• {repo-name}, {repo-root}, {session-id}
• {branch}: sanitized (human-friendly, may collide)
• {branch-escaped}: URL-escaped (collision-resistant, reversible)

Unknown variables like {foo} are left as-is in the resolved path. Falls back to location-based strategy using opts.Location when template is empty or RepoDir is invalid.