# Worktrees

> A checkout per line of work, made when needed, removed on its own once merged or when you say.

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: `fix` when it opens with fix, bug, hotfix or defect; `docs`, `test`, `chore` or `refactor` when it opens with one of those; `feat` for 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, so `devpit/{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 worktree` lists 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](/docs/settings#for-one-project).
- **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](/docs/projects) and [Where your data lives](/docs/your-data).
