What are the best practices for writing commit messages

Writing clear and meaningful commit messages is essential for maintaining a clean and understandable version control history. Good commit messages help developers understand the purpose of changes, track down bugs, and collaborate effectively. Below are some best practices for writing commit messages, along with examples.

1. Use a Clear and Concise Subject Line

The subject line should summarize the change in 50 characters or less. It should be clear and specific, avoiding vague terms like "fix" or "update."


git commit -m "Add user authentication feature"

2. Use the Imperative Mood

Write the subject line in the imperative mood, as if you are giving a command. For example, use "Add" instead of "Added" or "Adding."


git commit -m "Refactor user profile page"

3. Provide a Detailed Body (When Necessary)

If the change requires more explanation, use the body of the commit message to describe the what, why, and how of the change. Separate the subject line from the body with a blank line.


git commit -m "Fix memory leak in image processing module

The memory leak was caused by not properly releasing resources
after processing images. This commit ensures that all resources
are freed after use, preventing memory leaks."

4. Reference Issues or Tickets

If your project uses an issue tracker, reference the issue or ticket number in the commit message. This helps link the commit to the specific task or bug it addresses.


git commit -m "Fix issue #123: Incorrect calculation of total price"

5. Keep Commits Atomic

Each commit should represent a single logical change. Avoid bundling unrelated changes into a single commit. This makes it easier to understand and revert changes if necessary.


git commit -m "Add validation for email input field"

6. Use a Consistent Format

Adopt a consistent format for commit messages across your team. This could include a specific prefix for different types of changes (e.g., "feat:" for features, "fix:" for bug fixes).


git commit -m "feat: Add dark mode toggle"
git commit -m "fix: Resolve crash on null input"

7. Avoid Unnecessary Information

Avoid including unnecessary details or comments in the commit message. Focus on the essential information that helps others understand the change.


git commit -m "Update README with installation instructions"

8. Review and Edit Commit Messages

Before finalizing a commit, review the message to ensure it is clear and accurate. If necessary, use the --amend flag to edit the commit message.


git commit --amend -m "Fix typo in user registration form"

Sample Commit Messages

Here are some examples of well-written commit messages:


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

git commit -m "fix: Resolve issue #456: Incorrect date formatting

The date was being displayed in the wrong format due to a
misconfigured locale setting. This commit updates the locale
settings to ensure the correct date format is used."

git commit -m "refactor: Simplify payment processing logic

The payment processing logic was overly complex and difficult
to maintain. This commit simplifies the logic by removing
unnecessary steps and improving readability."

Conclusion

Writing good commit messages is a simple yet powerful way to improve collaboration and maintainability in your projects. By following these best practices, you can ensure that your commit history is clear, informative, and useful for everyone on your team.