How to Write Good Git Commit Messages

A good Git commit message explains a change clearly enough that teammates—and your future self—can understand it from the project history. Learn a simple format, see practical Conventional Commits examples, and avoid common message-writing mistakes.

Why commit messages matter

Commits are checkpoints in a project's history. Clear messages make it easier to review changes, find when a behavior was introduced, understand why a fix exists, and prepare a release. A message such as Fix checkout total after discount gives readers more useful information than updates or fixed bug.

The goal is not to describe every line of code. Summarize the purpose of the change, then use the commit body for context that cannot fit in a short subject.

A simple format for a Git commit message

Short summary in imperative mood

Optional details: explain why the change was needed and
anything reviewers or future maintainers should know.

Optional footer: reference an issue or describe a breaking change.

Keep the subject concise and specific. Write it as an instruction describing what the commit does, such as Add password reset validation or Remove obsolete cache setting. Many teams aim for about 50 characters, but clarity matters more than a strict character limit.

Conventional Commits format

Conventional Commits is a widely used convention that puts the change type at the start of the subject. Its basic structure is:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

• type describes the kind of change. Common types include feat for a feature, fix for a bug fix, docs for documentation, refactor for restructuring, and test for tests.
• scope is optional and identifies the affected area, such as api, auth, or checkout.
• The description briefly states what the commit changes. Teams may choose their own capitalization and punctuation style; apply it consistently.
• The optional body and footer provide more context, references, or breaking-change details.

Conventional Commits is a convention, not a feature built into Git. Tools can use it for changelogs or release automation, but those behaviors depend on how a project is configured.

Conventional Commits examples

feat(search): add filters for archived projects
fix(auth): reject expired password reset links
docs: clarify the local development setup
test(api): cover empty search results
refactor: extract date formatting helper

These subjects say both what changed and, when useful, which part of the project it affects. Choose a type based on the change itself, not on how large or difficult the work was.

Add useful context in the body

Add a body when the subject alone does not explain the reason, trade-offs, or behavior of the change. Separate it from the subject with a blank line. Wrap long lines if your team or tooling expects that, and keep the explanation focused.

fix(checkout): preserve discounts after address edits

Recalculate shipping when the address changes without resetting
the discount already applied to the order.

Mark breaking changes and reference issues

A breaking change alters behavior that existing users or dependent code may rely on. Conventional Commits allows a ! after the type or scope and a BREAKING CHANGE: footer with details:

feat(api)!: require a version on project requests

BREAKING CHANGE: Clients must now include the API version
in the request header.

Reference an issue using the format your team or hosting platform recognizes, for example Closes #42. An issue reference connects the change to its discussion; it does not replace a clear explanation of the change.

Common commit message mistakes

• Too vague: changes, fix, and WIP do not explain the result.
• Too much in the subject: move background, reasoning, and issue context into the body or footer.
• Describing the code, not the goal: focus on the user-visible or maintenance outcome rather than a list of edited files.
• Inconsistent convention: agree on types and style with your team instead of mixing unrelated formats.
• Misleading history: do not claim a change is a feature or fix if it does not deliver that behavior.

Git commit message FAQ

Does Git require a specific commit message format?

No. Git accepts ordinary commit messages. Conventional Commits and similar formats are team conventions that make history easier to scan and can support configured automation.

Should commit messages use present or past tense?

Use one consistent style. The imperative mood is common because the subject reads as an instruction: Add validation, not Added validation.

How do I write a commit message with a body?

Leave a blank line after the subject, then write the reason and relevant context. With git commit, you can use -m for a subject and another -m for a body, or open your configured editor by running git commit.