check

This feature checks whether a string or a range of git commits follows the given committing rules. Comments in git messages will be ignored.

To set up an automatic check before every git commit, please refer to Automatically check message before commit.

Usage

More specifically, there are three mutually exclusive ways to use cz check:

• Validate a range of git commit messages with --rev-range
• Validate a given string with --message or by piping the message to it
• Validate a commit message from a file with --commit-msg-file

Use cz check to validate a commit message before committing

Option 1: use --message to check a given string:

cz check --message <message_to_be_checked>

Option 2: pipe the message to cz check:

echo <message_to_be_checked> | cz check

Option 3: use --commit-msg-file to read the commit message from a file

cz check --commit-msg-file /path/to/file.txt

Command Line Options

--rev-range

Test if a given range of commits in the git log passes cz check.

cz check --rev-range REV_RANGE

For more information on REV_RANGE, check the git documentation.

Use cases

1. Validate the latest 3 commit messages:

   cz check --rev-range HEAD~3..HEAD
   # or
   cz check --rev-range HEAD~3..
   # or
   cz check --rev-range HEAD~~~..
   

2. Validate all git commit messages on some branch up to HEAD:

   cz check --rev-range <branch_name>..HEAD
   

   For example, to check all git commit messages on main branch up to HEAD:

   cz check --rev-range main..HEAD
   

   or if your project still uses master branch:

   cz check --rev-range master..HEAD
   

   Default branch

   Usually the default branch is main or master. You can check the default branch by running cz check --use-default-range.

3. Validate all git commit messages starting from when you first implemented commit message linting:

   (Why this is useful?) Let's say you decided to enforce commit message today. However, it is impractical to git rebase all your previous commits. --rev-range helps you skip commits before you first implemented commit message linting by using a specific commit hash.

   cz check --rev-range <first_commit_sha>..HEAD
   

--use-default-range

Equivalent to --rev-range <default_branch>..HEAD.

cz check --use-default-range
# or
cz check -d

--message

Test if a given string passes cz check.

cz check --message <message_to_be_checked>

--commit-msg-file

Test if a given file contains a commit message that passes cz check.

cz check --commit-msg-file <path_to_file_containing_message_to_be_checked>

This can be useful when cooperating with git hooks. Please check Automatically check message before commit for more detailed examples.

--allow-abort

Example:

cz check --message <message_to_be_checked> --allow-abort

Empty commit messages typically instruct Git to abort a commit, so you can pass --allow-abort to permit them. Since git commit accepts the --allow-empty-message flag (primarily for wrapper scripts), you may wish to disallow such commits in CI. --allow-abort may be used in conjunction with any of the other options.

--allowed-prefixes

Skip validation for commit messages that start with the specified prefixes.

If not set, commit messages starting with the following prefixes are ignored by cz check:

• Merge
• Revert
• Pull request
• fixup!
• squash!
• amend!

cz check --message <message_to_be_checked> --allowed-prefixes 'Merge' 'Revert' 'Custom Prefix'

For example,

# The following message passes the check because it starts with 'Merge'
cz check --message "Merge branch 'main' into feature/new-feature" --allowed-prefixes 'Merge'

# The following fails
cz check --message "Merge branch 'main' into feature/new-feature" --allowed-prefixes 'aaa'

--message-length-limit

Restrict the length of the first line of the commit message.

# The following passes
cz check --message "docs(check): fix grammar issues" -l 80

# The following fails
cz check --message "docs:very long long long long message with many words" -l 3

By default, the limit is set to 0, which means no limit on the length.

Note

Specifically, for ConventionalCommitsCz the length only counts from the type of change to the subject, while the body and the footer are not counted.