This content originally appeared on DEV Community and was authored by Eddie Gulay
đź“Ś The Formula for a Good Commit Message
A commit message should be structured as follows:
<type>: <short summary> (max 50-72 chars)
<optional detailed explanation - wrap at 72 chars>
<optional: issue reference or co-authored-by>
đź“Ť 1. Use Conventional Commit Types
Start your commit message with a commit type, followed by a short summary:
| Type | Usage Example |
|---|---|
| feat | feat: add date filtering for GitHub activity |
| fix | fix: handle API failure when GitHub is down |
| refactor | refactor: optimize API response formatting |
| docs | docs: update README with API usage guide |
| chore | chore: add .gitignore and remove logs |
| style | style: format code with Black |
| test | test: add unit tests for date filtering |
đź“Ť 2. Write a Clear & Concise Summary
- Keep it within 50-72 characters.
- Use imperative mood (e.g., "Add", "Fix", "Update" instead of "Added" or "Fixes").
- Avoid unnecessary words.
âś… Good Examples
feat: add API endpoint for fetching GitHub activity
fix: resolve bug in date filtering logic
docs: update README with setup instructions
❌ Bad Examples
added new API for activity ❌ (Avoid past tense)
fixing bug in date filtering ❌ (Not in imperative form)
Updated README ❌ (Vague, what was updated?)
đź“Ť 3. Add a Detailed Description (Optional)
If the commit needs more context, add a body section:
feat: add GitHub activity API
- Fetches user events from GitHub API
- Supports filtering by single date or date range
- Caches results for faster responses
Closes #12
Use this for:
âś… Complex changes
âś… Bug fixes requiring explanation
âś… Breaking changes
đź“Ť 4. Reference Issues & PRs
If the commit is linked to an issue or pull request, reference it:
fix: resolve date filtering issue
Closes #22
OR
feat: add daily cron job for auto-fetching
Related to #15
đź“Ť 5. Use "Co-authored-by" for Team Contributions
If multiple developers worked on a commit, acknowledge them:
feat: add webhook support for GitHub activity
Co-authored-by: Edgar Gulay <edgargulay@outlook.com>
Co-authored-by: John Doe <johndoe@example.com>
đź“Ť 6. Keep Commit History Clean
đźš« Avoid these commit messages:
wip: working on it ❌ (What are you working on?)
fix: bug fixes ❌ (Which bug? Be specific)
temp: test commit ❌ (Don’t commit temporary stuff)
âś… Instead, rewrite like this:
fix: correct timestamp format in API response
🚀 Bonus: Automate Commit Messages with a Git Hook
To enforce commit message rules, use a pre-commit hook:
echo 'exec < /dev/tty && git cz --hook || true' > .git/hooks/commit-msg
chmod +x .git/hooks/commit-msg
This will prompt you to enter a properly formatted message each time you commit.
đź’ˇ Summary Cheat Sheet
| ✅ Do | ❌ Don’t |
|---|---|
Use imperative tense (fix: instead of fixed:) |
Use vague messages (Updated stuff) |
| Keep the summary under 72 chars | Write long, unreadable messages |
| Add a detailed body when necessary | Overload the commit summary |
| Reference issues & PRs when relevant | Leave commits unexplained |
| Use Conventional Commit types | Use generic terms like misc:
|
🚀 Final Example
feat: implement GitHub activity summary API
- Fetches user events from GitHub API
- Filters activity based on date or date range
- Returns structured JSON response
Closes #1
🎯 Closing remarks: sometimes you have to let fire burn ...
This content originally appeared on DEV Community and was authored by Eddie Gulay
Eddie Gulay | Sciencx (2025-01-29T22:28:40+00:00) Writing clear, concise, and meaningful commit messages for a well-documented Git history. Retrieved from https://www.scien.cx/2025/01/29/writing-clear-concise-and-meaningful-commit-messages-for-a-well-documented-git-history/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.