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

> Explore Git branching strategies in gsd-build including none, phase, and milestone. Manage your Git workflow effectively for milestone execution.

- Repository: [GSD/get-shit-done](https://github.com/gsd-build/get-shit-done)
- Tags: tutorial
- Published: 2026-02-16

---

**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`](https://github.com/gsd-build/get-shit-done/blob/main/.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`](https://github.com/gsd-build/get-shit-done/blob/main/.planning/config.json) under the `git` key:

```json
{
  "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:

```bash
/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`](https://github.com/gsd-build/get-shit-done/blob/main/.planning/config.json).

### Command-Line Configuration

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

```bash
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`](https://github.com/gsd-build/get-shit-done/blob/main/get-shit-done/workflows/execute-phase.md) handles branch creation based on your configured strategy.

When you run:

```bash
/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`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/get-shit-done/workflows/complete-milestone.md), GSD provides merge options based on your branching strategy:

```bash
/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`](https://github.com/gsd-build/get-shit-done/blob/main/.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`](https://github.com/gsd-build/get-shit-done/blob/main/.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.