The Perfect Git Commit Quest
Tags: git, codereview, bestpractices, github
Published: 2023-08-07 19:16:44

---
title: The Perfect Git Commit Quest
published: true
description: Embark on a thrilling journey to perfecting your Git commits! Craft well-crafted messages that serve as documentation, offer valuable insights, and foster collaboration with peers. Embrace Conventional Commits, stage your changes, and commit regularly to streamline the review process.
tags: git, codereview, bestpractices, github
cover_image: https://sourcelevel.io/wp-content/uploads/git_commit-1024x683.jpg
canonical_url: https://sourcelevel.io/blog/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](https://www.conventionalcommits.org/en/v1.0.0/) 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](https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/CommitMessageConventions.html), 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](https://github.com/jesseduffield/lazygit)**, **[tig](https://jonas.github.io/tig/)**, **[GitHub Desktop](https://desktop.github.com/)**, **[Git Tower](https://www.git-tower.com/)**, or **[GitKraken](https://www.gitkraken.com/)**. 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:

```jsx
export EDITOR=nvim
```

You can also configure **`core.editor`** to open any **`git`** command in your preferred editor (Visual Studio Code in this example):

```jsx
git config --global core.editor code --wait
```

### **Use Templates for Commit Messages**

Simplify the git commit message structure by using templates:

```jsx
$ git config --global commit.template ~/.gitmessage.txt
$ git commit
```

Not sure how to start? Use this one:

```jsx
# 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](https://sourcelevel.io/blog/10-items-to-check-before-assigning-a-pull-request-to-someone-plus-a-bonus).' Should your team seek more opportunities for reviews, venture into the realm of '[Creating Code Review Opportunities](https://sourcelevel.io/blog/creating-code-reviews-opportunities)' for valuable insights. **Continue your quest for better commits and conquer new challenges, kupo!**