When we're learning to code, we are often taught the necessity of using version control. I feel like one thing that we are not taught properly is how to write effective commit messages.

---

Anatomy of a good commit message

Line 1 {Ticket ID / Feature} {Summary}

Include the Ticket ID if required by your team, or to integrate with your project management tool. Line 1 should be short - many tools recommend under 50 characters.

Line 2 Blank line

Required if you have a description below. This is used by git to separate the summary from the description.

Lines 3-n {Description}

The description should tell the reader what and why, not how. Use correct grammar and try to be concise. New paragraphs are denoted by a separating blank line. Include any relevant links at the end of the description.

Some examples

Below are some examples that I have pulled out of my own repositories. When working on solo projects I tend to get lazy and avoid my usual engineering practices, something which I am trying to remedy.

Never do this

$ git log
6d174c4 changes
21504c4 Start adding more stuff

Avoid doing this

$ git log
2e6174a Do groups properly
1c8786d Add drag and drop reorder

Do this

$ git log
e06b327 Mood tracker: chart component implementation

Add chart component for tracking mood; this uses Chart.js
and displays the user's mood as determined by their mood log.

Add Luxon DateTime library to replace Moment.js. See
https://momentjs.com/docs/#/-project-status/

Note how I have included a short summary line, and description of the work done.

What the creator of Git does

Did you know that Linus Torvalds, the creator of Linux, also created git?

He still actively contributes to the Linux Kernel; you can look at his recent commits on the Linux Kernel on GitHub

Past or present tense

A common argument when talking about how to write commit messages properly, is whether to use past or present tense. Most people starting out (including myself) reflexively opt for past tense.

Past tense feels natural because we are committing some work that we just did, and we view our git log as a kind of journal. However, the official guidelines for git itself state that we should use present tense instead.

The reason behind this is the meaning we give to a git commit. If you think about it, a commit represents one possible 'state' of a repository. Applying a commit, no matter if it happened in the past, present or future, replaces your current state with the committed state. Therefore, if you are applying a commit that adds a new class file Calculator.cs, it would make more sense for the message to be:

Add Calculator.cs...

instead of

Added Calculator.cs...

Personally, I use present tense because that's what I am used to. However, I believe the arguments for both are valid; the most important thing is to be consistent and use whatever your team uses.

---

Like many things in software development, there is no protocol or standard to define how commit messages should be written. All we can do, is to learn the 'best practice' and apply it to our work.