Let’s face it, Git is a chore. It’s about as exciting as cold oatmeal. However, when used properly, it can save millions™.
5 Sanity Checks For Your Commits
Frequent
The more often you commit, the better you track your changes and have the ability to revert if needed. Frequent and small commits are easily merged without conflict. It’s like saving a game, only better.
Atomic
Atoms are small and your commits should be, too. Don’t cram 8 hours of work into a single commit. Atomicity should also apply to your commits. Everything that’s in the commit should be related. This allows you to easily revert without undoing unrelated changes.
Descriptive
What’s the last thing you need when moving? Mislabeled boxes or boxes with incorrect labels. Commits should be written in the imperative sense. They should describe what they DO, not what they DID.
Decentralized
Git, in its design, allows complete shared “ledgers” of changes between each clone of the repo. The entire history of the project is kept on every machine. As such, don’t let commits stay on your local machine. If you have a remote repo, keep your code published somewhere else. You never know when your laptop will cache on fire, become self-aware, or worse.
Immutable
Git gives you the “keys to the kingdom” and allows you to do any number of destructive operations to your repo. I’ve seen bad merges go down and months of work lost from one wrong move. As such, treat your commits as immutable. Once they have been written, they are sealed for all eternity. If you need to make changes, revert a commit and make a proper change.
What are "Conventional" commits?
As Git gives you all the freedom in the world to name your branches and commits whatever you want, it’s a good idea to have a common convention for how those commit labels are authored.
Here’s the td;lr (Summary)
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Yes, commits can be multi-line and are written like emails. 99% of the time, however, you will be focusing on the first line.
Bare minimum
<type>[optional scope]: <description>
Scared? Don't be.
I know what you're thinking...
Luckily there are tools that help this process go super smooth.
Commitizen CLI - https://commitizen-tools.github.io/commitizen/
VS Code Extension - https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits
Commitlint - https://commitlint.js.org/
Other Tools - https://www.conventionalcommits.org/en/v1.0.0/#tooling-for-conventional-commits
Give me the deets already.
Type (Required) (Spec)
These categorize a commit and tell you what kind of change this is. Here are examples:
- feat - for new features
- fix - for defects or bugs
- chore - for changes that don’t alter the source, but necessary
- ci - for ci pipeline changes
- docs - for documentation changes
- perf - for performance enhancements
- refactor - for refactors; altering the code, but not changing functionality
- revert - reverting changes
- style - for cosmetic changes
- test - for unit tests
Scope (Optional) (Spec)
Scope allows you to box your commit into a specific feature, file, or sub-set of the application.
fix(Navigation): change Loggin to Login
chore(deps): upgrade Jest to v24.5.7
Body (Optional) (Spec)
Just like the body of an email, if you want to add more of a description to your commit, you can do so below the first line.
Note: If the commit contains a BREAKING CHANGE, this goes in the body of the commit.
feat(Authentication): update cipher for better security
BREAKING CHANGE all security keys will need to be regenerated and deployed.
Footer (Optional) (Spec)
Footers are optional, but allow for ticket references to be made in the commit without clogging up the commit subject line. The follow a specific format:
..."each footer MUST consist of a word token, followed by either a : or # separator, followed by a string value."
Conventional Commits
There are several tools that will parse commit messages and automatically make links to tickets.
refactor(Header): correct minor typos in code
see the issue for details
Refs: JIRA-9999
FAQ (source)
How should I deal with commit messages in the initial development phase?
Proceed as if you’ve already released the product. Typically somebody, even if it’s your fellow software developers, is using your software. They’ll want to know what’s fixed, what breaks etc.
Are the types in the commit title uppercase or lowercase?
Any casing may be used, but it’s best to be consistent.
Although, more often than not, lowercase is used.
What do I do if the commit conforms to more than one of the commit types?
Go back and make multiple commits whenever possible. Part of the benefit of Conventional Commits is its ability to drive us to make more organized commits and PRs.
Doesn’t this discourage rapid development and fast iteration?
It discourages moving fast in a disorganized way. It helps you be able to move fast long term across multiple projects with varied contributors.
Oldest comments (9)
Great post
Good to see you, @ben ! It's been a while since I've posted. So much has changed. I should write about it!
Thx for this! This is really what I wanted. Helped A LOT.
Can I translate in Korean this article? If you don't mind, I wanna share this awesome information in Korean. Surely, There will be a link directing to this original one.
The spec and all related info are already available, translated, on the conventional commits website. Regardless of what the article's author responds, you can share that in Korean with no added effort.
But you know that there are differences in form of the contents.
I cannot offer an opinion on the existing Korean translation, as I don't speak the language.
If we're talking about the english version, Im not of the opinion that this article makes any substantive addition beyond memes.
In any case, I hope you find what you need and make a convincing argument to your intended audience.
Good principles !
I would like to point out that it is VERY HARD to loose work with git.
Everything is saved, even after a bad manipulation, i've never not been able to find the HEAD of my a working branch somewhere.
I was afraid of rebase for a long time, I now find frequent rebase and working with a more linear history much easier and don't have big issue with merges anymore.
if it ever happens to you again, trust in git and dig in the reflog :)
"chore" is just so negative though. How about "core" instead?
Ooooo, I kinda like this, but chore implies a necessary, but boring task. It doesn't add anything or fix anything. It just is.
"core" to me seems essential, but could be confused with adding a feature or refactoring critical code.