🍙 how to write good git commit message

What is a git commit?

• At a high-level, Git can be thought of as a timeline management utility. Commits are the core building block units of a Git project timeline. Commits can be thought of as snapshots or milestones along the timeline of a Git project. Commits are created with the git commit command to capture the state of a project at that point in time.
• Simply, a git commit is a snapshot of the state of your code at a certain point in time.

What is a Commit Message?

• A commit message is a piece of descriptive text that is added by the developer who made the commit in the commit object.
• A commit message consists of five parts: type, scope, description, body, and footer.

Why is it important to write a good git commit message?

• Writing a good git commit helps you and others understand the changes made in the commit.
• Good commit messages are important for long-term projects.
• Good commit messages benefit collaborators and yourself.
• Good commit messages help track changes and understand commits.
• To make it easier to undo certain modifications.
• By writing good commits, you are simply future-proofing yourself. You could save yourself and/or coworkers hours of digging around while troubleshooting by providing that helpful commit message.
• writing a good commit message is a good example of collaboration and communication.

How to write a good git commit message?

Use atomic commits while following the conventional commits specification.

To come up with thoughtful commits, consider the following:

• Why have I made these changes?
• What effect have my changes made?
• Why was the change needed?
• What are the changes in reference to?

Atomic commits

The basic idea of an atomic git commit is that it contains the shortest amount of work that does what it is supposed to do.

• Every code change should be atomic
• one unit of work should be one commit

Conventional Commits

A specification for adding human and machine readable meaning to commit messages

• The Conventional Commits specification is a lightweight convention on top of commit messages.
• Conventional Commits specification provides easy rules for commit history.
• Conventional Commits allows for easy understanding by humans and machines.
• Conventional Commits facilitates easier collaboration on projects.
• Conventional Commits is used by many large open-source projects.
• Communicating the nature of changes to teammates, the public, and other stakeholders.
• Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history.
• write all lowercase

Structure of a good commit message

The commit message should be structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

type

The "type" communicates the intent of the change.

The type of the commit message can be one of the following:

• feat: A new feature.
• fix: A bug fix.
• perf – Performance improvements
• refactor: A code change that neither fixes a bug nor adds a feature.
• docs: Documentation changes.
• test: Adding missing tests or correcting existing tests.
• style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc).
• build – changes that affect the build system or external dependencies
• revert – reverts a previous commit
• chore: Changes to the build process or auxiliary tools and libraries such as documentation generation and modifying .gitignore.
• ci: Changes to our CI configuration files and scripts (for example changing the version of Node
• ops: Commits, that affect operational components like infrastructure, deployment, backup, recovery...

And you can create your own type of commits.

scope

• The "scope" provides additional context and is enclosed in parentheses.
• An exclamation mark before the colon indicates breaking changes.
• A scope MUST consist of a noun describing a section of the codebase surrounded by parenthesis.

description

• The "description" is a short message describing the commit.
• written in the imperative, present tense: “change” not “changed” nor “changes”
• maximum 50 characters

body

• The optional commit body should be used to provide further detail that cannot fit within the character limitations of the subject line description.
• you can use bullet points to list out the changes

footer

• The "footer" references issue IDs or other metadata.
• The footer is also optional. We use the footer to link the JIRA story that would be closed with these changes for example: Closes D2IQ-<JIRA #>.

Examples of Good Commit Messages

feat(profile): add button for update call

(JIRA-231) feat (dashboard): add sign-out button

----or----

build: update version

----or----

(JIRA-333) fix (profile): dummy commit

IMPORTANT CHANGE
to show how to add body in the commit

feat: improve performance with lazy load implementation for images

chore: update npm dependency to latest version

fix: fix foo to enable bar

This fixes the broken behavior of the component by doing xyz.

BREAKING CHANGE
Before this fix foo wasn't enabled at all, behavior changes from <old> to <new>

Closes D2IQ-12345

Conclusion

Writing good commit messages is an extremely beneficial skill to develop, and it helps you communicate and collaborate with your team.

Commits serve as an archive of changes. They can become an ancient manuscript to help us decipher the past, and make reasoned decisions in the future.

There is an existing set of agreed-upon standards we can follow, but as long as your team agrees upon a convention that is descriptive with future readers in mind, there will undoubtedly be long-term benefits.

The most important part of a commit message is that it should be clear and meaningful. In the long run, writing good commit messages shows how much of a collaborator you are. The benefits of writing good commit messages are not only limited to your team, but indeed expand to yourself and future contributors.

Notes

• while using conventional commits, remember to use all lowercase.
• use imperative mood in the subject line. Example: fix: add fix for dark mode toggle state.
• specify the type of commit. It is recommended and can be even more beneficial to have a consistent set of words to describe your changes.
• the first line should ideally be no longer than 50 characters, and the body should be restricted to 72 characters.
• be direct, try to eliminate filler words and phrases in these sentences (examples: though, maybe, I think, kind of). Think like a journalist.
• break down your changes into small, atomic commits. This makes it easier to review and understand the changes.
• every code change should be atomic
• limit the subject line to 50 characters
• do not end the subject line with a period
• separate the body from the subject with a blank line
• use the imperative mood in the subject line
• use the body to explain what and why not how
• wrap the body at 72 characters
• you and your team should have a consistent commit message style
• The most important part of a commit message is that it should be clear and meaningful.

Writing a great commit message checklist

• [ ] the commit is atomic
• [ ] the commit message is in lowercase
• [ ] imperative mood is used
• [ ] the subject line is limited to 50 characters
• [ ] the body is limited to 72 characters
• [ ] the body is used to explain what and why not how
• [ ] the subject line is not ending with a period
• [ ] the commit message is clear and meaningful
• [ ] you and your team should have a consistent commit message style

Resources

• Conventional Commits