How I Write Source Control Commit Messages

The concept of good messages to go along with your commits to source control seems to be one of those things that people either completely follow or completely drop the ball on. Fortunately my work right now is predominantly solo and I only have myself to blame if my commit messages are unhelpful, but I still try to follow a few rules to save the sanity of myself in the future. These are not industry rules, but merely my own standard that helps me maintain mine and my team's code base.

Rule #1: Good Messages Start With Good Story Cards

Some call them story cards, or tasks, or any number of other names for something that is a portion of work that must be completed from a less-manageable major task (aka an epic). Whatever you call them, many projects have some form of task list to work through and I leverage this list for my commit messages for later referencing. Several project management tools such as Jira or Mingle automatically assign cards to a number that increments as you go. The tool we use at my job unfortunately does no such thing, but I add a number to each card title manually to reap the same benefits. Each story card should have a basic title explaining what needs to happen. The description can go into more depth regarding the solution and other necessary information.

When I write up my commit messages, I start with the story card number for the work I'm submitting (you read that right - I try to keep it to one card per commit!) The beauty of providing the card number in your commit message is the ability to reference exactly what was done. If you need to go back to a week ago to figure out what changes were made that caused a new bug to crop up, you can look at the commit messages for the past week and see which cards were worked on and head over to your story board for further investigation.

Rule #2: Good Messages Are Descriptive

Consider for a moment that you've been tasked with going through the last month's commits of a fellow developer. Perhaps looking through the changes can lead you to what's causing this crazy new bug that just showed up. You bring up the source control manager and see something like this:
4/18/19 - committing stuff
4/15/19 - asdf
4/05/19 - before friday's meeting
4/04/19 - did stuff
4/01/19 - product card

Sure, you can look through each file that was changed in each commit to get an idea of what happened... but what if there was a better way? What if each source control message gave you a brief synopsis of the change that was done for that commit. Also, what if they were more frequent? A lot could have happened between April 5th and April 15th! I try to make a commit at least once a day; several times a day if I've been making a lot of significant changes in a short period of time.

The important part is to add some value to each commit message, whether you expect future-you or a coworker (or replacement) to read them or not. This simple act could save someone a great deal of time, giving them the ability to reference each major set of changes at a glance instead of needing to inspect each one.

Rule #3: Good Messages Explain What, Not How or Why

Another benefit to linking your commit messages to your storyboard by card numbers is the beauty of not having to repeat yourself. If your cards are written descriptively and show the steps taken to solve the problem, create the feature, etc., you don't need to write those things a second time in your source control because it can all be found if you follow the card number!

Your source control message should have some information in it though - I try to provide a sentence briefly explaining what changes were made. Some examples sentences could be "Added checklist for customer item selection" or "Removed discount button from main page". In the case of a card that spans over a longer period of time I will do several commits with a brief update of the work that happened in that span of time: "Implemented binding creation for Salesforce login feature".

If someone needs to trace back into the source control for the bug that showed up last week, they can get a birds eye view of the changes that went on in this period by reading the messages. If they see a message that sticks out, perhaps relating to the problem section of code, they can easily reference the number and check out the more detailed view in the related story card. The story card will provide them with the hows and whys of the changes that were made.

Good Messages Look Like...

So what do good source control commits look like? Here's a few examples of recent commits from my major project at work:
Card #213 - Updated formatting on Reports Form
Card #213 - Added Reports Form and first report to get and update all unprocessed orders
Card #208 - Updated query for discounts
Card #205 - Only requiring SOM_SalesOrderID in close/email dialog form
Card #204 - Moved SOM_UserDef5 and SOM_FOB updates ahead of SalesOrder XML creation

TLDR: When making source control commits, I try to keep my messages brief, descriptive, and maintain a regular formatting style. I also make an effort to keep one major change set or card per commit to avoid muddying up the change sets and messages.

Comments

[Kyle Chilcutt]

Rule #3: Good Messages Explain What, Not How or Why

One thing the consider is what the benefit of the commit message will be long-term. In the future, when the context is no longer fresh in your team's mind, you might be debugging an issue or building code based on the code in the initial commit. For me, I'm much more often asking "why is this here"/"why is this like this" than "what does this do" (because I have the context of "what does this do" from reading the code itself).

I often find myself pleasantly surprised when I'm debugging an issue with some code, say to myself "what was I thinking", hit git blame/git show and immediately know the context.

I think the card number is definitely great, but I don't think a distilled explanation in a commit message is a a waste of time either. Another small nuance is that the commit message is written in your own voice with your own understanding of the problem, at the point in time that you've just written the code, so you're in a much better place to write a technical description of what you've just done (in my experience, finished code often deviates from the plan).

It does take longer to write the commit message, and I agree that it takes a lot to move a team to this practice, but I can personally vouch for the benefits!

[Dan]

I stumbled on this not long ago and I'll share here as I learned from it. Based on Angular's convention for commit messages. Here's the link

Basically like this:

<type>[optional scope]: <description>

[optional body]

[optional footer]

