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/[email protected]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/[email protected]
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/[email protected]
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/[email protected]
with:
allow-one-liners: 'true'For use in terminals and monospaced GUIs it is a good practice to limit length of the subject to 50 characters.
For some projects, though, this limit is too restrictive.
For example, if you include tags in the subject (such as [FIX]) there is not much space left for the actual subject.
You can change the imposed maximum subject length by setting the flag max-subject-line-length:
steps:
- name: Check
uses: mristin/opinionated-commit-message@v2
with:
max-subject-line-length: '100'Similar to the subject line, for terminals and monospaced GUIs it is a good practice to limit the line length of the body to 72 characters. However, the restriction is unnecessarily harsh for teams that use modern GUIs such as GitHub Web. This is especially so when using a description of the pull request as the body, since there is no such limitation in the GitHub UI itself.
You can change the imposed maximum line length by setting the flag max-body-line-length:
steps:
- name: Check
uses: mristin/opinionated-commit-message@v2
with:
max-body-line-length: '100'For some repositories only the subject matters while the body is allowed to be free-form. For example, this is the case when the body of the commit is automatically generated (e.g., by a third-party service that we do not control). In such situations, we want check the subject line, but ignore the body in the checks.
You can disable checking the body by setting the flag skip-body-check:
steps:
- name: Check
uses: mristin/opinionated-commit-message@v2
with:
skip-body-check: 'true'When triggered by a pull_request event, the action checks the title and the
body of the pull request by default. GitHub does not include the content of the
commit message in the workflow context, so checking all the commit messages of
the PR requires additional API calls. If you want to check the commit messages
for pull requests you can either:
- Trigger the action on
pushevents. This will check the commit messages of each pushed commit, but it will run even for branches that do not have a PR associated with them. - Set the
validate-pull-request-commitsoption totrue. This will check the messages of every commit in the PR. However, because it requires extra API calls to retrieve the commit messages, setting this on option on private repositories require a GitHub token with at leastreadpermission on thecontentsscope.
steps:
- name: Check
uses: mristin/[email protected]
with:
validate-pull-request-commits: 'true'
# Required for private repos
github-token: ${{ secrets.GITHUB_TOKEN }}The default permissions for a GitHub Actions workflow is sufficient for this action to work. You only need to check permissions if you are already customizing the permissions of the workflow See the GitHub documentation.
jobs:
check-commits:
# If you have this line,
permissions:
# Make sure this you also have this line
contents: read
steps:
- uses: mristin/[email protected]
with:
validate-pull-request-commits: 'true'
github-token: ${{ secrets.GITHUB_TOKEN }}Most projects do not require a sign-off on the commits. However, there are projects which need every commit to be signed off to avoid legal, safety and other official repercussions (for more information, see this issue and this StackOverflow question).
We provide an enforce-sign-off flag so that you can enforce the sign-off in the commits by:
steps:
- name: Check
uses: mristin/[email protected]
with:
enforce-sign-off: 'true'The check expects that the body of the commit contains one or more lines like this one:
Signed-off-by: Some Body <[email protected]>
You usually sign off the commits using git commit --signoff.
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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent