⬡Worktrees
Multiple working directories for one repo — each on a different branch — managed from the WORKTREES section of the branch tree. A branch can only be checked out in one worktree at a time, so worktrees let you build/run one branch while editing another.
Worktree list worktree.list
- Branch treeThe WORKTREES section (collapsed by default). The main working tree is badged main; locked trees show a lock glyph, stale ones show missing.
Go runs worktree.list (git worktree list --porcelain) and returns []Worktree — path, HEAD, branch, and the main/detached/bare/locked/prunable flags.
Add worktree worktree.add
Entry points
- Action railThe purple New worktree button (overlapping-windows icon) at the bottom of the rail, after Create tag.
What happens next
- A filterable quick-pick opens listing, each with a description:
- ✚ Create new branch… — from <current branch>; prompts for a name and branches off HEAD.
- Local branches — local · <ahead/behind>; any branch not already checked out in another worktree (your current branch is excluded — it lives in the main worktree).
- Remote branches — remote → new branch '<short>'; only those without a local twin. Picking one creates a local tracking branch (
start = origin/<short>, so git sets the upstream).
- Confirm the folder — defaults to
<repo>.worktrees/<branch>alongside the repo (a common convention). - Go runs worktree.add with
{ path, branch }for an existing local branch, or{ path, newBranch, start? }for a new/remote-tracking branch (git worktree add [-b]).
Open in new window worktree.open
- Worktree rowClick a linked worktree, or use Open in New Window from its menu.
Host-only — the extension runs vscode.openFolder with forceNewWindow so the current window's context is kept. The main worktree is skipped (already open).
Lock / unlock worktree.lock worktree.unlock
- Worktree menuLock / Unlock.
Locking marks a worktree so prune won't reclaim it (e.g. on removable media or a long-running agent checkout). Go runs worktree.lock / worktree.unlock with { path }.
Move worktree.move
- Worktree menuMove… — prompts for a new path.
Go runs worktree.move with { from, to } (git worktree move).
Remove worktree.remove
What happens next
- Remove (red) in the worktree menu, after confirmation.
- If the worktree has uncommitted changes git refuses; you're offered a force remove.
- Go runs worktree.remove with
{ path, force }. Committed work on the branch is kept.
Prune stale worktree.prune
- Worktree menuPrune Stale Worktrees — repo-wide cleanup.
Clears administrative entries for worktrees whose directories were deleted from disk (the rows badged missing). Go runs worktree.prune (git worktree prune).