How worktrees work
A worktree is a working copy of one project, kept on one node. The Worktrees page calls each one a slot. Every task and every console session runs inside a slot, so a project can run as many tasks at once as it has free slots.
This page explains the ideas behind worktrees. For the steps, see Read a worktree's status, Add worktree slots and Release a worktree. For every column, filter and action, see Worktrees.
Terms
| Term | Meaning |
|---|---|
| Slot | One worktree: a numbered working copy of a project on a node, for example #1. |
| Worktree pool | All your organization's slots, across every node. |
| Holder | The task or person a slot is held by. A slot nobody holds is free. |
| Branch | The branch checked out in the slot. Git says how it compares with its base branch. |
| Stack | The project's local app stack, started inside the slot when the project has one. |
| Session | What is running in the slot right now, such as a runner or your console session. |
How slots are made
A project's slots live on the nodes assigned to it. You add them in two places:
- On the project's Worktrees tab: the Nodes that run it, how many slots each holds, and Pool max, the most worktrees the project may have. See How projects work.
- On the Worktrees page, with Add slots: a number of slots for one project on one node.
A new slot shows the chip Declared until its node builds it, and Observed reads never — still a declaration until then. The node does the building. See How nodes work.
Who holds a slot, and for how long
When a task starts, Jaah gives it a free slot of its project on a node that takes new tasks, and the runner works there. A console session holds a slot the same way, for the person using it. The Occupancy filter names the three cases: Free, Held by a task and Held by a person.
A slot stays with its holder until the task is completed, deleted or reset, or someone releases the slot. Stopping a task doesn't end the hold, so a task you stop and start again carries on with the work already in its slot. See How tasks work.
Release ends a hold so the slot can be handed out again. It keeps the worktree and its uncommitted work, and it doesn't complete or delete the task that held it.
What a slot's row tells you
A slot's row shows these states (the Filter & view menu calls a slot with no stack Not built):
| Column | States |
|---|---|
| Git | Clean, Dirty (uncommitted work) or Diverged (ahead of or behind its base). ? until it's checked. |
| Stack | Up, Down, or None when the project has no stack. ? when there's no recent report. |
| Session | Live while a session runs in the slot; None when nobody is in it. |
The actions on selected slots follow from these: Sync Git brings a slot that is behind up to date, Stop stack stops an idle stack and keeps its data, and Delete removes the slot for good.
How slots bound the work
A task needs a free slot to start. When every slot of its project is held, it waits as Queued until one frees up. So the slots a project has, across all its nodes, set how many of its tasks run at once. To run more, add slots, or add a node and assign the project to it. An epic's subtasks each take a slot too. See How epics and features work.
Who can do what
Anyone who can view worktrees sees the page. Releasing a slot needs the permission to edit worktrees. Adding and deleting slots needs the org admin role. See How team and access work.