DEV Community

loading...
Cover image for A guide on commit messages

A guide on commit messages

🦁 Yvonnick FRIN on January 29, 2020

The comic is from Daniel Stori. It is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License The time...
pic
Editor guide
Collapse
suckup_de profile image
Lars Moelleken

You can share your git commit conventions in the team via e.g.:

add this into your "~/.gitconfig"-file

[commit]
  template = ~/.gitmessage

example: github.com/voku/dotfiles/blob/mast...

Collapse
stephencweiss profile image
Stephen Charles Weiss

Just to confirm - this is a template, but does not act as a linter, correct? So, you could pair this with something like commitlint (github.com/conventional-changelog/...)

Collapse
yvonnickfrin profile image
🦁 Yvonnick FRIN Author

Waouh! Didn't know about it, thank you for sharing!

Collapse
iamschulz profile image
I am Schulz

If you work with Jira, It's also nice to prefix your commit with the ticket number, e.g.

XYZ-123: add the thing

That way you can easily navigate to the corresponding ticket and see why the change was made.

Collapse
stephencweiss profile image
Stephen Charles Weiss

I love linking like this, but it also proves problematic over time as teams move PM software and context is lost. For the most part, I'm trying to get in the habit of writing commits that include the sufficient context to explain why a change was made without relying on a ticket.

... definitely makes for longer commits though /shrug

Collapse
checkmatez profile image
Max

Maybe put ticket number in the footer of commit message? So it stays linked, but wouldn't clutter up git log since you can't tell at a glance what XYZ-123 means, when viewing git log output.

Collapse
yvonnickfrin profile image
Collapse
sneakycrow profile image
Zachary E. Sohovich

Checkout a package called commitzen. I've been using it professionally alongside Jira and it's made the commit messages very clean and meaningful.

In addition, utilizing a Changelog and proper versioning is super helpful.

Collapse
yvonnickfrin profile image
🦁 Yvonnick FRIN Author

Thank you for sharing about commitzen.

In addition, utilizing a Changelog and proper versioning is super helpful.

I could not agree more!

Collapse
vascoalramos profile image
Vasco Ramos

What a great article!

Usually, I do all my projects on my own, hence my commit habits and good practices are roughly none and this is felt when I work with other colleges in a team, like in a university project...

This article presents itself as an awesome way to start improving these collaboration skills!

Collapse
yvonnickfrin profile image
🦁 Yvonnick FRIN Author

Thank you!

Sure, side projects are a good way to practice. I try to pay attention on these details so it helps potential contributors πŸ‘Œ

It is easier to apply on professional work if it is already an habit πŸ‘

Collapse
tonivdv profile image
Toni Van de Voorde

Thanks for taking the time writing about this important topic. We also implemented a convention and at the time we were inspired by the following (old) blog post chris.beams.io/posts/git-commit/ . Combining this with some custom convention for the projects needs is very powerful!

Excerpt from the post:

A properly formed Git commit subject line should always be able to complete the following sentence:

If applied, this commit will your subject line here

For example:

  • If applied, this commit will refactor subsystem X for readability
  • If applied, this commit will update getting started documentation
  • If applied, this commit will remove deprecated methods
  • If applied, this commit will release version 1.0.0
  • If applied, this commit will merge pull request #123 from user/branch

Notice how this doesn’t work for the other non-imperative forms:

  • If applied, this commit will fixed bug with Y
  • If applied, this commit will changing behavior of X
  • If applied, this commit will more fixes for broken stuff
  • If applied, this commit will sweet new API methods

Remember: Use of the imperative is important only in the subject line. You can relax this restriction when you’re writing the body.

Collapse
epranka profile image
Edvinas Pranka

Great article, thanks! I always have problems with the commit messages. Especially in the new projects. So often it comes to:

rm -rf .git
git init
git commit -am "Initial commit"

:D

Thanks again :)

Collapse
yvonnickfrin profile image
🦁 Yvonnick FRIN Author

Glad it please you πŸ˜„

Collapse
jessekphillips profile image
Jesse Phillips

I really like the depth you decided to go. You had emphasized the value of the message and the explained how it added value to other tools.

