Git Strategy

GSD uses git worktrees for milestone isolation and sequential commits within each milestone. The strategy is fully automated — you don't need to manage branches manually.

Branching Model

main ─────────────────────────────────────────────────────────
  │                                                     ↑
  └── milestone/M001 (worktree) ────────────────────────┘
       commit: feat(S01/T01): core types
       commit: feat(S01/T02): markdown parser
       commit: feat(S01/T03): file writer
       commit: docs(M001/S01): workflow docs
       ...
       → squash-merged to main as single commit

Key Properties

One worktree per milestone — all work happens in .gsd/worktrees/<MID>/
Sequential commits on one branch — no per-slice branches, no merge conflicts within a milestone
Squash merge to main — when the milestone completes, all commits are squashed into one clean commit on main
Worktree teardown — after merge, the worktree and branch are cleaned up

Commit Format

Commits use conventional commit format with scope:

feat(S01/T01): core type definitions
feat(S01/T02): markdown parser for plan files
fix(M001/S03): bug fixes and doc corrections
docs(M001/S04): workflow documentation

Worktree Management

Automatic (Auto Mode)

Auto mode creates and manages worktrees automatically:

When a milestone starts, a worktree is created at .gsd/worktrees/<MID>/ on branch milestone/<MID>
Planning artifacts from .gsd/milestones/ are copied into the worktree
All execution happens inside the worktree
On milestone completion, the worktree is squash-merged to the integration branch
The worktree and branch are removed

Manual

Use the /worktree (or /wt) command for manual worktree management:

/worktree create
/worktree switch
/worktree merge
/worktree remove

Git Preferences

Configure git behavior in preferences:

git:
  auto_push: false            # push after commits
  push_branches: false        # push milestone branch
  remote: origin
  snapshots: false            # WIP snapshot commits
  pre_merge_check: false      # pre-merge validation
  commit_type: feat           # override commit type prefix
  main_branch: main           # primary branch name
  commit_docs: true           # commit .gsd/ to git

`commit_docs: false`

When set to false, GSD adds .gsd/ to .gitignore and keeps all planning artifacts local-only. Useful for teams where only some members use GSD, or when company policy requires a clean repository.

Self-Healing

GSD includes automatic recovery for common git issues:

Detached HEAD — automatically reattaches to the correct branch
Stale lock files — removes index.lock files from crashed processes
Orphaned worktrees — detects and offers to clean up abandoned worktrees

Run /gsd doctor to check git health manually.

Native Git Operations

Since v2.16, GSD uses libgit2 via native bindings for read-heavy operations in the dispatch hot path. This eliminates ~70 process spawns per dispatch cycle, improving auto-mode throughput.

3.3 KiB Raw Blame History