When developers first step into the world of Git, they often encounter a certain discomfort, especially when it comes to crafting meaningful commit messages. The Git commit message, which encapsulates the changes made and why they were made, is a crucial part of version control. Developing good committing habits early in your career is essential. In this guide, we’ll explore how to improve your Git commit messages and why it matters.

The Importance of Quality Commit Messages

Imagine this scenario: you open a repository, run git log, and find a list of cryptic commit messages like “Fix style” or “Update code.” Months later, you revisit the project and have no idea what these messages mean. Sound familiar? Well, this is a common issue with poorly written commit messages. Quality commit messages provide essential context and save you and your teammates time when troubleshooting or understanding past changes.

The Anatomy of a Commit Message

A Git commit message has two main parts: the subject line and the body.

• Subject Line: This should be concise, not exceeding 50 characters. It should start with a capital letter and use the imperative mood (e.g., “Add,” “Fix,” “Update”). The subject line provides a high-level overview of the change.
• Body: The body of the message is where you can explain in more detail. It should be wrapped at 72 characters and answer the questions of “why” and “what.”

Steps to Writing Better Commit Messages

Let’s dive into practical steps to improve your commit messages:

1. Capitalization and Punctuation

Always start the subject line with a capital letter and don’t end it with punctuation. Conventional Commits, a popular convention, encourages using all lowercase.

2. Mood Matters

Use the imperative mood in the subject line. This creates a tone of giving an order or request. For example, “Fix the dark mode toggle state” is more appropriate than “Fixed the dark mode toggle state.”

3. Specify the Type of Commit

It’s beneficial to categorize your commits. Use a consistent set of words to describe your changes. For example, “Bugfix,” “Update,” “Refactor,” or “Bump.” This helps in classifying and searching for specific types of changes.

4. Watch the Length

Keep the subject line short, ideally under 50 characters, and restrict the body to 72 characters per line. This ensures messages are concise and readable.

5. Content Clarity

Be direct and avoid filler words and phrases. Think like a journalist, aiming to answer the “what” and “why” questions. Pretend that the reader has no prior knowledge of the change and needs a clear explanation.

Conventional Commits

Conventional Commits is a widely adopted format that provides structured commit messages. It uses the format: <type>[optional scope]: <description>. The type can include values like “feat” (new feature), “fix” (bug fix), “chore” (maintenance), and more. The optional scope specifies the part of the codebase affected, and the description provides a concise summary.

This convention enhances consistency in commit messages and can be paired with tools like Commitizen to enforce standards.

Commit Message Comparisons

Let’s compare some examples to see the difference quality commit messages make:

Good:

• feat: Improve performance with lazy load implementation for images
• chore: Update npm dependency to the latest version
• Fix bug preventing users from submitting the subscribe form
• Update incorrect client phone number within the footer body per client request

Bad:

• Fixed bug on the landing page
• Changed style
• Oops
• I think I fixed it this time?
• Empty commit messages

By following these guidelines, your commit messages can become valuable documentation, saving you and your team time and frustration. Whether you’re working solo or in a collaborative development environment, investing a little extra effort in crafting clear and meaningful commit messages pays off in the long run.