Writing good commit messages is an under-valued skill. Why does it seem to count; shouldn't only technical skills count?

Well, possessing it as a developer helps in the following ways:

• It adds clarity to pull requests (PRs) raised
• It is key to effective debugging within a team.
• Makes tracking an implementation easier

NB: If you're yet to understand what Git is, read my article on Working with Git before revisiting this.

What is a Git commit?

This is a way to tell Git about the staged changes you made to the repository using the commit command. It takes a snapshot of what your project looks like once you commit, and stores a unique reference (40 character length) to it using a Secure Hashing Algorithm (SHA).

To add these changes, you need to specify a commit message to be attached to this change and a specific flag to use. Write the commit message as if it's about to be applied, rather than about what you just did.

Let's elaborate why you should care about writing good commit messages.

Adds clarity to PRs raised

If someone needs to read through your PR before getting a grasp of what it's meant to do, it means that you have a lot to do regarding writing good commit messages. Your commit message should be concise and state the context of the change. The message is truncated once it reaches the specified character limit.

Reference the ticket number or tracking ID within the commit message to add more context.

# Bad
git commit -m "Fix bug"

# Good
git commit -m "Add auto login for verified users - Closes BLG-20"

State why you're making the changes within the body (if necessary) as the diff already shows what is being changed. Focus on the way it worked before the change (and what was wrong with that), the way it works now, and why you decided to solve it the way you did. Explain the side effects of the change if any.

A new developer joining the team should be able to read the commit message and tell what the PR does. If it is difficult to understand, you may be adding too many changes, strive for atomic commits.

Key to Effective Debugging

For the commit message to help in debugging effectively, ensure that it is short and use an imperative mood (spoken or written as if giving a command or instruction) when constructing them.

The first word in your commit message should be one of these:

• Add
• Create
• Refactor
• Fix
• Release
• Document
• Modify
• Update
• Remove
• Delete etc...

# Bad
git commit -m "implemented automatic login for new verified signups because
currently new users have to manually log in after signing up."

# Good
git commit -m "Implement automatic login for new verified signups"

Take a look at the two commit messages to notice the difference. The first word of the message labelled good is written in an imperative mood, succint and starts with a capital letter. It communicates using an active voice.

When you substitute the message within the Git commit template, it becomes:

To view revision history when debugging, run the command.

git log

The output:

commit a6e7ab9ce174821a0c934df9e61450a230a855e0
Author: Chiamaka Ikeanyi <hello@chiamakaikeanyi.dev>
Date:   Thu Apr 02 04:00:00 2020 +0000

    Add article on commit messages - Closes BLG-27

This shows a detailed log of a specific commit.

To get a more streamlined output, provide more arguments to the log command.

git log --oneline -5 --author chiamaka --before "Thu Apr 02 2020"

This shows the subject of commits made by the specified author before the specified date.

Makes tracking an implementation easier

Within a project, you can ascertain if a developer is a good team player or not by running git log. Logs that are well cared for are useful and helps you to understand why something happened in the past.

Model of a good Git commit message:

• Capitalized, short (50 characters 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 generatedby 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

• If you use an issue tracker, add a reference(s) to them at the bottom, e.g. Resolve #123; See also: #456, #789

7 rules of a great Git commit message

1. Separate subject from body with a blank line
2. Limit the subject line to 50 characters
3. Capitalize the subject line
4. Do not end the subject line with a period
5. Use the imperative mood when in the subject line
6. Wrap the body at 72 characters
7. Use the body to explain what and why the change was made. This part should be added only when necessary
8. Remove unnecessary punctuation marks

Commit Types

Different teams have different means of structuring commit messages. Some use commit types to add more context to PRs raised.

• feat: A new feature
• fix: A bug fix
• style: Additions or modifications related to styling only
• refactor: Code refactoring
• test: Additions or modifications to test cases
• docs: README, Architectural, or anything related to documentation
• chore: Regular code maintenance

A PR that has a commit type added can look like this:

git commit -m "Resolve feat/BLG-20: Implement auto login for new signups"

Conclusion

Debugging becomes a thorn in the flesh when commit messages do not help. Ensuring that you write good commit messages do not only show that you are empathetic, but also helps you during the debugging process.

I hope this will help you and your team to write great commit messages that follows Git's built-in convention. You can still update previous commits if you've just made a mistake.