git-workflow

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 hygie

SKILL.md

GitHub

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

  • Branch name matches feat/, fix/, or chore/ intent
  • Commit subject uses a conventional commit type
  • Commit body explains why the change exists when context is non-trivial
  • PR title matches commit style
  • Merge strategy fits the branch history
  • Shared history is never force-pushed without --force-with-lease
  • Review fixups are squashed or left intentionally