Git Worktree Isolation and Parallel Milestones in GSD Pi

Use Git worktree isolation to run milestones in dedicated checkouts, keep parallel work conflict-free, and merge cleanly back to main.

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>/ (a sibling of .gsd/ at your project root) 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 Location

Newly created worktrees live at <projectRoot>/.gsd-worktrees/<MID>/ — a sibling of the .gsd/ state directory, kept at the project root regardless of where .gsd state is stored. This keeps every worktree visible next to your project and out of any external state location.

Legacy location still works. Worktrees created under the older .gsd/worktrees/<MID>/ layout remain fully recognized for resolution, listing, merge, and teardown — no migration step is required. Only newly created worktrees use the canonical .gsd-worktrees/ location, so in-flight milestones survive the upgrade unchanged.

If you keep .gsd/ ignored in your repo, add the canonical location to .gitignore as well (GSD does this automatically when git.manage_gitignore: true):

.gsd/
.gsd-worktrees/

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):

Command	Description
/gsd worktree list	Show 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 clean	Remove merged or empty worktrees; keep anything with pending changes
/gsd worktree remove <name>	Remove a named worktree and its branch
/gsd worktree remove <name> --force	Force-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.

Milestone Completion in Interactive Sessions

When you complete a milestone interactively — by running gsd_complete_milestone from inside a chat or TUI session — GSD now closes out the milestone’s Git state for you instead of leaving the working tree untouched.

On every interactive milestone completion, GSD:

1. Auto-commits the dirty working tree on the current branch with a conventional commit message and a GSD-Unit: <milestoneId> trailer, so the commit is recognizable as milestone closeout evidence. A clean tree is left alone.
2. Computes a Closeout Git Verdict when git.isolation is worktree or branch, and surfaces one of two notices when the situation needs your attention:

Needs attention — isolation bypassed

The milestone was completed outside a milestone/<MID> worktree or branch even though git.isolation is worktree or branch. GSD commits the work where it sits and emits a warning naming the isolation preference that was not honored this session, so the milestone never closes silently on the wrong branch.

Merge deferred to worktree tooling

The milestone was completed on its milestone/<MID> branch as expected. GSD commits the work and emits an info notice pointing you at /gsd worktree merge to land the branch on your integration branch.

Interactive closeout only fires on milestone boundaries. gsd_task_complete and gsd_slice_complete deliberately do not auto-commit — committing at every task or slice would sweep up unrelated working-tree changes. Auto-mode is also untouched: it keeps its existing closeout pipeline.

A milestone closeout commit looks like this:

chore: complete-milestone M003

GSD-Unit: M003

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:

Command	Description
/gsd parallel start	Analyze eligibility and spawn workers for ready milestones
/gsd parallel status	Show 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"