How to Write Commit Messages?

How to Write Commit Messages?​

What does git commit do and why do we need it?​

The “git commit” command takes a snapshot of the changes made, additions, deletions or modifications, in a git repository and saves them. This works similarly to the save function in computer games. When our project reaches a certain stage, we use the “git commit” command to record our progress. This allows us to revert to previous versions of the project and helps other developers we collaborate with to keep track of their work.

The easiest way to write a git commit message is to use the command git commit -m ‘your commit message’. This command takes a snapshot of the changes made and saves them to the repository with an explanatory message called the “commit message”, indicating what these changes are. This allows you to track information such as when and why changes were made to the repository and revert to previous versions of the project. Additionally, clear and descriptive commit messages can help other developers working on the project to track their work and facilitate future development of the project.

What is the message of Commit?​

A commit message is an explanatory text added during a Git commit process and is included by the developer who writes the commit to the commit object. Commit messages are used to explain what changes were made in the project and why they were made. This allows future readers or other developers to understand the changes and keep track of the project’s history.

Commit messages are also important for understanding the code we write. When we look back at our code at a later time, commit messages help us to better understand the old code we wrote. Commit messages usually have a title and an optional body. The title includes a summary of the changes while the body can provide more detailed information. Accurate and descriptive commit messages are crucial for tracking the development of the project and sharing it with other developers.

Why should we create a quality commit message?​

Our commits are snapshots of our code changes, stored along with commit messages that explain the changes made. Therefore, well-written commit messages help others understand what our code does when they look back at it later. If we write bad or insufficient commit messages, we may need to look back at old commit messages to find errors in our code. In this case, we may need to read through all of the code to find errors, which can be time-consuming and laborious. Additionally, understanding what code written months ago does can be difficult. Well-written commit messages make it easy to find where errors are and understand what our code does. This way we can fix bugs and make our code better.

General rules for writing commit messages​

As a general rule, commit messages should be short, descriptive, and a single line that does not exceed 50 characters in the header section. Then, a blank line should be left and a more detailed explanatory text can be written optionally. If there are multiple changes in your commit, it may be difficult to write a single short message. In this case, you can make your job easier by splitting the changes into multiple commits. For example, if you have made 3 changes in a commit, 2 of them are working fine but one is causing an error in the future, when you revert to the original state before committing to fix the error, you may have to remove the working 2 changes as well. To avoid this situation, it is recommended to commit changes in small pieces as much as possible.

1. Keep it short and concise

• Having fewer changes in a commit will help you write a shorter message.
• To make your message clear and understandable, focus on a single topic and keep it as simple as possible.

2. Use the present tense and imperative mood

• Use the present tense and imperative mood in your commit messages, such as “Make x method asynchronous”.

3. Add a short title

• The title should be less than 50 characters.
• Most code management systems provide a limited space for commit message titles, which is generally limited to 50 characters. Therefore, your message should be less than 50 characters to be fully visible.
• Having a short title helps other team members quickly understand the changes.

4. Add an optional body

• There should be a blank line between the header and the body.
• The body should be no more than 72 characters per line.
• Write a message explaining what and why the change is needed.
• This section is where we describe what the change is, why it was made, and the impact it has on the project.
• Be as detailed as possible in describing what the change is.
• Avoid unnecessary details.

5. Avoid large size commit messages

• A message that is 100mb in size will definitely cause performance issues.

Additionally, a footer can be added, which usually includes an external reference identifier such as a Jira or issue number.

Bad example of committing:


An example of good commit:


This commit message does not clearly describe what the change is and does not specify which issues it fixes. Such a commit message can make it difficult to trace this change back in the future.

Semantic commit​

Semantic commit messages provide a clear and concise structure that describes the purpose and actions performed in a commit. They improve the readability of commit messages and make it easier to track changes.

A semantic commit message consists of a prefix added to the commit message header and a short description. You can also specify the section where the change was made in parentheses.

Let’s look at the following commit as an example.


In the above commit, the “feat” suffix indicates that a new feature has been added. “login” indicates in which section the addition is made.

The general structure of the Semantic commit is as follows.


These are the common semantic commit types:

• feat: an abbreviation for “feature” and used when a new feature is added.
• fix: used for bug fixes.
• docs: used for documentation changes.
• style: used for changes in the code style.refactor: used for improving, restructuring, or editing existing code.
• test: used for changes related to tests.
• chore: used for changes related to code maintenance or configuration.

For more details see: https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716

Below are a few examples of commitments:

Teams with git ticket system​

Most teams use “Jira” and similar ticket systems that assign a ticket number to a specific work section.

When writing commit messages, if you use a ticketing or tracking system for project management, it can be useful to use ticket numbers in your commit messages.

For example, for a Jira ticket “ACME-1”, it is common practice to include the ticket number at the beginning of the commit as follows.


Here, the ticket number “ACME-1” clearly indicates for which ticket the change was made.

Using ticket numbers in commit messages not only helps other developers understand which tickets the changes are related to, but also makes it easier for project management to keep track of tickets. Thus, using ticket numbers increases the traceability and manageability of the project.

Sources I used: