Closing a Knowledge Gap: Best Practices for Writing Git Commit Messages

When I was learning git there was never much emphasis on commit messaging.

When it was time to push to GitHub it was always something like this:

git add .
git commit -m “fixed nav bar”
git push

That was fine, for a beginner that was working alone and never going back to old commits.

But just like writing clean code you want to write clean commit messages, you want to be able to clearly and easily read your old messages, and some other person working on the same project should be able to read your commits and know what changed and why.

Go back and look at your Git commit history and see if you struggle to understand what changes were made, and why they were made? Poorly written or inconsistent commit messages can make it difficult to understand the history of a codebase, track down bugs, or collaborate effectively with other developers.

One way to address this issue is by using consistent and descriptive commit message conventions. By following a set of agreed-upon conventions, developers can make it easier to navigate the commit history, understand the purpose of each change, and track issues or bugs related to specific commits.

Let’s explore the importance of good commit message conventions, discuss some common conventions and best practices, and provide examples of effective commit messages

Most common best practices:

• Use keywords in the subject line of the commit message, "fix", "add", "update", etc., to clearly convey the intent of the commit.
• Keep the subject line short 50 characters or less, to provide a clear and concise summary of the change.
• Add a more detailed description in the body of the commit message, explaining what the change does and why it was necessary.
• Use the body to describe any side effects, gotchas, or dependencies of the change, to help other developers understand how the change fits into the larger codebase.
• If the commit is related to an issue or bug, reference the issue or bug number in the commit message, "Closes #1234".
• Use consistent conventions for formatting and style, such as capitalization, punctuation, and line breaks, to make the commit history easier to read and understand.
• Break up large changes into smaller, atomic commits that can be more easily reviewed and understood by other developers.
• Use the -amend option to update a commit message that hasn't been pushed to the remote repository yet, rather than creating a new commit with an updated message.

Keywords in the Subject Line:

With git commit messages you can use keywords that can be used to help categorize and organize commits.

By using these keywords in Git commit messages, it becomes easier to identify the purpose of each commit, and it helps keep the commit history organized and easy to navigate. Also, GitHub can use these keywords to automatically generate useful information, such as release notes or change logs.

Commonly used Git message keywords:

• feat: A new feature or functionality has been added to the codebase.
• fix: A bug or issue has been fixed.
• refactor: The code has been refactored to improve performance, readability, or maintainability.
• docs: Documentation changes have been made, such as updating README files or inline comments.
• test: Changes have been made to the test suite, such as adding or updating tests.
• style: Changes have been made to the code style or formatting, such as adding or removing whitespace or changing variable names.
• chore: Miscellaneous changes that do not fit into the above categories, such as updating build scripts or dependencies.

By using these keywords in Git commit messages, it becomes easier to identify the purpose of each commit, and it helps keep the commit history organized and easy to navigate. Additionally, some Git hosting platforms, such as GitHub, can use these keywords to automatically generate useful information, such as release notes or change logs.

Aside: Release notes and change logs?

Release notes and change logs are documents that provide a summary of changes made to a software product.

A release note is typically a brief summary of the changes in a particular release or version of the software. It may include a list of new features, bug fixes, improvements, or known issues. Release notes can be written in a more informal style and are often used to announce a new release or update to the software.

A change log is a more detailed and structured document that provides a comprehensive list of changes made to the software over time. It may include information on the release date, version number, author of the change, a brief summary of the change, and any other relevant details. Change logs are often organized chronologically, with the most recent changes listed first.

Release notes and change logs are a whole other topic, but here are some links if you want to look into the subject now:

Automatically generated release notes - GitHub Docs

changelog-generator

Making a Commit

Okay, back to our commit message!

This time make some changes to your code and save.

Do git add, but this time when committing do not add the -m

git commit

depending on what editor you are using, this will appear in a file or in the terminal:

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch main
# Your branch is up to date with 'origin/main'.
#
# Changes to be committed:
#       modified:   README.md

above those # you want to add your message, in this styling:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Fix: CSS in nav bar fix Adjust nav bar styling for small screens

The nav bar was not displaying correctly on small screens due to a styling issue.
This commit addresses the issue by adjusting the CSS to ensure that the nav bar 
displays correctly on screens of all sizes

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch main
# Your branch is ahead of 'origin/main' by 1 commit.
#   (use "git push" to publish your local commits)
#
# Changes to be committed:
#       modified:   README.md
#

If you are working in a text file just save the file and then git push.

If you are working in the terminal, save by typing :wq then git push

Also if you are committing without a lot of detail in the body you can commit inline in the terminal with a double -m flag:

git commit -m <title> -m <detailed description>

git commit -m 'Fix css in nav bar fix Adjust nav bar styling for small screens' -m 'The nav bar was not displaying correctly on small screens due to a styling issue. This commit addresses the issue by adjusting the CSS to ensure that the nav bar displays correctly on screens of all sizes'

Further Reading: Pro Git and Conventional Commits

Pro Git Book

Conventional Commits

Git Docs

❤️❤️❤️

Follow me on LinkedIn for all the updates and future blog posts