git

Write A Good Git Commit Message

Matt 2021/04/28 15:21:04
44

Why Using Good Git Commit Messages ?

What for ?

Good commit messages are so important for people who works / codes together, or even yourself couple months after. People could understand quickly by reading the commit messages, what changes on the project.

And, what is Good Commit Messages, could we define that ? Yes, sure, here are some great templates, we could reference. And now, there is a great commit message template that many programmers recommend this kind of template from Udacity Git Commit Message Style Guide.

Commit message example

img "good commit messages example"

Another example shown on my favorite git gui.

img "another example shown on git gui"

Describe

A Good commit message should contain FOUR parts:

  1. The Type

    a type can be one of these types,

    1.1 feat: a new feature

    1.2 fix: a bug fix

    1.3 docs: Changes to documentation

    1.4 style: Formatting, missing semi colons, etc., no code change

    1.5 refactor: Refactoring production code

    1.6 test: Adding tests, refactoring test; no production code change

    1.7 chore: Updating build tasks, package manager configs, etc., no production code change

  1. The Subject

    A subject should be as short as you can, describe all these changes in 50 characters, also should being with a capital letter. Plus, it should NOT be end with a period (.).

  2. The Body (optional)

    A body is written to explain what a why changes you made. But not all commits are so complex to write a description. Some insignificant changes might not be described.

    A blank line between the body and the subject is required and each line should be in 72 characters, and it should start with hyphen/dash (-) to clarify them.

    We could treat message body as changelog.

  3. The Footer (if necessary)

    The footer is optional and is used to reference issue tracker IDs. Or, we could also make some additional notes for the changes.

    In my opinion, sometimes I would like to set a app version to track an app for publishing, such as App_name_android #4.5.1

Why I Will Use ?

We usually follow the git flow rules to create branches. It can help us cutting a needed function to several parts to deal with.

img "次元切割刀"

A branch will contain its type, sometimes maybe include a scope, too. And a brief change as its subject. It might look like: feature/dev/notifications/control-center-to-clients.

A separated function part could be worked easily for us. With a good branching model that follow git-flow rules, the commit message could be shorten to a reasonable scope, and its content also can be short as possible.

Enjoy it.


Pictures came from:

https://imgur.com/nFTxKmg

https://digitalvarys.com/git-branch-and-its-operations/


References:

Udacity Git Commit Message Style Guide

How to write a good commit message

How to Write Good Commit Messages: A Practical Git Guide

Patterns for writing better git commit messages

GitFlow

A successful Git branching model

git-flow cheatsheet

如何写好提交注释

Matt