How to Write Good Commit Messages: Best Practices for Teams

Git commit messages are essential for maintaining a clear and collaborative history of a project. Poorly written commit messages can lead to confusion, making it hard to understand the intent behind changes. In this guide we will run through practical best practices for writing meaningful commit messages and promoting uniformity in teams.

Why Good Commit Messages Matter

1. Clarity: A clear commit message explains what changes were made and why.
2. Collaboration: With multiple developers, standardized messages improve team understanding.
3. Debugging: Helpful messages make it easier to trace bugs to specific changes.

The 50/72 Rule

A typical commit message has two main parts:

1. Subject line: A concise summary of the change (max 50 characters).
2. Body (optional): Detailed description of what and why (wrapped at 72 characters).

Example:

feat: add user authentication feature

- Implement login/logout functionality
- Use JWT for session management
- Add tests for authentication endpoints

Commit Message Best Practices

1. Use the Imperative Mood: Start with a verb as if giving a command.

• Good: fix: resolve null pointer exception
• Bad: fixed the null pointer exception

2. Be Concise: Summarize the change in 50 characters or fewer.

3. Provide Context: Explain why the change was necessary in the body.

4. Use a Prefix for Type: Adopt a conventional format like type: message.

• Common prefixes:
• feat: New feature
• fix: Bug fix
• chore: Miscellaneous changes
• refactor: Code improvement without feature/bug changes
• test: Adding or updating tests
• docs: Documentation updates

5. Separate Concerns: Commit one logical change at a time.

• Avoid: fix auth and update UI
• Use: fix: resolve auth issue and style: update login page UI

6. Capitalize the First Word: Always start with a capital letter.

7. Avoid Periods in the Subject Line: Periods are redundant in short messages.

Practical Guidelines for Team Standardization

1. Adopt a Commit Convention:

• Use standards like Conventional Commits:

<type>[optional scope]: <description>

[optional body]
[optional footer]

• Example:

feat(auth): add password reset functionality

- Add endpoint for password reset
- Send email notifications for requests
- Log activity for auditing

2. Use Pre-Commit Hooks:

• Enforce rules using Git hooks or tools like Husky.

3. Code Reviews for Commit Messages:

• Ensure meaningful messages during pull requests.

4. Document the Guidelines:

• Include commit message standards in the team’s README or CONTRIBUTING.md file.

5. Automate Checks:

• Use tools like Commitlint to validate commit messages.

Sample CLI Commands for Writing Commit Messages

Here are some examples of how to craft commit messages using Git CLI while following best practices:

1. Simple Commit:

git commit -m "feat: add user authentication feature"

2. Commit with Body:

git commit -m "fix: resolve null pointer exception" -m "This fix prevents application crashes by checking for null values before processing user data."

3. Commit with Scope:

git commit -m "docs(readme): update contributing guidelines"

4. Amending a Commit:

git commit --amend -m "refactor: optimize database queries"

5. Interactive Add and Commit:

git add -p git commit -m "chore: clean up unused imports"

6. Commit Multiple Changes:

• Split changes into logical commits:

git add file1.js
git commit -m "feat: add API endpoint for fetching user data"
git add file2.js
git commit -m "test: add unit tests for user API endpoint"

Conclusion

Well-written commit messages are vital for project clarity and collaboration. By following best practices and enforcing team-wide standards, you can create a more efficient development workflow. Remember, a clean commit history is not just documentation — it’s a reflection of a well-organized project.