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 ¶
- Variables
- func BranchExists(branch string) bool
- func BranchExistsInRepo(repoPath, branch string) bool
- func Checkout(branch string) error
- func CheckoutInRepoWithOptions(repoPath, branch string, opts CheckoutOptions) error
- func CheckoutWithOptions(branch string, opts CheckoutOptions) error
- func Create(path, branch string, newBranch bool, base string) error
- func CreateInRepo(repoPath, path, branch string, newBranch bool, base string) error
- func CreateWithOptions(path, branch string, newBranch bool, base string, opts CreateOptions) error
- func CurrentBranch(dir string) string
- func CurrentBranchContext(ctx context.Context, dir string) string
- func DetectDefaultBranch(repoPath string) string
- func DetectMainRepo(worktreePath string) string
- func DetectRepoRoot(path string) string
- func DetectRepoRootContext(ctx context.Context, path string) string
- func DiscoverWorktreeTargets(repoPath, branch string) (string, string, error)
- func EnsureGitignored(mainRepo, wtPath string) (pattern string, err error)
- func Fetch(remote, branch string) error
- func FetchInRepo(repoPath, remote, branch string) error
- func FindWorktreeForBranch(branch string) string
- func FindWorktreeForBranchInRepo(repoPath, branch string) string
- func HasUncommittedChanges(worktreePath string) bool
- func IsDivergedPull(err error) bool
- func ListBranches(prefix string) []string
- func MergedBranches(repoPath, defaultBranchOverride string) ([]string, error)
- func Pull(dir, remote, branch string) error
- func Remove(worktreePath string, force bool) error
- func RepoNameFromRemote(repoPath string) string
- func RepoRoot(path string) (string, error)
- func RepoRootStrict(path string) (string, error)
- func RepoSlugFromRemote(repoPath string) string
- func RepoSlugFromRemoteContext(ctx context.Context, repoPath string) string
- func UnpushedCommitCount(worktreePath string) int
- func ValidateRemoval(worktreePath string) (string, error)
- func WorktreeBranches(repoPath string) map[string]string
- type CheckoutOptions
- type CreateOptions
Constants ¶
This section is empty.
Variables ¶
var ErrNotRepository = errors.New("not a git repository")
ErrNotRepository indicates that a path is outside any Git repository.
Functions ¶
func BranchExists ¶
BranchExists checks whether a branch exists locally or as a remote tracking ref.
func BranchExistsInRepo ¶ added in v0.58.1
BranchExistsInRepo checks for a branch in repoPath without consulting cwd.
func CheckoutInRepoWithOptions ¶ added in v0.59.0
func CheckoutInRepoWithOptions(repoPath, branch string, opts CheckoutOptions) error
CheckoutInRepoWithOptions keeps admitted checkout execution bound to its resolved worktree directory even when the caller runs from a subdirectory.
func CheckoutWithOptions ¶ added in v0.59.0
func CheckoutWithOptions(branch string, opts CheckoutOptions) error
CheckoutWithOptions can defer legacy automatic setup to an admitted caller without suppressing other post-checkout hook behavior.
func Create ¶
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 CreateInRepo ¶ added in v0.58.1
CreateInRepo adds a git worktree using repoPath as the repository context. Unlike Create, it never falls back to the process working directory.
func CreateWithOptions ¶ added in v0.58.2
func CreateWithOptions(path, branch string, newBranch bool, base string, opts CreateOptions) error
CreateWithOptions adds a git worktree with command-scoped behavior.
func CurrentBranch ¶
CurrentBranch returns the currently checked-out branch in dir. Returns "" if dir is not a git repo or HEAD is detached.
func CurrentBranchContext ¶ added in v0.56.1
CurrentBranchContext is CurrentBranch bounded by ctx.
func DetectDefaultBranch ¶
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 ¶
DetectMainRepo returns the root worktree path (the main repo) by parsing `git worktree list --porcelain`. Falls back to the given path.
func DetectRepoRoot ¶
DetectRepoRoot returns the top-level directory of the current git worktree. Falls back to the given path if detection fails.
func DetectRepoRootContext ¶ added in v0.58.3
DetectRepoRootContext is DetectRepoRoot bounded by ctx.
func DiscoverWorktreeTargets ¶ added in v0.59.0
DiscoverWorktreeTargets resolves the primary root and an optional existing branch root from one successful query. Admission callers must distinguish an absent branch from failed or ambiguous discovery; legacy readers remain unchanged.
func EnsureGitignored ¶
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 FetchInRepo ¶ added in v0.58.1
FetchInRepo fetches a branch from remote in repoPath without consulting cwd.
func FindWorktreeForBranch ¶
FindWorktreeForBranch returns the path of an existing worktree that has the given branch checked out, or empty string if none.
func FindWorktreeForBranchInRepo ¶ added in v0.58.1
FindWorktreeForBranchInRepo returns an existing worktree for branch in repoPath without consulting cwd.
func HasUncommittedChanges ¶
HasUncommittedChanges returns true if the worktree has staged or unstaged changes.
func IsDivergedPull ¶ added in v0.52.0
IsDivergedPull reports whether a Pull error is because the local and remote branches have diverged (fast-forward not possible), as opposed to some other failure.
func ListBranches ¶
ListBranches returns branch names matching the given prefix. Lists both local and remote branches, deduplicating origin/ variants.
func MergedBranches ¶
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 Pull ¶ added in v0.52.0
Pull runs `git pull --ff-only <remote> <branch>` in dir, fast-forwarding the checked-out branch to match the remote without creating a merge commit. Use IsDivergedPull to distinguish a genuine divergence (caller should warn and let the user resolve manually) from other failures (no remote, network, etc.).
func RepoNameFromRemote ¶ added in v0.40.2
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 RepoRoot ¶ added in v0.57.0
RepoRoot returns the top-level directory of the current Git worktree. It returns an error when Git cannot resolve a repository from path.
func RepoRootStrict ¶ added in v0.59.0
RepoRootStrict preserves path whitespace for execution admission. Git emits one terminating newline; additional whitespace can belong to the directory.
func RepoSlugFromRemote ¶ added in v0.44.0
RepoSlugFromRemote returns the "owner/name" identity from the `origin` remote URL (e.g. "acme/fitter" from "git@github.com:acme/fitter.git" or "https://github.com/acme/fitter"). This is the durable repo identity used to key cross-worktree relationships. Returns "" when there's no origin remote or the URL can't be parsed into at least owner/name.
func RepoSlugFromRemoteContext ¶ added in v0.56.1
RepoSlugFromRemoteContext is RepoSlugFromRemote bounded by ctx.
func UnpushedCommitCount ¶
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 ValidateRemoval ¶ added in v0.59.0
ValidateRemoval refuses primary clones and non-root paths before release effects.
func WorktreeBranches ¶
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.
Types ¶
type CheckoutOptions ¶ added in v0.59.0
type CheckoutOptions struct {
DeferSetup bool
}
type CreateOptions ¶ added in v0.58.2
type CreateOptions struct {
DeferSetup bool
}
CreateOptions controls behavior scoped to the git worktree add process.
Source Files