Skip to content

Worktrees

A worktree is an isolated git working directory linked to the same repository. Each worktree has its own branch, its own working tree, and — in RaiSE — its own environment files. They are the mechanism that makes true parallel story work possible without branch switching or stash juggling.

Why Worktrees?

Without worktrees, parallel work requires constant git stash / git checkout cycles, or multiple repository clones. Both are fragile. git stash silently drops with hooks; clones drift out of sync.

RaiSE's worktree model gives each stream of work its own directory, its own .env files, and its own mission binding — fully isolated from the main checkout and from each other.

RaiSE Worktree Model

RaiSE manages worktrees as first-class objects registered in the consolidated database. Creation uses git worktree add followed by rai worktree register, which:

  1. Creates the git worktree under .worktree/{repo-name}-{slug}/
  2. Propagates environment files listed in .worktreeinclude
  3. Registers the worktree in ~/.rai/raise.db with its merge target and associated stories
  4. Sets up the worktree for rai commands (project path resolution)

Closing uses rai worktree complete (marks status as closed) followed by rai worktree prune (removes merged/stale worktrees and their branches).

Worktree Naming

Worktrees live at:

.worktree/{repo-name}-{slug}/

For example: .worktree/raise-commons-docs-release-31b1/

The slug is derived from the branch name or a short label you provide at creation.

Environment File Propagation

Secrets and local configuration (.env, .env.local, .raise/secrets.yaml) are not tracked in git but are needed in each worktree. The .worktreeinclude file at the repo root lists which files to copy:

.env
.env.local
.raise/mcp/openai.yaml

The worktree creation process reads this file and copies each listed path into the new worktree. Changes to these files in the main checkout are not automatically synced — re-copy manually when needed.

Mission Binding

Every worktree is bound to a mission at creation time. Sessions started inside the worktree automatically bind to that mission — no manual selection.

This is the recommended pattern: one worktree per work item, persistent across all epics and stories bound to it. Don't create a new worktree per story; create one per work item and work stories sequentially (or fan out to multiple worktrees for parallel epic tracks).

Branch Model Inside a Worktree

For epic-level work in a worktree, the branch convention is:

worktree-{epic-slug}    ← intermediate branch (never pushed to remote)
  └── story/{id}/{name} ← story branches, created and merged here

Story branches are created from and merged back to the worktree-{epic-slug} branch. When the epic is complete, the epic branch is merged to the release branch via MR — a single clean diff per epic.

release/3.1.0
  └── worktree-my-epic   (local only)
       └── story/s1.1/feature-a  (merged back to worktree-my-epic)
       └── story/s1.2/feature-b  (merged back to worktree-my-epic)

CLI Summary

Command What it does
rai worktree register Register a worktree with its merge target and associated stories
rai worktree resolve-base Resolve the base branch/ref for a new worktree
rai worktree context Show worktree context: branch, merge target, stories, status
rai worktree complete Mark a worktree as complete (status → closed)
rai worktree list List worktrees for the current project
rai worktree prune Delete merged/stale worktrees and their branches

Next Steps