Skip to content

Commit Messages

Writing good commit and merge request (MR) messages can sometimes look hard. Having them available at a time when you have to track down the motivation of a developer making a certain change is priceless and irreplaceable.

We urge you to read the blogs of C. Beams: "How to Write a Git Commit Message" and T. Pope: "A Note About Git Commit Messages" on how to get it right.

Based on their works messages on Titan (sub)projects should look like this.

Guideline for commit and MR messages

  1. Tracker ID (PROJECT-XXX) at start of subject line
  2. Limit the subject line to about 50 characters but max at 72 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Separate subject from body with a blank line
  7. Wrap the body at 72 characters
  8. Use the body to explain what and why not the how
  9. The body is only optional if the subject line does say it all

Example

PROJECT-8 Add match rule for CTP speed related loglines

Optionally more detailed explanatory text, if necessary. Wrap it to about 72
characters or so.

Explain the problem that this commit is solving. Focus on why you are making
this change as opposed to how (the code explains that). Are there side effects
or other unintuitive consequences of this change? Here's the place to explain
them.

Further paragraphs come after blank lines.

- Bullet points are okay, too

- Typically a hyphen or asterisk is used for the bullet, preceded
  by a single space, with blank lines in between

Explanations for some of the items above

Use the imperative mood in the subject line

Imperative mood just means "spoken or written as if giving a command or instruction". A few examples:

  • Clean your room
  • Close the door
  • Take out the trash

The imperative can sound a little rude; that's why we don't often use it. But it's perfect for Git commit subject lines. This is also the reason for Git itself useing the imperative whenever it creates a commit on your behalf.

For example, the default message created when using git merge reads:

Merge branch 'myfeature' into develop

So when you write your commit messages in the imperative, you're following Git's own built-in conventions. For example:

  • Refactor subsystem X for readability
  • Update getting started documentation
  • Remove deprecated methods
  • Release version 1.0.0

Writing this way can be a little awkward at first. We're more used to speaking in the indicative mood, which is all about reporting facts. That's why commit messages often end up reading like this:

  • Fixed bug with Y
  • Changing behavior of X

And sometimes commit messages get written as a description of their contents:

  • More fixes for broken stuff
  • Sweet new API methods

To remove any confusion, here's a simple rule to get it right every time.

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

If applied, this commit will: your subject line here

For example:

  • If applied, this commit will refactor subsystem X for readability
  • If applied, this commit will update getting started documentation
  • If applied, this commit will remove deprecated methods
  • If applied, this commit will release version 1.0.0
  • If applied, this commit will merge pull request #123 from user/branch

Notice how this doesn't work for the other non-imperative forms:

  • If applied, this commit will fixed bug with Y
  • If applied, this commit will changing behavior of X
  • If applied, this commit will more fixes for broken stuff
  • If applied, this commit will sweet new API methods

Remember: Use of the imperative is important only in the subject line. You can relax this restriction when you're writing the body.