DEV Community

Cover image for A Guide to writing Industry Standard Git Commit Message
Tuasegun
Tuasegun

Posted on • Updated on

A Guide to writing Industry Standard Git Commit Message

I bet you already heard something about Git before starting this article whatever led you here, you’re welcome and I hope you find the solutions.

Brief Explanation of Git

We have large projects that need contribution, Git simply helps developers manage the different contributions and bonds them into one unit. It also helps in controlling the versions of the projects which is version control, this is a dummy definition but it’s the best way I could explain Git.

A standard meaning of Git is that it’s a DevOps tool used for managing source code. It is a free and open-source version control system used to handle small to very large projects efficiently.

Before proceeding, I advise you understand a bit of git workflow Here

Git commits

Git commits are a snapshot of the codebase or project's current stage/state. It allows the system to store the staged changes.
Commits are used as a timeline for the project’s contribution and changes, It also helps in defining milestones in the project. Commits can also be used to track the team’s productivity and KPIs.

Industry Standard Git commits

I choose to describe this as Git commits that can be generally understood across the tech ecosystem. It shouldn’t commit messages that have very complex terms, it should be readable and understood by people that don’t even contribute to the code base.

The necessity of Industry-standard commits

Now, the necessity of this is to make your commit messages specific to your committed code even if you look back at the code you should be able to understand the change you made via the commit message. It also helps new contributors understand the commits and changes made. You could know why a person made this commit and the effects it would make if you change that particular line of code.

Your commit message should be:

  • Understandable
  • Enough
  • Unambiguous

Before coming up with a commit message you should consider:

  • Why did I add this commit
  • What changes does this commit make
  • Are the changes necessary
  • Do the changes solve any ticket or do they refer to any external links or part of the code

The Industry standard commit message method we will be checking out is the

<type>[optional scope]: <description>

[optional body]

[optional footer]

Enter fullscreen mode Exit fullscreen mode

Different standard commit types we can look into:

fix: This is to commit a resolved bug in the codebase

feat: This is to commit a new feature to the code base

chore: This commits changes that are not related to a feature or a bug it involves modification or updating dependencies

refactor - this commits changes that involve refactored code, that includes refactored code or changes

docs - This commits changes made on the documentation, readme.md or markdown files

style - This involves style changes in the codebase

test - This commits changes made in the test file including corrections made

perf - This commits to improve the app's performances

ci - This commits make changes in the CI integration like the files and scripts

build - These are files that involve the build files and blue dependency

revert - This commit signifies reverting to a previous commit

An example of this is

feat: Add withdrawal button on home page

You could also add standard commits with their emojis different commit types have different emojis like
fix: Fixed the contact form
Read more about that here

Conclusion:

The skill learned in this writing will improve you and make your codebase more organised. It is necessary to document your processes and track your changes.

When your code becomes legacy code and a new developer has to work on it your commit message has made it way easier for the incoming developer to work in your codebase even in your absence.

If you have suggestions on how to improve commits you could suggest them below.

I really hope we have all learnt something from this article on improving our git commit messages.

Discussion (28)

Collapse
chadalen profile image
Chad Adams • Edited on

Several companies I’ve worked at wanted us to prefix our commits with the Jira ticket number e.g MIN-1533. So you can look through the commit history and see right away which ticket the person was working on.

Collapse
fjones profile image
FJones

This works excellently up until the point where it generates links or comments on the ticket itself. I've stopped using ticket IDs in commit messages because of that spam, and I rely on GitLab to reference the merge request (which does have the ticket ID) now.

On a different occasion, I found that ticket IDs do, in fact, expire when the ticketing system changes, so it becomes useless information then, too.

Overall, I've stopped caring about commit messages. I care about the context of the changes (especially on bisect or blame), but the message? Screw that. Give me well-contained commits. Rebase your branches before your Merge/Pull Request, sort them into commits that make sense from their contents, and give it a reasonable message that reflects what the commit was kinda-sorta supposed to do. Beyond that, don't waste time on commit messages.

Collapse
kaylumah profile image
Max Hamulyák

I was gonna mention the ticketing system changing. Happend to me in the past we moved to a different Jira board so a lot of links did now work anymore

Thread Thread
fjones profile image
FJones

