Git Workflow Standards

---
name: git-workflow-standards
description: >-
  Use when managing branches, resolving merge conflicts, syncing with the
  default branch, or working with worktrees. Covers both trunk repos (main)
  and git-flow repos (develop) — see gh-cli-patterns (github-workflows) for
  default-branch detection.
---

# Git Workflow Standards

Worktree setup and structure: see `superpowers:using-git-worktrees`. This
skill covers what comes after the worktree exists.

Every branch with commits MUST have an associated PR.
Orphaned branches must get a PR or be deleted.

**Stale branch** (worktree-paired, bare local, or remote-only — see
`prune-branches`, github-workflows, for the full procedure): a non-default
branch, checked out nowhere, unreferenced by any open PR (`--head` or
`--base`), with no uncommitted changes (when a worktree exists), and either
a merged PR whose `headRefOid` matches the branch tip, or zero commits ahead
of the default branch. Use `git worktree remove` (never `--force`) for
worktree-paired branches — Git blocks removal of dirty worktrees — and
`git push origin --delete` for a live remote ref, only after
`prune-branches`'s pre-push ancestry re-check.

## Branch Hygiene

- Sync the default branch daily: `git pull`
- Long-running branches: rebase from the default branch weekly
- Before PRs: ensure branch is on the latest default branch
- Never branch from feature branches — always from the default branch fresh
  (git-flow repos: `git flow feature start` branches from `develop`).
  The one exception is layering a PR stack, and only via `gh stack`; see
  `pr-stacks` (github-workflows).
- Commit messages: conventional-commit prefixes only, no emoji (see `pr-standards`)

### Git Flow Repositories

For repositories using the Git Flow model (where the default branch is `develop`):

1. **Target Branch**: All feature and bugfix branches must target and merge into `develop`.
2. **Validation**: Once changes are merged into `develop`, they must be thoroughly validated against production/tested on `develop`.
3. **End-of-Session Promotion**: At the end of every session, all changes on `develop` MUST be merged into `main` via `/promote-release`.
   This promotion is a **mandatory, non-optional step**.
4. **Planning Checklist**: You must explicitly add "Merge develop into main (promote release)" to your session to-do / plan checklist at the start of work.

| Method | When |
| --- | --- |
| `git merge origin/<default>` | Default — preserves history, safer |
| `git rebase origin/<default>` | Only if branch has NOT been pushed yet |

Sync workflow (replace `<default>` with the repo's actual default branch — see
`gh-cli-patterns`, github-workflows):

```bash
git pull origin <default>                                   # in the <default> worktree
git merge origin/<default> --no-edit                       # in the feature worktree
```

## Merge Conflict Resolution

**NEVER assume newer is correct.** Analyze both versions.

1. **Understand** — read full file, check `git log --oneline -10 -- <file>`
2. **Analyze** — identify what each side changed and why, check compatibility
3. **Resolve** — use the resolution table below
4. **Verify** — run `pre-commit run --files <file>`, read resolved file

| Scenario | Resolution |
| --- | --- |
| Additive changes | Keep both |
| Same logic modified | Combine intent of both |
| One is a bug fix | Always include the fix |
| One is a refactor | Apply refactor, then add other change |
| Truly incompatible | Prefer branch's changes, add comment |

Escalate to human review for complex business logic, fundamental
contradictions, or security-sensitive code.

| Command | Purpose |
| --- | --- |
| `git diff --name-only --diff-filter=U` | List conflicted files |
| `git log --merge -p <file>` | Show commits causing conflict |
| `git show :1:<file>` | Common ancestor version |
| `git show :2:<file>` | HEAD (your branch) version |
| `git show :3:<file>` | Incoming (their branch) version |
| `git merge --abort` | Abort and return to pre-merge state |

## Related Skills

- **sync-main** (git-workflows) — Syncs the repo's default branch and merges into current or all PR branches
- **refresh-repo** (github-workflows) — PR status and default-branch sync
- **prune-branches** (github-workflows) — Stale branch and worktree cleanup
- **pr-stacks** (github-workflows) — the sanctioned exception to "never branch from feature branches": layering a PR stack
- **gh-cli-patterns** (github-workflows) — Canonical default-branch detection (trunk vs git-flow)
- **pr-standards** (github-workflows) — PR creation guards, issue linking, and review standards
- **git-flow-next** (git-workflows) — Dedicated git-flow-next guide, worktree setup, and promotion steps