Skip to main content
GSD Pi can isolate each milestone’s work in its own Git worktree — a separate directory with its own branch, fully decoupled from your main checkout. This prevents in-progress work from bleeding into your dev environment and makes parallel milestone execution possible. Choose the isolation mode that best fits your project structure.

​
Isolation Modes

GSD supports three isolation modes, set via git.isolation in your PREFERENCES.md:

none

Default. Work happens directly on your current branch. No worktree or milestone branch is created. Best for hot-reload workflows or small projects where branch overhead isn’t worth it.

worktree

Each milestone gets its own directory at .gsd/worktrees/<MID>/ on a milestone/<MID> branch. Work is fully isolated. Squash-merged to main on completion.

branch

Work stays in the project root but on a milestone/<MID> branch. No separate directory. Useful for submodule-heavy repos where worktrees cause symlink problems.
Set your preferred mode in PREFERENCES.md: 
git:
  isolation: worktree   # "none" (default), "worktree", or "branch"
Worktree mode requires at least one commit in the repository. In a zero-commit repo, GSD temporarily falls back to none mode until the first commit exists, then automatically resolves to worktree.

​
Worktree CLI Commands

Use these commands from your shell (outside a GSD session) to inspect and manage worktrees: 
gsd worktree list            # List all GSD-managed worktrees
gsd worktree merge [name]    # Merge a worktree back to main
gsd worktree clean           # Remove only merged or empty worktrees
gsd worktree remove <name>   # Remove a specific worktree
gsd worktree remove <name> --force   # Force-remove even with unmerged changes

​
In-Session Worktree Commands

From inside an active GSD TUI session, use the /gsd worktree family of commands (alias: /gsd wt):
CommandDescription
/gsd worktree listShow each worktree’s branch, path, diff stats, commit count, and status
/gsd worktree merge [name]Merge a worktree into main and remove it afterward
/gsd worktree cleanRemove merged or empty worktrees; keep anything with pending changes
/gsd worktree remove <name>Remove a named worktree and its branch
/gsd worktree remove <name> --forceForce-remove, discarding unmerged or uncommitted work
remove --force permanently discards any unmerged commits and uncommitted changes in the worktree. Always review with worktree list before forcing removal.

​
Starting a Session in a Specific Worktree

Use the --worktree flag (short: -w) when launching GSD to open a session directly inside a named worktree: 
gsd --worktree my-feature     # Start in the "my-feature" worktree
gsd -w                        # Start in a new auto-named worktree
If you omit the name, GSD generates one automatically.

​
Merge Behavior

When a worktree milestone completes, GSD handles the merge automatically:
1

Sequential commits on the milestone branch

All task commits land on milestone/<MID> with conventional commit messages and GSD-Task trailers.
2

Squash merge to main

By default, all commits are squashed into one clean commit on your main branch. Change this with git.merge_strategy: merge to preserve individual commits.
3

Worktree and branch cleanup

The worktree directory and milestone branch are removed automatically after a successful merge.

​
Parallel Milestones

When you have independent milestones, you can run them simultaneously in separate worktrees. GSD’s parallel orchestration engine manages worker processes, coordinates shared project state, and merges back to main when each milestone finishes. Use the /gsd parallel commands to manage parallel execution:
CommandDescription
/gsd parallel startAnalyze eligibility and spawn workers for ready milestones
/gsd parallel statusShow all workers with their state, progress, and cost
/gsd parallel stop [MID]Stop all workers, or a specific milestone’s worker
/gsd parallel pause [MID]Pause all workers, or a specific one
/gsd parallel resume [MID]Resume paused workers
/gsd parallel merge [MID]Merge completed milestones back to main
Enable parallel mode in your preferences before using these commands: 
parallel:
  enabled: true
  max_workers: 2        # 1–4 concurrent workers
  budget_ceiling: 50.00 # Aggregate cost limit in USD (optional)
  merge_strategy: "per-milestone"
  auto_merge: "confirm" # "auto", "confirm", or "manual"
Run /gsd parallel start and GSD will show you an eligibility report before spawning any workers — including dependency checks and file overlap warnings for milestones that touch the same files.

​
Safety Behavior

Auto-commit before merge

worktree merge auto-commits dirty files in the worktree before merging when possible, so you don’t lose uncommitted work.

Conflict-aware merge

Merge stops and reports which files conflict rather than silently failing. Resolve manually, then retry with /gsd parallel merge <MID>.

Clean only safe worktrees

worktree clean never removes worktrees with pending diffs or uncommitted changes — only merged or empty ones.

Detached HEAD protection

Merge and worktree flows refuse to proceed from a detached project root. Check out your integration branch first.

​
Worktree Post-Create Hooks

Run a custom script automatically after GSD creates a new worktree — useful for copying .env files, symlinking asset directories, or running setup commands the worktree doesn’t inherit from the main tree: 
git:
  worktree_post_create: .gsd/hooks/post-worktree-create
The hook receives two environment variables: SOURCE_DIR (the original project root) and WORKTREE_DIR (the newly created worktree path). 
#!/bin/bash
cp "$SOURCE_DIR/.env" "$WORKTREE_DIR/.env"
ln -sf "$SOURCE_DIR/assets" "$WORKTREE_DIR/assets"