DEV Community

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...
Collapse
 
chilcutt profile image
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!

Collapse
 
cookrdan profile image
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.

Collapse
 
chriskarpyszyn profile image
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!

Collapse
 
cookrdan profile image
Dan

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

Collapse
 
rachelsoderberg profile image
Rachel Soderberg

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

Collapse
 
chriskarpyszyn profile image
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.

Collapse
 
brunorodrigues profile image
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/

Collapse
 
dhintz89 profile image
Daniel Hintz

Love the analogy, I think of it the same way šŸ˜€

Collapse
 
rachelsoderberg profile image
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.

Collapse
 
chriskarpyszyn profile image
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

Collapse
 
sdhutchins profile image
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.

Collapse
 
viccw profile image
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.

Collapse
 
rachelsoderberg profile image
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!

Collapse
 
viccw profile image
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!

Thread Thread
 
rachelsoderberg profile image
Rachel Soderberg

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

Collapse
 
felipe1982 profile image
Felipe Alvarez • Edited

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

Readme: add install instructions

Collapse
 
_rice_salad profile image
Rhys S

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

Collapse
 
jnareb profile image
Jakub Narębski

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

Collapse
 
colorcodedcode profile image
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.

Collapse
 
rachelsoderberg profile image
Rachel Soderberg

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

Collapse
 
tetiross profile image
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
Collapse
 
jessekphillips profile image
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.

Collapse
 
kendalmintcode profile image
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.

Collapse
 
erikpischel profile image
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.

Collapse
 
matthewbdaly profile image
Matthew Daly

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

Collapse
 
rachelsoderberg profile image
Rachel Soderberg

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

Collapse
 
dbanty profile image
Dylan Anthony

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.

Collapse
 
emptyother profile image
emptyother

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.

Collapse
 
rachelsoderberg profile image
Rachel Soderberg

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