Looking at how developers work with git at my current employer, it surprised me how bad they actually work. Yes I have a very strong opinion about that, and I believe good engineering shows at each level, starting on how you make changes and communicate them. For this reason we recently release a guideline on how all developers shall commit their work in git.

Why does it matter

A proper Git commit message is the best way to communicate context about a change to other developers - or even for yourself if you look at your changes in one week or so. Whole a diff will tell you what changed, only the commit message can properly tell you why. Peter Hutterer makes this point well:

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.

In addition tools like git blame, revert, shortlog, … will become much more useful when reviweing other commits and pull requests and help you to understand why something has changed. Or in other words

A project’s long-term success rests (among other things) on its maintainability, and a maintainer has few tools more powerful than his project’s log. It’s worth taking the time to learn how to care for one properly. What may be a hassle at first soon becomes habit, and eventually a source of pride and productivity for all involved.

How to write good commit messages

How to Write a Git Commit Message (cbea.ms) is an amazing post which goes into details - please check it out. In summary some important things to consider - especially also as they go along well with the tools git blame, revert, shortlog, …

1. Separate subject from body with a blank line

   Though not required, it’s a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description.

2. Limit the subject line to 50 characters

   Keeping subject lines at this length ensures that they are readable, and forces the author to think for a moment about the most concise way to explain what’s going on. If you’re having a hard time summarizing, you might be committing too many changes at once. Strive for atomic commits (a topic for a separate post).

3. Capitalize the subject line

4. Do not end the subject line with a period

   Trailing punctuation is unnecessary in subject lines. Besides, space is precious when you’re trying to keep them to 50 chars or less.

5. Use the imperative mood in the subject line

   A properly formed Git commit subject line should always be able to complete the following sentence…

6. Wrap the body at 72 characters

   Git never wraps text automatically. When you write the body of a commit message, you must mind its right margin, and wrap text manually.

7. Use the body to explain what and why vs. how

   In most cases, you can leave out details about how a change has been made. Code is generally self-explanatory in this regard (and if the code is so complex that it needs to be explained in prose, that’s what source comments are for). Hwever, it may be important to add some details on what was changed and why. This doesn’t need to be a code review/walk through but it should be informative to someone reading the log and looking over the diff in 6 months. The focus should be on “why” since the target audience reading the logs can usually figure out “what” from looking the diffs.

Conventional Commits

I am a huge fan of Conventional Commits as it is a simple standardized way of writing commit messages while enabling the change for automation (e.g. automatically create release notes). I use them consistently on my project like Terraform modules or Ansible Roles.

Content of commits

Besides of the format - which helps communicate - you should also consider the following

1. Each commit should be a separate patch/fix/addition/etc.

Don’t bundle multiple unrelated bug fixes into a single commit with a vague message like “Fixed some bugs.” Instead, fix one bug, test it, commit it — then repeat. This makes life much easier when your peers need to cherry-pick or pull only the relevant fixes into a specific branch. Or even git revert becomes to be much more practically

1. Group commits together that are part of the same fix.

While working you can have multiple commits, but for the final PR you should cleanup the commits and squash commits which are part of the same fix together. This means you group them together to fewer commits so they can be easily be back ported to an older release (see point above).

Maybe have a look at Another Way to Git: Bundle Commits into Logical Groups

The approach eschews the common tendency to commit often, documenting a work in progress, and instead bundles commits of the same feature branch into logical categories, only after work on the feature is largely finished.

1. Reference a work item

Mostly you do implement changes based on issues or feature requests. These items are usually tracked somewhere (e.g. Gitlab Issues, JIRA, …). Reference them in your commit messages as well, so you have a nice traceability almost for free.

Keep pull request size manageable

While we speak about commits, we also have to speak about pull requests, as they go hand-in-hand. Following Best practices for managing pull request size you should keep the size of your pull request manageable. This means

• Aim to keep pull requests under 200 lines: Research suggests that pull requests under 200 lines of code get merged much faster, with the ideal length being around 50 lines.
• Focus on a single feature or bug fix: A PR should only address one task at a time. Merging multiple changes into a single PR complicates the review process, so it’s important to break down large tasks into smaller, self-contained units that can be reviewed independently.
• Consider the number of files affected: Along with the number of lines, the number of files changed should remain limited. If too many files are touched, the review becomes harder to follow.

Follow Commit Best Practices above: use conventional commits and write proper commit messages with subject, body and Jira reference

References

The ideas are taken from here:

• How to Write a Git Commit Message (cbea.ms)
• NetBSD Commit Guidelines
• Another Way to Git: Bundle Commits into Logical Groups - The New Stack