Worktrees
A worktree is a working copy of one project on one node, called a slot. Every task runs in a slot, so a project can run as many tasks at once as it has free slots.
Where worktrees fit
Slots sit between three other parts of Jaah:
- Projects. A project's slots live on its nodes: All, or its node groups, picked in the project's Settings tab, section Nodes. See Run a project on some nodes only.
- Nodes. The machines slots live on, which build each slot themselves. A node's details show how many slots it holds and which tasks hold them. See How nodes work.
- Tasks. A starting task takes a free slot and keeps it until it is completed, deleted or reset, so a task you stop and start again picks up the work already in its slot. When every slot is held, a new task waits as Queued. See How tasks work.
If tasks often sit in Queued, the project needs more slots. Each subtask of an epic takes a slot of its own too; see How epics and features work.
Pages in this section
- How worktrees work — the terms (slot, holder, stack), how a project gets slots, who holds one and for how long, how slots bound the work, and who can change them.
- Give a project more slots — run more of a project's tasks at once, by adding a node.
- Free a held slot — find which tasks hold a node's slots, and let a waiting one go.
- Move a task off an offline node — find where a task is held, then reset it so it starts on another node.
- Run a project's stack in each slot — set the stack commands, and give each slot its own ports.
- Try a task's change in its slot — open the app a task's slot is running, before its change merges.
- Give a service a fixed port in every slot — list its port variable, so each slot keeps its own port for the service.
- See what ran in a slot — find a task's node and slot, then list every run that slot hosted and how each ended.
- Find the projects short of slots — compare running, queued and active-slot counts on the Projects list, and see why tasks wait.
- Check on a task that won't start in its slot — read its Runner field, open its console to see what it waits on, and start it over.
- Keep a slot's console open beside your work — dock, float or maximize a task's console, copy what it shows, and reconnect it.
- Fix a task whose slot couldn't copy the repository — read why the copy failed, fix it, and answer Checkout failed with Retry, a new branch or Cancel task.
- See which slots a model account is working in — hover an account's Sessions count to see its projects, slots and which are busy.
- Arrange the console's windows — use Console layout to show several of a node's sessions side by side in one console.
- Connect a slot's console straight to its node — turn on the ⚡ direct connection to skip the relay, and read its state.
Changing a project's slots and nodes needs the org admin role; see How team and access work.