1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
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](../tutorials/auto_check.md).
## 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:
```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
```
## Command Line Options
### `--rev-range`
Test if a given range of commits in the git log passes `cz check`.
```bash
cz check --rev-range REV_RANGE
```
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`.
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 <first_commit_sha>..HEAD
```
### `--use-default-range`
Equivalent to `--rev-range <default_branch>..HEAD`.
```bash
cz check --use-default-range
# or
cz check -d
```
### `--message`
Test if a given string passes `cz check`.
```bash
cz check --message <message_to_be_checked>
```
### `--commit-msg-file`
Test if a given file contains a commit message that passes `cz check`.
```bash
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](../tutorials/auto_check.md) for more detailed examples.
### `--allow-abort`
Example:
```bash
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!`
```bash
cz check --message <message_to_be_checked> --allowed-prefixes 'Merge' 'Revert' 'Custom Prefix'
```
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 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
```
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.
|
