How To Write Better Git Commit Messages

January 2, 2022

Git is by far a most used and default choice for individual developers and teams. Developed by Linus Torvalds (who also created Linux operating system kernel in 2005) now adopted by many from small teams to the biggest companies or individual who is just working on personal project.

It makes a lot easier to maintain large codebase which require multiple changes frequently, especially if you are working with a team. No matter if you are working on some personal project or with a team, you need some sort of version control system to keep all the development things on track.

Why write good commit messages

If you are just getting started with git, then you will often find struggling with commit messages. Try to do `git log` to see your commit history, you can get lost or overwhelmed by your own commits! If not done right.

Suppose you have to go back in time and fix some issues or look for something, you can get confuse or frustrated (as it happened to me) by all the inconsistent messages you have written.

Another reason is if you are working in team, well most established team follows some kind of rules on how should everyone write their commit messages. But when you are forming a new team or part of a new team (or just starting out on your own) you should be able to write better commit messages to keep peace with other team members.

So it's important to write good and clean commit messages, because when you use `git log` you will get what you what in less time, and also your team members will understand what this commit is for.

How to write better commit messages

Generally you can commit via two ways, first via command git commit -m "your message" and another by git commit which opens a commit editor to write detailed type commits which is like:

<Summarize message in 50 or less>
<blank line>
<BODY: detailed explanation of change, use 100 or less>
<blank line>

Well you can commit your messages in details, but generally speaking try to summarize it in 50 characters or fewer because you will probably not look into the body of commits that often as the subject line is self-explanatory enough to tell you what's this commit for if done right.

Below are some steps on how to write better commit messages.

Simplicity is the ultimate sophistication. ~ Leonardo da Vinci

Prefix you commit messages

Whenever you are making a change it will always be related to some kind of fix, refactor, test, etc. so you can define some prefix which will help you to identify what this commit message is for like: git commit -m "fix: your message goes here" This clearly defines that this messages is related to some kind of fix in your codebase.

Use short acronym for your commits, some of them are given below or fell free to make your own acronym.

  • docs: changes in documentation only
  • feat: a new feature
  • fix: a bug fix
  • perf: a code change which improves performance
  • refactor: a code change that neither fixes a bug nor adds a feature
  • style: changes which do not affect the meaning of code like formatting, missing white-space
  • test: adding or correcting tests
  • git commit -m "fix: need to require email in form validation"
    git commit -m "docs: correct the grammar in CLI documentation"
    git commit -m "eat: support for Spanish language"

    Tip: You could use "!" to define the breaking change in codebase, later while looking through your log history it will draw attention towards breaking changes you had made in codebase.

    git commit -m "fix!: this will break something"

    Note: Well, any casing can be used, but it's best to be consistent. I use lowercase with no period at the end of messages.

    Define message scope (optional)

    This is optional but recommended, including scope, which defines the section or part of your codebase you are making a change to. Like it can be components, templates, settings, etc.

    You can define the scope of commit message like if you have done some changes related to components or templates then you can define your commit messages like:

    git commit -m "fix(component): broken link in navigation bar"

    This clearly states that the fix is carried out in a component section, which limits the search area for you.

    Try to summarize your message

    Limit yourself to fewer character possible, try to write a concise and clear message describing your change. The soft limit for commit messages is 50, so try to summarize your messages in 50 or less.

    Use imperative present tense

    You would notice that above commit message are written in present tense like change, correct instead of changed and corrected. Well, this sort of style comes directly from git itself

    It says you should make the changes in present tense instead of past tense as if you were giving orders to codebase to change its behavior like: instead of `"changed the xyz thing"` write like `"change xyz thing"`

    I know it sounds like kind of weird, but simply put it, the commit shows what it will do instead of what it did.

    Why we use this sort of behavior, why not just write in past or whatever tense suitable to us, because it's good practice even when you are working on some personal project, it makes you commit style consistent and much appreciated when working with others as it establishes good habits.

    I used to write commits in past tense and struggle to get it through as sometimes it does not fit in the sentence properly, but as time passes it becomes natural. You can make this habit by writing in such a manner that you are giving command to codebase: like 'feat: add like button' or 'config: block suspicious traffic'

    Git works best, and works in your favor, when you commit your work often. Instead of waiting to make the commit perfect or after finishing all change, it is better to work in small chunks and keep committing your work.

    Now you are thinking that doing often git commits or frequently does not drag down rapid development and fast iteration, well you are not totally wrong about that, but think in long terms. Did you want messy, understandable, confusing or disorganized commit messages in your log history. So why not do a favor for your future self by committing and moving in an organized way.

    For every minute spent organizing, an hour is earned. ~ Benjamin Franklin

    Having said that, if you want to do things your own way, feel free to do so, but make some standard and consistent choices and stick to them.