A well-written commit message not only explains what was done, but also why it was done, making it an invaluable tool for teams and future maintainers. This article provides concise, actionable tips and examples to help developers learn how to write better commit messages, enhancing team collaboration and project maintainability.
The Basics of a Good Git Commit Message
Before diving into advanced tips, let’s ensure the basics are covered. A good git commit message should clearly and succinctly describe the what and the why of the commit. Here are some fundamental practices:
1. Keep the Subject Line Concise and Informative
Limit the subject line to 50 characters. This forces you to focus on the key change, making the message clear and easy to skim.
Example: Instead of “fixes,” write “Fix user login issue.”
2. Use the Imperative Mood
Write your commit message as if giving an order or instruction. This aligns with git’s own conventions when it auto-generates messages.
Example: Use “Add” instead of “Added,” and “Fix” instead of “Fixes.”
3. Provide Context in the Body
Separate the body from the subject line with a blank line, and use it to explain the why and how of the changes, especially for complex adjustments.
Example:
Add JSON parsing capability
Include a new JSON parser to handle incoming payload more efficiently than the previous XML parser, reducing latency for end users.4. Reference Issue or Ticket IDs
Link the commit to related issues or tickets for additional context and tracking purposes.
Example: Append “Closes #123” to connect a commit to a GitHub issue or Jira ticket.
Advanced Strategies for Effective Commit Messages
Moving beyond the basics, here are some advanced strategies to refine your git practices further.
[Tip]: ☝️How to undo a Git Commit 👇
5. Craft a Narrative
Explain not just what was changed but why it was necessary. This turns a functional message into a piece of the project’s story.
Example:
Refactor database connection logic
Update the DB connection class to use singleton pattern, reducing the number of simultaneous connections under heavy load and improving response times during peak usage.6. Emphasize Small, Focused Commits
If you struggle to summarize a commit, it might be doing too much. Focused commits make for easier review and clearer messages.
Example: “Optimize image loading” rather than a vague “Update image handling.”
7. Use Git Commands for Managing Complex Changes
For larger features, utilize git reset, git rebase -i, and git cherry-pick to organize and clean up your commit history. This makes each commit a readable “chapter” of your development story.
Example: To combine related changes into a single commit, you might use:
git rebase -i HEAD~4 # Interactively rebase the last four commits8. Fill in the Blank: “If this commit is applied, it will …”
This technique forces you to describe the commit’s impact in a clear and direct way.
Example: “Enable users to reset their password directly from the login screen.”
Conclusion
Clear commit messages are a keystone of successful development projects. They facilitate effective reviews, simplify maintenance, and help all team members understand the evolution of a codebase. By adhering to these tips and integrating the examples provided, developers can enhance both their workflow and their communication within the team. Remember, a commit message is more than just a technical description—it’s a record of your project’s history and your decision-making process.
