Collaborative coding with Git has led to Commit Logs From Last Night, a website showcasing humorous commit messages on GitHub repos. Writing good commit messages is important for documentation and clarity, with a header, body, and signoff recommended by Git creator Linus Torvalds. Formatting and clarity are also key for effective communication and high-quality code.
With this article, learn the importance of writing good commit messages in Git, including the key elements of a good commit message and how it can benefit both your colleagues and future self.
Here are our 5 Key Takeaways:
- A good commit message includes a header, body, and signoff, with the header serving as a one-line summary of the commit.
- The commit message body should provide more detailed information about the changes made and why they were made.
- Writing good commit messages can benefit both your colleagues and future self by providing documentation and context for changes made.
- Formatting is important, with Linus Torvalds recommending keeping word wrap to 74 characters or so.
- Taking the time to write good commit messages can lead to higher quality code and a better understanding of the why and how behind changes made.
One delightful unintended consequence of the shift towards collaborative coding with Git is Commit Logs From Last Night. As the domain name suggests, this website shows a running list of humorous commit messages on actual GitHub repos. You can watch an endless stream of developers writing funny commit messages and laugh as you empathize with their pain.
It’s not the salty language that makes it funny, but rather the sense of palpable frustration you can see as developers code. Though we often expect our code to flow forth straight from our brains to the terminal, the reality is usually more muddied. You code by trial and error and we’ve all been there in caffeine-addled disgust at 2am wondering why this simple change won’t work as expected. We’re basically stumbling our way through print statements and console logs to glory.
Of course, Salesforce commit messages are important. But most people are not trained on how to write them. We learn by following what others are doing. And unfortunately a lot of us are just hacking our way to a solution and writing short, shallow commit messages like the ones above.
Git creator Linus Torvalds actually dropped by GitHub in 2011 to explain in a commit what he felt a good commit message ought to look like:
+ header line: explaining the commit in one line
+
+ Body of commit message is a few lines of text, explaining things
+ in more detail, possibly giving some background about the issue
+ being fixed, etc etc.
+
+ The body of the commit message can be several
+ paragraphs, and please do proper word-wrap and keep
+ columns shorter than about
+ 74 characters or so. That way "git log" will show things
+ nicely even when it's indented.
+
+ Reported-by: whoever-reported-it
+ Signed-off-by: Your Name <youremail@yourhost.com>
There are 3 key elements to a good commit message.
The header is where most people start (and stop) with a commit message. The header is a one line high-level summary of what the commit includes. It’s like the subject line of an email.
Though there is no hard rule, many blogs like tbaggery suggest 50 characters as a good headline length. You should always follow the headline with a blank line so that it can be identified as the subject. Tim Pope enumerates some of the commands you can use when you format correctly:
According to Tim Pope:
The subject/body distinction may seem unimportant but it’s one of many subtle factors that makes Git history so much more pleasant to work with than Subversion.
Most people never get past the headline. When I was learning to code and use Git, I never included more than a one line summary. Because I so rarely saw long, detailed commit messages I assumed there was some sort of hard limit on the number of characters you can have in a commit message. But this is not so! Linus himself suggest that we offer longer descriptions with our commits so that people can follow in more detail with what the commit includes.
For many software projects, commit messages are the only documentation. So it makes sense to take the time to write more detailed commit messages. When your colleagues want to know why something was implemented the way it was, they can look to the Git history to understand better how an Apex Class or VisualForce Page evolved over time. They can see when and why you added a particular method and what it’s function was.
It doesn’t just help your colleagues. A good commit message that you wrote can sometimes be a lifesaver. It’s as if a future version of yourself came back and said to you, “Hey, you’re going to need to know why this method was added someday and here is the reason.”
Finally, Linus recommends a “reported by” and “signed off by” signoff at the end of the message. This is less important than the header and commit message body, but can still be useful when sorting through thousands of commit messages.
Linus suggests keeping word wrap to 74 characters or so. Most terminals are 80 columns and using 74 characters or so keeps you commit message nicely indented when you type git log. Whatever text editor you use should allow you to set how many characters you want in your commit messages.
More and more Salesforce teams are moving to Git for their source control.
Writing good commit messages doesn’t just help your colleagues and future self. Taking the time to write them gives your brain the time and space to think about the why and how of your code. This makes it easier to ensure that your commits are of high quality and that there is a good reason behind every change. Pausing every so often to get this kind of information is invaluable.
.png)