Any rules, tips and tricks for commit message
#vcs#git#tips#discuss
JeffD

JeffD @cotcotcoder

About: Code-quality 🩺 Teamwork 🐝 & everything that can simplify the developper's life 🗂️.

Location:
France
Joined:
Oct 16, 2017

Any rules, tips and tricks for commit message

Publish Date: Oct 16 '17
17 14

Reading commit messages is a great way to understand software evolution without reading all the code.

I use the following rule:

  • start with an action verb: Add, Fix, Remove, Update, Refactore...
  • include the concerned domain (if != code): test, documentation, config, scripts...
  • a description to explain the "Why?" or "How?"
  • and a reference to ticket or bug

To obtain:

  • Fix tests for Linux platform: filesystem was hardcoded - #123
  • Add configuration: support article pagination - #345
  • Refactore customer subscription service to improve performance - #898

And you, do you use any rules to write better commit message in your company or open source project ?

Comments 14 total

  • zeh fernando
    zeh fernandoOct 16, 2017

    I don't use Angular, but I practice something similar to Angular's commit message conventions:

    <type>(<scope>): <subject>

<body>

<footer>
    Enter fullscreen mode Exit fullscreen mode

    Makes it easy to create logs out of it, too.

    You can check examples in their commit log.

  • Ben Halpern
    Ben HalpernOct 16, 2017

    Solid rules of thumb you've, thanks.

    I'll note that commit messages are also something you may search for in the future, so conducting your own mini-SEO by thinking about keywords you or some other future person might think of is a plus.

  • Sergey Kislyakov
    Sergey KislyakovOct 16, 2017
    <named part of a program>: <verb in P.S.> <message>[; fixed #1234]

[body]
    Enter fullscreen mode Exit fullscreen mode

    E.g.

    UI: changed button's color from blue to red; fixed #42

Red goes faster!
    Enter fullscreen mode Exit fullscreen mode
  • Rachel Breeze
    Rachel BreezeOct 16, 2017

    No swearing - we've had to give a dump of commits to a client previously.
    No insults (self deprecating or otherwise) - or jokes - yes work should be fun but you just look unprofessional.
    Reference the right ticket and we tend to put them first to make it easier to scan.
    Try to avoid typos
    Always write the commit so that you in a weeks time understands why they made the change (rather than what was changes)
    Also compare individual file changes - don't bulk commit.
    Only fix/create one thing between commits
    Make sure that the commit compiles and works before commiting

  • Pratik Ambani
    Pratik AmbaniOct 17, 2017

    For Jira Users:
    Don't forget to prefix your commit message with Jira Ticket ID.
    You can view the same activity on Jira later on...

    Ex:
    MV-1234 added mySampleModule

    • emptyother
      emptyotherOct 17, 2017

      No need to prefix, you can add Jira's ticket id to the commit body instead. Useful if you prefer to keep the commit title length below 80 characters.

      • Pratik Ambani
        Pratik AmbaniOct 18, 2017

        Okay!! I tried once after comma,using below mentioned format but it didn't work. #needInputs

        Ex. removed unRequiredModule, MV-1235 added actual implementation

        • emptyother
          emptyotherOct 18, 2017

          I do it like this, and Jira seems to be able to pick it up:

          (commit title, 74 characters max)

(commit body, one or more paragrahps)
MV-1234
          • Pratik Ambani
            Pratik AmbaniOct 20, 2017

            Taken, I'll try. Thanks for correcting :)

  • Tony Diaz
    Tony DiazOct 17, 2017

    My project enforces the structure of the commit message using githooks. The packages we use to enforce the commit message are validate-commit-msg (npmjs.com/package/validate-commit-msg) along with husky (npmjs.com/package/husky)

    It follows the Angular's commit message convention since validate-commit-msg was developed by some of their contributors.


    <type>(<scope>): <subject>

  • Jacob Tan 🤓
    Jacob Tan 🤓Oct 17, 2017

    I used this when I'm working with JIRA, [Ticket ID] : [Descriptive message of what the commit fixes]

  • Zizaco
    ZizacoOct 17, 2017

    From the CONTRIBUTING.md of our current project:

    Ideally, the commits should be as small and descriptive. As the user stories, the commits should ideally clarify what is it's purpose. A way to do that is to answer to this 4 questions:

    • To which story does it belongs? (story id)
    • How does it address the issue? ("updated", "added", "implemented", "removed", etc)
    • Why is this change necessary? ("to", "in order to", )
    • What side effects does this change have? ("from now on ...")

    With this in mind, no commit message should be less than 50 characters and should contain more than one line. This is not a strict rule, but by following the structure:

    <id> - <how> <why> <side-effects>

    It becomes easy to write more than 50 characters. For example:

    h3C2s4HX - Updated user/User entity in order to properly validate it's attributes.
From now on if the validation is made before saving it to the database.

    "Having a story in your git log will make a huge difference in how you and others perceive your project. By taking great care in commit messages, as you do in your code, you will help to increase overall quality." - Caleb Thompson

  • emptyother
    emptyotherOct 17, 2017

    The best tool ever to create a neutral and understandable commit message is this sentence: "If you apply this commit to your code, it will [this part becomes the commit title]".

    I try to keep the title length below 74 characters, and try to remove words like "the" from it. Then a blank line, then the commit body in one paragraph, no line breaks, describing in better detail what and why the commit. Then the Jira issue ID on the last line.

  • Anton Frattaroli
    Anton FrattaroliOct 17, 2017

    [fix|chore|refactor|feat]: [title of work item that was addressed]

Add comment