We can learn from history. History tells us which events in the past shaped the present. The Boston Tea Party lead to the Independence War. The Battle of Waterloo led to the defeat of Napoleon. Can you tell which decision, and which commit lead to the current state of your software? Maybe not.

Because many commit messages are confusing, messy, and useless.

I bet you have seen (or written) commit messages like these:

wipwork on feature XYZfixed typoFixed JIRA-123

Those messages don’t help if you need to trace a problem or discover why implementation is the way it is.

We must answer two questions to improve our commit history:

1. What makes a good commit message?
2. How do I get my colleagues (and myself) to follow this format?

What makes a good commit message?

There is no definite answer. Commit messages should contain enough information to see what changed and why. Should it be a complete sentence or will bullet points suffice? Do you need the ticket number in each commit message?

The best answer I can give is:

Talk to your colleagues and agree on the scope of the commit message.

You do not have to enter that discussion unprepared. There are proposals regarding the structure of commit messages. We will look at one of them: Conventional Commits.

Think of Conventional Commits as a framework for commit messages. It gives you a structure to use. Each commit message contains at least a type and the message itself. Scope, body, and footer are optional. There is also a simple way to show that a commit contains a breaking change.

The basic structure looks like this:

<type>[optional !][optional scope]: <description>

[optional body]

[optional footer(s)]

Here are some examples:

feat: allow user to keep logged infix: messages are now serialized correctlyfeat(api)!: removed the old way users are handledci(deployment): the application will now be deployed on nonlive as well

The first improvement is visible immediately.

You can skim the commits since each now has a type. If you search for a bug fix, just look at all commits with fix. The optional scope helps you to narrow down your search.

An exclamation mark shows breaking changes. This can also be more explicit in the footer of the commit message, like:

chore: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

You can generate semantic version numbers automatically using the types. A fix increases the patch level, while a feat increases the minor level. Each breaking change increases the major level.

Conventional commits will improve your commit messages.

However, the spirit is willing, but the flesh is weak. Your colleagues and you might use it, but you might forget it quickly. You still end up with messy commit messages. The simple solution: let git force you to use Conventional Commits.

Use git hooks to enforce Conventional Commits

You can change the behavior of git with git hooks. There are server-side and client-side hooks. We will concentrate on client-side hooks since most of us do not host our own git. A git hook is a shell script that is executed at an event in git’s workflow.

One hook is of special interest: the commit-msg hook. Git executes it after you entered the commit message. It gets the path to a temporary file with your commit message as a parameter. You can check if the commit message follows your rules.

For example, this hook checks if the commit message is at least ten characters long:

To use the hook, create a new directory at the root of your repository, for example .githooks and add a new file there, commit-msg . The name is crucial for git to understand which hook it is. Do not forget to make the file executable!

chmod +x .githooks/commit-msg

Now tell git to look for hooks in the created folder. Each of your coworkers has to do it once.

git config core.hooksPath .githooks

Git will reject short commit messages from now on.

> git commit -am "abc"
[Commit message] abc
The commit message is to short!

And it works in IntelliJ as well:

Bringing it all together

You can now use git hooks to enforce Conventional Commits. I even expanded it so that after the type, each message must include the ticket number or NO-JIRA if no ticket exists. This is my hook:

Final Word

The commit messages for your repositories got more readable. It is a quick win, trust me. But the most important thing is that everybody must agree on the idea. People will always avoid stuff they dislike. So talk to your coworkers first.

Do not follow this faithfully. Take what works for you and implement it. Try it!

Sources

Want to Connect?Subscribe to my newsletter so you never miss a new post:https://verbosemode.dev/subscribe