Development

Get Legit with Git (and GitHub): The Art of the Commit Message

29 May 2018 8:58am, by

Welcome back, Git Pilgrims! So far in our series on Getting Legit with Git and GitHub, we have learned essential Git commands and the Git workflow. Then, how to work with GitHub.com to upload project code to a repository in our GH account. The third installment was how to manage and update projects via working with branches in Git and GitHub. I hope you have done your homework assignments. Yes? Good. Let’s keep going!

A very important Git concept that we worked within each of these previous tutorials is the Git commit. Recall that a commit is what happens in Git when you save a change to a project repository (or set of files), like making a snapshot of your project at that exact instant in time. It’s like how Google docs file every time you have changes, except instead of a “revert” history git creates a unique name (a.k.a. the “SHA” or “hash” ID) for each commit to record what changes were made, also when and by who.

Commits almost always include a commit message, which is where you write is a brief description of what changes were made.  The commit message is basically the most important part of the commit workflow because it’s the one and only place that records not only what was changed, but why. Unfortunately, many developers fail to pause for a moment to craft a good commit message to accompany and explain, all the hard work that went into their project between the last snapshot and the current one.  But doing just that — putting the effort into clearly and succinctly explaining to future you exactly what current you just did in this particular commit — is really, really important.

From xkcd. Used with permission.

Git and GitHub offer all kinds of different tools for opening up a project and viewing what exactly has been changed between commits — “git diff” for example. The beauty of a well-crafted commit message, however, is that it saves you from having to find, figure out and then use those tools because you’ve already written a short, smart summary of exactly this — in your commit message.

It can help to think of the log of commits as a newsfeed for your project. It’s akin to skim-reading headlines on Reddit to get a quick summary of what is going on in the world: those taglines don’t need to tell every detail of the story. Just enough to let you know what the story is about. Here is a very basic example in the form of the last commit from our Studious Octo “hello world” sample project from our previous tutorial on branches:

When working with a team of project collaborators, commit messages are clearly essential to let everybody know what everybody else is doing (and why). But: If you’re just working by yourself the whole commit message thing may seem beyond the point. Obviously, you were there, right? So just dialing in a generic commit message seems all that is needed.

But: what did you have for breakfast this morning? How about yesterday?  How about one year ago yesterday? See how it gets harder to remember details, the further time goes back? Writing a nice, informative commit message now helps future you to not want to punch you in the face when trying desperately to figure out precisely which point the bug got introduced into the codebase.

The Art of the Commit Message

So, then, how to write a good commit message?

First, it needs to be short. Commit messages are most often viewed in the context of a Git commit log, where there’s just not much real estate for displaying text.

The first line is the most important because that is what will appear in the actual commit. So invest the most thought and effort here.

That said, commit messages can — and should — be as long or as detailed as you want. They can even span multiple lines. Git doesn’t place any hard limit on what goes into a commit message, and in fact, if a given commit does call for additional context, you can add additional text to a message. Paragraphs, even.

Elements of (Commit Message) Style

The kind of maddening thing about Git commit messages is that, even though they’re really critical for good collaborative workflow and project documentation, there are actually no hard rules. Nobody ever sent down tablets from above engraved with RENDER THOU THY COMMIT MESSAGES THUSLY.

So, of course, in the place of a collectively accepted Commit Message Style Guide (where are Strunk & White when you need them most?) we have instead lots and lots of articles about guidelines and good practices, which — if you read only a few — will quickly confuse the absolute hell out of you because many of them directly contradict each other.

So the first rule of Commit Club is, do what makes sense and works for your project.

The second rule of Commit Club is that there are a few basic guidelines that a lot of developers do actually follow:

Use the imperative tense. This is the one element of commit message style that most GitHub contributors actually follow. Imperative means writing “Refactor form handler tests” rather than “refactored” or “refactoring.” There’s nothing wrong with “-ed” or “-ing” — they’re just slightly longer. Which is why this is the biggest common commit message commonality around: we all agree that less typing is better. If another style works better for you or your team, go for it—just try to go for it consistently.

Be brief. Be detailed. The main impetus for a new commit — summarizing what changed in this new “snapshot” — is the heart of the commit message. This reason for the change(s) should be succinctly explained in your first line. Think of this as your “subject” line for your commit, and try to keep it to a single line (about 70 characters).  Then the most important details — pretty much the why of the change — can follow as a separate paragraph.

Don’t be funny. A commit message is a story that summarizes a change: here is the thing I did and why I did it. As tempting as it may be to vent frustrations in your commit messages, whether at a bug, or at Git, or your team’s/your own stupid mistakes, don’t do it. When you’re about to write a frustration-fueled commit message along the lines of “$git commit –m I FUCKING HATE EVERYTHING” — and we aren’t saying this isn’t true, there are times where a person does indeed fucking hate everything — this is simply not helpful information. Anything that goes into a message should be of value to the people who will engage with your project. Blowing off steam is important, too. Just not in “$git commit.”

Be consistent. Your repo is just going to be cleaner, clearer and easier to use if all collaborators agree upon, and then follow, collective commit style rules. You don’t need an elaborate style guide; commit messages, after all, are more haiku than epic tome. Just have that quick conversation to establish some conventions, or throw together a quick list of commit do’s (don’ts are also useful) help things run more smoothly.

What happens if your commit message style isn’t consistent, or you just make shit up as you go? Really bad things?

 

JK! We are all just human. Lapses happen, and you can just do better on your next commit message. Establishing and following just a few style rules like these, though, makes writing commits easier and faster because you don’t have to think through how to say the “what did I do and why did I do it” information at the heart of each commit. It gets easier the more you do it, and eventually just becomes automatic. Aim to write the best commit messages you can, and your repositories will be all the better and more useful, for it.

And future-you won’t ever want to punch current-you in the face.

A newsletter digest of the week’s most important stories & analyses.

View / Add Comments

Please stay on topic and be respectful of others. Review our Terms of Use.