| name | git-workflow |
| description | Git workflow guidance for branch naming, conventional commits, PR title format, merge strategy, and safe history rewriting. Use when creating branches, preparing commits, or reviewing repository hygiene. |
Git Workflow
Keep history readable, reviewable, and safe for collaborators by using consistent branch names, conventional commits, and disciplined merge behavior.
When to Activate
- Start a new feature or fix branch
- Prepare commits before opening a PR
- Rename a noisy branch before review
- Decide whether to squash or merge
- Rewrite branch history after review feedback
- Audit commit hygiene before release
- Recover from a mistaken push safely
Branch Naming
| Change Type | Pattern | Example |
|---|
| Feature | feat/<topic> | feat/api-pagination |
| Fix | fix/<topic> | fix/jwt-expiry-check |
| Chore | chore/<topic> | chore/update-ci |
Conventional Commits
| Type | Use When |
|---|
feat: | User-visible capability added |
fix: | Bug fixed |
docs: | Documentation only |
chore: | Maintenance with no product behavior change |
refactor: | Structure changed without behavior change |
test: | Tests added or updated |
perf: | Measurable performance improvement |
feat(api): add cursor pagination to list users
Why:
- offset scans were timing out on large tenants
What:
- added cursor token parsing
- exposed page.has_more
Pull Requests and Merge Strategy
| Field | Format |
|---|
| PR title | <type>(<scope>): <summary> |
| Description | problem, approach, risks, validation |
| Linked work | issue or ticket reference when available |
| Situation | Preferred | Avoid |
|---|
| Small feature branch | Squash merge | Preserving noisy fixup history |
| Multi-commit change with meaningful milestones | Merge commit | Squashing away useful audit trail |
| Local cleanup before review | Rebase locally | Rewriting shared branch unexpectedly |
Safe Rewrites
| Operation | Rule |
|---|
| Rewrite your own reviewed branch | Use --force-with-lease |
| Rewrite shared branch used by others | Do not do it without explicit coordination |
| Recover from mistaken push | Prefer revert when branch is public |
BAD
commit message: stuff
branch: new-branch
GOOD
commit message: fix(auth): reject expired refresh tokens
branch: fix/refresh-token-expiry
Checklist
