Patterns for writing better git commit messages
#git#github
Helder Burato Berto

Helder Burato Berto @helderberto

About: Software Engineer who loves to craft challenging projects and share knowledge with people.

Location:
Portugal
Joined:
Oct 15, 2017

Patterns for writing better git commit messages

Publish Date: Sep 10 '20
275 41

It's an opinionated guide I keep with me to consult every time I catch myself in doubt if I'm writing nice commit messages with context of what I'm delivering.

A good commit should complete the following sentence

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>

Commit Sample

See an example of commit below:

[type](optional scope): [subject]

[optional body]

[optional footer]
Enter fullscreen mode Exit fullscreen mode

Types

Must be one of the following:

  • build - Build related changes
  • ci - CI related changes
  • chore - Build process or auxiliary tool changes
  • docs - Documentation only changes
  • feat - A new feature
  • fix - A bug fix
  • perf - A code change that improves performance
  • refactor - A code change that neither fixes a bug or adds a feature
  • revert - Reverting things
  • style - Markup, white-space, formatting, missing semi-colons...
  • test - Adding missing tests

Scope

A scope may be provided to a commit’s type, to provide additional contextual information and is contained within parenthesis, e.g., feat(parser): add the ability to parse arrays.

Subject

The subject contains a succinct description of the change:

  • Use the imperative, present tense: "change" not "changed" nor "changes"
  • No dot (.) at the end.

Body

Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior.

The 7 rules of a great commit message:

  1. Separate subject from the body with a blank line
  2. Limit the subject line to 50 characters
  3. Summary in the present tense. Not capitalized.
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how

Commit Template

Go to my git commit template

References

Comments 41 total

  • Karran Besen
    Karran BesenSep 10, 2020

    Really useful article! I end up not focusing on the commit messages as much as I should. I'll try to follow these rules from now on.

  • duncan-dubblecloud
    duncan-dubblecloudSep 10, 2020

    Great article.

  • Bruno Mariano
    Bruno MarianoSep 11, 2020

    Very nice! Parceiro.

  • Lawson
    LawsonSep 11, 2020

    Great

  • Jannik Wempe
    Jannik WempeSep 11, 2020

    Great, thanks. I personally would appreciate 2-3 examples for clarification 😊

    • Helder Burato Berto
      Helder Burato BertoSep 11, 2020

      Nice to know that! I'll share more examples to clarify.
      Thanks for your reply.

  • Bill Raymond
    Bill RaymondSep 11, 2020

    These are great ideas. Could you consider a post with some solid examples to go with these practices?

  • Andrew Baisden
    Andrew BaisdenSep 12, 2020

    Good article thanks for sharing these tips.

  • Vishnu Haridas
    Vishnu HaridasSep 12, 2020

    Good ideas. Adding examples will be good to see.

    Here are my rules that I stick on to:

    • Use simple present - Update login button to use the new API
    • Begin fixes with "Fix" and include ticket number if possible - Fix #234: User cannot log in with email
    • If pausing the work today and planning to continue tomorrow, start with [WIP] (Work-In-Progress) - [WIP] improving the login process
    • Begin temporary commits (usually for testing out something) with [TEMP] - [TEMP] add a temporary logout button
    • Helder Burato Berto
      Helder Burato BertoSep 12, 2020

      Nice tips!
      The unique one I try to maintain in the body is the ticket ID because in my case it's just to be tracked in Jira and isn't to be shown.

  • Bengt Brodersen
    Bengt BrodersenSep 12, 2020

    I absolutely agree to your approach. I've created a highly configurable commit message checker to ensure the right format and valid types and scopes. See github.com/qoomon/git-conventional....

  • Héctor Iván Patricio Moreno
    Héctor Iván Patricio MorenoSep 12, 2020

    Great article! Would you mind if I translate this to Spanish in my blog?

    • Helder Burato Berto
      Helder Burato BertoSep 12, 2020

      I really appreciate that, no problem, just mention the original post. :)

  • Chang-Woo Rhee
    Chang-Woo RheeSep 12, 2020

    Cool!
    I was add "ed" to type word
    ex1) Fixed pagination gem bug
    ex2) Changed pagination1 gem to pagination2 gem
    i think your format is pretty and cool

  • Ali Ghali
    Ali Ghali Sep 13, 2020

    good to know, I am always curios to know how other people use git commits, isn't your approach (Angular convention)?
    -BTW I checked your github, looks that you don't use your idea that much, is there cases where you think it's too much to nail a uniform commits?

    • Helder Burato Berto
      Helder Burato BertoSep 14, 2020

      Thanks for the reply.
      I commonly use the conventional rules, I think it's the same used as the angular convention.

      In a repository like my dotfiles I keep in a different way, because I'm not working with a team and organize the commits based in the scopes without types, considering it's just me in the project I make a commits pattern that works for me, but it's very personal.

  • Em Ji Madhu
    Em Ji MadhuSep 15, 2020

    It was a great article. And it's informative. If you want to do it in gui and add emoji support too. I would recommend this vscode plugin

    marketplace.visualstudio.com/items...

    I have been using this extension for an year and is awesome.

    • Helder Burato Berto
      Helder Burato BertoSep 15, 2020

      Thanks for the suggestion!
      Some months ago I started using the Emacs + Magit and IMO it's awesome to use together.

  • Josh Martens
    Josh MartensSep 16, 2020

    Verb tense in commit messages is always a fun one, and each "tense" has a reason (IMO.. comment away but I'm not passionate enough to debate)

    Past: What happened to the code, good for merge
    Present: Current state of the code, middle-ground for merge/PR
    Future: What will happen to the code, good for PR

  • perpetual . education
    perpetual . educationSep 16, 2020

    We like to think:

    "Derek was trying to ____________________________."

    But our projects are green-field and not toooo crazy.

    add the user-card component
    adjust loud-voice clamp
    add padding to the page-header component

    • jacekgajek
      jacekgajekSep 16, 2020

      I've created an account to give a like. This comment gave a good laugh; when I read it I initially though that the pattern is literally "Derek was trying to ____________________________."... if you know what I mean. ;)

    • Helder Burato Berto
      Helder Burato BertoSep 16, 2020

      Thanks for the reply and I really enjoy this pattern you talked about.

    • sheriffderek
      sheriffderekSep 16, 2020

      My name is Derek - and I approve this git message. hahaha

      I think we started doing this because / well, we just wanted to be consistent. So - we read somewhere that people use "imperative voice" or something...

      But it wouldn't be the first time we decided to do something a certain way and then changed it... so, always looking for "THE BEST" way. ha! Always trying to improve... but we can lazy-load it.

  • jacekgajek
    jacekgajekSep 16, 2020

    I's a nice idea to write good commit messages... but in the case of simple tasks it becomes more like "fix #851" which is picked by Jira or other tool automatically... so you can click on a message (if you use an IDE) and it takes you to the description.

    One could copy the subject and description from Jira, but sometimes the fix is simple (like change + to - somewhere), but the bug is so weird that it's impossible to fit it in a commit message which wouldn't end up being cryptic. For example, in a situation when elephant extinction level goes down and it is a full moon, timestamps are shifted by a millisecond in systems which have an odd IP number.

  • Thomas Gotwig
    Thomas GotwigSep 16, 2020

    Don't forget to put an Emoji at the start of each commit 🧐🤪🚀

  • markestrada8
    markestrada8May 23, 2022

    I'm trying to get the flow of this down atm, and I was wondering how these should be written. It makes sense, although I feel like to learn github you should really be on two computers at once, but as commits show up, this is a description of what a merge will do to your code base.

Add comment