Your commit message sucks

Does this look familiar?

$ git log --oneline

3c80736 session tests  
d6dbe2e small update to test  
7ce13fb add mockery as a dev dependency  
4b61990 update namespace  
811b01b use new flash messages implementation  
1d2632d remove twig comment  
6803457 create test for example form validator  
d44f7bf fix tabbing  
3d8d097 extend the laravel session class  
a63d0e4 created form validator classes  
2cfbfe4 rewrite of flash messages twig handling  

It probably does.

As the lines are printed to your terminal you start to feel the vein on the side of your head protrude and you immediately switch back to your browser and open YouTube.

Maybe laughing at children falling over and crashing into glass windows will make me feel better you think to yourself.

Maybe there is more information if I just do this:

$ git log

commit 2cfbfe4160731ef4908443bdcad9c0cc1b6a2035  
Author: XXXX XXXX <[email protected]>  
Date:   Wed Nov 13 21:16:12 2015 +1100

    rewrite of flash messages twig handling

commit b97e3970da3505d18236516317035f6bfb65f589  
Author: XXXX XXXX <[email protected]>  
Date:   Wed Nov 13 13:06:49 2015 +1100

    test bug

commit 692e41f07c195a3f9368976dca4e12fc23705e1f  
Author: XXXX XXXX <[email protected]>  
Date:   Wed Nov 13 13:01:07 2015 +1100

    created tests for data class

How about one from a popular open source project?

$ git log --oneline

87c0908 increment version  
5f27020 Merge pull request #12709 from vlakoff/class  
67abe0a Merge pull request #12713 from mustafaaloko/patch-1  
694d164 Code style  
56bc6f8 Mention array in mail recipients docstrings  
e8c0d70 Make use of static::class  
bdbc2a4 Merge pull request #12613 from sileence/feature/5.2/blade_literals  
dbcb4ab Merge pull request #12638 from vlakoff/arrays-2  

If I'm tending to your pull request, trying to fix a bug or contributing to your open source project I want to be armed with as much information as possible.

Does this look a little better?

$ git log --oneline

577f708 fix(web-messages): Display minutes when concierge call scheduled  
6d92a74 fix(web-concierge): Fix automated messages when scheduling call  

...and with a bit more information:

$ git log

commit 577f7089a7d2d684cf24c13d1f31f4e5d1d539be  
Author: Jared Mooring <[email protected]>  
Date:   Wed Sep 16 16:23:12 2015 +0100

    fix(web-messages): Display minutes when concierge call scheduled

    The message sent to concierge and client when a call was scheduled was not including the minutes. It now does.

    [QA]:
    Has unit tests: Yes
    Reviewed by: Angel P

    [TRELLO]:
    https://trello.com/c/XXX-XXX

commit 6d92a749ffaaff7dfa095f8ea68a12061587e12b  
Author: Jared Mooring <[email protected]>  
Date:   Wed Sep 16 14:02:07 2015 +0100

    fix(web-concierge): Fix automated messages when scheduling call

    This is to fix Commit #0d84995465932b7ab4fe1a88ffaa0f9dfffb3c5a missing this code. For some reason it was lost.

    The message that is sent to a client once a call has been scheduled has been changed to reflect a much better tone. It includes specifics around the call.

    A push notification is also sent to the concierge. It's pretty dull though 'X has sent you a message'.

    [QA]:
    Has unit tests: Yes
    Reviewed by: Angel P

    [TRELLO]:
    https://trello.com/c/XXX-XXX

It's verbose, I can see the commit has unit tests, I can see it was reviewed, oh and look, I can also go to the ticketing system to see the origin of this issue.

The extra time needed to formulate such a commit is negligent when you consider value.

Make life easier and add a commit template:

<type>(web/api/admin-<component>): <subject>

# More detailed explanatory text, if necessary.  Wrap it to
# about 72 characters.  Please make sure to put some
# effort in to making this descriptive enough for others
# to read and understand.


[QA]:
Has unit tests:  
Reviewed by:

[YOUR_TICKETING_SYSTEM]:

# More information here:
# https://pootle.in/your-commit-messages-suck

Adding the template is easy:

$ git config commit.template /location/to/your/template.txt

Filling in the template

  1. Configure your project to use the above template
  2. Try to be as verbose as possible. I know that sometimes it's a pain, but please try.
  3. It's okay to put NIL against items where they do not apply.

Message subject (first line)

First line cannot be longer than 70 characters, second line is always blank and other lines should be wrapped at 80 characters. The type and
scope should always be lowercase.

Allowed <type> values

  • feat (new feature for the user)
  • fix (bug fix for the user)
  • docs (changes to the documentation)
  • chore (updating config files etc)

Web/API/Admin/Whatever

This just helps narrow down the search. Was this change part of the admin section? Was it part of the API?

Component

The component pertains to something specific in your app. Maybe you're working on registration, analytics,user profile, whatever. It's a specific component within your app and product.

Try not to leave the component blank. It can help when skimming through commits.

Here's an example:

  • fix(api-registration) This is a bugfix for the registration section of the API.
  • docs(api-account) This is API documentation for the users account.
  • feat(web-frontpage) This a new feature for the websites frontpage.
  • fix(web-faqs) - This is a bugfix to the FAQ's on the website.

Message Body

Includes motivation for the change and contrasts with previous behavior For more info about message body, see:
http://365git.tumblr.com/post/3308646748/writing-git-commit-messages http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

QA

Has Unit Tests: yes/no.
Reviewed By: or NIL.

Your ticketing system

If you're using something like GitHub and a modern ticketing system (Jira / Sprintly for example) you have the advantage of being able to update those tickets directly through your commit message (one they are pushed to remote/origin).

Here's an example of a commit message that updates Jira. It'll update TASK-1882 to be in a new state on the Kanban board, as well as adds a comment:

fix(web-matches): Too many matches being generated

The daily matches algorithm was not taking into consideration  
the offset between existing matches and the total amount  
of matches to generate when a user had a larger number of  
friends on network.

[QA]:
Has unit tests: Yes  
Reviewed by: Jared Mooring

[JIRA]:
TASK-1882 #ready-to-test-on-stage #comment This is now ready being built on  
staging.  

Want to see some incredible commit messages? Take a look at the linux kernel: https://github.com/torvalds/linux

In closing, take the extra time to put together a nice commit message.

Further reading:

Jared

Read more posts by this author.

London