This week, I’m going to give you a 3 step process for writing perfect commits.

If you’re working on code and aren’t using a versioning system, you should definitely start there. Atlassian has a great introductory section in their docs if you want to learn more.

One of the best things about version control is being able to scan through a list of commits and you can get a general sense of what was changed. However, one thing I see too much is really bad commits.

How many times have you taken a look at the git log and saw something like this?

526e8136fdd94f68db88a3cae408441871c490cf update again
246a668ebd7a991212a96692b669867c191c17ff update
dc377b78d60b4d1381f48e461cae2ba3953d7b52 more changes
fa5ce17ac44b44e3db89596b82df4afa6032c060 changes
bada5dde22ba7e733a14cfc2ee7f9da49d023d86 Update
23b0090475a4f9ab8471ec75f18a21e55d393d2e Initial commit

Commit messages should help you identify changes easily

You should always strive to provide the most context you can for a set of changes in code:

• it helps those coming behind you understand what you did
• it can help others review your code more easily
• it gives meaning to the git log
• it provides all the context

Other than that, writing good git commits is just a good practice for everyone. Be a good steward of your codebase and you may save yourself time and frustration one day.

Here are the steps I walk through every time I start writing a commit:

Explain your changes simply

The first line of a commit message should be succinct.

There’s only enough room for 50 characters, so write it as if you are writing the subject of an email.

Here’s something I’ve put in my commit message template to help me remember this:

This is my really short description of my changes
######## Subject Line (50 characters) ############
# - Use the imperative mood (imagine the words "This will")
# - Capitalize the first letter
# - Limit to 50 characters
# - Do not end the subject line with a period

If you’re curious how you can include this in your editor, I wrote a guide that will help you configure VS Code to prompt you with this (and following examples) each time you use git commit.

The first line of a commit message is the subject and will be displayed in your git log, but every line afterward is the body of the message.

Use the body of the commit to explain

Often, your commits only need to consist of the first line.

But sometimes you need to explain yourself more than in a single 50 character line.

In the body of my commit message, I can spend a little more time
explaining the logic behind my changes. Maybe it's the solution to a
really difficult bug and I want whoever is coming behind me to see that
I did some deep digging here.
######## The Body (72 characters per line) #############################
# - Add line breaks so each line is a maximum of 72 characters
# - Explain the thinking behind the commit
# - Do not use Markdown

If you just made a really weird code change that feels hacky, or it needs more explaination, you can add it directly to the following lines of the commit.

Each line in the body should not be longer than 72 characters (so it looks good in most applications and logs). Explain your thinking as much or as little as you need to, seriously, there’s no real limit here.

However, you probably shouldn’t use markdown here.

If you’re using Github as your version control service and you submit a pull request with a single commit, it will extract the first line as the subject of the PR and use the commit body as the body of the PR.

Here’s my git commit:

This is the subject of my new feature change

And this is the body explaining why this feature or bug is necessary to
add to the project. I can add any additional context to help explain
my logic, or something specific I want to remember about this change.
Github will automatically include this as the body of my Pull Request.

And when I go to create a Pull Request in Github’s UI, I’m presented with exactly what I added in my commit.

It’s in your best interest to write good commits because you won’t have to repeat yourself!

Use the last line to include an issue or ticket number

If you use some kind of project management software, or actively use Github’s issues, you can include that information here.

It’s a great way of providing more context around the change and linking directly to your ticket or issue just provides one more snippet of context and rounds out your commit with everything your teammates would want.

This commit closes #2987
######## Issue or Ticket Reference ########
# - The last line should reference the issue or ticket

Also, if you use Github’s keywords, you can close an issue directly within a commit and once it’s merged into the primary branch, Github will automatically close your issue for you and link the two together.

This is a really useful feature when you have a busy codebase.

In Summary

Commit messages provide a scannable history of the changes made to your plugin’s codebase. Use them to jog your own memory, or help explain things to fellow team members.

1. Write the subject of your commit using no more than 50 characters
2. Use the following lines to explain your changes with more detail or context
3. Finish your commit off with the last line being the issue or ticket number (if necessary)

Take time this week to really focus on writing good commits and you’ll start to see the benefit.

And again, if you want to set this all up in VS Code, check out the guide I wrote.