singularity-forge/docs/git-strategy.md

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:

1. When a milestone starts, a worktree is created at .gsd/worktrees/<MID>/ on branch milestone/<MID>
2. Planning artifacts from .gsd/milestones/ are copied into the worktree
3. All execution happens inside the worktree
4. On milestone completion, the worktree is squash-merged to the integration branch
5. 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

Workflow Modes

Instead of configuring each git setting individually, set mode to get sensible defaults for your workflow:

mode: solo    # personal projects — auto-push, squash, simple IDs
mode: team    # shared repos — unique IDs, push branches, pre-merge checks

Setting	solo	team
git.auto_push	true	false
git.push_branches	false	true
git.pre_merge_check	false	true
git.merge_strategy	"squash"	"squash"
git.isolation	"worktree"	"worktree"
git.commit_docs	true	true
unique_milestone_ids	false	true

Mode defaults are the lowest priority — any explicit preference overrides them. For example, mode: solo with git.auto_push: false gives you everything from solo except auto-push.

Existing configs without mode work exactly as before — no defaults are injected.

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.