Commit work

Goal

Make commits that are easy to review and safe to ship:

• only intended changes are included
• commits are logically scoped (split when needed)
• commit messages describe what changed and why

Inputs to ask for (if missing)

• Single commit or multiple commits? Default to multiple small commits when there are unrelated changes.
• Any extra rules: max subject length, required scopes.

Workflow

1. Inspect the working tree
   • git status and git diff (unstaged)
   • If many changes: git diff --stat
2. Decide commit boundaries (split if needed)
   • Split by: feature vs refactor, backend vs frontend, formatting vs logic, tests vs prod code, dependency bumps vs behavior changes
   • If you cannot describe the commit cleanly in one sentence, it's too big — split further
3. Stage only what belongs in the next commit
   • Use git add -p for mixed changes in one file
   • To unstage: git restore --staged -p or git restore --staged <path>
4. Review what will be committed
   • git diff --cached
   • Verify: no secrets/tokens, no debug logging, no unrelated formatting churn
5. Describe the staged change in 1-2 sentences before writing the message
   • "What changed?" + "Why?"
   • If you cannot describe it cleanly, the commit is probably too big or mixed — go back to step 2
6. Write the commit message (see format below)
   • Prefer git commit -v for multi-line messages
7. Verify — run the repo's fastest relevant check (lint, unit tests, or build)
8. Repeat for the next commit until the working tree is clean

Organization Rules

• Changes with their tests go in the same commit
• If 2 unrelated changes are in one file, use patch staging to organize commits
• Documentation files (README.md, Schemas.yaml, etc.) go in separate commit
• Translation files go in separate commit
• Separate dependency installation from usage (two commits)
• One commit = one responsibility

Commit Format

Format: type(context): description

Types

• feat: new feature
• fix: bug fix
• docs: documentation changes
• style: formatting, no code change
• refactor: code change without new feature or fix
• perf: performance improvement
• test: adding or fixing tests
• chore: build process or auxiliary tools

Rules

• Context in kebab-case (e.g., user-signup)
• Optional component after context with / (e.g., api/LoginService)
• Imperative verb: "add" not "added" or "adds"
• No capital letter at start
• No period at end
• Max 100 characters
• Body (optional): what changed and why, not implementation diary
• Footer: BREAKING CHANGE: if applicable

Deliverable

• The final commit message(s)
• A short summary per commit (what/why)
• The commands used to stage/review (at minimum: git diff --cached, plus any tests run)

Important

• Keep messages concise and direct