How I Write Source Control Commit Messages

Rachel Soderberg on April 19, 2019

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 o... [Read Full]
markdown guide
 

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!

 

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.

 

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!

 

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

 

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

 

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.

 

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/

 

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.

 

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

 

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.

 

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
 

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.

 

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!

 

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!

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

 

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

Readme: add install instructions

 

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

 

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

 

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

 

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.

 

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.

 

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.

 

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.

 

Have you looked at Commitizen? I find it useful for prompting me to write better commit messages.

 

I havent, but I'll certainly check it out later today! Thanks for the tip

 

Great examples! I do much the same, but branch by card number and do descriptions with each commit, but I like your way better. If a merge gets squashed it still carries the commit messages

 

Great post! It pretty much explains the way my company does commits, though I think we all need to work on committing more frequent, smaller bits that can easily be explained by a simple message.

 

When writing commit subjects I found a good tip saying to start a sentence with "If you applied this commit then it would..." then use the rest of the sentence as the subject line.

 

That is a brilliant tip! I might just have to steal that and add it to how I currently do them. Thanks for sharing!

 
Sloan, the sloth mascot Comment marked as low quality/non-constructive by the community View code of conduct

The beauty of providing the card number in your commit message is the ability to reference exactly what was done.

That's a noob mistake to rely on your issue tracker. You can add a reference but the commit should be self-sufficient. If your issue tracker is replaced—and not archived—you will be left with a diff and the message body.

 

I feel like your comment could have been just as effective without calling me a noob to start. Thanks for the comment though.

 

ha, you're probably right. But we become less noob at some things as we learn from our mistakes (errr... experiences?)

In dev world mistakes are experiences as much as bugs are features.
(This one is growing into being my favorite topic on devto)

 

I was just warning you because I used to be that noob and it sure was embarrassing to not have foreseen the dependency problem. You will have to experience it for yourself.

I feel like

triggered :)

See that was a more effective argument/starting point than just calling it a noob mistake. Experience, be it my own or someone else's, is a good place to learn.

What did the dependency issue end up being? Right now my cards arent physically linked to the source control, so I am manually using the numbers as a sort of reference point. (We use Microsoft Planner for our cards and VS for source control)

 

I have yet to see a development organization that would be willing to copy the full context of the ticket/card into a commit message. I'm sure they exist, but based on my own experience I'd think they are a minority. So linking the card/ticket absolutely provides greater context into what the change was trying to achieve, even if the commit itself is nicely squashed and written up.

And yes, if you switch ticket systems you will likely lose the ability to automatically link to those cards. Having done this several times, I've found that it is generally possible to import into the system with the same id/number as the original system. You lose the automatic linking, since each system seems to have a different pattern it expects the number in, but when you see #12345 in a ticket you can still pop open your ticket system and find [12345] or XYZ-12345. The key is whether your org sees the value and finds it worth the extra investment during the migration from ticket system A to B.

In my career, I've seen several source control migrations where we had to make the same call. Is it worth migrating so we keep the original commit messages or should we just start clean with a single "All the changes up to now" commit?

 

Whenever possible go for the migration. I work on a product with a 15-years-history and sometimes it helps to know that a feature/"behaviour" was introduced 10 years ago ("it has always been like this") rather than 15 months ago. Good commit messages are really helpful, of course.

 

copy the full context of the ticket/card into a commit message

You probably misunderstood me. I just want to deter messages like "feat: close #235".

Is it worth migrating so we keep the original commit messages or should we just start clean with a single "All the changes up to now" commit?

If you really care you will have to rewrite the history.

 

An issue tracker is an essential tool in development. You should be able to rely on its existence for as long as the history of the source code is relevant. Eventually tools are replaced, but so are commits relegated to history by then.

 

Sadly it happens. My last org went through a few kinds of issue trackers. Some of which had licences and would cost money to keep around, so they were ditched. Adding a reference can be super useful, but I feel the commit should speak for itself.

Anyways we ended up using gitlab's issue tracking features, which are quite nice as well.

 

…but so are commits relegated to history by then.

It seems that you are not using log and blame as much as I do.

 

I find the opposite better. Closing the cards with the commit or merge SHA:
Fixed in c678ads...etc.

 

I would agree if I wasn't lazy and relied on the auto closing feature of the issue trackers that are properly linked to the repository.

 

Pretty sure the post went on to say that your message should be descriptive by itself too. So it doesn’t sound like they were suggesting we “rely” on the issue tracker, just utilize it.

code of conduct - report abuse