Skip to main content

Writing Git Commit Messages

warning

This document has been translated using machine translation without human review.

This document contains general recommendations for writing commit messages in Git.
These recommendations are based on well-known practices, as well as personal experience with teamwork and automation.

note
  • Subject — this is the first line of the comment, a brief description.
  • Body — the subsequent lines that may contain more detailed information.

Include the task number in the subject line​

  • This will help automate the process of tracking and analyzing completed work for the task.
  • This will help find the task and understand what happened when the need arises. In large projects and during teamwork, this happens more often than it might seem.
✔️ Good Example⛔ Bad Example
JIRA-1725: Add README.md fileAdded README.md file

Use the imperative mood in the subject line​

In English, this primarily solves the problem of incorrect tense usage and, in general, makes the text simpler.

In Russian, the imperative mood also works quite well. The comment sounds like a command. When reviewing history or applying individual commits, this looks quite logical, like executing a script that performs certain actions, and the commit message is the action being performed.

✔️ Good Example⛔ Bad Example
ISSUE-5217: Add CHANGELOG.mdISSUE-5217: Added CHANGELOG.md
ISSUE-5217: Update external service callISSUE-5217: Updated external service call
ISSUE-5217: Remove arguments from method FooISSUE-5217: Removed arguments from method Foo

Do not put a period at the end of the subject line​

The first line of the comment should not end with a period. This is the subject of the message. A subject cannot end with a period.

✔️ Good Example⛔ Bad Example
EXMPL-1925: Add upload methodEXMPL-1925: Add upload method.

The subject should be as short and informative as possible​

The first line of the commit message should be as short as possible.

At the same time, the first line should contain the maximum amount of useful information so that it is clear what exactly changed in the code.

This is necessary for the convenience and speed of reviewing history. Moreover, it will be convenient both when viewing via the command line interface and in clients with a graphical interface.

On average, it is recommended to use no more than 50 characters.

✔️ Good Example⛔ Bad Example
MYLLM-7841: Add MCP client configurationMYLLM-7841: Add address, port, and token to settings for connecting to the MCP server

Separate the subject and body with a blank line​

If the comment is multi-line, a blank line should be placed between the subject and the body.

This will make the text easier to read.

✔️ Good Example⛔ Bad Example
DATA-2078: Delete Users table

The customer is against storing users in the database. We will now use an external cloud storage.		DATA-2078: Delete Users table
The customer is against storing users in the database. We will now use an external cloud storage.

The body should answer the question "why was all this done"​

A good message body should explain why the changes were made.

✔️ Good Example⛔ Bad Example
AWESOME-2356: Add exclude argument

This will allow excluding unnecessary data from the selection.		AWESOME-2356: Add exclude argument

Change function logic. Minor refactoring.

Variety​

Do not write identical commit messages. Such messages are difficult to work with and do not carry any useful load.

✔️ Good Example⛔ Bad Example
MYPROJECT-2518: Create message sending serviceMYPROJECT-2518: Implementation of message sending service
MYPROJECT-2518: Create tests for message sending serviceMYPROJECT-2518: Implementation of message sending service