Git is currently the most popular version control of the software industry. Created by Linus Torvalds, the mind behind Linux kernel, himself back in 2005, It is now one of a must-have tool in your software development arsenal.
One of the things I like the most about Git is the commit system. It makes revising older changes and patching them super convenient because of the context it provides. However, it is also one of the most abused features of Git.
Take a look at this example:
It was undeniably a mess.
This is what happens to a lot of projects including ones I used work on. What people usually do are one (if not several) of the followings:
Lazy commits
Such as bug fix, new feature, GUI doneand etc. This type of commit destroys the purpose of the commit message which should provide context to the changes.
End of the Day Commits
Many people I’ve worked with use Git this way. They push everything they’ve work on during the day as one commit before heading home. This creates a huge commit with multiple changes which makes it harder to revise if it introduces a bug into the system.
Multitasking Commits
What I mean by multitasking is that the commit does multiple things e.g. fix class A for feature A and add method B to update feature B.
These types of commit remove context from themselves and make it hard and sometimes even impossible to trace what has happened. The maintainer has to go through the `diff` which could take up to several hours if not days.
Software development is collaborative work.
Even if you’re working solo. You still need to collaborate with yourself months ago. Your current self wouldn’t have the exact idea of what you were doing. Bad log wastes time when others (including future you!) need to look for some changes!
“Re-establishing the context of a piece of code is wasteful. We can’t avoid it completely, so our efforts should go to reducing it[as much] as possible. Commit messages can do exactly that and as a result, a commit message shows whether a developer is a good collaborator.”
There are hundreds of guidelines already on the internet that helps you write a better commit message. Here are some tips and an example template I’ve been using.
1. Use `git commit` without the `-m` flag
This will let you write your commit in your favourite text editor which makes it a lot easier to write longer commit message.
2. Why what and how
Think before you make a short one-lined commit message. Most of the time it’s not a good idea. The commit should address these three aspects of the patch. `Why is this commit here?` `What it does to the system? Are there any side effect?` and `How it’s done`
Here is a template I’ve been using taken from Tim Pope personal blog which confers you how to write a good commit message.
Capitalized, short (50 chars or less) summary
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body. The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.
Write your commit message in the imperative: “Fix bug” and not “Fixed bug”
or “Fixes bug.” This convention matches up with commit messages generated
by commands like git merge and git revert.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, followed by a
single space, with blank lines in between, but conventions vary here
- Use a hanging indent
As I’ve stated earlier, software development is a collaborative work. By carefully crafting your commit message, you are also increasing the productivity and quality of your software.