I've taken that knowledge and adapted it into what I do. The <type> part I am flexible with.

[Chris Karpyszyn]

I've seen similar. I've used the karma git template which is this. This link has more detail though while I'll use to train with in the future. Thanks!

[Dan]

Be sure to check out the angular documentation which is a few clicks and a google doc away...
here

[Rachel Soderberg]

Sounds like a good convention! I'll look into the link later today, thanks!

[Chris Karpyszyn]

I try to keep it to one card per commit!

I'd like to offer a deeper tip here. It is good practice to keep commits to functional units of work. A story might, and should, contain multiple commits.

Then your final commit of the story can contain a git message footer that links back to the story number.

Then you can also separate units of functional code apart from refractors and doc chores.

This will make code review and reviewing the git history a lot cleaner!

Great post! Commit messages are important on large projects with multiple team members.

[Bruno Rodrigues]

First, thanks for sharing @rachelsoderberg ;)

Just came down here to write the same, I consider commits as the good old video game checkpoints.

Every time you hit a "safe place" where you would like to go back in case of something goes wrong, add a commit with a very descriptive message.

Your "future myself" (and code reviewers) will thank you a lot.

Further reading: pauline-vos.nl/atomic-commits/

[Daniel Hintz]

Love the analogy, I think of it the same way 😀

[Rachel Soderberg]

Thank you! And that is a great point - a lot of times I commit every time I have finished a solid (hopefully working) portion of the card. Basically if I'm going to step away for a break and would regret losing what I built, I commit. If what I commit isn't working, I make sure to specify what doesn't work and why.

[Chris Karpyszyn]

I would urge against commiting incomplete code. It really is a matter of opinion and process but for my team of 12 working on a large project keeping our git history clean is really helpful.

Some more tips to consider:

If you need to port code to another machine to continue working you can create a patch file:

git diff > patchfile
git apply patchfile

Or, if you do commit a temporary commit you could also squash the commits together using interactive rebase

git rebase -i HEAD~2

[Shaurita D. Hutchins]

Great post, and one that more people need to read (and I need to adhere to more often). It's so easy to get lazy. Also, I think what I've noticed with myself and others is sometimes a commit message or commit includes far more than what's in the actual changes which can be problematic.

[Vic Seedoubleyew]

Thanks for triggering a discussion on a topic that deserves it and is very important.

I find that this article would gain from being refactored from a "this is what good commit is" to "this is how I commit".

Many of the things it recommends are far from consensual or standard, as pointed out by several comments. Similarly, the examples lack several features which are often considered as required for good commit messages.

As a consequence I think it would be more helpful for young programmers and for the community if it took a less normative approach, and rather a more descriptive one.

[Rachel Soderberg]

You make a good point, I am one of those young developers and probably made the article name a little too "absolute" as in everyone does them this way, rather than implying that it's my understanding of them.

I'm curious too - if you don't mind, what features did I miss that would be considered required for good commit messages?

Thanks for the comment, I always appreciate constructive criticism & feedback!

[Vic Seedoubleyew]

I am glad that you are receiving my comment positively!

It would probably take a whole blog post to answer your question, but I guess what comes closest to my opinion is this: chris.beams.io/posts/git-commit/

Best of luck for the start of your career!

[Rachel Soderberg]

Thanks - and thank you for the link! That will be good reading, I appreciate it.

[Felipe Alvarez]

Prepend commits with the file or component which it is affecting.

Readme: add install instructions

[Rhys S]

In git, there are commands to see what files a commit changed - to me, prepending files names seems unnecessary

[Jakub Narębski]

I agree with the component / subsystem - the file is just a special case of that (of a very small component).

[Robert Schaap]

We did this at my last job as well. Either the filename or if it's multiple the source of the changes. It makes for a much easier to read git history / merge request.

[Rachel Soderberg]

Visual Stuido Team Explorer shows them as well, but this makes sense for ones that dont!

[Rostyslav Semanyshyn]

Here are the rules that I did save from one of the sources some time ago.

• Separate subject from body with a blank line
• Limit the subject line to 50 characters
• Capitalize the subject line
• Do not end the subject line with a period
• Use the imperative mood in the subject line
• Wrap the body at 72 characters
• Use the body to explain what and why vs. how

[Jesse Phillips]

You also only want to change what you say is changing. I've pushed for using gitmoji in every commit. The goal is to help review what the changes are supposed to do and make it fun to try and craft a commit to use a specific emoji.

Some of them should never make it to mainline though.

[Rob Kendal {{☕}}]

This is great! Commit messages are one of those weird parts of the development cycle that feel like they're just some boring, but necessary admin task. Having some guidelines (and enforced templates) help, but your article does a grand job of showing what bad and good messages look like and why the latter is important.

I also agree with Kyle's comment about context, but then you can also add a little more detail in the commit body for that where it's needed.

[Erik Pischel]

I'd recommend against writing the card/issue number in the first line. It's the summary line and IMO it takes away precious space I'd rather use for a good summary. I put the issue number in the last line of the message. We are using gitlab and I can easily search for it in the GUI if that is necessary.