Committing

Committing Skill

Create meaningful, conventional commits that tell the story of your changes.

Workflow

1. Analyze Staged Changes

# See what's staged
git diff --staged --stat

# See detailed changes
git diff --staged

Understand the changes:

• What files changed?
• What's the nature of the change?
• Is this one logical change or multiple?

2. Determine Commit Type

3. Extract Scope (Optional)

Scope identifies the area of the codebase:

feat(auth): add password reset flow
fix(api): handle null response
refactor(cart): extract price calculation

Common scopes:

• Component/module name: auth, cart, user
• Layer: api, ui, db
• Feature area: checkout, search, settings

4. Write the Message

Format:

<type>(<scope>): <description>

[optional body]

[optional footer]

Description rules:

• Imperative mood: "add" not "added" or "adds"
• Lowercase first letter
• No period at end
• Max 50 characters for subject line
• Explain what and why, not how

5. Verify and Commit

# One more look
git diff --staged

# Commit
git commit -m "type(scope): description"

# Or with body
git commit -m "type(scope): description

More detailed explanation if needed.
Explain why this change was made."

Quick Reference

Good Commit Messages

feat(auth): add two-factor authentication

fix(api): prevent null pointer on empty response

refactor(user): extract validation to separate module

docs(readme): add installation instructions

test(cart): add edge cases for discount calculation

chore(deps): upgrade react to 18.2

Bad Commit Messages

# Too vague
fixed stuff
updates
WIP

# Not imperative
added new feature
fixing bug

# Too long/detailed in subject
feat: add new user authentication system with support for OAuth, SAML, and password-based auth

Commit Scope Detection

Based on changed files:

Breaking Changes

For breaking changes, add ! after type/scope:

feat(api)!: change response format

BREAKING CHANGE: Response now returns { data, meta } instead of raw data.

Multiple Changes

Split into multiple commits when:

• Changes are logically separate
• Different types (fix AND feat)
• Could be reverted independently

Keep together when:

• Changes are related to same feature
• One change requires the other
• Tests for the feature being added

# Stage selectively
git add -p  # interactive staging
git add src/feature.ts
git commit -m "feat: add feature"

git add tests/feature.test.ts
git commit -m "test: add tests for feature"

See Also

• examples.md - More commit message examples by scenario