Writing Clean and Meaningful Commit Messages

Commit messages in Git are more than just a technical requirement; they are a form of communication between you and your collaborators (including your future self). Writing clear, descriptive commit messages can drastically improve the quality of a project’s history and make it easier to understand and manage code .

In this post, we will explore:

• The importance of good commit messages
• Common problems with poorly written commit messages
• Guidelines for writing effective commit messages
• Conventional commit formats
• Examples of good vs. bad commit messages
• Tools to help with commit message conventions

1. Why Commit Messages Matter

Commit messages serve several critical purposes:

1. Documentation of Changes: A commit message provides a summary of what was changed and why. When someone (including yourself) revisits the code in the future, clear messages make it easier to understand the context of the changes.
2. Collaboration and Communication: In collaborative projects, team members rely on commit messages to understand each other’s work. Good commit messages facilitate smooth communication among developers, reviewers, and even managers.
3. Simplifying Code Reviews: Meaningful commit messages help code reviewers quickly understand the scope of the changes, making the review process faster and more efficient.
4. Debugging and Blame: When something goes wrong, commit messages help developers trace back through the project history to find the root cause of issues. Well-written commit messages make this process much more manageable.

2. Problems with Poorly Written Commit Messages

Poorly written commit messages can lead to confusion, wasted time, and potential miscommunication among developers. Some common problems include:

1. Lack of Context: Messages like "Fixed bug" or "Updated file" don't provide any context about what was fixed or updated. This makes it difficult to understand the purpose of the change, especially when looking back at the commit later.
2. Too Vague or Short: Short messages like "Stuff" or "Changes" are too vague and don't offer any insight into the changes made in the commit.
3. Overly Long and Unstructured: Long-winded commit messages without structure can be difficult to read, especially when looking at the project's history.
4. Unrelated Changes in a Single Commit: Sometimes, developers bundle unrelated changes into a single commit with a message like "Misc updates." This makes it harder to isolate specific changes and can complicate debugging.
5. Spelling/Grammar Issues: While commit messages don’t need to be perfect essays, messages riddled with typos and grammatical errors reduce readability and professionalism.

3. Guidelines for Writing Effective Commit Messages

3.1. Start with a Short, Descriptive Summary (50 characters or less)

The first line of your commit message should be a concise summary of the changes. It should give enough information that someone browsing the commit history can understand the gist of the change at a glance.

• Keep the summary under 50 characters.
• Use the imperative mood (e.g., "Add feature" instead of "Added feature").Examples:
  • ✅ Fix login button alignment on mobile
  • ✅ Add user authentication middleware
  • ❌ Fixed the login issue
  • ❌ Minor changes

3.2. Use the Body to Explain Why the Change Was Made (if necessary)

If the change isn't immediately obvious from the summary, add a more detailed explanation in the body of the commit message. This is especially useful for non-trivial changes or when fixing a bug.

• Leave a blank line between the summary and the body.
• Explain the why, not just the what. Include reasoning or context that might not be apparent from the code itself.

Example:

Fix user authentication issue

This commit fixes a bug where users could log in without a password. The issue occurred because the authentication middleware was not properly checking for empty passwords.

3.3. Use Bullet Points or Lists for Multiple Changes

If your commit includes multiple changes or steps, use bullet points or lists to make the body more readable.

Example:

Add Docker configuration for local development

- Add Dockerfile to create a local development environment.
- Update the README with instructions on how to build the container.
- Include docker-compose.yml for running the app and database together.

3.4. Reference Related Issues or Pull Requests

If the commit relates to a specific issue or pull request, reference it in the message. Most version control platforms like GitHub or GitLab will automatically link these references.

Example:

Fix user login issue (#123)

3.5. Break Large Changes into Multiple Commits

Instead of creating a single large commit with all your changes, break the changes down into smaller, logical commits. This makes it easier to review and understand each piece of the change.

4. Commit Message Formats

Adhering to a structured format for commit messages helps keep your project's history clean and consistent. Below are two commonly used formats:

4.1. The Conventional Commit Format

The Conventional Commits specification provides a standard for writing commit messages that makes it easier to understand the history and automate tasks (like versioning). A conventional commit message follows this format:

<type>[optional scope]: <description>

Where:

• type describes the purpose of the change (e.g., fix, feat, docs, chore, refactor).
• scope (optional) clarifies what part of the code the change affects.
• description is a brief summary of the change.

Example:

feat(auth): add JWT authentication middleware

fix(api): handle 404 errors for missing resources

This format is particularly useful when working with continuous integration (CI) and continuous delivery (CD) systems, as it can help automate versioning (e.g., Semantic Versioning).

4.2. Other Common Formats

• JIRA Ticket Reference: Some teams use JIRA or another issue tracker to manage development tasks. In this case, commit messages may reference the ticket number.

Example:

PROJ-1234: Fix broken header links

• Commitizen: Commitizen is a tool that enforces the Conventional Commit format. It prompts the developer to provide structured commit messages using an interactive CLI.

5. Examples of Good and Bad Commit Messages

Good Commit Messages

1. Single Change with Clear Purpose:

fix(auth): prevent users from logging in without a password

2. Multiple Related Changes:

refactor(api): improve error handling for invalid input

- Add validation middleware to check for missing parameters.
- Return descriptive error messages for bad requests.

3. Bug Fix with Explanation:

fix(session): handle expired tokens

The app was crashing when an expired session token was used. This commit adds a check for expired tokens and returns a 401 Unauthorized error instead of crashing.

Bad Commit Messages

1. Too Vague:

fixed some stuff

2. Too Short and Lacking Context:

update

3. Overly Long and Detailed in the Summary:

This commit fixes the issue where users couldn't log in if their password was less than 6 characters long by updating the validation logic in the authentication middleware to check the length of the password before processing the login request.

6. Tools to Enforce Commit Message Conventions

Several tools can help you enforce consistent commit message conventions across your team.

• Commitlint: A tool that helps enforce commit message conventions, such as the Conventional Commit format. It integrates with Git hooks to ensure that each commit follows the specified guidelines.
• Husky: A Git hook manager that lets you run scripts (like commit message linters) before commits or pushes.
• Commitizen: As mentioned earlier, Commitizen prompts developers to write commit messages in the Conventional Commit format. It standardizes messages and makes them more readable.

Conclusion

Writing clean and meaningful commit messages is an essential part of using Git effectively. By following best practices—such as using a clear and concise summary, providing context in the body, and adhering to a consistent format—you can make your project's history more understandable and easier to work with.

Remember that your commit history is not just for you, but for your teammates and future developers who may work on the codebase. Clean, informative commit messages help foster better communication and collaboration, ultimately leading to more successful projects.