The Importance of Writing a Good Commit Message
When it comes to Git commits, a well-crafted message is more than just a technical necessity. It serves as documentation, providing essential context for future reference. During a
git show, a descriptive commit message offers valuable insights into the changes made, aiding comprehension and troubleshooting.
Furthermore, communicating with accessible peers about implementation and modifications opens doors for constructive collaboration and alternative perspectives. Tech leads can also better understand your approach, enabling them to offer valuable advice on advancing the solution using alternate methods.
The commit header should be concise, with a maximum length of 72 characters in GitHub, to avoid truncation with ellipsis. Ending the title with a period is unnecessary, as every character counts. Starting with an imperative mood verb, such as
Refactor, sets a clear and actionable tone for the commit.
Using Conventional Commits
To provide even more context, consider following the Conventional Commits specification, which builds on the Angular Commit Guidelines. Prefix the title with specific keywords like fix, feature/feat, refactor, deploy, chore, docs, or test. Each prefix highlights the nature of the changes made.
- fix: Represents a bug fix for your application.
- feature / feat: Adds a new feature to your application or library.
- refactor: A code change that neither fixes a bug nor adds a feature.
- deploy: Changes related to the deployment process.
- chore: Upgrades libraries and/or performs maintenance tasks.
- docs: Documentation-only changes.
- test: Adding missing tests or correcting existing tests.
Here’s an example:
feature(shopping-cart): Add remove button
User can now remove the item entirely from shopping cart.
On clicking the button an animation transition will be
Adding a line break between the header and the body helps organize information clearly. You can mention the files affected by the changes and explain the purpose and accomplishments of the commit. Keeping individual lines within 100 characters enhances readability.
- Add a linebreak between Header and the body
- You can mention which files are included in these changes
- Explain why and what was accomplished in this commit
- Many tools recommends that any line cannot be longer than 100 characters, making each one more readable
Commit message conventions (Annotations)
Marking your pairs during commits is essential for effective collaboration, especially in pair programming (eXtreme Programming). When the author accepts the
suggestions block made during a Pull Request review, GitHub doesn’t use
Suggested-by convention, instead it uses
While there are more conventions to follow, in common workflows, using
Co-authored-by is strongly recommended.
When to Commit?
Committing early and often throughout development is highly recommended. Delaying commits until the end of the process can create challenges in organizing atomic commits, crafting a coherent narrative, and receiving timely feedback during the Code Review process. By committing regularly, you can easily create a Draft Pull/Merge Request to seek immediate peer input.
Staging the Changes
Simplify your commit process with tools like LazyGit, tig, GitHub Desktop, Git Tower, or GitKraken. When making changes, think of each commit as a “package” that should be “revertable” through
git revert without breaking the build or test suite. Run tests right after creating a commit to ensure changes do not disrupt the suite. To temporarily remove existing changes, use
git stash --include-untracked, then remember to
git stash pop and continue the commit process.
Forgot Something in the Previous Commit?
If you missed including a change, you can easily remedy the situation with
git add followed by
git commit --amend. The
--amend command picks up your previous commit message (don’t forget to update the details about the inclusion) before pushing it with
Note that if you already pushed the commit, you’ll need to use
git push -f to replace the existing commit with the regenerated SHA1 commit from the amendment. If you’re collaborating with others in the same branch, remind your peers to pull the changes, though no impact is expected if they haven’t started working in this branch yet.
The Art of Summarize: Drafting/Opening a Pull Request
When working on a project for 2-5 days, summarizing your work in a Pull Request can be challenging. Leverage your well-crafted commit messages to read the story and provide concise summaries to your reviewers. Doing so not only streamlines the review process but also serves as documentation for future reference.
$EDITOR is set to your favorite editor for
git commit execution:
You can also configure
core.editor to open any
git command in your preferred editor (Visual Studio Code in this example):
git config --global core.editor code --wait
Use Templates for Commit Messages
Simplify the git commit message structure by using templates:
$ git config --global commit.template ~/.gitmessage.txt
$ git commit
Not sure how to start? Use this one:
# Replace this title (<- imperative), <= 50 chars, no period
# Keep this blankline above but replace this line and below
# by your body explaining *what* and *whay* (not *how*) no
# more than 100 chars.
# Here is a footer, include the Git Conventions annotations
# you prefer, such as:
# Co-authored-by: name <firstname.lastname@example.org>
✅ The Journey to Better Commits: Level Up! Quest Completed!
In the journey of perfecting your Git commits, you’ve unlocked the art of crafting informative and context-rich messages that enhance your development process. Embracing Conventional Commits, staging your changes, and committing early and often, you’ve laid the foundation for collaborative and efficient code reviews.
Before marking your Pull Request as “Ready for review”, check this blog post: ‘10 Items to Check Before Assigning a Pull Request to Someone.’ Should your team seek more opportunities for reviews, venture into the realm of ‘Creating Code Review Opportunities‘ for valuable insights. Continue your quest for better commits and conquer new challenges, kupo!