d20d5e8fb5
Add a proper public-facing documentation site using Mintlify with 19 MDX pages covering getting started, auto mode, commands, configuration, and all user-facing features. Move internal/SDK documentation (Pi SDK, TUI, context & hooks, research notes, ADRs) to docs-internal/ since they should not be part of the public documentation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
150 lines
4.8 KiB
Text
150 lines
4.8 KiB
Text
---
|
|
title: "Git strategy"
|
|
description: "Isolation modes, branching model, and merge behavior for milestone work."
|
|
---
|
|
|
|
GSD uses git for milestone isolation and sequential commits. You choose an **isolation mode** that controls where work happens. The strategy is fully automated — no manual branch management needed.
|
|
|
|
## Isolation modes
|
|
|
|
Configure via the `git.isolation` preference:
|
|
|
|
| Mode | Working directory | Branch | Best for |
|
|
|------|-------------------|--------|----------|
|
|
| `worktree` (default) | `.gsd/worktrees/<MID>/` | `milestone/<MID>` | Most projects — full file isolation |
|
|
| `branch` | Project root | `milestone/<MID>` | Submodule-heavy repos |
|
|
| `none` | Project root | Current branch | Hot-reload workflows |
|
|
|
|
### `worktree` mode (default)
|
|
|
|
Each milestone gets its own git worktree on a `milestone/<MID>` branch. All execution happens inside the worktree. On completion, the worktree is squash-merged to main as one clean commit. The worktree and branch are cleaned up.
|
|
|
|
### `branch` mode
|
|
|
|
Work happens in the project root on a `milestone/<MID>` branch. No worktree is created. On completion, the branch is merged to main.
|
|
|
|
### `none` mode
|
|
|
|
Work happens directly on your current branch. No worktree, no milestone branch. GSD still commits sequentially with conventional commit messages, but there's no branch isolation.
|
|
|
|
## Branching model
|
|
|
|
```
|
|
main ─────────────────────────────────────────────────────────
|
|
│ ↑
|
|
└── milestone/M001 (worktree) ────────────────────────┘
|
|
commit: feat(S01/T01): core types
|
|
commit: feat(S01/T02): markdown parser
|
|
commit: feat(S01/T03): file writer
|
|
→ squash-merged to main as single commit
|
|
```
|
|
|
|
### Parallel worktrees
|
|
|
|
With [parallel orchestration](/guides/parallel-orchestration) enabled, multiple milestones run in separate worktrees simultaneously:
|
|
|
|
```
|
|
main ──────────────────────────────────────────────────────────
|
|
│ ↑ ↑
|
|
├── milestone/M002 (worktree) ─────────┘ │
|
|
│ → squash-merged first │
|
|
│ │
|
|
└── milestone/M003 (worktree) ────────────────────────┘
|
|
→ squash-merged second
|
|
```
|
|
|
|
Merges happen sequentially to avoid conflicts.
|
|
|
|
### Commit format
|
|
|
|
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
|
|
```
|
|
|
|
## Workflow modes
|
|
|
|
Set `mode` to get sensible defaults:
|
|
|
|
```yaml
|
|
mode: solo # personal projects
|
|
mode: team # shared repos
|
|
```
|
|
|
|
| Setting | `solo` | `team` |
|
|
|---|---|---|
|
|
| `git.auto_push` | `true` | `false` |
|
|
| `git.push_branches` | `false` | `true` |
|
|
| `git.pre_merge_check` | `false` | `true` |
|
|
| `git.merge_strategy` | `"squash"` | `"squash"` |
|
|
| `unique_milestone_ids` | `false` | `true` |
|
|
|
|
Mode defaults are the lowest priority — any explicit preference overrides them.
|
|
|
|
## Git preferences
|
|
|
|
```yaml
|
|
git:
|
|
auto_push: false
|
|
push_branches: false
|
|
remote: origin
|
|
snapshots: false
|
|
pre_merge_check: false
|
|
commit_type: feat
|
|
main_branch: main
|
|
merge_strategy: squash # "squash" or "merge"
|
|
isolation: worktree # "worktree", "branch", or "none"
|
|
commit_docs: true
|
|
auto_pr: false
|
|
pr_target_branch: develop
|
|
```
|
|
|
|
### Automatic pull requests
|
|
|
|
For teams using Gitflow or branch-based workflows:
|
|
|
|
```yaml
|
|
git:
|
|
auto_push: true
|
|
auto_pr: true
|
|
pr_target_branch: develop
|
|
```
|
|
|
|
Pushes the milestone branch and creates a PR targeting your specified branch. Requires `gh` CLI installed and authenticated.
|
|
|
|
### `commit_docs: false`
|
|
|
|
Adds `.gsd/` to `.gitignore` and keeps all planning artifacts local-only. Useful for teams where only some members use GSD.
|
|
|
|
## Worktree management
|
|
|
|
### Automatic (auto mode)
|
|
|
|
1. Milestone starts → worktree created at `.gsd/worktrees/<MID>/`
|
|
2. Planning artifacts copied into the worktree
|
|
3. All execution happens inside the worktree
|
|
4. Milestone completes → squash-merged to main
|
|
5. Worktree and branch cleaned up
|
|
|
|
### Manual
|
|
|
|
```
|
|
/worktree create
|
|
/worktree switch
|
|
/worktree merge
|
|
/worktree remove
|
|
```
|
|
|
|
## 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 cleanup
|
|
|
|
Run `/gsd doctor` to check git health manually.
|