From 6751cca9b16c44b2220ff95fabb55776b891d971 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Fri, 5 Dec 2025 00:06:38 +0800 Subject: [PATCH] docs(check): rewrite command document --- docs/commands/check.md | 151 ++++++++++++++++++++++++++++++----------- docs/config.md | 4 +- 2 files changed, 112 insertions(+), 43 deletions(-) diff --git a/docs/commands/check.md b/docs/commands/check.md index 320bffb88..ef7f8f5f9 100644 --- a/docs/commands/check.md +++ b/docs/commands/check.md @@ -1,95 +1,164 @@ -# 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. -## About - -This feature checks whether the commit message follows the given committing rules. Comments in git messages will be ignored. - -If you want to set up an automatic check before every git commit, please refer to -[Automatically check message before commit](../tutorials/auto_check.md). +To set up an automatic check before every git commit, please refer to [Automatically check message before commit](../tutorials/auto_check.md). ## Usage ![cz check --help](../images/cli_help/cz_check___help.svg) -There are three mutually exclusive ways to use `cz check`: +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: + +```bash +cz check --message +``` + +#### Option 2: pipe the message to `cz check`: +```bash +echo | cz check +``` + +#### Option 3: use `--commit-msg-file` to read the commit message from a file +```bash +cz check --commit-msg-file /path/to/file.txt +``` -- with `--rev-range` to check a range of pre-existing commits -- with `--message` or by piping the message to it to check a given string -- or with `--commit-msg-file` to read the commit message from a file +## Command Line Options -### Git Rev Range +### `--rev-range` -If you'd like to check a commit's message after it has already been created, then you can specify the range of commits to check with `--rev-range REV_RANGE`. +Test if a given range of commits in the git log passes `cz check`. ```bash -$ cz check --rev-range REV_RANGE +cz check --rev-range REV_RANGE ``` -For example, if you'd like to check all commits on a branch, you can use `--rev-range master..HEAD`. Or, if you'd like to check all commits starting from when you first implemented commit message linting, you can use `--rev-range ..HEAD`. +For more information on `REV_RANGE`, check the [git documentation](https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection#_commit_ranges). + +#### Use cases + +1. Validate the latest 3 commit messages: + ```bash + cz check --rev-range HEAD~3..HEAD + # or + cz check --rev-range HEAD~3.. + # or + cz check --rev-range HEAD~~~.. + ``` -You can also use `--use-default-range` to check all commits from the default branch up to HEAD. This is equivalent to using `--rev-range ..HEAD`. +1. Validate all git commit messages on some branch up to HEAD: + ```bash + cz check --rev-range ..HEAD + ``` -For more information on how git commit ranges work, you can check the [git documentation](https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection#_commit_ranges). + For example, to check all git commit messages on `main` branch up to HEAD: + ```bash + cz check --rev-range main..HEAD + ``` -### Commit Message + or if your project still uses `master` branch: + ```bash + cz check --rev-range master..HEAD + ``` -There are two ways you can provide your plain message and check it. + !!! note "Default branch" + Usually the default branch is `main` or `master`. + You can check the default branch by running `cz check --use-default-range`. -#### Method 1: use `-m` or `--message` +1. 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. + + ```bash + cz check --rev-range ..HEAD + ``` + +### `--use-default-range` + +Equivalent to `--rev-range ..HEAD`. ```bash -$ cz check --message MESSAGE +cz check --use-default-range +# or +cz check -d ``` -In this option, `MESSAGE` is the commit message to be checked. +### `--message` -#### Method 2: use pipe to pipe it to `cz check` +Test if a given string passes `cz check`. ```bash -$ echo MESSAGE | cz check +cz check --message ``` -In this option, `MESSAGE` is piped to `cz check` and will be checked. +### `--commit-msg-file` -### Commit Message File +Test if a given file contains a commit message that passes `cz check`. ```bash -$ cz check --commit-msg-file COMMIT_MSG_FILE +cz check --commit-msg-file ``` -In this option, `COMMIT_MSG_FILE` is the path of the temporary file that contains the commit message. -This argument can be useful when cooperating with git hooks. Please check [Automatically check message before commit](../tutorials/auto_check.md) for more information about how to use this argument with git hooks. +This can be useful when cooperating with git hooks. Please check [Automatically check message before commit](../tutorials/auto_check.md) for more detailed examples. -### Allow Abort +### `--allow-abort` + +Example: ```bash -cz check --message MESSAGE --allow-abort +cz check --message --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 +### `--allowed-prefixes` + +Skip validation for commit messages that start with the specified prefixes. -If the commit message starts with some specific prefixes, `cz check` returns `True` without checking the regex. -By default, the following prefixes are allowed: +If not set, commit messages starting with the following prefixes are ignored by `cz check`: - `Merge` - `Revert` - `Pull request` - `fixup!` - `squash!` +- `amend!` ```bash -cz check --message MESSAGE --allowed-prefixes 'Merge' 'Revert' 'Custom Prefix' +cz check --message --allowed-prefixes 'Merge' 'Revert' 'Custom Prefix' ``` -### Commit message length limit +For example, + +```bash +# 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 argument `-l` (or `--message-length-limit`) followed by a positive number can limit the length of commit messages. -For example, `cz check --message MESSAGE -l 3` would fail the check, since `MESSAGE` is more than 3 characters long. -By default, the limit is set to 0, which means no limit on the length. +# 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. + +```bash +# 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 +``` -**Note that the limit applies only to the first line of the message.** +By default, the limit is set to `0`, which means no limit on the length. -Specifically, for `ConventionalCommitsCz` the length only counts from the type of change to the subject, while the body and the footer are not counted. +!!! 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. diff --git a/docs/config.md b/docs/config.md index a3e317988..307cf54a9 100644 --- a/docs/config.md +++ b/docs/config.md @@ -407,11 +407,11 @@ setup( [major-version-zero]: commands/bump.md#-major-version-zero [prerelease-offset]: commands/bump.md#prerelease_offset [retry_after_failure]: commands/commit.md#retry -[allow_abort]: commands/check.md#allow-abort +[allow_abort]: commands/check.md#-allow-abort [version-scheme]: commands/bump.md#version-schemes-version-scheme [pre_bump_hooks]: commands/bump.md#pre_bump_hooks [post_bump_hooks]: commands/bump.md#post_bump_hooks -[allowed_prefixes]: commands/check.md#allowed-prefixes +[allowed_prefixes]: commands/check.md#-allowed-prefixes [additional-features]: https://github.com/tmbo/questionary#additional-features [customization]: customization.md [shortcuts]: customization.md#shortcut-keys