Bad git commit messages?

How many times as a software engineer have you struggled with maintaining a clean and meaningful git history?

We all know that a diff will let us know what changed in a commit, but only the commit message can tell us why.

Unfortunately commit messages are overlooked and we write very short commit messages in our projects:

git commit -m "wip"

Over time those commit messages will become an issue for anyone who will look for information.

Can we write better commit messages? Yes... Moreover, we can automatically check that a message follows specific conventions with the help of a 'pre-commit' hook.

How does it work? Check out Conventional Commits, in the same way as there are standards on how to name variables, this is a standard on how to write git messages. Following conventions would allow automated tools to process commits; for example to lint commits, help you write them or even generate changelogs and manage versioning.

Conventional Commits by default would check a git message for the following structure:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Examples of valid messages:

git commit -m "feat(admin dashboard): add burndown chart"

git commit -m "feat(admin dashboard): add collapsible sidebar (PROJ-21)"

git commit -m "fix: add missing check for null"

git commit -m "build: update dependencies"

git commit -m "refactor: extract method"

git commit -m "style: change background color on hover"

Who is already using it? Angular, Electron, Vue

A well written git commit message would be the best way to express the context of the changes to other team members, but also to your future self.

Irrespective of the team size using conventional commits would bring advantages to your project and would give the team a solution to the often mistake of writing meaningless or unstructured commit messages.

If you use Node.js in your project integrating conventional commits is simple and straightforward using their commitlint packages, check out this official guide.

Related tools: VSCode Conventional Commits, semantic-release

Bonus, if you want to reference Jira tickets check out the following configuration for 'package.json':

  "commitlint": {
    "extends": [
      "@commitlint/config-conventional"
    ],
    "rules": {
      "references-empty": [
        2,
        "never"
      ]
    },
    "parserPreset": {
      "parserOpts": {
        "issuePrefixes": [
          "PROJ-"
        ]
      }
    }
  }

The above configuration would pass the validation of the following messages:

git commit -m "PROJ-17 feat(pencil): add 'graphiteWidth' option"

git commit -m "feat(pencil): add 'graphiteWidth' option (PROJ-17)"