Opinionated-commit-message is a GitHub Action which checks commit messages according to an opinionated style.

The style was inspired by https://chris.beams.io/posts/git-commit/:

• Separate subject from body with a blank line
• Limit the subject line to 50 characters
• Capitalize the subject line
• Do not end the subject line with a period
• Use the imperative mood in the subject line
• Wrap the body at 72 characters
• Use the body to explain what and why (instead of how)

Here is an example commit message:

Set up Open ID HttpClient with default proxy

Previously, the Open ID HttpClient was simply instantiated without 
default proxy credentials. However, if there are company proxies,
HttpClient must use the default proxy with OpenID Connect.

There exist a good action to check commit messages, commit-message-checker (https://github.com/GsActions/commit-message-checker). However, it is limited to regular expressions which makes more complex checks (such as imperative mood) hard or impossible to implement.

I based my implementation heavily on commit-message-checker and would like to thank the author for the great work!

You can set up a GitHub workflow to automatically check messages. Put the following file in .github/workflows/check-commit-message.yml and GitHub should pick it and set it up.

name: 'Check commit message style'
on:
  pull_request:
    types:
      - opened
      - edited
      - reopened
      - synchronize
  push:
    branches:
      - master
      - 'dev/*'

jobs:
  check-commit-message-style:
    name: Check commit message style
    runs-on: ubuntu-latest
    steps:
      - name: Check
        uses: mristin/opinionated-commit-message@v2

Opinionated-commit-message verifies commit messages on the GitHub events pull_request and push.

In the case of pull requests only the title and the body of the pull request are checked.

On push, all the commit messages of the push are verified.

Since the subject needs to start with a verb in the imperative mood, we pre-compiled a whitelist of most frequent English verbs together with verbs frequently used in commit messages from our own projects.

However, given the variety of projects in the wild, this whitelist is not sufficient to cover all the possible verbs. We therefore introduce the action input additional-verbs so that you can add your own verbs.

The additional verbs are given as a comma, semicolon or new line separated string in the workflow file. For example:

    steps:
      - name: Check
        uses: mristin/opinionated-commit-message@v2
        with:
          additional-verbs: 'chrusimusi, unit-test'

If you prefer to have your additional verbs in imperative mood in a separate file (e.g., to keep the workflow file succinct), you can supply the path as input:

    steps:
      - name: Check
        uses: mristin/opinionated-commit-message@v2
        with:
          path-to-additional-verbs: 'src/additional-verbs.txt'

Splitting URLs on separate lines to satisfy the maximum character lenght breaks the link functionality on most readers (e.g., in a terminal or on GitHub). Therefore we need to tolerate long URLs in the message body.

Nevertheless, in order to make the text readable the URL should be put either on a separate line or defined as a link in markdown.

For example, this is how you can write a message with an URL on a separate line:

Please see this page for more details:
http://some-domain.com/very/long/long/long/long/long/long/long/long/long/path.html
or read the manual.

Here is the same message with a link definition (arguably a bit more readable):

Please see [this page for more details][1] or read the manual.

[1]: http://some-domain.com/very/long/long/long/long/long/long/long/long/long/path.html

Usually, you need to write elaborate commit messages with a shorter header and more verbose body for an informative Git history. However, this might be too rigid for certain projects.

You can allow one-liner commit messages by setting the flag allow-one-liners:

    steps:
      - name: Check
        uses: mristin/opinionated-commit-message@v2
        with:
          allow-one-liners: 'true'

We translated the opinionated-commit-message to a powershell script so that you can include it in your local pre-commit and pre-push checks.

The script is available at: local/powershell/OpinionatedCommitMessage.ps1

You can just copy & paste it into your project. There are no dependencies to be installed.

Commit messages of the pull request are not verified unless you trigger the workflow on the push as well. GitHub does not include the content of commit messages in the context payload, so checking all the commit messages of the pull request would involve various API call and additional complexity.

To overcome this issue, run opinionanted-commit-message both on pull_request and push. Please upvote this issue to signal the visibility and so that we could judge when this feature merits the effort.

If you would like to report bugs or request a feature, please create a new issue.

Please see CONTRIBUTING.md if you would like to contribute to the code.

This project is released under the terms of the MIT License.