I think you’ve all had this experience:

You are developing a project that uses Git for version control.

You have just made changes and want to update branches quickly.

So you open the terminal and update the remote branch with the changes with some quick commands.

git add .
git commit -m "added new feature"
git pushCopy the code

But then you do some testing and find bugs in your code.

Don’t worry, you can quickly find a solution and submit it again to fix the problem.

git add .
git commit -m "fix bug"
git pushCopy the code

You repeat this process several times and now end up with a Git commit log like this:

For now, this seems fine to you; after all, you’re currently working on that part of the code, and even if the submitted information doesn’t convey your intent to change, you can still easily explain what was done.

The problem

A few months have passed, and now another developer is reviewing your changes.

They try to understand the details of the changes you are making, but because the messages you submit are not descriptive, they can’t get any information.

They then tried to see the differences in each submission. But even when they do, they still can’t determine the thought process behind your choice in implementation.

So they can use Git Blame to find out who made the changes and start asking you questions about the implementation.

However, you won’t remember much since so much time has passed. You check by submission, and you no longer remember the logic behind the decision to execute on the project.

You end up sending your colleagues the sad emoji 😔 on wechat and telling them that you can’t provide more information than they already know.

Well written submission information

Hopefully, this has given you an idea of why writing good Git commit messages is important.

In team development, we must make it easy for other collaborators to understand what we are doing.

Ideally, a good commit message will be divided into three parts: subject, body, and ending.

The theme

The topic should be a concise one-line summary of the changes you committed.

Here’s an example of a good submission, such as the “feature: Query project utilization rate feature.”

A wrong commit message, such as “fix bug,” can be confusing to others when they see it.

The body of the

The body contains your message, where you can learn more about the changes. Note that for some small submissions, such as typos, you may not need the body, as the subject line should be informative enough.

In the body, you should delve into the changes being made and explain the context of what you are doing.

You can explain why you made these changes, why you chose to implement them in this particular way, and any other reasons that might help people understand the thought process behind your submission.

Try not to repeat the obvious things in comparing code, don’t explain your changes line by line, and focus on covering more advanced details that might not be obvious from reading the code. The ultimate goal is to provide context for the development process around this change, which is primarily about its reasons and goals.

At the end

You can write useful metadata about submitting in the last line, such as JIRA ticket number, author name, and additional links.

This helps link together important information related to your changes.

conclusion

What are you waiting for? Waiting to get beat up by a co-worker? Start following best practices for Git commit messages!