/git-flow

name: git-flow
description: Use when committing, branching, opening PRs, or deciding merge/branch strategy.
user-invocable: false
related-skills: commit-optimization, post-commit, commit-detection

<objective> Covers Git workflow strategy end to end: the GitHub Flow (default) vs trunk-based vs Git Flow tradeoff table, the branch naming convention (`<type>/<scope-or-summary>`, kebab-case, <50 chars, no personal prefix), protected-branch enforcement (main/master/develop/production never committed to directly, auto-named feature branch proposed instead), the full branch lifecycle (create → work → push → PR → review → merge → delete), merge strategy (real merge commit is fuse-commit-pro's default; rebase vs squash tradeoffs — squash is unused here because it would orphan the release tag's target commit), the CI-gate-before-merge decision tree (three cases by whether required checks are configured, including the `gh pr checks` registration-race workaround), post-merge tag timing, the PR description template, anti-patterns, and solo-dev mode. </objective>

Git Flow Best Practices (2026)

Workflow Choice

| Strategy | When | Verdict | |----------|------|---------| | **Trunk-based** (direct main) | Solo dev, prototypes, strong CI | OK if you have automated tests | | **GitHub Flow** (feature branch → PR → merge → delete) | Teams, OSS, code review | ✅ Default | | **Git Flow** (develop/release/hotfix) | Heavy release cycles | ❌ Outdated for most projects |

**fuse-commit-pro default: GitHub Flow.**

Branch Naming Convention

Format: `<type>/<scope-or-summary>` (kebab-case).

| Type | Use | Example | |------|-----|---------| | `feat/` | New feature | `feat/seo`, `feat/oauth-google` | | `fix/` | Bug fix | `fix/sniper-loop`, `fix/csv-parser` | | `chore/` | Maintenance, deps | `chore/bump-deps`, `chore/rename-files` | | `docs/` | Documentation | `docs/api-reference` | | `refactor/` | Refactoring (no behavior change) | `refactor/extract-utils` | | `perf/` | Performance | `perf/db-indexes` | | `test/` | Tests only | `test/auth-coverage` | | `ci/` | CI/CD config | `ci/github-actions-cache` | | `build/` | Build system | `build/vite-config` | | `style/` | Formatting | `style/prettier-pass` |

**Rules**:

• kebab-case only (no underscores, no spaces, no caps)
• < 50 chars total
• No personal prefix (`bruno/...`) — collaborators don't know who you are 6 months later
• No issue number alone (`fix/123`) — meaningless once issue closed

Protected Branches

`main`, `master`, `develop`, `production` → **never commit directly**.

`fuse-commit-pro:commit` enforces this in Step 0:

• Detects current branch
• If protected → blocks + proposes auto-named feature branch from commit type/scope
• Exceptions: solo prototype (no remote), explicit `--no-branch-check`, or post-commit version bump

Branch Lifecycle

1. git checkout -b feat/<scope>      # create
2. work + commit                      # multiple commits OK
3. git push -u origin feat/<scope>    # push with upstream
4. gh pr create                       # open PR
5. (review + CI)
6. gh pr merge --merge --delete-branch  # merge + cleanup

**Keep branches short-lived** (< 3 days ideally). Long-lived branches accumulate conflicts and lose context.

Merge Strategy

| Strategy | When | Result | |----------|------|--------| | **Merge commit** | fuse-commit-pro default | Branch commits (incl. the bump commit) land on `main` intact, no rewrite | | **Rebase merge** | Small atomic commits worth preserving, no merge commit wanted | Linear history, individual commits kept | | **Squash merge** | *not used here*: the release tag points at the bump commit, squash would orphan it | 1 commit per feature, but incompatible with fuse-commit-pro's post-merge tagging |

**fuse-commit-pro recommendation**: real merge commit via `gh pr merge --merge --delete-branch` (see `commands/commit.md` Step 7).

CI Gate Before Merge

**Cardinal rule: never merge before CI checks are resolved; never assume "zero CI" without verifying.**

**Known race condition** ([cli/cli#7401](https://github.com/cli/cli/issues/7401), confirmed by GitHub CLI maintainers): checks take a few seconds to register on a freshly-created PR. Calling `gh pr checks --watch` immediately after `gh pr create` can error out — exit code 1, `no checks reported on the '<branch>' branch` — even though checks are about to appear. The GitHub API gives no way to tell "genuinely zero checks" apart from "not registered yet," so the client must either sidestep the race (native auto-merge) or poll for registration before watching.

Determine which of the three cases applies from what actually exists on the PR — never from assumption. The key branch point is **whether the repo enforces *required* status checks in branch protection**, not merely whether auto-merge is available: `gh pr merge --auto` only ever waits for *required* checks. On a repo where checks run but aren't marked required (e.g. this repo — CodeQL + Analyze execute but aren't required), `--auto` merges **immediately without waiting**, silently reproducing the exact race this section exists to close. Check first with `gh pr checks <pr> --required` (empty output / `no required checks reported on the '<branch>' branch` → no required checks configured) before picking a branch:

1. **Repo has required status checks in branch protection** → the only case where `--auto` actually gates. GitHub waits server-side for the *required* checks to appear and pass — no race, regardless of their state at call time:

   gh pr merge <pr> --auto --merge --delete-branch

Also requires "Allow auto-merge" enabled in repo Settings → General (otherwise `GraphQL: Auto merge is not allowed for this repository`). 2. **Repo has checks but none are required** (this repo's current state — CodeQL/Analyze run but aren't required) — `--auto` would merge immediately without waiting, so don't use it here. Poll client-side until checks register, then watch: don't