Saltar a contenido

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. They are not raw git worktree add invocations — they go through rai worktree open, 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 mission binding
  4. Sets up the worktree for rai commands (project path resolution)

The inverse is rai worktree close, which deregisters the entry and removes the directory cleanly.

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

rai worktree open 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-run rai worktree open --reprovision to refresh.

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 mission, persistent across all epics and stories in that mission. Don't create a new worktree per story; create one per mission and work stories sequentially (or fan out to multiple worktrees for parallel epic tracks).

See Missions for the mission lifecycle.

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 open Create, register, and provision a new worktree
rai worktree close Deregister and remove a worktree
rai worktree list List registered worktrees and their missions
rai worktree status Show worktree health (branch, mission, env files)

Next Steps