How to add commit message in Git [Practical Examples]

Quick cheat sheet to git commit message

You should understand the git commit message to keep track of changes and the reasons for the changes. A comprehensive commit message history confirms that you know what you are doing in a collaborative environment.

So, how do you write a commit message? What situations determine git commit message structure? What rules should you follow when writing a git commit message in various software development environments?

Worry no more if you seek answers to the three questions because you will find answers in this tutorial.

The structure of the commit message changes depending on what you intend to accomplish with the git commit message. For instance, you could be releasing software. You then want to speed up change tracking by breaking the tasks into smaller, understandable commit messages.

This format should be great for a commit message for a simple personal project:

git commit -m <message>

Where the -m option sets the commit message. You can also use other options, such as --amend to rewrite the commit message or --all to commit all files irrespective of whether they get deleted automatically, tracked, or modified.

In a collaborative platform use the conventional format

<commit type> [optional scope]: <description>

[optional body]

[optional footer(s)]

Before exploring a commit message structure, let us dig into the roots of the git commit message.

 

The role of git commit message in git workflow

Git commit message is crucial in the git workflow as it determines the cleanliness of the history. Here is how it relates to the workflow.

Running the command

git init

notifies git to create a repository in your current directory. It does that by creating a subdirectory called .git.  that stores all information about the repository.

After instantiating a repo, you can create files in the working directory. You then move the file changes to the second stage of the workflow, the index, also called the staging area. Finally, you can unstage the files or permanently record the changes in the git database. Moving the changes from the index to the database is called git committing.

Since the primary reason for creating a commit history is to mark specific change stages, it is crucial to save the commits with a reference. The reference (git commit message) helps you or another person viewing your changes later to figure out why you made the change.

That begs the question, "Will your commits make sense later if you write multiple commits without minding an easy-to-understand format?" Definitely, no.

To avoid creating a mess of commit history, you should care about who will review the changes. After identifying the target repo user, you can follow the recommended conventions, as you will learn in this tutorial, to write remarkable git commit messages.

The most typical development environments pioneering git commit message structure are simple personal repo, collaborative development platform, or software releases.

Although the development environment's complexity defines the git commit message structure, here are the should-observe rules for all git commit messages.

 

5 General rules for writing a standard git commit message

• The description should tell why, NOT how you made the change.
• Do not end the description with a period.
• Write the description in the imperative form, for example, "Fix a bug," NOT "Fixed a bug," "Fixes a bug," or "Fixing a bug."
• Wrap each line in the body after 72 characters.
• If your commit message has a body, separate the body and the subject line using a blank line.

Enough with rules. Let's do some practice.

 

Lab setup to explore git commit message

We will configure the default editor before creating and practicing git commit message using two repos.

The first (local) repo helps us explore writing git commit messages on a simple personal project. The second (remote) repo, on the other hand, illustrates the recommended ways to write commit messages when collaborating on the remote repo.

 

Configure the default editor

We need a text editor to write a complex git commit message. You can change git's default text editor, Vim, to a more manageable one by entering the editor's name in the following command:

git config --global core.editor "[your preferred editor] -w"

Since I will use Visual Studio Code, I am setting it as follows:

git config --global core.editor "code -w"

The -w flag informs the terminal to wait until we close the editor before updating the commit message. Otherwise, on running the commit command

git commit

we will get a report on the terminal like Aborting commit due to empty commit message after entering the commit message then closing Visual Studio Code.

 

Create two repos

Let us create the two repos to practice the git commit message, starting with the local one. Head over to the command line, create and initialize a repo as follows:

mkdir personal_commits

cd personal_commits

git init

Move to GitHub and create the remote. I am creating a repo, shared_commit, and cloning it using these steps.

Copy the repo URL,

Now that we have a setup to practice the git commit message, let's dive into some relatable examples.

 

Example-1: Git commit message for a simple personal repo

When managing a simple personal repo, you must not be so hard on yourself. You can write a basic commit message as follows:

cd into the personal_commits repo.

cd personal_commits

Create a file.

touch file

Stage it.

git stage file

and commit it using a git commit message as follows:

git commit -m "Track file"

We can check the saved commit message by logging the history.

git log

 

Example-2: Handling git commit messages for a shared remote repo

The most standard route to collaborate on a project is through branching, merging and pulling changes. You can create a tidy repo by squashing git commit messages. Better yet, you should use a descriptive commit message after doing the merge to create a more straightforward repo.

The conventional commits enable you to

• automatically generate changelogs
• build a structured commit history
• create a semantic-based repo

 

Structural details of a conventional git commit message

The general structure of a conventional git commit message is

<commit type>[optional scope]: <description>

[optional body]

[optional footer(s)]

The main commit types are fix for fixing bugs and feat for code features.

Other commit types are build, test, refactor, docs, chore, style or ci. It would be best to follow the Angular convention when using them.

The one-word noun scope provides additional information. The description should be written in an imperative verb.

Here is an example of a git commit message.

feat(api): send an email notification on successful token creation

feat is the commit type, api is the scope while the description is send a push notification when the app closes.

The body explains the description and must not follow a specific order like the type, scope, and description. Below is an example.

Resolves #13

Missing step: log in before attempting to create a token

Reviewed by: Adi

The most familiar footer type is the breaking change, capitalized as BREAKING CHANGE. You can accompany it with an exclamation mark ! on the commit type to denote an urgent need for attention.

chore!: use node 16

BREAKING CHANGE: no more support for node version below 16

BREAKING CHANGE, feat and fix commits follow the semantic versioning: Major, minor and patch versions, respectively.

Now that you understand conventional commits and rules for writing them, let's look at a typical way to apply them in a git commit message.

 

Using a conventional git commit message with a shared remote

Unlike a release project with a changelog, a simple shared remote repo may not have a body or footer. You will mainly specify the commit type and body as follows.

cd in shared_commit.

cd shared_commit

Create a file.

touch file

Stage it.

git stage file

Give it a git commit message

git commit -m "Fix (github): explain git commit message remotely"

To write a commit body and footer using the standards described above, run the

git commit

command without the commit message to open a default text editor we configured in the setup section.

Lastly, let's push the changes

git push

then refresh the remote repo on GitHub.

 

Key Takeaways

Understanding git commit message operation is one of the most crucial skills for any software developer. The skills let you create a comprehensive commit history. You can easily collaborate with other developers, especially during issue tracking and feature releases.