Type (Required)

Type	Use For
`feat`	New feature
`fix`	Bug fix
`docs`	Documentation only
`style`	Formatting, whitespace (not CSS)
`refactor`	Code change that neither fixes nor adds
`perf`	Performance improvement
`test`	Adding or fixing tests
`build`	Build system or dependencies
`ci`	CI configuration
`chore`	Maintenance tasks
`revert`	Reverting previous commit

Scope (Optional)

The area of the codebase:

feat(auth): add OAuth login
fix(api): resolve timeout issue
docs(readme): update installation steps

Subject (Required)

Imperative mood: "add" not "added" or "adds"
Lowercase first letter
No period at end
Max 50 characters

Body (Optional)

Explain "what" and "why", not "how"
Wrap at 72 characters
Blank line between subject and body

Footer (Optional)

Breaking changes: BREAKING CHANGE: description
Issue references: Fixes #123, Closes #456

Examples

Simple Feature

feat: add user profile page

Feature with Scope

feat(auth): add password reset functionality

Bug Fix with Issue Reference

fix(cart): resolve incorrect total calculation

The cart total was not including the shipping cost
when calculating the final amount.

Fixes #234

Breaking Change

feat(api)!: change authentication to OAuth 2.0

BREAKING CHANGE: The /auth/login endpoint now requires
OAuth 2.0 credentials instead of username/password.

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

Refactoring

refactor(utils): extract date formatting to separate module

Moved date formatting functions from utils.ts to
dates.ts for better organization and reusability.

Multiple Changes

If commits have unrelated changes, split them:

# Bad: one commit with unrelated changes
git commit -m "fix: login bug and add profile page"

# Good: separate commits
git commit -m "fix(auth): resolve login timeout issue"
git commit -m "feat(profile): add user profile page"

Commit Message Process

1. Check What Changed

git status
git diff --staged

2. Determine the Type

Added something new? → feat
Fixed a bug? → fix
Only documentation? → docs
Code reorganization? → refactor

3. Identify the Scope

What area of the code?

auth, api, ui, db, config, etc.
Skip if change is global

4. Write the Subject

Start with verb: add, fix, update, remove, refactor
Be specific but concise
Focus on what, not how

5. Add Body if Needed

Include body when:

Change is complex
Context helps future readers
Non-obvious decisions were made

Good vs Bad Examples

Subject Line

# Bad
fix: fixed the bug
feat: new feature added
update: updated some stuff

# Good
fix(cart): resolve race condition in checkout
feat(search): add fuzzy matching support
refactor(api): extract validation to middleware

Body

# Bad (how, not why)
Changed the function to use a loop instead of recursion
and added a cache variable.

# Good (why)
The recursive implementation was causing stack overflow
on large datasets. Switched to iterative approach with
memoization to handle inputs up to 100k items.

Commit Workflow

# Stage specific files
git add src/auth/login.ts src/auth/login.test.ts

# Write commit message
git commit -m "fix(auth): resolve session timeout issue

Sessions were expiring immediately due to incorrect
timestamp comparison. Fixed by using UTC timestamps.

Fixes #189"

Amending Commits

# Amend last commit message
git commit --amend -m "new message"

# Add forgotten files to last commit
git add forgotten-file.ts
git commit --amend --no-edit

Warning: Don't amend commits that have been pushed.

Commit Message Template

Create .gitmessage template:

# <type>(<scope>): <subject>
#
# <body>
#
# <footer>

# Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore
# Scope: auth, api, ui, db, etc. (optional)
# Subject: imperative, lowercase, no period, max 50 chars
# Body: what and why, wrap at 72 chars
# Footer: BREAKING CHANGE:, Fixes #, Closes #

Configure git:

git config --global commit.template ~/.gitmessage

Quality Checklist

Type is appropriate for the change
Subject is imperative mood ("add" not "added")
Subject is under 50 characters
Subject doesn't end with period
Body explains why, not how (if included)
Breaking changes are marked
Related issues are referenced

commit-helper

Commit Helper

When to Use

Conventional Commits Format