Mastering the Art of Writing Effective Git Commit Messages

June 23, 2023
I face this multiple times when leading or consulting tech teams. Even experienced developers although aware end up writing very awful commit messages in Git.  And once incident happened this morning. Hence, It is okay to remind ourselves of good habbits and good software development hygines. 

Git commit messages play a crucial role in documenting the changes made to a codebase and facilitating collaboration among team members. Well-crafted commit messages not only improve code maintainability but also help in understanding the purpose and context of code changes. In this blog post, we'll explore a guideline to write effective Git commit messages that can enhance clarity, collaboration, and project organization.

Here is my guideline for writing good commit message.

1. Be concise:
Keep your commit messages clear and concise. Aim for a maximum of 50 characters for the subject line and use the body of the message for additional details.
2. Use present tense:
Write your commit messages in the present tense to describe what the commit does. For example, use "Fix a bug" instead of "Fixed a bug."
3. Start with a capitalized verb:
Begin the subject line with a capitalized verb to indicate the action performed by the commit. For example, "Add feature," "Update documentation," "Refactor code," etc.
4. Use imperative mood:
Write your commit messages in an imperative mood, as if you are giving a command. For example, "Add feature" instead of "Adding feature."
5. Provide a clear and descriptive message:
Be clear and specific about the changes made in the commit. Mention the why and what of the change. If applicable, include references to relevant issues, tickets, or discussions.
6. Wrap the subject line at 50 characters:
Keep the subject line of the commit message within 50 characters. If it exceeds the limit, try to rephrase or provide more context in the body of the message.
7. Use the body for more information:
If necessary, provide additional details in the body of the commit message. This can include explaining the problem being addressed, describing the approach taken, or providing any relevant information that helps understand the commit better.
8. Separate subject and body with a blank line:
Leave a blank line between the subject line and the body of the commit message for better readability.
9. Use bullet points for multiple changes:
If your commit includes multiple changes or affects different areas, consider using bullet points in the body of the message to list them out and provide a brief description for each.
10. Be mindful of grammar and punctuation:
Pay attention to grammar, punctuation, and spelling in your commit messages. While minor mistakes might not be critical, clear and well-formatted messages reflect professionalism and attention to detail.

Remember, commit messages are valuable for understanding the history and changes in a project. Following these guidelines can help create informative and meaningful commit messages that make it easier for others (including your future self) to comprehend the purpose and impact of each commit.