For us, it was a switch from Bugzilla to Jira, and then from one Jira project to four. Effectively, six years worth og tickets gone. And at the time, a lot of developers did not care for making their commits self-explanatory, so we had one giant 100k line commit, and dozens of useless oneliners, all with messages that referenced one non-existent ticket. That was hell. So I've stopped caring about messages - and begun caring greatly about tooling associating those commits with the merge, and commits containing relevant information to relate the changes to the business requirement.

Collapse
synchromatik profile image
synchromatik

You can comment/transition/log jira tasks with commits without even opening jira. For example: git commit -m "JIRATICKET12 #time 1w #resolve #comment Jira comment"

support.atlassian.com/bitbucket-cl...

Collapse
sandordargo profile image
Sandor Dargo

I put them at the end of the headline. What is neet is that Bitbucket transforms them to direct link to the corresponding Jira tickets .

Collapse
tuasegun profile image
Tuasegun Author

That makes a lot of sense for companies, thanks for that.

Collapse
pdamra_7 profile image
Philip Damra

There's actually a specification that covers this topic called Conventional Commits: conventionalcommits.org/en/v1.0.0/

Collapse
tuasegun profile image
Tuasegun Author

Yes, I used this when writing the article. Thanks for sharing.

Collapse
ynk profile image
Julien Barbay

you should at least mention them in your article. without this, it sounds like a huge uninformed rip-off rather than an explanation of it.

Collapse
kelvinskell profile image
Kelvinskell

What prefix would be best to use when you're making an update to a feature?
Let's assume you've already added the feature and you're now making an update to it, should you use chore or "update"?

Collapse
layzee profile image
Lars Gyrup Brink Nielsen

"refactor" changes the implementation of existing functionality. No observable change from the user's perspective.

"feat" can add a new feature or introduce breaking changes to existing functionality. Add "BREAKING CHANGES:" to the commit body or an exclamation point to the commit type, for example "feat!: make name parameter mandatory" for an API.

Collapse
jcandan profile image
James Candan

Does your update add a feature enhancement or simply change implementation. I would use feat for the former and change for the later.

Collapse
tuasegun profile image
Tuasegun Author

You could also use feat, I wouldn’t want you to overthink it

Collapse
tuasegun profile image
Tuasegun Author

I’m not really sure and I wouldn’t love to direct you wrongly

Collapse
creativezoller profile image
Zoller

Actually despite this is a good writing, a lot of cases restrit you from using it. Like big companies, where the ticket numbers are a must to include, or other restrictions. In the other hand, a lot of big companies does not give a fork about git commits, when I worked for Bl*kR*k, they only used master branch for all ther codes pushing from the office located in Delhi and they were just looking at us, why do we want to use several branches for our work to commit? I was frankly stunned... For another company I am actually working now only I am using proper git commits and I always see the backend developer pushing commit with messages like "trying again" and "try #68", "third time the charm", etc... I am really enjoying using proper commit messages, I also created some scripts which creates a release documentation with all the commits between last and recent releases with ticket numbers, descriptions, and changes as countes integers. But as I already said, majority of IT does not think about this as an important thing. But in fact it is.

Collapse
cappe987 profile image
Casper

You should avoid emojis. It might look pretty in a GUI, but for those that use a terminal it might not be as pleasant. It's better to keep it simple.

Collapse
tuasegun profile image
Tuasegun Author

Thank you

Collapse
aaravrrrrrr profile image
Aarav Reddy

Nice work

Collapse
tuasegun profile image
Tuasegun Author

Thanks

Collapse
snelson1 profile image
Sophia Nelson

Thanks for this.

Collapse
brunoj profile image
Bruno

Thanks for the post

Collapse
ambriel profile image
Ambriel Goshi

Thanks for writing this.

Collapse
ivis1 profile image
Ivan Isaac

good read

Collapse
tuasegun profile image
Tuasegun Author

Thank you

Collapse
dan_le_brown profile image
Brown

I've been using "feat:" all my life and now, I'm literally ashamed 😭. Thank you Segz, for bringing an end to my embarrassment.

Collapse
tuasegun profile image
Tuasegun Author

Thanks Brown

Collapse
rbrtbrnschn profile image
Robert Bornschein

More people need to know this.