The Perfect Git Commit Quest

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.

Commit Title/Header/Subject

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 Add, Fix, Remove, or 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
displayed.

https://linear.app/<workspace>/issue/A-123/add-ability-to-remove-item-from-shopping-cart

Commit Body

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)

Co-authored-by

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 Co-authored-by.

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 git push.

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.

Tuning Your git Command

Ensure your $EDITOR is set to your favorite editor for git commit execution:

export EDITOR=nvim

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 <user@users.noreply.github.com>

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!