A card that needs a checkout gets a git worktree of its own, on its own branch. The work happens there rather than in the checkout you are using, and it stays until its branch is merged or you remove it.
When one is made
Never before it is needed. A card's checkout is created the first time something asks for one:
- a step runs on the card and that step needs a checkout. Session and command steps do by default; agent steps do not, because refining and reviewing read the card's text and a worktree would cost minutes and gigabytes for nothing;
- you press Open a terminal or Make a checkout in the card's Work section.
Until then the card says: "No checkout yet. One is made on its own branch the first time this card needs it." Once it exists, the Work section shows its branch, its path, how many files are uncommitted, and Reveal and Open in to get to it from outside devpit.
A new checkout is prepared once, before anything runs in it. If that fails, the message names the preparation rather than the work: "preparing the worktree failed: <command> exited <code>".
A checkout made again after its worktree was removed goes back on the card's branch, and its diff still starts from where the card's work began.
Its branch
A new card's branch is named {type}/{number}-{slug}, such as feat/322-chat-base-visual or fix/351-flaky-macos-tests:
{type}comes from the card's title:fixwhen it opens with fix, bug, hotfix or defect;docs,test,choreorrefactorwhen it opens with one of those;featfor anything else. That first word then leaves the slug.{number}is the card's number.{slug}is the title in whole words, up to 30 characters, without accents.{id}is the end of the card's id, sodevpit/{slug}-{id}gives the older style back.
A name already taken, here or on the remote, gets -2, -3 and so on. Branch name, in Settings → Worktrees, changes the pattern: it shows the branch an example card would get, refuses a pattern git would not accept or that has none of {number}, {slug} and {id}, and Reset goes back to the default. Only new checkouts follow it; a card keeps the branch it was made on.
Setting up a new checkout
A fresh worktree has none of what git ignores — your .env, installed dependencies. New worktree setup, in the project's Edit project… (right-click it in the rail), says what a card's own checkout gets before anyone works in it, one entry per line:
| Field | What it does |
|---|---|
| Copy from the main checkout | files copied into the new checkout |
| Link to the main checkout | files linked rather than copied, so both see one copy |
| Run, in order | commands run in the new checkout, such as an install |
| Variables for those commands | NAME=value, set for those commands |
It is kept on this machine and never committed.
Settings → Worktrees
For the open project:
- Worktree folder: "Where a card's checkout is created. A relative path puts them inside the project; an absolute one holds every project in the same place." Left empty it is the project's devpit workspace. Browse picks a folder, Reset goes back to the default, and a line underneath shows where the next one will land.
- Sources:
git worktreelists every worktree a repository has, and someone working with agents has three kinds at once — devpit's card checkouts, the ones Claude Code makes for itself, and any made by hand. Show and Hide choose which kinds devpit counts. Hiding is a view, never a deletion, and the count stays on the row so you can see what the switch is taking away. - Branch name: the pattern above, for every project.
- Branch name for this project: a pattern for one project, picked with Applying settings for on the row. Left empty, the project takes its repository's
.devpit/settings.json, then Branch name. See Settings. - Cleanup: Delete merged worktrees, on by default, with Delete now and what the last run removed, kept and freed.
- The list: every card's checkout, with its branch, its size on disk and its uncommitted files and lines. An orphan pill marks a checkout with no card left to match it. The pane's total size on disk is at the top.
When a card is merged
Once every commit of a card's branch is in the default branch, devpit removes the card's checkout, its build cache and its local branch. It looks a few minutes after it starts and every hour after that, and Delete now in Settings → Worktrees → Cleanup looks at once.
- Kept, and listed as kept: a checkout with uncommitted work, or with something still running in it.
- Only devpit's own: a checkout devpit made for a card, its cache folder, and a branch named for that card. Nothing outside them is touched, and nothing is forced.
- A branch merged by squashing reads as not merged, so its checkout stays until you remove it.
The last run's count — removed, kept, and the space freed — shows under the button. Turn Delete merged worktrees off and checkouts stay until you remove them.
Removing one
A checkout you no longer need goes with Remove. The dialog says what that means: "The folder goes; the branch stays, with everything committed on it."
If the checkout holds uncommitted work, devpit refuses to remove it until you have been told what would be lost: the dialog names how many files and how many lines have not been committed, and only then does confirming remove it.
Removing a project does not remove its worktrees. They stay on disk, and the removal dialog says how many there are. See Projects and Where your data lives.