Skip to content

Commit af7f9a7

Browse files
muthukrishnan24muthukrishnan24
committed
docs: update README
1 parent b9e5ca2 commit af7f9a7

File tree

1 file changed

+131
-47
lines changed

1 file changed

+131
-47
lines changed

‎README.md‎

Lines changed: 131 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,8 @@ commitlint checks if your commit message meets the [conventional commit format](
2828
- [Commands](#commands)
2929
- [config](#config)
3030
- [lint](#lint)
31-
- [Precedence](#precedence)
32-
- [Config](#config-1)
33-
- [Message](#message)
31+
- [Config Precedence](#config-precedence)
32+
- [Message Precedence](#message-precedence)
3433
- [hook](#hook)
3534
- [debug](#debug)
3635
- [Default Config](#default-config)
@@ -40,6 +39,16 @@ commitlint checks if your commit message meets the [conventional commit format](
4039
- [Custom Ignore Patterns](#custom-ignore-patterns)
4140
- [Disabling Default Ignores](#disabling-default-ignores)
4241
- [Available Rules](#available-rules)
42+
- [Length rules](#length-rules)
43+
- [Enum / allow-list rules](#enum--allow-list-rules)
44+
- [Charset rules](#charset-rules)
45+
- [Case rules](#case-rules)
46+
- [Empty / presence rules](#empty--presence-rules)
47+
- [Full-stop rules](#full-stop-rules)
48+
- [Leading-blank rules](#leading-blank-rules)
49+
- [Header formatting rules](#header-formatting-rules)
50+
- [Trailer / sign-off rules](#trailer--sign-off-rules)
51+
- [Breaking change rules](#breaking-change-rules)
4352
- [Available Formatters](#available-formatters)
4453
- [Extensibility](#extensibility)
4554
- [FAQ](#faq)
@@ -136,11 +145,9 @@ To lint a message, you can use any one of the following
136145
- run `echo "message" | commitlint lint`
137146
- run `commitlint lint < file`
138147

139-
#### Precedence
140-
141148
`commitlint lint` follows below order for `config` and `message`
142149

143-
##### Config
150+
#### Config Precedence
144151

145152
- config file passed to `--config` command-line argument
146153
- `COMMITLINT_CONFIG` env variable
@@ -151,7 +158,7 @@ To lint a message, you can use any one of the following
151158
- commitlint.yaml
152159
- [default config](#default-config)
153160

154-
##### Message
161+
#### Message Precedence
155162

156163
- `stdin` pipe stream
157164
- commit message file passed to `--message` command-line argument
@@ -219,7 +226,7 @@ ignores: []
219226
Commonly used commit types from [Conventional Commit Types](https://github.com/commitizen/conventional-commit-types)
220227
221228
| Type | Description |
222-
| :------- | :------------------------------------------------------------------------------- |
229+
|:---------|:---------------------------------------------------------------------------------|
223230
| feat | A new feature |
224231
| fix | A bug fix |
225232
| docs | Documentation only changes |
@@ -242,21 +249,21 @@ If the **first line** of a commit message matches any ignore pattern, linting is
242249
The following patterns are enabled by default
243250
(source: [`config/default.go`](config/default.go)):
244251

245-
| Pattern | Matches |
246-
| :--- | :--- |
247-
| `^Merge pull request #\d+` | GitHub pull request merges |
248-
| `^Merge .+ into .+` | Generic merge (X into Y) |
249-
| `^Merge branch '.+'` | `git merge` branch |
250-
| `^Merge tag '.+'` | `git merge` tag |
251-
| `^Merge remote-tracking branch '.+'` | `git merge` remote-tracking branch |
252-
| `^Merged .+ (in\|into) .+` | Azure DevOps / Bitbucket merged |
253-
| `^Merged PR #?\d+` | Azure DevOps pull request |
254-
| `^(R\|r)evert ` | `git revert` |
255-
| `^(R\|r)eapply ` | `git reapply` |
256-
| `^(amend\|fixup\|squash)! ` | `git commit --fixup/--squash/--amend` |
257-
| `^Automatic merge` | Automatic merges |
258-
| `^Auto-merged .+ into .+` | Auto-merged branches |
259-
| `^Initial commit$` | Initial commit (exact match) |
252+
| Pattern | Matches |
253+
|:-------------------------------------|:--------------------------------------|
254+
| `^Merge pull request #\d+` | GitHub pull request merges |
255+
| `^Merge .+ into .+` | Generic merge (X into Y) |
256+
| `^Merge branch '.+'` | `git merge` branch |
257+
| `^Merge tag '.+'` | `git merge` tag |
258+
| `^Merge remote-tracking branch '.+'` | `git merge` remote-tracking branch |
259+
| `^Merged .+ (in\|into) .+` | Azure DevOps / Bitbucket merged |
260+
| `^Merged PR #?\d+` | Azure DevOps pull request |
261+
| `^(R\|r)evert ` | `git revert` |
262+
| `^(R\|r)eapply ` | `git reapply` |
263+
| `^(amend\|fixup\|squash)! ` | `git commit --fixup/--squash/--amend` |
264+
| `^Automatic merge` | Automatic merges |
265+
| `^Auto-merged .+ into .+` | Auto-merged branches |
266+
| `^Initial commit$` | Initial commit (exact match) |
260267

261268
### Custom Ignore Patterns
262269

@@ -281,30 +288,107 @@ ignores:
281288

282289
## Available Rules
283290

284-
The list of available lint rules
285-
286-
| name | argument | flags | description |
287-
| ---------------------- | ------------------------ | ----------------- | --------------------------------------------- |
288-
| header-min-length | int | n/a | checks the min length of header (first line) |
289-
| header-max-length | int | n/a | checks the max length of header (first line) |
290-
| body-max-line-length | int | n/a | checks the max length of each line in body |
291-
| footer-max-line-length | int | n/a | checks the max length of each line in footer |
292-
| type-enum | []string | n/a | restrict type to given list of string |
293-
| scope-enum | []string | allow-empty: bool | restrict scope to given list of string |
294-
| footer-enum | []string | n/a | restrict footer token to given list of string |
295-
| type-min-length | int | n/a | checks the min length of type |
296-
| type-max-length | int | n/a | checks the max length of type |
297-
| scope-min-length | int | n/a | checks the min length of scope |
298-
| scope-max-length | int | n/a | checks the max length of scope |
299-
| description-min-length | int | n/a | checks the min length of description |
300-
| description-max-length | int | n/a | checks the max length of description |
301-
| body-min-length | int | n/a | checks the min length of body |
302-
| body-max-length | int | n/a | checks the max length of body |
303-
| footer-min-length | int | n/a | checks the min length of footer |
304-
| footer-max-length | int | n/a | checks the max length of footer |
305-
| type-charset | string | n/a | restricts type to given charset |
306-
| scope-charset | string | n/a | restricts scope to given charset |
307-
| footer-type-enum | []{token, types, values} | n/a | enforces footer notes for given type |
291+
Rules marked **✅ enabled** are active by default. All others can be opted into via the `rules:` list in your config.
292+
293+
### Length rules
294+
295+
| name | argument | flags | description | default |
296+
|:-------------------------|:---------|:------|:----------------------------------|:----------------|
297+
| `header-min-length` | int | n/a | min length of header (first line) | ✅ enabled (10) |
298+
| `header-max-length` | int | n/a | max length of header (first line) | ✅ enabled (72) |
299+
| `body-min-length` | int | n/a | min length of body | N/A |
300+
| `body-max-length` | int | n/a | max length of body | N/A |
301+
| `body-max-line-length` | int | n/a | max length of each line in body | ✅ enabled (100) |
302+
| `footer-min-length` | int | n/a | min length of footer | N/A |
303+
| `footer-max-length` | int | n/a | max length of footer | N/A |
304+
| `footer-max-line-length` | int | n/a | max length of each line in footer | ✅ enabled (100) |
305+
| `type-min-length` | int | n/a | min length of type | N/A |
306+
| `type-max-length` | int | n/a | max length of type | N/A |
307+
| `scope-min-length` | int | n/a | min length of scope | N/A |
308+
| `scope-max-length` | int | n/a | max length of scope | N/A |
309+
| `description-min-length` | int | n/a | min length of description | N/A |
310+
| `description-max-length` | int | n/a | max length of description | N/A |
311+
312+
### Enum / allow-list rules
313+
314+
| name | argument | flags | description | default |
315+
|:-------------------|:---------------------------|:--------------------|:----------------------------------------|:----------|
316+
| `type-enum` | `[]string` | n/a | restrict type to given list of strings | ✅ enabled |
317+
| `scope-enum` | `[]string` | `allow-empty: bool` | restrict scope to given list of strings | N/A |
318+
| `footer-enum` | `[]string` | n/a | restrict footer token to given list | N/A |
319+
| `footer-type-enum` | `[]{token, types, values}` | n/a | enforce footer notes for given type | N/A |
320+
321+
### Charset rules
322+
323+
| name | argument | flags | description | default |
324+
|:----------------|:---------|:------|:--------------------------------|:--------|
325+
| `type-charset` | string | n/a | restrict type to given charset | N/A |
326+
| `scope-charset` | string | n/a | restrict scope to given charset | N/A |
327+
328+
### Case rules
329+
330+
All case rules accept one of: `lower-case`, `upper-case`, `camel-case`, `kebab-case`, `pascal-case`, `sentence-case`, `snake-case`, `start-case`.
331+
332+
| name | argument | flags | description | default |
333+
|:-------------------|:---------|:------|:-------------------------------------------|:--------|
334+
| `type-case` | string | n/a | enforce case format on type | N/A |
335+
| `scope-case` | string | n/a | enforce case format on scope (skips empty) | N/A |
336+
| `description-case` | string | n/a | enforce case format on description | N/A |
337+
| `body-case` | string | n/a | enforce case format on entire body | N/A |
338+
| `header-case` | string | n/a | enforce case format on full header | N/A |
339+
340+
### Empty / presence rules
341+
342+
These rules enforce that a field is **not empty**.
343+
344+
| name | argument | flags | description | default |
345+
|:--------------------|:---------|:------|:------------------------------|:--------|
346+
| `type-empty` | n/a | n/a | type must not be empty | N/A |
347+
| `scope-empty` | n/a | n/a | scope must not be empty | N/A |
348+
| `body-empty` | n/a | n/a | body must not be empty | N/A |
349+
| `footer-empty` | n/a | n/a | footer must not be empty | N/A |
350+
| `description-empty` | n/a | n/a | description must not be empty | N/A |
351+
352+
### Full-stop rules
353+
354+
Check that a field does **not** end with a given character (default `"."`).
355+
356+
| name | argument | flags | description | default |
357+
|:------------------------|:---------|:------|:-------------------------------------------------|:--------|
358+
| `header-full-stop` | string | n/a | header must not end with given char (e.g. `"."`) | N/A |
359+
| `body-full-stop` | string | n/a | body must not end with given char | N/A |
360+
| `description-full-stop` | string | n/a | description must not end with given char | N/A |
361+
362+
### Leading-blank rules
363+
364+
Enforce that a blank line separates commit sections (conventional commits spec).
365+
366+
| name | argument | flags | description | default |
367+
|:-----------------------|:---------|:------|:----------------------------------------|:--------|
368+
| `body-leading-blank` | n/a | n/a | body must be preceded by a blank line | N/A |
369+
| `footer-leading-blank` | n/a | n/a | footer must be preceded by a blank line | N/A |
370+
371+
### Header formatting rules
372+
373+
| name | argument | flags | description | default |
374+
|:--------------|:---------|:------|:----------------------------------------------------|:--------|
375+
| `header-trim` | n/a | n/a | header must not have leading or trailing whitespace | N/A |
376+
377+
### Trailer / sign-off rules
378+
379+
The argument is the trailer token. A trailing `:` is accepted and stripped automatically,
380+
so `"Signed-off-by"` and `"Signed-off-by:"` are equivalent.
381+
382+
| name | argument | flags | description | default |
383+
|:-----------------|:---------|:------|:---------------------------------------------------------------------|:--------|
384+
| `signed-off-by` | string | n/a | commit must have a footer note whose token matches (e.g. `"Signed-off-by"`) | N/A |
385+
| `trailer-exists` | string | n/a | commit must have a footer note whose token matches (e.g. `"Co-authored-by"`) | N/A |
386+
387+
### Breaking change rules
388+
389+
| name | argument | flags | description | default |
390+
|:-----------------------------------|:---------|:------|:---------------------------------------------------------------------------------------------------------------|:--------|
391+
| `breaking-change-exclamation-mark` | n/a | n/a | XNOR: either both `!` in header and `BREAKING CHANGE` in footer are present, or neither N/A not just one alone | N/A |
308392

309393
## Available Formatters
310394

0 commit comments

Comments
 (0)