Share It:
Senior Software Engineer, RTB
May
26
2016
Engineering

How to Write Well-Formed Git Commit Messages

TubeMogul’s Engineering team uses a number of tools to help us collaborate and track progress more effectively, including Git, the popular version control system. Git’s commit messages are an integral part of establishing context for code changes, and maintaining an effective workflow. Read on for some best practices for creating effective Git commit messages.

What is a commit message and why is it important?

A commit message is a text description that developers write before submitting code changes to a version control system. Git, the popular version control system that TubeMogul uses, requires any commit to have a message to accept it. These messages provide an easy way for a developer to gather information about a code change without reading the code. Commit messages can also act as context before reading the code. However, if the commit message is not well formed and meaningful, it doesn’t serve much purpose. Well formed commit messages provide useful information for code reviewers, merge masters, quality engineers, future developers, and even executives as part of the release notes.

It’s not hard (at all) to submit code with well-formed commit messages, and the time and effort committed will pay off many times over when it comes to knowledge sharing with others (or when you have to revisit some old code a month later and try to figure out “what the heck was I doing here!?”).

What makes a commit message well formed?

There are handful of things that help make a commit message well-formed. First, Git commit message are composed of 2 parts – header and body. At TubeMogul we use JIRA for issue tracking, so we use the header line of a commit message to tell us which JIRA ticket we are committing against, as well as a very short description of the change to commit.

The Header

Here is a sample header (or summary) line:
The above commit header begins with JIRA ticket number and concludes with a descriptive statement. The JIRA ticket number is usually 10-12 characters long, 2 characters for the “:” and a space, and the header message here is 38 characters long. That makes it a 50 character long summary of the commit. A Git commit header should ideally be 50 to 72 characters long in a single line, and if you are using JIRA or another issue tracker, it should resemble your ticket subject. Ticket subjects can often be pretty long, so you might have to edit them down a bit. On the other hand, if your header is too short, you may not be communicating effectively through it.

If you use the command git log –oneline or git shortlog in your module, you will see the header lines from Git log history, giving a quick overview of the module in chronological order as small changes introduced over time. This is why the header should be precise but meaningful. For example, “Fix bug that…”, “Add file/feature…” or “Increase code coverage for…”, etc.

After you write the header, add a full blank line as a gap before starting the body of the commit message. This works as a visual separator between the two majors parts of a commit message.

The Body

Next, a detailed message about the commit serves as the body of the message. The body of a Git commit message can be as long as you want, but we generally discourage people from authoring novels for commit messages. TubeMogul’s commits wrap every line after 72 characters as a best practice for consistency and to follow standard industry practice.

Good commit message bodies should provide answers to the following 3 questions:
  1. Why is it necessary? It may fix a bug, add a feature, improve performance, reliability, or stability.
  2. How does it address the issue? This should be a high-level description of what the approach was.
  3. What side effect could the commit have? This may include benchmarks, side effects, or features that need focus during testing.

Finally, provide links to any external documents, if needed, as part of the message.
The example above shows a complete commit message that meets the definition of a well-formed commit. Consider a commit message as a page in Git log history book, so make it reader-friendly for future generations of developers.

Best practices when creating commit messages.

  1. Commit frequently during development, then clean up to make a push. If it’s difficult to summarize what your commit does because it includes several logical changes or bug fixes, consider splitting into several commits. Each commit should represent a single change.
  2. Avoid lazy commit messages. Funny (“Fixes all our problems”) or meaningless (“asdf asdf”) commit messages were once common occurrences at TubeMogul. Take 2 minutes to provide good information with your commit message, and you may save yourself a headache later.
  3. Keep the audience in mind when writing commit messages. Your commit message will speed up the code review process, help make good release notes, give quality engineers ideas about edge cases to test, and help onboard new developers faster. Don’t describe the code; describe the intent and the approach to the change.


TL;DR. When creating your commit messages, avoid making these common excuses:
  • I’m in a hurry. Yes, but it will make referencing the change in the future much easier.
  • But it works! It may work now, but code is always changing.
  • I am the only one working on it. Not true, any software project is a collaborative project.
  • Do people look at Git log history? Yes. You may not, but others will.
Senior Software Engineer, RTB
May 26, 2016

Interested in joining our team?

Share It:
Sorry, this page is currently only available in English. Lo sentimos. Esta página solo está disponible en inglés por el momento. Désolé, cette page n’est disponible qu’en anglais pour le moment. Desculpe, esta página está disponível apenas em inglês no momento. このページは現在、英語でのみ提供されています。 抱歉,本页面目前仅提供英文版。