# Good Git commit messages

> Uncover key strategies for crafting effective, clear Git commit messages.

July 24, 2022 · 4 min read · https://yasint.dev/good-git-commit-messages/
Tags: git, engineering

---

Hey there 👋

When using `git`, it's tempting to commit all your changes at once with a vague message like "fixed stuff" or "updates". But here's the thing: your future self (and your teammates) will thank you for taking a few extra seconds to write clear, meaningful commit messages.

## Why commit messages matter

The Git history is the complete record of all changes made to your repository. It's not just a log — it's a story of why decisions were made, what problems were solved, and how the codebase evolved.

![Git log on carbon repository](./git-log-carbon.png "This is a [sample git history with nice commits](https://github.com/carbon-language/carbon-lang). To get this output, run the `git log` command. For more, see [git-log official documentation](https://git-scm.com/docs/git-log).")

Good commit messages help you:

- **Understand changes quickly** — Know exactly what a commit does without reading the code
- **Debug faster** — Find when and why a bug was introduced
- **Review efficiently** — Make code reviews smoother and more meaningful
- **Revert safely** — Undo specific changes without affecting unrelated work

## Keep commits small

Small, focused commits are easier to understand, review, and revert if needed. Instead of one massive commit with 20 file changes and a message saying "various fixes", break it into logical chunks:

- ✅ "Fix null pointer exception in user authentication"
- ✅ "Add validation for email input field"
- ✅ "Update dependencies to latest versions"

Each commit should represent one logical change. If you can't describe your commit in a single sentence, it's probably doing too much.

## The anatomy of a good commit message

Structure your commit message like an email with a subject line and body.

### The subject line

Keep it **50 characters or fewer** and make it descriptive.

![Commit header format](./commit-header.png)

**Good examples 🟢:**
- `Fix race condition in payment processing`
- `Add user avatar upload feature`
- `Remove deprecated API endpoints`

**Bad examples 🛑:**
- `fixed bug` (too vague)
- `Update the entire authentication system to use OAuth 2.0 instead of custom tokens` (too long)
- `stuff` (useless)

### The body (optional but recommended)

If your change needs explanation, add a body after a blank line. Wrap lines at **72 characters or fewer** and write in present tense.

![Commit body format](./commit-body.png)

The body should answer:
- **What** does this change do?
- **Why** was this change necessary?
- **How** does it solve the problem?

**Example:**
```
Fix memory leak in WebSocket connection handler

The connection handler wasn't properly closing connections when
clients disconnected unexpectedly. This caused memory usage to
grow over time in long-running services.

Added explicit cleanup in the disconnect handler and added tests
to verify connections are properly released.
```

## Markdown in commit messages

GitHub, GitLab, and similar platforms render Markdown in commit messages. You can use:

- `**bold**` for emphasis
- `_italics_` for subtle emphasis
- `` `code` `` for technical terms
- `- lists` for multiple points

Don't go overboard, but basic formatting can make longer commit messages much more readable.

## Conventional commits

Many teams follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. It adds a standardized prefix to commit messages:

- `feat:` — New feature
- `fix:` — Bug fix
- `docs:` — Documentation changes
- `refactor:` — Code refactoring
- `test:` — Adding or updating tests
- `chore:` — Maintenance tasks

**Examples:**
- `feat: add dark mode toggle to settings`
- `fix: resolve CORS issue on API endpoints`
- `docs: update installation instructions for Windows`

This makes it easy to scan history and even auto-generate changelogs.

## Summary

![Commit message format summary](./summary.png)

Good commit messages are:
- **Clear** — Describe what changed and why
- **Concise** — Keep subject lines under 50 characters
- **Consistent** — Follow a standard format
- **Complete** — Include context in the body when needed

Your commit history is documentation that lives forever with your code. Make it count!

> **Further reading:** This article was inspired by [Tim Pope's classic post](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) on commit messages. Check it out for deeper insights into the reasoning behind these practices.

Thanks for reading! Now go write some beautiful commits ✨