Photo by Olu Eletu on Unsplash.
I feel extremely lucky to have been instructed in the basics of Git-etiquette from essentially the first day in my journey to become a software engineer (Thank you, Krailo!). A seemingly minor concept, was one of the first things taught to me as a budding developer, and accordingly I placed upon it the importance that was conveyed to me in that education.
Surprisingly, it seems to me that there are many developers who appear to be unfamiliar with the dos and don’ts of possibly the most ubiquitous tool in software development, Git. Since many programmers learn Git on-the-job, they are likely not coached in best practices for something considered more of a soft-skill, and it’s doubtful that anyone chooses to use poor git-etiquette. Nonetheless, the problem is still rampant amongst developers of all skill-levels.
Don’t worry though, the solution will not require hours of reading and completely changing your workflow. In fact, it’s a fairly easy problem to solve, and it just requires that you follow some easy to remember guidelines.
So let’s get started with a few of the basics. Knowledge and implementation of these concepts will help you make the first steps from greeny-junior to Git-guru.
Use the CLI and an editor…
..and stop using git commit -m “Useless message here"
Trying to fit a well-formed commit message into a single command doesn’t work.
A commit message is supposed to take a minute.
You should have to stop and reason about the work you just did in order to explain it to others who may work on the project as well as you future self should you need to revisit these changes.
Writing a well-thought-out message is your way of writing into “history” the changes you have made and explaining what you changed, and why.
When you take the time to compose your messages in a text-editor window(as opposed to on the command line) it will cause you to slow down and make sure your changes are complete and worth sharing, as well as allow you to be more descriptive in your explanation of why the changes were necessary.
When you use the editor to compose messages, it can help catch errors in your code much sooner.
For example, I use the Oh-My-Zsh git aliases in my work flow. The command gc expands into git commit --verbose which will open your default editor with a summary of your current changes in the form of comments. What’s staged, what isn’t, untracked files, and a diff of the changes you are currently committing, allowing you to review the changes as you are writing your commit message.
Tip: Reading through the diffs before you write your message can save you from committing ‘debugger’ code and/or help spot a typo/spelling error that normally wouldn’t get caught until code review.
Follow proper commit message format
The Title-line
When composing a title-line, I try and follow 3 rules:
- The title-line starts with a capital letter, is 50 characters(or less), and has no punctuation at the end.
- It should be in the imperative voice. i.e. ‘Add new About Us page’ or ‘Refactor tests for the order model’
-
It should correctly complete the sentence,
“If accepted, this commit will <your commit message goes here>.”
A super-basic commit message using proper grammar and structure. (`git commit — verbose` usingNeovim)
The Body
A brief summary of the changes. If the changes were simple enough they can be understood with just a “Title” line then you may opt out of this section(the above picture is a good example of changes that don’t need a detailed explanation).
The body should explain the “what” and the “why” for your changes, not the “how.” Anyone who reads the code should be able to discern how you implemented your change. Use the body section to cover the parts that might not be so obvious.
An example of pretty thorough commit messages with explanatory body sections
Tip: If you are using a ticket management system(Trello, Jira, etc.), INCLUDE THE LINK TO THE CARD/ISSUE. It’s a nice reference to have for anyone reviewing your PRs who may be unfamiliar with the issue or for other developers working on the same project.
Be atomic and keep changes together in related commits
Group like changes together in the same commit
Not even close to logical grouping
Don’t throw some config changes and new CSS in the same commit. Break things apart in a logical manner.(Remember, even if you do more than one chunk of changes at a time, you can still commit them in a sensible manner, grouped by like-changes)
The same changes from the previous image, but broken out into more “atomic” commits.
Your commits show the progression of your code. Make it a story that is easy to follow. Even if it doesn’t seem important right now, being able to follow the history of your code can help you locate the source of regressions through logical deduction(that JS error in the console likely isn’t from the commit where you updated CSS and changed some icons in the footer).
The Git log from a feature I recently worked on.
This by no means is all you need to know to use git masterfully, but it is a solid foundation from which to build. Knowledge of your tools and how best to use them is just one facet of becoming a high-quality developer. Attention to these “small” things will help you become more productive, and make working with you much more enjoyable. Even if the only person reaping those benefits is ten-weeks-from-now-You.
Yes, something as small as the form of your commit messages may seem unimportant or tedious, but attention to the small things and fostering good habits is key to success.
“We are what we repeatedly do; Excellence, then, is not an act but a habit.” — Aristotle
For further reading, check out:
This blog post by Tim Pope which, along with this blog post by Chris Beams, are the sources for most of the material in this article.
Caleb Thompson’s article for Thoughtbot is a definite must read.
The book “Pro Git” by Chacon & Straub. === GitBible
This set of tutorials by Atlassian is frequently my go-to reference for some of the more advanced git-topics(**really solid examples and explanations**).