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.
FREE TOOL
Profiles & Permissions Deployer
Easily compare and deploy Profiles, Permission Sets, and Field-Level Security (FLS) between any two Salesforce organizations.
Get Started
Made with love by the Blue Canvas team ❤️
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.
XKCD pretty much sums it up :
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.
Writing Good Commit Messages 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
There are 3 key elements to a good commit message.
The Header 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:
git log –pretty=oneline git rebase –interactive provides the summary for each commit in the editor it invokes if the config option merge.summary is set, the summaries from all merged commits will make their way into the merge commit message git shortlog uses summary lines in the changelog-like output it produces git format-patch, git send-email, and related tools use it as the subject for emails reflogs, a local history accessible with git reflog intended to help you recover from stupid mistakes, get a copy of the summary gitk has a column for the summary GitHub uses the summary in various places in their user interface 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. Commit Message Body 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.”
Signoff 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.
Formatting 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.
Clarity 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.
Try bluecanvas now!
Start your 14-day trial!
Get Started
Made with love by the Blue Canvas team ❤️
