How Git Commits Should Be Written
Understand Git commit message conventions, recommended formats, common mistakes and best practices for maintaining a clean Git history.
A Git commit message explains why a change was made and provides context for everyone who works with the repository. Well-written commit messages make project history easier to understand, simplify code reviews and help developers quickly identify when and why changes were introduced.
Although Git allows any commit message, following consistent conventions greatly improves collaboration, debugging and long-term project maintenance.
Why Commit Messages Matter
Git history is more than a record of code changes—it documents the evolution of a project. Clear commit messages allow developers to understand past decisions without reading every modified file.
- Improve project history.
- Simplify code reviews.
- Help with debugging.
- Support collaboration.
- Enable automated tooling.
A Good Commit Message
An effective commit message is short, specific and describes what the commit accomplishes. It focuses on the change rather than the implementation details unless additional explanation is necessary.
| Poor Message | Better Message |
|---|---|
| update | Fix login validation |
| changes | Add pagination to blog |
| bug fix | Prevent duplicate form submission |
| work | Refactor authentication middleware |
Recommended Structure
Many projects use a short summary line followed by an optional blank line and a detailed explanation. The summary should describe the primary purpose of the commit in a concise way.
Short summary
Optional detailed explanation describing
why the change was necessary and any
important implementation notes.Write in the Imperative Mood
Commit messages are commonly written in the imperative mood because they describe what applying the commit will do. This style keeps messages consistent across projects.
| Preferred | Avoid |
|---|---|
| Add user authentication | Added user authentication |
| Fix broken link | Fixed broken link |
| Remove unused code | Removing unused code |
Keep Commits Focused
Each commit should represent a single logical change whenever possible. Small, focused commits are easier to review, test, revert and understand than commits that combine unrelated modifications.
The Conventional Commits Standard
Many software projects follow the Conventional Commits specification, which adds a structured prefix to commit messages. This makes commits easier to categorize and enables tools to automatically generate changelogs, release notes and semantic version numbers.
type(scope): short description
Examples:
feat(auth): add password reset
fix(api): handle empty responses
docs: update installation guide
refactor(ui): simplify sidebar componentCommon Commit Types
| Type | Purpose |
|---|---|
| feat | Introduce a new feature |
| fix | Resolve a bug |
| docs | Update documentation |
| style | Formatting changes only |
| refactor | Improve code without changing behavior |
| test | Add or update tests |
| chore | Maintenance tasks |
When to Add a Commit Body
Most commits only need a concise summary, but more complex changes can benefit from an additional description. The body explains why the change was made, highlights important implementation details or documents decisions that may not be obvious from the code itself.
Atomic Commits
An atomic commit contains one logical change. Instead of combining unrelated bug fixes, refactoring and new features into a single commit, separate them into smaller commits that each solve one problem.
| Poor Practice | Better Practice |
|---|---|
| One commit for many unrelated changes | Separate commits for each logical task |
| Feature and refactor together | Feature first, refactor separately |
| Multiple bug fixes in one commit | One bug fix per commit when practical |
Commit Message Length
The summary line should be concise while still describing the purpose of the commit. If additional explanation is needed, include it in the body rather than making the title excessively long.
Examples of Good Commit Messages
Add dark mode support
Fix memory leak in image loader
Update API documentation
Refactor user authentication service
Improve search performance
Remove deprecated utility functionsBenefits of Consistent Commit Messages
| Benefit | Description |
|---|---|
| Readable history | Makes changes easier to understand |
| Faster code reviews | Reviewers immediately know the purpose |
| Simpler debugging | Helps identify when issues were introduced |
| Automation support | Enables changelog and release note generation |
Common Mistakes
Even experienced developers sometimes write commit messages that provide little context. Since commit history often serves as long-term project documentation, vague or inconsistent messages make debugging, reviewing changes and understanding past decisions much more difficult.
- Using generic messages such as 'update', 'fix' or 'changes'.
- Combining multiple unrelated changes into one commit.
- Writing overly long summary lines.
- Describing implementation details instead of the purpose of the change.
- Using inconsistent commit styles across the project.
- Skipping commit messages entirely when using automated tools.
Best Practices
- Write concise, descriptive summaries.
- Use the imperative mood (for example, 'Add', 'Fix' or 'Remove').
- Keep commits focused on a single logical change.
- Use Conventional Commits if your project follows the specification.
- Include a commit body when additional context is helpful.
- Maintain a consistent commit style across the entire repository.
Frequently Asked Questions
How long should a Git commit message be?
The summary should be short and descriptive, typically one concise sentence. If more explanation is needed, add a body below the summary rather than making the title excessively long.
What is the imperative mood in commit messages?
The imperative mood describes what applying the commit will do, using verbs such as 'Add', 'Fix', 'Remove' or 'Refactor'. This style is widely used because it creates consistent Git history.
What are Conventional Commits?
Conventional Commits are a standardized format that prefixes commit messages with types such as feat, fix, docs or refactor. They improve consistency and support automation tools that generate changelogs and release notes.
Should every commit include a detailed description?
No. Simple changes often require only a clear summary. A detailed body is most useful for complex changes, architectural decisions or modifications that need additional explanation.
Why are small commits recommended?
Small, focused commits are easier to review, test, debug and revert. They also produce a cleaner project history that is easier for developers to understand over time.
Helpful Git Tools
A Git Commit Generator helps create clear, descriptive commit messages, a Conventional Commit Generator formats commits according to the Conventional Commits specification, a Git Branch Name Generator suggests consistent branch names, a Changelog Generator builds project changelogs from commit history, and a Release Notes Generator converts commits into organized release summaries for software versions.
Conclusion
Well-written Git commit messages are an essential part of professional software development. They document the purpose of code changes, improve collaboration, simplify debugging and make project history significantly easier to navigate. By keeping commits focused, writing clear summaries, following consistent conventions and adopting standards such as Conventional Commits when appropriate, development teams can maintain a Git history that remains valuable throughout the lifetime of a project.