Worktrees
A worktree is a separate checkout of a project on its own branch, made with git worktree. It shares the repository’s history but has its own files, so an agent can change anything in it without touching your main checkout or another agent’s work. For the general case, see the guide to Git worktrees for coding agents.
Where they live
Section titled “Where they live”ket keeps worktrees outside your repository:
~/.local/share/ket/worktrees/<project>/<worktree>/If you set XDG_DATA_HOME, they go under $XDG_DATA_HOME/ket/worktrees/ instead. The folder name is a readable form of the branch name (up to 40 characters) followed by a short hash, so two branches never collide.
Which commit a worktree starts from
Section titled “Which commit a worktree starts from”A new worktree starts from the project’s base branch unless you choose another. ket fetches the remote first:
- If the remote branch is ahead, ket starts from it, and fast-forwards your local branch when that loses nothing.
- Otherwise ket starts from your local branch.
If the fetch fails, ket carries on from the local branch. ket worktree add prints a note when that happens.
Provisioning
Section titled “Provisioning”A fresh checkout has no node_modules, virtual environment or .env file. Provisioning brings them over from the primary checkout so the worktree can build straight away. By default ket:
- clones
node_modules,.venvandvendor, - skips
target, - copies
.env,.env.localand.env.*.local.
On macOS, cloning uses copy-on-write (clonefile), so even a node_modules with tens of thousands of files appears in well under a second and takes no extra disk space until something changes. Where copy-on-write isn’t available, ket falls back to a normal copy. The contents of .env files never appear in ket’s logs.
ket worktree add provisions every worktree it creates. Worktrees made in the app, from the Create worktree dialog, the quick prompt, the backlog or a phone, aren’t provisioned; run Re-run provisioning for a worktree from the command palette.
Each directory can be cloned, symlinked or skipped. Set this in the [provision] section of your config.toml, or per repository in .ket.toml, which replaces the global section entirely. A post_command in .ket.toml runs only when the project’s Automation setting is on. See Files and settings.
Provisioning doesn’t give a worktree its own ports or database. Making a new worktree ready for an agent covers those.
The row menu
Section titled “The row menu”Right-click a worktree’s row for:
- Rename…, Pin / Unpin
- Send snippet
- Economy: change the level for the next agent session. See Economy.
- Clear build output: delete build folders to reclaim disk. ket lists the folders and their total size before it deletes anything. By default it looks for
target,node_modules,dist,buildand.next. - Delete
- Copy Path
Deleting a worktree
Section titled “Deleting a worktree”Delete removes the worktree’s folder, including anything ket provisioned into it, and then its branch. If the branch has commits that aren’t merged anywhere, ket keeps the branch and tells you. If git refuses to remove the worktree, for example because of uncommitted changes, the dialog shows why and offers Delete anyway.
If a worktree’s folder disappears outside ket, its row says so and no terminal opens in it.