worktree

Documentation

Overview

Package worktree provides git worktree operations including creation, branch detection, and repository inspection. It wraps git CLI commands for worktree management and merged branch detection.

Index

• func BranchExists(branch string) bool
• func Checkout(branch string) error
• func Create(path, branch string, newBranch bool, base string) error
• func CurrentBranch(dir string) string
• func DetectDefaultBranch(repoPath string) string
• func DetectMainRepo(worktreePath string) string
• func DetectRepoRoot(path string) string
• func EnsureGitignored(mainRepo, wtPath string) (pattern string, err error)
• func Fetch(remote, branch string) error
• func FindWorktreeForBranch(branch string) string
• func HasUncommittedChanges(worktreePath string) bool
• func ListBranches(prefix string) []string
• func MergedBranches(repoPath, defaultBranchOverride string) ([]string, error)
• func Remove(worktreePath string, force bool) error
• func RepoNameFromRemote(repoPath string) string
• func UnpushedCommitCount(worktreePath string) int
• func WorktreeBranches(repoPath string) map[string]string

Functions

func BranchExists

func BranchExists(branch string) bool

BranchExists checks whether a branch exists locally or as a remote tracking ref.

func Checkout

func Checkout(branch string) error

Checkout switches the current directory's worktree to a different branch.

func Create

func Create(path, branch string, newBranch bool, base string) error

Create adds a git worktree at path. If newBranch is true, it creates a new branch from base. Otherwise it checks out an existing branch.

func CurrentBranch

func CurrentBranch(dir string) string

CurrentBranch returns the currently checked-out branch in dir. Returns "" if dir is not a git repo or HEAD is detached.

func DetectDefaultBranch

func DetectDefaultBranch(repoPath string) string

DetectDefaultBranch resolves the default branch for the repo at repoPath. It tries (in order): local symbolic-ref, `git remote show origin` (network), then common local branch names. Returns branch name and true if found, or "main" and false if detection failed entirely.

func DetectMainRepo

func DetectMainRepo(worktreePath string) string

DetectMainRepo returns the root worktree path (the main repo) by parsing `git worktree list --porcelain`. Falls back to the given path.

func DetectRepoRoot

func DetectRepoRoot(path string) string

DetectRepoRoot returns the top-level directory of the current git worktree. Falls back to the given path if detection fails.

func EnsureGitignored

func EnsureGitignored(mainRepo, wtPath string) (pattern string, err error)

EnsureGitignored checks whether a worktree path that lives inside the repo root is gitignored. If not, it appends the directory to .gitignore and returns the pattern that was added. Paths outside the repo root (the default sibling layout) are a no-op and return "".

func Fetch

func Fetch(remote, branch string) error

Fetch fetches a branch from the given remote.

func FindWorktreeForBranch

func FindWorktreeForBranch(branch string) string

FindWorktreeForBranch returns the path of an existing worktree that has the given branch checked out, or empty string if none.

func HasUncommittedChanges

func HasUncommittedChanges(worktreePath string) bool

HasUncommittedChanges returns true if the worktree has staged or unstaged changes.

func ListBranches

func ListBranches(prefix string) []string

ListBranches returns branch names matching the given prefix. Lists both local and remote branches, deduplicating origin/ variants.

func MergedBranches

func MergedBranches(repoPath, defaultBranchOverride string) ([]string, error)

MergedBranches returns branch names that have been merged into the default branch. If defaultBranchOverride is non-empty it is used directly; otherwise the default branch is detected via symbolic-ref, falling back to "main" then "master".

func Remove

func Remove(worktreePath string, force bool) error

Remove runs `git worktree remove` on the given path. If force is true, it passes --force to remove even with uncommitted changes. Returns nil if the path is the main worktree (cannot be removed).

func RepoNameFromRemote

func RepoNameFromRemote(repoPath string) string

RepoNameFromRemote returns the repo basename from the `origin` remote URL (e.g. "fitter" from "git@github.com:acme/fitter.git" or "https://gitlab.com/group/sub/fitter"). Returns "" when there's no origin remote or the URL can't be parsed.

func UnpushedCommitCount

func UnpushedCommitCount(worktreePath string) int

UnpushedCommitCount returns the number of commits on the current branch that haven't been pushed to the remote. Returns 0 if the remote branch doesn't exist or if the check fails (e.g., offline).

func WorktreeBranches

func WorktreeBranches(repoPath string) map[string]string

WorktreeBranches returns a map of worktree absolute path → branch name by parsing `git worktree list --porcelain`. Paths are normalized via filepath.EvalSymlinks to match the paths stored in the registry.