Rethink How You Write Git Commits

Published May 29, 2021

Table of Contents

How to Write a Git Commit Message

There are no set rules how you should structure a commit message. As long as it’s descriptive, and clear. I’m often guilty of writing horrible non-descriptive commit messages myself, after I’m left with no mental energy to distill succinctly what I’ve done. You might write:

git commit -m "Added feature to add todos"

I prefer using the imperative mood way:

git commit -m "Add feature to add todos"

You often perform other verb actions on your Git history, using subcommands such as git revert.

”The imperative mood is a grammatical mood that forms a command, or request.”

You can learn more by reading How to Write a Git Commit Message which inspired the title of this section.

Same as writing comments in your code — try that your commits answer what, and why, instead of how.

You can see the Git history, by saying git log. You’re going to get a list ordered by most recent commits. Each commit is listed with a SHA-1 checksum. Since it’s long, we can just specify the first 8 characters.

This problem can be more pronounced, when not considering these things:

git log --pretty=oneline

# ca82a6df Added new feature
# 085bb3bc Fixed breaking changes
# a11bef06 Polishing
Person with a confused look on their face

Compared to being more clear, and descriptive:

git log --pretty=oneline

# ca82a6df Add feature to add todos
# 085bb3bc Fix bug in Safari that prevented adding a todo
# a11bef06 Add micro-interactions to improve the user experience

Which one do you prefer?

Conventional Commits

The Conventional Commits specification is just an agreed upon convention with a simple set of rules for an explicit commit history.

  • The commit should be prefixed with a type of feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
  • The type prefix must be followed by a colon, and space
  • After it you write a description (short summary of the code changes)
git commit -m "feat: Add todo"
git log --pretty=oneline

# ca82a6df feat: Add todo
# 085bb3bc fix: Solve bug in Safari that wouldn't add a todo
# a11bef06 style: Add micro-interactions to improve the user experience

You don’t have to strictly adhere to it. I use a types type, when I’m working with TypeScript type definitions.

I prefer capitalizing the description. It doesn’t matter what you prefer, as long as you’re consistent. Sometimes a project you’re contributing to doesn’t have rules. In that case, I first look at how they structure their project, so it’s consistent.

There’s other reasons why this system is useful:

  • You can have automatically generated changelogs
  • Semantic versioning is done for you (since it can understand what type of change you’ve made based on the type)
  • It’s self-explanatory, so anyone can understand it
  • Having a more structured commit history makes contribution to your project easier

Using the VS Code Extension

You can use the Conventional Commits extension. It makes it simple to write commits, in a couple of steps, using a dialogue. Pressing Ctrl + Shift + G brings us to the source control panel:

Arrow pointing to the location of Conventional Commmits inside VS Code

You can select the type of change:

Dialogue with options for type of commit

There’s even emoji options:

Dialogue with options for emojis

After you’re done, and do a git log:

Shows git log, after creating a conventional commit



This is a great way to get started, but after a while you’re going to notice how slow it feels. At that point you have already memorized, and read the descriptions for the options.

I suggest you get comfortable using your terminal, if you already aren’t. I use a mix of both, as sometimes I prefer the visual feedback, such as looking at the difference between two files after I’ve made changes.

Read you later.


If you want to support the content you're reading or watching on YouTube consider becoming a patreon starting low as 1$ per month.

Become a patreon
Subscribe For Updates
Found a mistake?

Every post is a Markdown file so contributing is simple as following the link below and pressing the pencil icon inside GitHub to edit it.

Edit on GitHub