Better Commit Messages
Going through my TL saw the below tweet, I felt attacked a bit. As a one man army on most of my projects, I always do typical one liners, init, update, readme, fix-01, and so on. In this article I will show you how to configure git to launch your template on vscode for better commit messages.
Ben Orenstein@r00k
Most commit messages are next to useless because they focus on WHAT was done instead of WHY.
This is exactly the wrong thing to focus on.
You can always reconstruct what changes a commit contains, but it's near impossible to unearth the reason it was done.
(thread)17:33 PM - 20 Sep 2019
The Template
This is the template that I currently use, you can change whatever you want to your liking. Here's an example of me using it. In the beginning it does make you think what to write, but after a few commits you'll get the hang of it.
# Commit Title (50 chars)
# Why? Issue, enhancement, etc.
# How does it address the why?
# Tickets, Links, etc...
Save the template in your home directory
I named my template .git_commit_msg.txt but you can name it whatever you want. If you don't have environment HOME paths, then do an absolute path.
Linux, Mac
${HOME}/.git_commit_msg.txt
Windows
%HOME%/.git_commit_msg.txt
Activate template on git
Linux, Mac
git config --global commit.template ${HOME}/.git_commit_msg.txt
Windows
git config --global commit.template %HOME%/.git_commit_msg.txt
Configuring your editor
Check your default text editor:
git config core.editor
I configured mine with vscode on git configuration :
git config --global core.editor "code -w"
code needs to be on path, if you type
codein terminal/prompt and the editor doesn't open, then open vscode and do CMD/CTRL+SHIFT+P, and typeshell command, you should see install and uninstall options. Windows adds code by default during installation.code can be replaced with your preferred text editor, vim, emacs, sublime, if you are having issues with your text editor, SO is your friend.
How it works?
Once you do a commit, the template will open up on vscode, you can uncomment the template lines, add new ones, whatever. Save message, and close file. At that point your commit will be complete. If you close the template without adding anything, commit will be cancelled. When you do the PR, that whole detailed commit message will be in your PR, ready for the maintainer to review.
git commit
You can still use
-margument for those pesky one liners.
What do you prefer?
- Do you enjoy one liners, and then do detailed PRs.
- Do you use commit templates?
- Does your team/company enforce a template?
- Any other methods?
I hope you enjoyed this post, thanks for reading!
Top comments (20)
"Quick Fix" FTW!
"Fixed quick fix" =D
Fixed quick fix fix :V!
I didn't realize you could even make a template. Maybe now I won't forget to add some more content.
I didn't either, is incredibly crazy how configurable git is. 😁
It is actually pretty useful.
Now I use it all the time
What worked for us and I see it in many Github repositories is the Angular commit convention.
You can read about it in the Angular contribution section or in the conventional commit description
In general I make small commits which solve one issue / task and aim not to mix up code refactoring with the actual task. In most cases a one liner is totally enough then. I also add the ticket number to get background information if necessary. In case it's a bug fix for a regression I add the commit hash that introduced it.
The one liner, ticket number and commit itself is fine for me. Yet this requires to set proper messages and a good maintained ticket.
Thus, tbh I sometimes catch myself not doing it. If possible I fix things by using the interactive rebasing then.
Bottom line, as of now I am not using templates.
Yeah everyone got a different workflow. You can add a one liner template to remind you too. 😉
git commit -m 'changes'😂This is pretty cool!
But I'd still prefer doing one line commit messages.
I try hard to make my code speak for itself. But whenever I really need to explain the whys, I put it in the ticket discussion or in the pull request.
Code speaks to you and only you. Even then after a few months maybe not even you lol.
Do you know if discussions are pulled once PR is merged?
You could follow 50/72 format in your commit messages
stackoverflow.com/questions/229001...
If you really want to you could use emoji's gitmoji.carloscuesta.me/
Thanks for the tip!
I think templates per project can be a good idea, to make sure everyone meets the project guidelines, and to be a prompt for better messages. Otherwise if to in a hurry to get a patch out, then you'll make a crummy, no value message like 'fixed the fob'
I generally make commits that follow the guidelines from GitHub with one line, 50 char subject summary, then a blank line and more verbose summary, wrapped at 72 chars, with link to ticketing system or GitHub/GitLab issue for the full explanation. This plays well with editor tools like Magit (Emacs) or GitLense (Code), or git blame, which show just the first line in summaries or logs, but can expand our pop up the full commit message.
"X fixed"
"Forgot to remove prints"
"Forgot to remove the last print"
Very clever way to enforce convention on those meaningless commits messages! Great for people like me who use git blame viewer (I use GitLens on VSCode).
We use one line commit messages on conventional commit style, then we create detailed PRs with detailed problem and solution sections. The structure of the PT is defined in guthubs or template.
Yeah a very high percentage of repos don't implement templates unfortunately.