# Worktrees Every task gets its own git worktree: an isolated directory on its own branch. Work on several tasks at once without branch switching, stashing, or agents overwriting each other. ## How tasks map to worktrees Git worktrees let one repository check out several branches into separate directories at the same time. Ouijit creates one per task when the task starts, so each piece of work has its own directory and branch. ``` ~/Ouijit/worktrees/ my-project/ T-42/ # Worktree for task 42 T-43/ # Worktree for task 43 ``` ## Task lifecycle A task has one of four statuses: **To Do**, **In Progress**, **In Review**, **Done**. Each event below changes the status and can run a [hook](https://ouijit.com/docs/hooks/). | Event | Status | What Ouijit does | | --- | --- | --- | | **Create** | → To Do | Adds a task card to the To Do column. | | **Start** | To Do → In Progress | Creates a branch (e.g. `T-42`) and a worktree at `~/Ouijit/worktrees//T-42`, opens a terminal in it, runs the `start` hook. | | **Continue** | In Review or Done → In Progress | Opens a new terminal in the existing worktree, runs the `continue` hook. | | **Review** | → In Review | Runs the `review` hook. | | **Done** | → Done | Runs the `done` hook. | | **Delete** | Task removed | Moves the worktree to the trash, deletes the branch. | ## Merge targets Each task has a merge target, the branch its work is destined for. It defaults to the repository's main branch and drives the default [diff base](https://ouijit.com/docs/diff/). Set it per task to chain a task off a parent branch: ``` ouijit task set-merge-target 43 T-42 ``` ## Copy-on-write cloning Ouijit clones worktrees with copy-on-write (APFS on macOS, btrfs/XFS reflinks on Linux): - Worktree creation is fast regardless of repository size. - Disk usage is proportional to your changes, not the full repository. - Gitignored files (dependencies, build caches) come along, so the worktree is ready to run. ## Choose a creation mode Each project picks how new worktrees are populated, under **Project Settings → Worktree**. | Mode | What lands in the worktree | When to pick it | | --- | --- | --- | | **Quick start** (default) | Tracked files plus a copy-on-write clone of every gitignored path (`node_modules`, `.env`, build caches). | You want a worktree that runs immediately, with no setup step. | | **Clean checkout** | Just `git worktree add`. Only tracked files appear. | You want a reproducible setup driven by your [start hook](https://ouijit.com/docs/hooks/) (e.g. `npm ci`), or you don't want gitignored secrets copied across tasks. | Sandboxed tasks always use clean checkout, regardless of this setting. Provision the VM-side environment with the sandbox setup hook. ## Inspect worktrees manually Ouijit manages worktrees for you, but they are standard git worktrees: ``` # List all worktrees git worktree list # From inside a worktree, check which branch it's on git branch --show-current ```