How to commit like a pro?
Please, don't embarrass yourself the next time you commit to an open source repo or at work.
In this week’s issue of Programming in Public, I would like to share tips and suggestions to improve or reflect on your and others’ Git experience. In Pakistan, many college students don’t even know about Git or GitHub which is not acceptable in any case. I am not blaming them for not knowing something that is the bread and butter of a software engineer but stating a fact that shouldn’t go unnoticed.
Commit messages are probably the most important features of version control and Git. It serves as evidence of change in the software development lifecycle of a project. It doesn’t matter if it is personal or corporate, what matters is that it shows that a piece of code went through an evolution of sorts to reach the final result. It can’t be emphasized enough.
By writing better commit messages, you are simply future-proofing yourself. The extra time it takes to write a thoughtful commit message as a letter to your potential future self is extremely worthwhile.
Now that we have established an important fact, let’s move on to discussing what will a great commit looks like.
5 steps to write better commit messages
I am sharing a set of steps that you may want to use in case of a personal project or there are no official guidelines for your project.
Command
git commit -m <message>
Example
git commit -m “Add padding to columns to prevent them from overlapping on each other“
Capitalization and punctuation: Only capitalize the first word and do not end in punctuation. Remember to use all lowercase after the first word.
Mood: Use imperative and explicit mood in the description.
Type of commit: Specify the action that you took while making changes in the code. For example, if you Add, Update, Fix, Refactor, and so on in the code.
Length: Make sure the message is long enough to convey a complete message. Ideally, 50 to 72 characters long.
Commit like a pro with Conventional Commits
Now let’s talk about the real shit.
Conventional Commits is a specification for adding human and machine readable meaning to commit messages. According to the convention the commit message should be structured as follows:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
The commit contains the following structural elements, to communicate intent to the
The commit type can be the following:
feat
– a new feature is introduced with the changesfix
– a bug fix has occurredchore
– changes that do not relate to a fix or feature and don't modify src or test files (for example updating dependencies)refactor
– refactored code that neither fixes a bug nor adds a featuredocs
– updates to documentation such as a the README or other markdown filesstyle
– changes that do not affect the meaning of the code, likely related to code formatting such as white-space, missing semi-colons, and so on.test
– including new or correcting previous testsperf
– performance improvementsci
– continuous integration relatedbuild
– changes that affect the build system or external dependenciesrevert
– reverts a previous commit
The commit type subject line should be all lowercase with a character limit to encourage succinct descriptions.
The optional commit body should be used to provide further detail that cannot fit within the character limitations of the subject line description.
It is also a good location to utilize BREAKING CHANGE: <description>
to note the reason for a breaking change within the commit.
The footer is also optional. It can be anything
You can read the full specifications here.
Commit Message Comparisons
Review the following messages and see how many of the suggested guidelines they check off in each category.
Good
feat: improve performance with lazy load implementation for images
chore: update npm dependency to latest version
Fix bug preventing users from submitting the subscribe form
Update incorrect client phone number within footer body per client request
Bad
fixed bug on landing page
Changed style
oops
I think I fixed it this time?
empty commit messages
You can also use git hooks such as pre-commit to ensure that people working on the same project adhere to a commit convention such as given above or your own.
I hope you can write better commit messages after reading this week’s issue of Programming in Public.