The Art of Committing

A commit message is not a description—it's communication. It tells your future self (and your team) not just what changed, but why it matters.

Philosophy

Bad commits describe files: "Updated user.ts"
Good commits describe intent: "fix(auth): prevent session fixation on login"

The best commit messages answer three questions:

1. What type of change is this? (feat, fix, refactor, docs, etc.)
2. What area is affected? (auth, api, ui, etc.)
3. Why was this change necessary? (the actual message)

---

Before You Write

1. Analyze the Changes

git status
git diff --staged

Understand:

• Which files changed and why
• Is this ONE logical change or multiple?
• What problem does this solve?

2. Check Project Conventions

Look for existing patterns:

• Read recent commits: git log --oneline -20
• Check for commitlint config, CONTRIBUTING.md, or similar
• Match the project's style (lowercase? uppercase? emoji?)

3. Determine the Type

Type	When to Use
feat	New feature for the user
fix	Bug fix
refactor	Code change that neither fixes nor adds
docs	Documentation only
style	Formatting, missing semicolons, etc.
test	Adding or fixing tests
chore	Maintenance (deps, config, etc.)
perf	Performance improvement
ci	CI/CD changes

---

Commit Message Format

<type>(<scope>): <subject>

[optional body]

[optional footer]

Subject Line Rules

• Imperative mood: "add feature" not "added feature"
• No period at the end
• Max 50 characters (hard limit: 72)
• Lowercase (unless project uses different convention)

Body (When Needed)

Use the body when the "why" isn't obvious:

fix(auth): invalidate sessions on password change

Previously, changing password didn't invalidate existing sessions,
allowing attackers with stolen session tokens to maintain access.

This closes a security vulnerability reported in #142.

Footer (When Needed)

• Breaking changes: BREAKING CHANGE: description
• Issue references: Closes #123, Fixes #456
• Co-authors: Co-authored-by: Name <email>

---

Multi-Change Commits

If you have multiple unrelated changes staged, stop.

Ask yourself:

• Can I split this into separate commits?
• Is there a logical grouping?

If truly atomic commit isn't possible, list changes:

chore: update dependencies and fix linting

- Bump typescript to 5.0
- Fix eslint errors in auth module
- Update jest configuration

---

Examples

Simple Feature

feat(cart): add quantity selector to product cards

Bug Fix with Context

fix(api): handle null response from payment gateway

The Stripe API occasionally returns null for declined cards
instead of an error object. This caused unhandled exceptions
in production.

Fixes #234

Refactoring

refactor(auth): extract token validation to separate service

No functional changes. Improves testability and prepares
for upcoming OAuth integration.

Breaking Change

feat(api): require authentication for all endpoints

BREAKING CHANGE: All API endpoints now require valid JWT.
Unauthenticated requests return 401 instead of proceeding
with limited data.

Migration guide: https://docs.example.com/auth-migration

---

What NOT to Do

• ❌ "Fixed stuff" — What stuff? Why?
• ❌ "WIP" — Commits should be complete units
• ❌ "asdfasdf" — Respect your future self
• ❌ "Updated file.ts" — The diff shows that; tell me WHY
• ❌ Mixing unrelated changes — One commit, one purpose

---

Your Task

1. Run git diff --staged to see what's being committed
2. Run git log --oneline -10 to understand project conventions
3. Determine the type, scope, and intent
4. Generate a commit message following the format above
5. If changes should be split, suggest that first

If --amend is specified: Review the previous commit and suggest an improved message.

If --scope is specified: Use that scope in the commit type.

Now analyze: $ARGUMENTS