5 Simple Steps to Write Great Git Commit Messages

When it comes to software development, commit messages are more important than many of us realize. A good commit message not only provides clarity and context for future developers (including the future you!), but it also simplifies code reviews, documentation, and troubleshooting. In this post, we’ll walk through five simple steps that will help you craft more readable, consistent, and informative commit messages.

1. Use the Imperative Mood

The first step is to write commit messages as if you are giving a command:

• Do this:
  Add user login feature

• Not this:
  Added user login feature
Adding user login feature

Why does it matter? Writing in the imperative mood (“Add,” “Refactor,” “Remove”) is a convention adopted by tools and development teams worldwide. It creates a consistent, clear style that can be used for release notes, automated scripts, and even when scanning through commit histories.

2. Keep the Summary Short

The best commit messages often have a short subject line. A common rule of thumb is to keep your summary to 50 characters or fewer.

• Examples of concise summaries:

  • Fix bug in user signup flow

  • Update UI for mobile screens

  • Refactor database queries for efficiency

A short, punchy summary makes it easier to scan through git logs or pull requests and quickly see what changed. If you need more space to explain why you made the change, that’s where the commit body comes in (which we’ll get to next).

3. Provide a Detailed Body (When Needed)

For simple, self-explanatory commits, a single line might be enough. But for anything non-trivial, you should add a body.
Use a blank line after the short summary, then dive into the context, background, or any other details future developers might need.

• Example of a commit message with a body:

  Fix bug in user signup flow
  
  This commit resolves a bug where the signup process would crash
  if the user submitted a blank email address. The solution adds
  validation to ensure the email field is not empty.

The body is the perfect spot to explain why the change was necessary and how it addresses the issue. A well-written body means future developers (or you, six months later) won’t have to guess at the reasoning behind the code changes.

4. Reference Tickets or Issues

In many teams, changes are tracked using an issue-tracking system (e.g., GitHub Issues, Jira, Trello). When a commit resolves or relates to a specific ticket, referencing that ticket helps connect the code to the broader context of your project planning.

• Examples of referencing issues in commit messages:

  • Fix form validation issue (#123)

  • Add new payment gateway (Closes #456)

Including references like “Closes #123” can even tell certain platforms to automatically close the ticket once the commit lands in the main branch—saving you an extra step and making the workflow more seamless.

5. Consider a Structured Format (Conventional Commits)

For teams that want an extra layer of organization, consider adopting the Conventional Commits specification. It uses a specific format that tools and CI systems can parse automatically:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types

• feat: A new feature

• fix: A bug fix

• docs: Documentation only changes

• style: Changes that do not affect the meaning of the code (e.g., formatting)

• refactor: A code change that neither fixes a bug nor adds a feature

• perf: A code change that improves performance

• test: Adding or correcting tests

• chore: Build process, auxiliary tools updates

Example

feat(auth): add OAuth login flow

This commit introduces an OAuth-based login flow, allowing
users to sign in with Google and Facebook. It lays the
groundwork for supporting other identity providers later.

Closes #101

Using a structured commit message format like this can help you automate versioning, generate change logs, and maintain consistent practices across your team.

Conclusion

Crafting clear and concise commit messages should never be an afterthought. By following these five simple steps:

1. Use the Imperative Mood

2. Keep the Summary Short

3. Provide a Detailed Body (When Needed)

4. Reference Tickets or Issues

5. Consider a Structured Format (Conventional Commits)

…you’ll set your project up for long-term maintainability and make life easier for everyone on your team. After all, when you revisit your codebase months or years down the line, you’ll thank yourself for leaving a solid paper trail of why and how your code evolved.

So the next time you hit git commit, remember these best practices, and you’ll be well on your way to building a cleaner, more efficient workflow.

Happy committing!