I joined dev.to specifically to help get this point across.

Collapse
yvonnickfrin profile image
🦁 Yvonnick FRIN Author

Thank you for sharing. I definitely added your series in my reading list πŸ™Œ

Collapse
eyarz profile image
Eyar Zilberman

Great article!

The only part that I was missing and I would like to understand more on, is once you decide on your project commit message conventions, how do you verify everyone (including yourself) is following it?

BTW, funny story - I actually wrote a really similar post a few months ago:
datree.io/resources/git-commit-mes...

Collapse
vishnuharidas profile image
Vishnu Haridas

I have come across recommendations to write commit messages in present tense by some people and past tense by some other.

For example,

$git commit -m "Updated the search API to include search filters."
$git commit -m "Update the search API to include search filters."

Any preferences in the tense of the commit message?

Collapse
ginomempin profile image
Gino Mempin • Edited

In our project, we combine the conventions for branch naming and commit messages. Then we partially automate the commit message format with git hooks.

For example, our branches are commonly organized by ticket number and type. So, something like bug/#123/moduleA/crash-on-close. You can then setup a git commit hook that provides a template like this:

#123: bugfix: [Fixed ...]

[Details]

where #123 and bugfix are parsed from the branch name. You can also use git commit templates, but they are not as dynamic as git hooks.

Collapse
patarapolw profile image
Pacharapol Withayasakpunt • Edited

I wonder if it is safe, if it is ever done, to rename a commit message? -- help.github.com/en/github/committi...

One more wonder, is, how often should I commit?

Collapse
yvonnickfrin profile image
🦁 Yvonnick FRIN Author

It depends if someone or something depend on this commit identifier. Amending a commit and push force it will change the commit identifier.

In my opinion you should commit as often as possible. It will help you split your code πŸ‘Œ Keep in mind you must commit only working things. The first four points in the following article git-tower.com/blog/version-control... describe well what is a good commit πŸ‘

Collapse
jofisaes profile image
JoΓ£o Esperancinha

Really nice article! I really love the tips you gave and the convention examples you mentioned.

I think the gitmoji convention must bet a lot of fun to use, although I never used it professionally so far.

thanks for sharing! πŸ‘

Collapse
yvonnickfrin profile image
🦁 Yvonnick FRIN Author

Thank you, I use it on professional project. It really depends on your team and the common rules you commit to. In my opinion emojies are compatible with professional project since we already use it a lot in chatting tools at work πŸ˜„

Collapse
kironroy profile image
Kiron Roy

This a great article. I am also cleaning up my commit messages for this project SQL practice. I use Visual Studio's GitHub interface.

Collapse
yvonnickfrin profile image
🦁 Yvonnick FRIN Author

I think a well structured commit history helps potential contributors. Nice initiative!

Collapse
kironroy profile image
Kiron Roy

I only use GitHub to host my portfolio and maintain my C# page. Contributing to open source is my next step, so I need to write great commit comments

Collapse
ac000 profile image
Andrew Clayton

But will you remember why you made those changes in six months time?

Collapse
yvonnickfrin profile image
🦁 Yvonnick FRIN Author

If your stuff is open source I would recommend paying attention on your commit history if you want to attract some contributors πŸ˜„

Collapse
vuesomedev profile image
GΓ‘bor SoΓ³s

Conventional Gitmoji commits the missing part 🐳

Collapse
yvonnickfrin profile image
🦁 Yvonnick FRIN Author

You can't be more right!

Collapse
sudo_kaizen profile image
Orim Dominic Adah

Husky has something to offer here. It can help automate these things

Collapse
yvonnickfrin profile image
🦁 Yvonnick FRIN Author

Sure, automate this kind of checks is nice πŸ‘

Collapse
shanadinacaroti profile image
Shana Dina Caroti • Edited

Thanks for Sharing! IΛ‹m looking forward to use your guiding tips in my future projects! ☺️

Collapse
yvonnickfrin profile image
Collapse
tbetous profile image
Thomas Betous

Great article ! Well documented with great sources !

Collapse
yvonnickfrin profile image
🦁 Yvonnick FRIN Author

Thanks Thomas for your review πŸ™