- Published on Wednesday, July 3, 2024, last updated
Ultimate Guide to Git Commit Message Templates: Best Practices and Examples
- Authors
- Name
- Sydney Cohen
- @chnsydney
Table of Contents
- TLDR: Git Commit Message template
- Introduction
- Importance of Clear Git Commit Messages
- Git Commit Messages checklist
- Enhancing Project Management and Collaboration
- Benefits for Code Tracking and Version Control
- Part 1: Understanding Git Commit Messages
- What is a Git Commit Message?
- Why Git Commit Messages Matter
- Part 2: Structure of a Git Commit Message
- Subject Line
- Body
- Footer
- Part 3: Writing Effective Git Commit Messages
- Tips for Crafting Clear and Concise Messages
- The Imperative Mood
- Using Markdown for Formatting
- Part 4: Git Commit Message Best Practices
- Keep Messages Short but Descriptive
- Separate Subject and Body with a Blank Line
- Use the Body to Explain What and Why, Not How
- Reference Issues and Pull Requests
- Capitalize the Subject Line
- Do Not End the Subject Line with a Period
- Wrap the Body at 72 Characters
- Examples of Good vs. Bad Commit Messages
- Part 5: Git Commit Message Best Practices Examples
- Part 6: Automating Git Commit Messages
- Tools for Enforcing Commit Message Standards
- Setting Up Commit Message Templates
- Part 7: Common Pitfalls and How to Avoid Them
- Vague Commit Messages
- Overly Detailed Commit Messages
- Ignoring the Subject Line
- Part 8: Git Commit Message Conventions
- Conventional Commits
- Semantic Commit Messages
- Customizing Commit Message Guidelines for Your Team
- Part 9: Advanced Git Commit Message Techniques
- Using Emojis in Commit Messages
- Crafting Commit Messages for Automated Tools
- Commit Messages in Open Source Projects
- Conclusion
- Recap of Key Points
- Importance of Consistent Commit Messages
- Encouragement for Ongoing Improvement and Adaptation
- Appendix
- Glossary of Terms
- Additional Resources and References
- Templates and Checklists for Git Commit Messages
TLDR: Git Commit Message template
Use the following examples to craft clear and effective Git commit messages for various scenarios:
## Commit message with description and breaking change footer
feat: allow provided config object to extend other configs
BREAKING CHANGE: 'extends' key in config file is now used for extending other config files.
## Commit message with ! to draw attention to a breaking change
feat!: send an email to the customer when a product is shipped
## Commit message with scope and ! to draw attention to a breaking change
feat(api)!: send an email to the customer when a product is shipped
## Commit message with both ! and BREAKING CHANGE footer
chore!: drop support for Node 6
BREAKING CHANGE: use JavaScript features not available in Node 6.
## Commit message with no body
docs: correct spelling of CHANGELOG
## Commit message with scope
feat(lang): add Polish language
## Commit message with multi-paragraph body and multiple footers
fix: prevent racing of requests
Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from the latest request.
Remove timeouts which were used to mitigate the racing issue but are
obsolete now.
Reviewed-by: Z
Refs: #123
## Commit message for a minor bug fix
fix(ui): resolve issue with dropdown menu alignment
The dropdown menu was misaligned on the profile page due to CSS conflicts.
Updated the styles to ensure proper alignment across different screen sizes.
Fixes issue #789.
## Commit message for adding a new test
test: add unit tests for user authentication module
Added unit tests for the user authentication module to cover login, registration, and token verification functionalities.
Ensured all tests pass with the new authentication logic.
Refs: #456
## Commit message for a configuration change
chore(config): update ESLint configuration to support latest standards
Updated the ESLint configuration to support the latest JavaScript standards and best practices.
Included new rules for code formatting and improved error detection.
Reviewed-by: A, B
Introduction
Importance of Clear Git Commit Messages
Clear and concise Git commit messages are essential in the software development lifecycle. They provide context and understanding of changes, aiding in project management, collaboration, and maintaining a clean version history. Here’s why they matter.
Git Commit Messages checklist
Enhancing Project Management and Collaboration
Effective commit messages can significantly improve project management and team collaboration. Here's how:
- Context and Clarity: Each commit message offers a snapshot of what changes were made and why. This context is invaluable for anyone reviewing the project's history or understanding the codebase's evolution. Clear messages reduce onboarding time for new team members and make revisiting old code easier for existing members.
- Efficient Code Reviews: Well-written commit messages streamline the code review process. Reviewers can quickly grasp the purpose and scope of changes, allowing for more focused reviews.
- Enhanced Collaboration: Clear commit messages foster better communication among multiple developers working on the same project. They help synchronize efforts, understand each team member’s contributions, and avoid redundant work.
For more detailed guidelines, refer to the Git Commit Guidelines.
If you type Git Log in your Git Repository in your terminal you will see a Git history that looks similar to this!
Benefits for Code Tracking and Version Control
Commit messages are essential for tracking changes and maintaining an organized version control history. Here are the benefits:
- Traceability: Clear commit messages make it easy to trace the origin of specific changes. This is crucial for debugging, as developers can pinpoint when and why a particular change was made.
- History Navigation: With well-structured commit messages, navigating through the history of the repository becomes straightforward. Developers can quickly find specific changes related to a bug fix, feature implementation, or refactor.
- Automated Tools Integration: Many continuous integration (CI) and deployment tools rely on commit messages to trigger actions or generate release notes. Clear and consistent messages ensure these tools function correctly and provide meaningful outputs.
Here is a Git History using GitLens in VS Code. It clearly shows which modifications has been made by who with descriptive messages. This can be highly beneficial when debugging.
For an in-depth understanding, check out the Git Documentation on Commit Messages.
By adhering to best practices for writing Git commit messages, developers can enhance the overall efficiency and effectiveness of their project workflows, ensuring that the version control history is a valuable resource for everyone involved in the project.
Part 1: Understanding Git Commit Messages
What is a Git Commit Message?
A Git commit message is a brief text that accompanies each commit in a Git repository. It provides a snapshot of what changes were made and why, serving as an essential piece of documentation within the version control system.
- Definition and Purpose: A Git commit message serves to explain the context and intent of the changes made in a particular commit. This makes it easier for other developers (and your future self) to understand the rationale behind changes when reviewing the project history.
- Anatomy of a Commit Message: A well-structured commit message typically consists of a subject line, a body, and a footer. The subject line is a brief summary of the changes, the body provides more detailed information, and the footer includes any relevant metadata, such as issue references.
Why Git Commit Messages Matter
Beyond their role in basic project management, Git commit messages play several critical roles in the development lifecycle and overall project health.
- Facilitating Code Reviews: Clear commit messages make it easier for reviewers to understand the scope and purpose of changes. This leads to more effective and efficient code reviews.
- Debugging and Troubleshooting: When bugs arise, a well-documented commit history allows developers to trace changes that might have introduced issues. This can significantly speed up the debugging process.
- Project Onboarding: For new team members, commit messages provide valuable insights into the project's evolution and decision-making processes, easing the onboarding process.
- Automating Workflows: Many CI/CD systems and release tools use commit messages to trigger actions, generate changelogs, and automate parts of the deployment process. Consistent messaging ensures these tools work effectively.
- Historical Context: Over time, commit messages build a historical narrative of the project. This context is invaluable for understanding why certain decisions were made, especially in complex projects.
By consistently writing informative commit messages, developers can ensure that the version control history remains a valuable resource for everyone involved in the project.
Part 2: Structure of a Git Commit Message
Subject Line
The subject line is the first part of a commit message and should provide a brief summary of the changes made. It sets the tone for the rest of the message and helps reviewers quickly understand the purpose of the commit.
- Brief Summary of the Commit (50 characters max): The subject line should be concise, ideally limited to 50 characters, to ensure readability in various Git tools and interfaces.
Body
The body of a commit message provides detailed information about the changes made. It explains the "what" and "why" behind the changes, offering valuable context for reviewers and future maintainers.
- Detailed Explanation of What and Why: The body should elaborate on the changes introduced by the commit, explaining what was done and why it was necessary. This section can include technical details, design decisions, and any relevant background information.
- Reference to Relevant Issues or Pull Requests: Whenever possible, include references to related issues or pull requests. This helps link the commit to broader project discussions and provides additional context.
- Separate Paragraphs for Different Points: To enhance readability, separate different points or topics within the body into distinct paragraphs. This makes the message easier to scan and understand.
Footer
The footer of a commit message includes additional metadata that may be relevant to the commit. This can include co-authors, issue tracking information, and other pertinent details.
- Metadata Like Co-Authors, Issue Tracking, etc.: The footer can be used to acknowledge co-authors, track related issues, or include other relevant metadata. This helps maintain a clear and comprehensive record of contributions.
- Sign-off Details: When required, include a "Signed-off-by" line in the footer to indicate who authored or reviewed the commit. This is particularly useful in projects that follow the Developer Certificate of Origin (DCO).
Git Commiting using Vimium
Part 3: Writing Effective Git Commit Messages
Tips for Crafting Clear and Concise Messages
Writing clear and concise commit messages is an art that can significantly improve the readability and maintainability of your codebase. Here are some tips to help you craft effective commit messages:
- Be Precise and to the Point: Avoid vague language and focus on specific changes. Clearly describe what the commit does.
- Use Active Voice and Present Tense: Writing in active voice and present tense makes commit messages more direct and easier to understand.
The Imperative Mood
Using the imperative mood in commit messages is a widely recommended practice. It helps maintain a consistent and professional tone.
- Explanation and Importance: The imperative mood (e.g., "Fix bug," "Add feature") gives a command and clearly states what the commit does. This approach aligns with how commit messages are interpreted: they describe what applying the commit will do.
- Examples of Imperative Mood in Commit Messages: Examples help illustrate how to effectively use the imperative mood in your commit messages.
Using Markdown for Formatting
Markdown is a lightweight markup language that can be used to format commit messages, making them more readable and organized.
- Adding Bullet Points and Code Blocks: Use bullet points to list changes and code blocks to highlight code snippets. This enhances the clarity and readability of the commit message.
- Enhancing Readability: Utilizing Markdown formatting can significantly improve the visual structure of your commit messages, making them easier to scan and understand.
Part 4: Git Commit Message Best Practices
Writing great commit messages is an art that combines clarity, brevity, and structure. Here are some best practices to follow, ensuring your commit messages are both informative and efficient.
Keep Messages Short but Descriptive
Your commit message should be concise yet descriptive enough to convey the main change. Aim for subject lines under 50 characters and body text that provides necessary details without being overly verbose.
- Optimal Length for Subject Lines and Bodies: Keep your subject line to 50 characters or less to ensure it fits nicely in various Git tools and interfaces.
Separate Subject and Body with a Blank Line
Always separate the subject from the body with a blank line. This enhances readability and ensures that tools parsing your commits can do so accurately.
Use the Body to Explain What and Why, Not How
The body of your commit message should focus on what changes were made and why they were necessary, not on how the changes were implemented. This keeps the message concise and focused.
Reference Issues and Pull Requests
Linking to relevant issues or pull requests provides context and helps trace the history of the changes. It’s a good practice to reference issues directly in the commit message.
- Linking to GitHub or GitLab Issues: Use autolinked references to connect your commits to issues and PRs.
Capitalize the Subject Line
Always start the subject line with a capital letter. This is a simple yet effective way to keep your commit messages looking professional and consistent.
Do Not End the Subject Line with a Period
Avoid ending the subject line with a period. It’s unnecessary and goes against the convention of keeping the subject line brief and to the point.
Wrap the Body at 72 Characters
For better readability, wrap the body text at 72 characters. This makes your commit message easier to read in various interfaces, especially those that display text in a narrow column.
Examples of Good vs. Bad Commit Messages
Seeing examples can help you understand these best practices in action. Here are some comparisons to illustrate good and bad commit messages.
Good Commit Messages: Clear, concise, and informative.
Example 1:
Subject: Fix null pointer exception in login Body: Resolved a null pointer exception that occurred when the user attempted to log in without entering credentials. Added validation to check for null values before processing login requests. Fixes issue #123.
Example 2:
Subject: Add search functionality to product page Body: Implemented a search feature on the product page allowing users to filter products by name, category, and price. Updated UI components to accommodate the new search bar. References issue #456.
Bad Commit Messages: Vague, unstructured, or overly detailed.
Example 1:
Subject: Fix bug Body: Fixed a bug that was causing issues.
Example 2:
Subject: Update code Body: Updated some parts of the code. Changed various files and fixed some bugs that were reported.
Example 3:
Subject: Implemented new feature for product search which includes multiple parameters like name, category, and price. Also, updated the UI to accommodate this feature and added a new search bar at the top of the product page for better user experience. This change required modifying several components and adding new tests to ensure everything works as expected.
By following these best practices, you'll ensure your commit messages are a valuable part of your project's documentation and history, aiding both current and future developers in understanding the codebase.
More examples from https://www.conventionalcommits.org/
Part 5: Git Commit Message Best Practices Examples
To make these best practices more tangible, here are some examples of well-crafted commit messages for different scenarios. Each example includes a subject line and a detailed body that adheres to the guidelines we've discussed.
- Example 1: Adding a New Feature
Subject: Add user authentication feature
Body:
Implemented user authentication functionality using JWT.
Added login and registration endpoints.
Updated frontend to handle authentication.
- Example 2: Fixing a Bug
Subject: Fix null pointer exception in login
Body:
Resolved a null pointer exception that occurred when the user attempted to log in without entering credentials.
Added validation to check for null values before processing login requests.
Fixes issue #123.
- Example 3: Updating Documentation
Subject: Update README with setup instructions
Body:
Added detailed setup instructions for the development environment.
Included steps for database setup and initial configuration.
Clarified existing instructions for clarity.
- Example 4: Refactoring Code
Subject: Refactor user service for better readability
Body:
Refactored the user service to improve code readability and maintainability.
Split large methods into smaller, more manageable functions.
Added unit tests to ensure the refactoring did not introduce any bugs.
- Example 5: Improving Performance
Subject: Optimize database queries for user endpoints
Body:
Optimized database queries to improve performance of user-related endpoints.
Reduced query execution time by adding appropriate indexes.
Updated ORM configurations to use more efficient query methods.
Performance benchmarks show a 30% improvement in response times.
Axolo User Experiences
2480+ developers online
We used to send each other our GitHub PR links on Slack to ask for a review. Having Axolo made it a zero-effort thing. Having discussions on Slack is much more natural and Axolo does a great job doing it. The support is amazing as well! Arthur and Sydney proactively reach out to ask if we're facing any issues and even released one feature request within hours!
Axolo is a must-have for teams using GitHub. My team can discuss pull requests without leaving Slack now. Axolo helped us merge pull requests faster in a more seamless way. I was waiting for this product for so long!
I've been a CTO at various companies for a decade now. One of my biggest pain points has always been PR review responsiveness. I've tried so many home baked solutions. Axolo is the app that solves the problem perfectly.
Part 6: Automating Git Commit Messages
Automation can help maintain consistency and adherence to best practices in Git commit messages. By using tools and templates, you can enforce standards and make sure every commit message is clear and informative.
Tools for Enforcing Commit Message Standards
There are several tools available to help enforce commit message standards, ensuring that every commit message meets your team's guidelines.
Commitlint: Commitlint checks if your commit messages meet the conventional commit format. It can be integrated with various CI tools to enforce standards automatically.
- Commitlint Documentation
Screenshot of how Commit Link works
- Commitlint Documentation
Husky: Husky is a tool that allows you to run Git hooks easily. It can be used to enforce commit message conventions by integrating with tools like Commitlint.
Git Hooks: Git hooks are scripts that run automatically at specific points in the Git workflow. You can use them to enforce commit message standards, run tests, or perform other checks.
Setting Up Commit Message Templates
Using commit message templates can help ensure that your commit messages are consistently formatted and include all necessary information.
- Creating and Using a Commit Message Template in Git: You can set up a commit message template in Git to standardize your commit messages. This ensures that every commit message follows a predefined structure.
- Example Templates and How to Customize Them: There are many examples of commit message templates available online. You can customize these templates to fit your team's specific needs.
Part 7: Common Pitfalls and How to Avoid Them
Even with the best intentions, it's easy to fall into common pitfalls when writing commit messages. Here are some typical mistakes and how to avoid them, ensuring your commit history remains clear and useful.
Vague Commit Messages
Vague commit messages fail to provide enough information about the changes made, making it difficult for others to understand the purpose and impact of the commit.
- Examples and Why They Are Problematic: Vague messages like "fix stuff" or "update code" are uninformative and do not help in understanding the changes made. They complicate code reviews and future maintenance.
- How to Make Them More Specific: Be precise and descriptive. Explain what was changed and why. Use the commit body to provide additional context if needed.
Overly Detailed Commit Messages
While it's important to provide context, overly detailed commit messages can be just as problematic as vague ones. They can overwhelm readers with unnecessary information.
- Finding the Right Balance: Aim for clarity and conciseness. Provide enough detail to explain the change without overloading the reader with information.
- Examples of Concise Yet Informative Messages: Focus on what and why, keeping explanations brief and to the point.
Ignoring the Subject Line
The subject line is the most visible part of your commit message. Ignoring its importance can lead to confusion and reduced readability in commit logs.
- Importance of a Clear and Concise Subject: A clear subject line summarizes the commit and makes it easy to understand at a glance. It should be succinct and to the point.
- Examples of Effective Subject Lines: Compare good and bad subject lines to see the difference. Good subject lines are specific and informative, while bad ones are vague or overly detailed.
By being aware of these common pitfalls and actively working to avoid them, you can ensure your commit messages are clear, concise, and valuable to your team. This practice will significantly enhance the quality and navigability of your project's commit history.
Part 8: Git Commit Message Conventions
Standardizing commit messages with conventions can greatly improve the readability and manageability of your project's history. Let's explore some widely-used conventions and how you can customize them for your team.
Conventional Commits
The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history, which makes it easier to write automated tools on top of.
- Overview and Benefits: Conventional Commits use a simple, structured approach to writing commit messages. This helps automate the release process, generate changelogs, and ensure consistent communication across the team.
- Types and Examples of Conventional Commits: There are specific types of commit messages, such as
feat
for new features,fix
for bug fixes, and more. Each type has a clear purpose, making it easy to understand the nature of each commit.
Semantic Commit Messages
Semantic commit messages follow the principles of semantic versioning. They help in understanding the impact of each commit on the project’s version and automate the versioning process.
- Using Semantic Versioning in Commit Messages: Semantic versioning provides a structured way to increase version numbers based on the type of changes. Using it in commit messages ensures that version numbers accurately reflect the nature of changes.
- Examples and Use Cases: Examples include using
fix:
for bug fixes,feat:
for new features, andBREAKING CHANGE:
for changes that break backward compatibility. These examples help in automating version bumps and generating release notes.
Customizing Commit Message Guidelines for Your Team
While standardized conventions are useful, customizing them to fit your team’s workflow and preferences can enhance productivity and consistency.
- Establishing and Enforcing Team-Specific Conventions: Create a set of guidelines tailored to your team's needs. This could include specific tags for different types of work, additional metadata requirements, or custom formatting rules.
By adopting and customizing commit message conventions, you can ensure that your project's commit history is consistent, informative, and easy to manage. This not only improves collaboration within the team but also facilitates automation and enhances the overall quality of the project documentation.
Part 9: Advanced Git Commit Message Techniques
Taking your Git commit messages to the next level involves adopting advanced techniques that can enhance clarity, drive automation, and improve collaboration, especially in larger or open source projects. Let's dive into some of these techniques.
Using Emojis in Commit Messages
Emojis can add a visual element to commit messages, making them more engaging and easier to scan. They can quickly convey the type of change at a glance.
- Benefits and Examples: Emojis help in categorizing commits and making the commit history more readable. For example, 🐛 for bug fixes, ✨ for new features, and 📝 for documentation updates.
- When and How to Use Emojis Effectively: Use emojis consistently and sparingly. They should enhance readability, not clutter the commit message.
Crafting Commit Messages for Automated Tools
Automating workflows with CI/CD tools can be significantly enhanced by using structured commit messages. This helps in triggering specific actions, generating changelogs, and automating deployments.
- Best Practices for Commit Messages that Trigger CI/CD Actions: Use conventional commit messages to trigger automated processes. For example,
fix:
can trigger a patch release, whilefeat:
can trigger a minor version bump. - Examples of Commit Messages for Automated Deployments: Commit messages that integrate with CI/CD pipelines can streamline deployment processes. For example, using
[deploy]
in the commit message to trigger a deployment pipeline.
Commit Messages in Open Source Projects
Commit messages are crucial in open source projects for maintaining clear and communicative histories that facilitate collaboration among a wide range of contributors.
- Guidelines for Contributing to Open Source: Follow the specific contribution guidelines provided by the open source project. These often include standardized commit message formats to ensure consistency and clarity.
- Examples from Popular Open Source Projects: Many popular projects have detailed guidelines for commit messages. For instance, Kubernetes and Angular have specific conventions to follow.
By incorporating these advanced techniques into your commit message practices, you can further enhance the quality and utility of your project's commit history. These practices support better automation, clearer communication, and more effective collaboration, especially in larger teams or open source environments.
Conclusion
Recap of Key Points
In this guide, we've explored the crucial elements of writing effective Git commit messages. We've delved into the structure of commit messages, discussed best practices, highlighted common pitfalls, and introduced advanced techniques to elevate your commit messages. By mastering these aspects, you can significantly improve the clarity and utility of your commit history.
Importance of Consistent Commit Messages
Consistent commit messages are the backbone of a well-maintained codebase. They:
- Enhance Collaboration: Clear commit messages ensure that team members can quickly understand changes, making collaboration smoother and more efficient.
- Facilitate Code Reviews: Well-written messages streamline the code review process, allowing reviewers to focus on the quality of the code rather than deciphering the intent behind changes.
- Support Automation: Structured commit messages are crucial for integrating with CI/CD pipelines and other automated tools, enabling seamless deployments and accurate changelogs.
- Aid in Troubleshooting: Detailed and specific messages help in tracing the origins of bugs and understanding the history of changes, making debugging more straightforward.
Encouragement for Ongoing Improvement and Adaptation
The field of software development is dynamic, and so are the best practices for writing commit messages. Here’s how you can stay ahead:
- Regularly Review Practices: Periodically evaluate your commit message guidelines to ensure they align with the latest industry standards and team needs.
- Encourage Team Feedback: Foster an environment where team members can suggest improvements and share insights on what works best for them.
- Adapt to New Tools and Workflows: Stay updated with the latest tools and methodologies that can enhance your commit message practices. Automation tools, in particular, are constantly evolving and can offer new ways to enforce standards and improve consistency.
- Promote a Culture of Excellence: Commit to continuous learning and improvement. Encourage your team to view commit messages not as a chore, but as an integral part of the development process that adds significant value to the project.
By embracing these principles, you can ensure that your commit messages not only document the history of your project effectively but also contribute to a more efficient, collaborative, and high-quality development process. Remember, every commit is a piece of the larger puzzle that makes up your project's history. Make each one count.
Appendix
Glossary of Terms
- Commit: A snapshot of changes made to the codebase at a specific point in time.
- Commit Message: A brief text that accompanies a commit, describing the changes made and the reason for them.
- Conventional Commits: A specification for adding human and machine-readable meaning to commit messages, based on a set of rules.
- CI/CD: Continuous Integration and Continuous Deployment/Delivery. A set of practices and tools that automate the process of code integration and deployment.
- Semantic Versioning: A versioning scheme that uses a three-part version number (major.minor.patch) to convey meaning about the underlying changes.
Additional Resources and References
For further reading and to deepen your understanding of effective commit message practices, here are some valuable resources:
Templates and Checklists for Git Commit Messages
Using templates and checklists can help standardize your commit messages, ensuring they are clear, consistent, and informative.
By leveraging these resources and tools, you can enhance your commit message practices, contributing to a more efficient and collaborative development process. These templates and guidelines serve as a solid foundation for maintaining high standards in your project's commit history.