Atul Kumar



Write Better Commits

Write Better Commits

Build better software

Atul Kumar's photo
Atul Kumar
Β·Sep 10, 2022Β·

5 min read

Table of contents

How many times you have found yourself thinking πŸ€”:

  • What is the purpose of this code? πŸ’­
  • Where did this bug arise from? πŸ›
  • How to start working on this massive pull request? 🀯

There are many ways to deal with these issues (code comments, style guides, documentation), and we will inevitably find ourselves spending hours just trying to understand code. 🀦

Commits in Git repositories are more than just save points or logs of incremental progress in a larger project. High-quality Git commits are the key to a maintainable and collaborative open or closed-source project.

I will share some strategies to improve and use commits to streamline your development process. So, let's get started without any further ado πŸ˜€.

What are commits? πŸ€·β€β™‚οΈ

Commits are snapshots of your entire repository at specific times based on logical units of change. Over time, commits should tell a story of the history of your repository and how it came to be the way that it currently is.

In layman's terms, commits are a firsthand historical record of exactly how and why each line of code came to be.

Commits are most effective when they’re tweaked and polished to deliberately convey a message to their audiences: reviewers, other contributors, and even your future self.

The Anatomy of a Commit Message πŸ«€


git commit -m <message>


git commit -m <title> -m <description>

Writing Better Commits πŸ‘

Capitalization and Punctuation πŸ…°οΈ

Capitalize the first word and do not end in punctuation. If using conventional commits, remember to use all lowercase.

Mood 🌚

Use the imperative mood in the subject line. The imperative mood gives the tone you are giving an order or request.

Type of Commit πŸ₯Έ

Specify the type of commit. It is recommended and can be even more beneficial to have a consistent set of words to describe your changes.

Length 🍒

The first line should ideally be no longer than 50 characters, and the body should be restricted to 72 characters.

Content πŸ“ƒ

Be direct, try to eliminate filler words and phrases in these sentences.

Structure the narrative πŸͺΆ

A series of commits has a narrative structure that contextualizes the β€œplot” of your change with the code. The commit history should tell the story of your project. It should be the biography of your project.

Disorganized commits that lack a clear narrative are gonna affect two people: the reviewer, and the developer itself 😨.

If those commits do not tell an easy-to-follow story, the reviewer will need to context switch as the author’s commits jump from topic to topic πŸ₯΄.

Make sure to outline your narrative, and reorganize your commits to match it.

Resize and stabilize the commits βš›οΈ

Although the structure of a commit series can tell the high-level story of an author’s feature, it’s the code within each commit that creates software. Code itself can be quite complex but in order to collaborate, others need to understand it. So, make each commit both β€œsmall” and β€œatomic.”

A small commit is one with minimal scope; it does one β€œthing.” A commit is atomic when it is a stable, independent unit of change.

Explain the context ❓

Commits are more than just the code they contain. Commit messages are an extremely valuable, but often overlooked component of a commit. Do describe what you’re doing and why you’re doing it in the commit message.

The content of a commit message should clearly communicate what readers need to understand.

Commit Early & Often ⌚

Committing early and frequently keeps your commits small and helps you commit only related changes. Moreover, it allows you to share your code more frequently with others and avoid having merge conflicts.

Conventional Commits πŸ“œ

Conventional Commit is a formatting convention that provides a set of rules to formulate a consistent commit message structure.

The commit type can include the following:


  • Title: Feature
  • Description: A new feature
  • Emoji: ✨


  • Title: Bug Fix
  • Description: A bug fix
  • Emoji: πŸ›


  • Title: Documentation
  • Description: Documentation only changes
  • Emoji: πŸ“š


  • Title: Styles
  • Description: Changes that do not affect the meaning of the code (white space, formatting, missing semi-colons, etc)
  • Emoji: πŸ’Ž


  • Title: Code Refactoring
  • Description: A code change that neither fixes a bug nor adds a feature
  • Emoji: πŸ“¦


  • Title: Performance Improvements
  • Description: A code change that improves performance
  • Emoji: πŸš€


  • Title: Tests
  • Description: Adding missing tests or correcting existing tests
  • Emoji: 🚨


  • Title: Builds
  • Description: Changes that affect the build system or external dependencies
  • Emoji: βš’οΈ


  • Title: Continuous Integrations
  • Description: Changes to our CI configuration files and scripts
  • Emoji: βš™οΈ


  • Title: Chores
  • Description: Other changes that don't modify src or test files
  • Emoji: ♻️


  • Title: Reverts
  • Description: Reverts a previous commit
  • Emoji: πŸ—‘

Now, let's see some commit aliases:


  • Maps to: feat
  • Title: Initial
  • Description: Initial Commit
  • Emoji πŸŽ‰


  • Maps to: fix
  • Title: Dependencies
  • Description: Update dependencies
  • Emoji: ⏫


  • Maps to: fix
  • Title: Peer dependencies
  • Description: Update peer dependencies
  • Emoji: ⬆️


  • Maps to: chore
  • Title: Dev dependencies
  • Description: Update development dependencies
  • Emoji: πŸ”Ό


  • Maps to: fix
  • Title: Metadata
  • Description: Update metadata (package.json)
  • Emoji: πŸ“¦

Good Commits VS Bad Commits ⚑

Good πŸ‘

  • git commit -m "Add margin to nav items to prevent them from overlapping the logo"
  • ✨ feat: improve performance with lazy loading
  • ♻️ chore: update npm dependency to the latest version
  • ✨ feat: set the background color to red to improve contrast
  • πŸ› Fix bug redirecting users to 404 page

Bad πŸ‘Ž

  • git commit -m "Add margin"
  • lazy loading
  • dependency updated
  • Set bg to red
  • endgame
  • deleted all the files
  • Style changed

Additional Resources 🌟

  • git-absorb: A tool that automatically splits miscellaneous fixes into assigned fixup! commits
  • Commitizen: Its main purpose is to define a standard way of committing rules and communicating them using the CLI provided by Commitizen.
  • Git Commit Message Emoji List

I am glad that I successfully wrote 4 articles in these 4 weeks with your constant love and support 😊.

Thank you so much for reading!

Happy coding!


Share this