| name | git-workflow |
| description | Covers branching strategies, commit conventions, PR creation, and squash merge workflow. Use when creating branches, writing commits, creating or merging PRs, or managing git history. Provides patterns for collaborative git workflows. Not for code style (use foundations) or CI/CD pipelines (use infrastructure-management). |
Git Workflow
Git conventions for branching, commits, PRs, and merge workflow.
Contents
- Critical Rules
- Verification
- Quick Reference
- Topics
Critical Rules
- Use Conventional Commits format for all commit messages
- Commit complete units of work -- don't commit partial or in-progress changes
- Squash merge feature branches -- never merge commits directly
- One branch per shippable root;
loaf issue start walks to that root and creates or joins issue/<root-alias-or-id> (or use feat/{slug} / fix/{slug} when not starting from an issue). Related child issues share the parent's branch and the PR to main.
- Never force-push to
main or shared branches
- Never push without explicit user confirmation
Verification
- Commit messages follow unscoped Conventional Commits format (
type: description)
- Branch is up to date with base branch before creating PR
- PR title is under 70 characters with PR# suffix convention
Quick Reference
| Action | Command/Pattern |
|---|
| Branch naming | issue/<root-alias-or-id> from loaf issue start; else feat/{slug}, fix/{slug}, chore/{slug} |
| Commit format | type: description |
| Squash merge | gh pr merge --squash |
| PR creation | gh pr create --title "..." --body "..." |
Topics
| Topic | Reference | Use When |
|---|
| Commits | references/commits.md | Writing commit messages, creating PRs, branching, curating CHANGELOG entries, pre-PR/pre-push/post-merge hooks |
| PR shipping | ship skill | Reviewing, verifying, and squash-merging one PR |
| Release ritual | release skill | Publishing a version from already-landed work |
