DEV Community

Cover image for Writing clear, concise, and meaningful commit messages for a well-documented Git history
Eddie Gulay
Eddie Gulay

Posted on

Writing clear, concise, and meaningful commit messages for a well-documented Git history

#github #commitmessage #git

📌 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>
Enter fullscreen mode Exit fullscreen mode

📍 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
Enter fullscreen mode Exit fullscreen mode

❌ 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?)
Enter fullscreen mode Exit fullscreen mode

📍 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

OR

feat: add daily cron job for auto-fetching

Related to #15
Enter fullscreen mode Exit fullscreen mode

📍 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>
Enter fullscreen mode Exit fullscreen mode

📍 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)
Enter fullscreen mode Exit fullscreen mode

✅ Instead, rewrite like this:

fix: correct timestamp format in API response
Enter fullscreen mode Exit fullscreen mode

🚀 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

🎯 Closing remarks: sometimes you have to let fire burn ...

Top comments (0)

Read next

574n13y profile image

Whatis Git?

Vivesh -

nickytonline profile image

Building an Ollama-Powered GitHub Copilot Extension

Nick Taylor -

sarvar_04 profile image

🔀 Merging Strategies: Handling Conflicts Like a Pro 🔃

Sarvar Nadaf -

sarvar_04 profile image

📂 Repository Management: Organizing and Optimizing Your Projects 🗂️

Sarvar Nadaf -