git-workshop/04_COMMIT-MESSAGES.md

Writing Good Commit Messages

A good commit message explains what the change does and why it matters. Your future self (and your teammates) will thank you.

The Golden Rule: Write the Intent

Write your message as a command - what will this commit do when applied?

Good (imperative, present tense):

Add login button to navbar
Fix crash when username is empty
Remove unused database connection

Avoid (past tense, describing what you did):

Added login button to navbar
Fixed crash when username is empty
Removed unused database connection

Why? Think of it as completing this sentence:

"If applied, this commit will... add login button to navbar"

Use Prefixes to Categorize

Start your message with a prefix that tells readers what kind of change this is:

Prefix	Use For	Example
feat:	New features	feat: add password reset flow
fix:	Bug fixes	fix: prevent duplicate form submission
docs:	Documentation only	docs: add API examples to README
style:	Formatting, no code change	style: fix indentation in auth module
refactor:	Code change that doesn't fix or add	refactor: extract validation logic
test:	Adding or fixing tests	test: add unit tests for login
chore:	Maintenance, dependencies	chore: update pytest to 8.0

Keep It Short

The first line should be 50 characters or less. This ensures it displays properly in:

• Git log output
• GitHub/Azure DevOps commit lists
• Email notifications

fix: resolve memory leak in image processing
│                                            │
└──────────── 45 characters ─────────────────┘

Add Details When Needed

For complex changes, add a blank line and then more context:

fix: prevent crash when user uploads empty file

The application crashed because we tried to read the first byte
of an empty file. Now we check file size before processing.

Closes #142

Use the body to explain:

• Why this change was necessary
• What was the problem or context
• How does this approach solve it (if not obvious)

Examples

Simple bug fix:

fix: correct tax calculation for EU customers

New feature:

feat: add dark mode toggle to settings

With context:

refactor: split user service into smaller modules

The user service had grown to 800 lines and was handling
authentication, profile management, and notifications.
Split into three focused modules for maintainability.

Documentation:

docs: add setup instructions for Windows

Quick Reference

<prefix>: <what this commit does>

[optional body: why and how]

[optional footer: references issues]

Checklist:

• Starts with a prefix (feat:, fix:, etc.)
• Uses imperative mood ("add" not "added")
• First line under 50 characters
• Explains why, not just what (for complex changes)

Common Mistakes

Instead of...	Write...
fixed bug	fix: prevent null pointer in search
updates	feat: add email notifications
WIP	feat: add basic form validation
stuff	chore: clean up unused imports
fix: fix the bug	fix: handle empty input in calculator

Your commit history tells the story of your project. Make it a story worth reading.