docs(check): rewrite command document

Author: bearomorphism

docs/commands/check.md

@@ -1,95 +1,154 @@
-# 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 <message_to_be_checked>
+```
+
+#### Option 2: pipe the message to `cz check`:
+```bash
+echo <message_to_be_checked> | 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 <first_commit_sha>..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~~~..
+    ```
+
+1. Validate all git commit messages on some branch up to HEAD:
+    ```bash
+    cz check --rev-range <branch_name>..HEAD
+    ```
+
+    For example, to check all git commit messages on `main` branch up to HEAD:
+    ```bash
+    cz check --rev-range main..HEAD
+    ```
+
+    or if your project still uses `master` branch:
+    ```bash
+    cz check --rev-range master..HEAD
+    ```
+
+    !!! note "Default branch"
+        Usually the default branch is `main` or `master`.
+        You can check the default branch by running `cz check --use-default-range`.
 
-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 <default_branch>..HEAD`.
+1. Validate all git commit messages starting from when you first implemented commit message linting:
 
-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).
+    **(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.
 
-### Commit Message
+    ```bash
+    cz check --rev-range <first_commit_sha>..HEAD
+    ```
 
-There are two ways you can provide your plain message and check it.
+### `--use-default-range`
 
-#### Method 1: use `-m` or `--message`
+Equivalent to `--rev-range <default_branch>..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 <message_to_be_checked>
 ```
 
-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 <path_to_file_containing_message_to_be_checked>
 ```
 
-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 <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
+### `--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:
 
 - `Merge`
 - `Revert`
 - `Pull request`
 - `fixup!`
 - `squash!`
+- `amend!`
 
 ```bash
-cz check --message MESSAGE --allowed-prefixes 'Merge' 'Revert' 'Custom Prefix'
+cz check --message <message_to_be_checked> --allowed-prefixes 'Merge' 'Revert' 'Custom Prefix'
 ```
 
-### Commit message length limit
+### `--message-length-limit`
+
+Restrict the length of **the first line** of the commit message.
 
-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.
+```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.

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