Introduction

Crafting effective Git commit messages can significantly enhance collaboration, code readability, and project maintainability for years. Yet, it's often overlooked or treated as an afterthought in the development process. In this blog post, I'll cut straight to the chase and outline the key principles for writing outstanding Git commit messages that every developer should follow!

1. Start with a Capitalized Imperative Verb for the Subject Line

A commit message should clearly state what this commit does. Use a capitalized imperative verb at the start for easier readability and maintainability.

Example

• Add new feature for user login
• Fix bug in payment processing
• Update documentation for API endpoints

2. Keep the Subject Line Concise

Your commit message should be descriptive enough to convey the purpose of the commit but concise enough to be quickly scanned. Aim for around 50 characters for the subject line and use the body for additional details.

• Good Commit Message: Refactor user authentication module
• Bad Commit Message: Refactored the user authentication module to improve performance and readability

3. Separate the Summary from the Body with a Blank Line

If your commit message needs more detail, add a body. Make sure to add a blank line between the summary and the body to make it more readable.

Add local caching to improve application performance

This change implements a local caching mechanism to reduce database load
and improve overall response times over the network. The cache invalidates every ten minutes to ensure data freshness.

4. Use the Imperative Mood

Keeping in mind the standard convention, write commit messages in the imperative mood, a tense typically associated with commands and actions. This is instructing about what is being done when the commit is applied.

Examples:

• Correct: Add user authentication
• Incorrect: Added user authentication
• Correct: Fix user authentication
• Incorrect: Fixed user authentication
• Correct: Update user authentication
• Incorrect: Updated user authentication

5. Explain the "What" and "Why" in the Body

Use the body to give more detail about the commit: explain what was done and why it was done. This makes it easier for others—and your future self—to understand the context and reason for the change:

• What: Refactor authentication logic
• Why: Improve performance and reduce code duplication

Example:

Refactor authentication logic

Extracted the authentication logic from a class into a separate module to improve performance and reduce code duplication. This change
will also make future enhancements easier to implement.

6. Use Bullet Points for Lists

If the commit includes several changes, then list them in bullet points. This makes it easier to read and understand each change:

Improve error handling in payment processing

- Add validation for payment input fields
- Handle API errors with retry mechanism
- Log detailed error messages for debugging

7. Reference Relevant Issues or Tickets

If your commit resolves or is related to a specific issue or task, reference it in your project management system—e.g., GitHub Issues, Jira. This helps keep the issues' status up to date, and the context would be quite helpful for readers later.

Fix incorrect total calculation (#4342)

Corrected the calculation logic for order totals, ensuring
taxes and discounts are applied.

8. Review and Revise

Before committing and pushing it to the repository, take a moment to review your message. Check for spelling errors, grammar mistakes, and clarity. A well-written commit message reflects professionalism and attention to detail, which can save time and headaches downstream.

Quick Checklist

• Capitalize: Did you start your subject line with a capital letter?
• Concise: Is your subject line 50 characters or less?
• Blank Line: Did you add a blank line after the summary if there’s a body?
• Imperative Mood: Is the message in the imperative mood?
• Detail: Does the body (if present) explain the what, why, and how?
• Lists: Did you use Bullet Points for your list?
• References: Did you reference any relevant issues or PRs?
• Proofread: Did you check for clarity and typos?

Conclusion

Writing great Git commit messages enhances collaboration and project maintainability. By following these simple guidelines—using imperative verbs, keeping the subject concise, explaining the "what" and "why," and referencing relevant issues—you'll create a valuable project history that's easy to navigate and understand. We also have another post titled "3 Reasons Why You Should Use Conventional Commits" if you're eager to learn more.

We’d also love to have you join us on the Vonage Community Slack or send us a Post on X and we will get back to you. Thanks again for reading, and I will catch up with you on the next one!

Happy committing!