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:¶

Option 2: pipe the message to cz check:¶

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

Command Line Options¶

--rev-range¶

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

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.

--message¶

Test if a given string passes cz check.

--commit-msg-file¶

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

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

--allow-abort¶

Example:

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!

For example,

--message-length-limit¶

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

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