Sign in


On the master branch

How to write a good git commit message that people can read and tools can parse.

First read How to Write a Git Commit Message

The seven 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 in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how

Example of a well-formed commit message:

Simplify serialize.h's exception handling

Resolves: BOX-123

Remove the 'state' and 'exceptmask' from serialize.h's stream
implementations, as well as related methods.

As exceptmask always included 'failbit', and setstate was always
called with bits = failbit, all it did was immediately raise an
exception. Get rid of those variables, and replace the setstate
with direct exception throwing (which also removes some dead

As a result, good() is never reached after a failure (there are
only 2 calls, one of which is in tests), and can just be replaced
by !eof().

fail(), clear(n) and exceptions() are just never called. Delete

Commit verbs

The following git message verb conventions helps us read fast and also is parsable by toolchains:

Add Create a capability e.g. feature, test, dependency.

Add authorization to admin endpoints

Cut Remove a capability e.g. feature, test, dependency.

Cut support for sms otp login

Fix Fix an issue e.g. bug, typo, accident, misstatement.

Fix bug in email validation

Bump Increase the version of something e.g. dependency.

Bump skynet dependency version to 1.1

Make Change the build process, or tooling, or infra.

Make the Makefile run grunt targets

Refactor A code change that MUST be just a refactoring.

Refactor environment variable names

Reformat Refactor of formatting, e.g. omit whitespace.

Reformat email verification template

Optimize Refactor of performance, e.g. speed up code.

Optimize user queries

Document Refactor of documentation, e.g. help files.

Document service start-up procedures

Debug Debugging/investigating CI flows. Not allowed in master branch.

Merge Merge commit into current branch.

Exactly one of the verbs must prefix each commit. The grammatical tense of the verb must be the same as in the list. Each verb must start with an uppercase letter.

The message Initial commit is an exemption to the verbs, if used as the message to the initial git commit.


The commit format is important as non-structured and inconsistent git-history makes tracking down issues time-consuming and in worst case erronous.

Messages that start with a leading tag, or flag, or abbreviation, or link, or tracking number, such as any of these styles will be rejected:

  • [bug] ... (Starts with tag)
  • (release) ... (Starts with flag)
  • #12345 ... (Starts with ticket number)
  • Added ... (Wrong grammatical tense in verb)
  • bump ... (Verb starts with non-capital letter)
  • Fix refactored Cucumber tests (Conflicting verb and subject)