Git Branching Strategies in gsd-build: A Complete Guide to none, phase, and milestone

gsd-build supports three mutually exclusive git branching strategies—none, phase, and milestone—that control when and how branches are created during milestone execution.

The Get-Shit-Done (gsd-build) automation framework provides flexible git workflows through configurable branching strategies defined in .planning/config.json. Whether you prefer linear history or structured release branches, understanding these three strategies helps you tailor GSD's behavior to your team's git conventions.

Understanding the Three Git Branching Strategies

1. none (Default)

The none strategy is the default behavior when you initialize a new GSD project. Under this configuration:

• No branch is created during milestone execution
• The workflow runs directly on your current checkout
• All commits go to the active branch without isolation

This strategy works best for solo developers or when GSD manages planning artifacts separately from code changes.

2. phase

The phase strategy creates one branch per execution phase. When enabled:

• A new branch spawns at the start of each execute-phase step
• Branch names follow the template gsd/phase-{phase}-{slug} (e.g., gsd/phase-03-auth-login)
• Users are prompted to merge each phase branch after the phase completes, or later via complete-milestone

This approach provides granular isolation between distinct implementation phases, making code reviews easier for complex milestones.

3. milestone

The milestone strategy creates a single branch for the entire milestone:

• Branch creation occurs on the first execute-phase of a milestone
• The branch persists across all phases (e.g., gsd/v1.0-mvp)
• When you run complete-milestone, GSD offers squash-merge, full merge, or branch deletion options

Use this strategy for release branches or when you want to isolate an entire feature milestone from the main branch.

Configuring Your Branching Strategy

Project Configuration File

Set your strategy in .planning/config.json under the git key:

{
  "git": {
    "branching_strategy": "phase",
    "phase_branch_template": "gsd/phase-{phase}-{slug}",
    "milestone_branch_template": "gsd/{milestone}-{slug}"
  }
}

The branching_strategy field accepts only three values: "none", "phase", or "milestone".

Interactive Settings Command

Change strategies without editing JSON directly using the built-in settings workflow:

/gsd:settings

The interactive prompt displays:

Git branching strategy?
  • None (Recommended)      – commit directly to current branch
  • Per Phase                – create branch for each phase (gsd/phase-{N}-{name})
  • Per Milestone            – create branch for the whole milestone (gsd/{version}-{name})

Selecting an option automatically updates .planning/config.json.

Command-Line Configuration

For automation or CI/CD pipelines, modify the configuration programmatically:

node -e 'const fs=require("fs"); let cfg=JSON.parse(fs.readFileSync(".planning/config.json")); cfg.git.branching_strategy="milestone"; fs.writeFileSync(".planning/config.json", JSON.stringify(cfg, null, 2));'

How Branching Works During Execution

The runtime logic in get-shit-done/workflows/execute-phase.md handles branch creation based on your configured strategy.

When you run:

/gsd:execute-phase 2

The system behaves as follows:

• none → No git checkout occurs; work continues on the current branch
• phase → Executes git checkout -b gsd/phase-02-{phase-slug} (or switches to existing branch)
• milestone → On first phase execution, creates git checkout -b gsd/{milestone}-{slug}; subsequent phases switch to this existing branch

The workflow checks config.json at runtime to determine which git operations to execute.

Completing and Merging Branches

When you finish a milestone using get-shit-done/workflows/complete-milestone.md, GSD provides merge options based on your branching strategy:

/gsd:complete-milestone

For phase strategy:

• Offers to merge each phase branch individually
• Provides squash-merge, full merge, or deletion options per branch

For milestone strategy:

• Offers single merge operation for the milestone branch
• Options include squash-merge, standard merge, or branch deletion without merging

For none strategy:

• No merge prompts appear (no branches were created)
• Completion simply marks the milestone as finished

Summary

• gsd-build supports three git branching strategies: none (default), phase, and milestone
• Configure your strategy in .planning/config.json under the git.branching_strategy key
• none runs workflows on the current branch without isolation
• phase creates isolated branches for each execution phase (e.g., gsd/phase-03-auth-login)
• milestone creates a single branch for the entire milestone lifecycle
• Change strategies interactively via /gsd:settings or programmatically via the configuration file
• Branch merging and cleanup are handled by the complete-milestone workflow based on your selected strategy

Frequently Asked Questions

How do I switch from one branching strategy to another mid-project?

You can change strategies at any time by running /gsd:settings and selecting a different option, or by manually editing .planning/config.json. However, switching strategies does not affect branches that have already been created—existing phase or milestone branches remain in your repository until you complete or delete them through the complete-milestone workflow.

Can I customize the naming convention for branches created by gsd-build?

Yes, the configuration file supports custom templates via phase_branch_template and milestone_branch_template fields. You can use placeholders like {phase}, {milestone}, and {slug} to dynamically generate branch names that match your team's naming conventions (e.g., feature/gsd-{milestone} instead of the default gsd/ prefix).

What happens if I select the phase strategy but fail to complete a phase?

If you exit or abort during a phase execution, the branch created for that phase (e.g., gsd/phase-02-feature-name) remains in your repository. When you resume the milestone later, gsd-build detects the existing branch and switches to it rather than creating a duplicate. You can clean up incomplete phase branches manually or wait until running complete-milestone, which will offer to merge or delete all pending branches.

Is the none branching strategy suitable for team environments?

The none strategy works best for solo developers or when gsd-build manages planning artifacts (like TODO files) separately from code repositories. In team environments where multiple developers work on the same codebase, using phase or milestone strategies is recommended to isolate changes, facilitate code reviews through pull requests, and prevent conflicts on shared branches.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}