peopleforrester Commit Helper
Write clear, meaningful commit messages following conventions.
When to Use
- User asks to commit changes
- Help writing commit messages
- Following Conventional Commits
- Preparing commits for PR
Conventional Commits Format
<type>(<scope>): <subject>
<body>
<footer>
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