birch worktree

birch worktree is the CLI face of the worktree-first model: new creates a worktree on a fresh branch (with the same file carryover as the GUI), ls lists every worktree across your registered repositories, and rm removes one — optionally with its branch.

birch worktree new

terminal

birch worktree new <ticket> [--base <branch>] [--repo <name>]

Argument / option	Meaning
<ticket>	Required. A ticket reference (e.g. ABC-123 or #123) or a plain branch name.
--base <branch>	Base branch to fork from. Defaults to the repository’s default branch.
--repo <name>	Repository name. Required when more than one repository is registered.

Branch name. A ticket-shaped argument is normalized into a branch name: ABC-123 becomes feature/abc-123, #123 becomes feature/issue-123. Anything else is used verbatim as the branch name.

Path. The worktree is created as a sibling of the repository’s own folder, named <repo>-<branch> with / in the branch replaced by - — e.g. my-repo-feature-abc-123 next to my-repo.

Text output:

text

created  feature/abc-123  /Users/you/dev/my-repo-feature-abc-123

--json output (note these field names are capitalized, unlike the other subcommands):

json

{
  "Id": "0b6f2c1e-…",
  "Path": "/Users/you/dev/my-repo-feature-abc-123",
  "BranchName": "feature/abc-123",
  "HeadSha": "1a2b3c4d…"
}

birch worktree ls

terminal

birch worktree ls

Lists every worktree of every registered repository. Text output is a table with columns REPO, BRANCH, HEAD (short SHA), and PATH; rows may carry a trailing flag suffix in parentheses combining primary, locked, and prunable. With no repositories it prints (no repositories registered); with none found, (no worktrees).

--json returns an array of objects with these fields:

Field	Meaning
repo	Repository display name.
repositoryId	Repository id (GUID).
worktreeId	Worktree id (GUID).
branch	Branch name; omitted for a detached worktree.
path	Absolute worktree path.
head	Full HEAD SHA.
primary	true for the repository’s primary checkout.
locked	true when the worktree is locked.
prunable	true when git reports it prunable.
lastActivityAt	Timestamp of the last recorded activity.

birch worktree rm

terminal

birch worktree rm <name> [--delete-branch]

Argument / option	Meaning
<name>	Required. The worktree’s branch name or a path segment; resolved against all registered worktrees. A name that matches nothing — or more than one worktree — exits 1 with an explanatory message.
--delete-branch	Also delete the local branch after removing the worktree.

Removal always drops the worktree from Birch. If the folder itself can’t be deleted (e.g. a process holds it open), the command still succeeds and warns:

text

removed  feature/abc-123  /Users/you/dev/my-repo-feature-abc-123
warning: the folder could not be deleted and is still on disk

--json output:

json

{
  "removed": true,
  "folderRemoved": true,
  "id": "9f1e4a3b-…",
  "path": "/Users/you/dev/my-repo-feature-abc-123"
}

With and without the app running

worktree new and worktree rm relay through a running Birch app so the sidebar updates immediately, and execute locally when no app is running — --verbose shows which path was taken. worktree ls always reads local state directly. See IPC vs standalone.

Examples

terminal

# Ticket-driven flow: one worktree per ticket
birch worktree new ABC-123
cd ../my-repo-feature-abc-123

# Explicit base and repository
birch worktree new hotfix/crash --base release/2.4 --repo my-repo

# Scripted cleanup: remove every prunable worktree (branches included)
birch worktree ls --json \
  | jq -r '.[] | select(.prunable and (.primary | not)) | .branch' \
  | xargs -n1 birch worktree rm --delete-branch