gitutil

Documentation

Overview

Package gitutil holds helpers for interacting with git and with the Claude Code worktree layout (.claude/worktrees/<name>).

Index

• func AddWorktree(path, branch string) error
• func ClaudeWorktreeRepoRoot(path string) (string, bool)
• func CurrentClaudeWorktree() (path, name string, err error)
• func DeleteBranch(branch string, force bool) error
• func PruneWorktrees() error
• func RemoveWorktree(path string) error
• func RepoRoot(stripClaudeWorktree bool) (string, error)
• type Commit
  • func LastCommit(repoPath string) (Commit, error)
• type Worktree
  • func ListWorktrees() ([]Worktree, error)

Functions

func AddWorktree

func AddWorktree(path, branch string) error

AddWorktree creates a new linked worktree at `path` on a freshly-created branch `branch`, via `git worktree add -b <branch> <path>`. On success the command is silent — git's progress chatter ("Preparing worktree…", "HEAD is now at…") is captured and discarded. On failure the captured output is written verbatim to the process stderr so the user sees git's own error message.

func ClaudeWorktreeRepoRoot

func ClaudeWorktreeRepoRoot(path string) (string, bool)

ClaudeWorktreeRepoRoot derives the enclosing repository root for a path that lives inside a Claude Code worktree (.../.claude/worktrees/<name>, or any descendant of it) using pure string manipulation — no git invocation and no filesystem access. It returns the path up to, but not including, the .claude directory and true; or ("", false) when path is not inside such a worktree.

Unlike stripClaudeWorktreeSuffix, which only strips an exact .claude/worktrees/<name> suffix, this locates the component anywhere in the path. It exists for the case where the worktree directory has been deleted while it was the current directory: git can no longer read the cwd (getcwd fails), so RepoRoot errors out, but the shell still records the old path in $PWD and that string is enough to compute where to escape to.

func CurrentClaudeWorktree

func CurrentClaudeWorktree() (path, name string, err error)

CurrentClaudeWorktree returns the path and name of the Claude Code worktree that contains the git toplevel of the current working directory, or ("", "", nil) if the toplevel isn't shaped like .../.claude/worktrees/<name>. An error is returned only if `git rev-parse --show-toplevel` itself fails.

func DeleteBranch

func DeleteBranch(branch string, force bool) error

DeleteBranch deletes a local branch. Without force, `git branch -d` is used, which refuses to delete an unmerged branch; with force, `-D` force-deletes. A branch that doesn't exist is treated as success so the caller can re-invoke after a partial deletion without surfacing an error.

func PruneWorktrees

func PruneWorktrees() error

PruneWorktrees runs `git worktree prune` to clean up stale registrations (worktree entries whose on-disk directory no longer exists).

func RemoveWorktree

func RemoveWorktree(path string) error

RemoveWorktree removes the linked worktree at path via `git worktree remove --force <path>`. --force is used so a worktree with local modifications still gets removed. If the path is not a registered worktree (already gone), nil is returned — making the operation idempotent.

func RepoRoot

func RepoRoot(stripClaudeWorktree bool) (string, error)

RepoRoot runs `git rev-parse --show-toplevel` and returns the resulting path with its trailing newline trimmed. Git's stderr is passed through to the process stderr so the caller's user sees `fatal: not a git repository` and similar messages.

If stripClaudeWorktree is true and the toplevel sits inside a Claude Code worktree (`.claude/worktrees/<name>`), the enclosing repository root is returned instead.

Types

type Commit

type Commit struct {
	Time    time.Time
	Subject string
}

Commit holds the bits of a git commit we display.

func LastCommit

func LastCommit(repoPath string) (Commit, error)

LastCommit returns the HEAD commit of the repository at repoPath.

type Worktree

type Worktree struct {
	Path   string
	Branch string // empty when HEAD is detached
}

Worktree is one entry from `git worktree list`.

func ListWorktrees

func ListWorktrees() ([]Worktree, error)

ListWorktrees parses `git worktree list --porcelain` and returns all registered worktrees (including the main one).