Skip to content

Commit e44f04e

Browse files
muthukrishnan24muthukrishnan24
committed
docs: update README
1 parent 8c251f6 commit e44f04e

File tree

1 file changed

+144
-96
lines changed

1 file changed

+144
-96
lines changed

‎README.md‎

Lines changed: 144 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -1,149 +1,120 @@
1+
[![PkgGoDev](https://pkg.go.dev/badge/github.com/conventionalcommit/commitlint)](https://pkg.go.dev/github.com/conventionalcommit/commitlint)
2+
13
# commitlint
24

35
commitlint checks if your commit messages meets the [conventional commit format](https://www.conventionalcommits.org/en/v1.0.0/)
46

5-
[![PkgGoDev](https://pkg.go.dev/badge/github.com/conventionalcommit/commitlint)](https://pkg.go.dev/github.com/conventionalcommit/commitlint)
7+
```
8+
<type>[optional scope]: <description>
69
7-
#### Table of Contents
10+
[optional body]
11+
12+
[optional footer(s)]
13+
```
14+
15+
- [Why Use Conventional Commits?](https://www.conventionalcommits.org/en/v1.0.0/#why-use-conventional-commits)
16+
17+
### Table of Contents
818

919
- [Installation](#installation)
1020
- [Releases](#releases)
1121
- [Using go](#using-go)
12-
- [Enable in Git Repo](#enable-in-git-repo)
22+
- [Setup](#setup)
23+
- [Manual](#manual)
1324
- [Quick Test](#quick-test)
14-
- [Benefits of using conventional commit](#benefits-of-using-conventional-commit)
15-
- [Commit Types](#commit-types)
16-
- [Commands](#commands)
17-
* [Custom config for each repo](#custom-config-for-each-repo)
18-
* [Verify config file](#verify-config-file)
19-
- [Rules](#rules)
20-
- [Library](#library)
21-
- [Config Precedence](#config-precedence)
22-
- [Commit Message Precedence](#commit-message-precedence)
23-
- [Default Config](#default-config)
25+
- [Usage](#usage)
26+
- [Commands](#commands)
27+
- [config](#config)
28+
- [lint](#lint)
29+
- [Default Config](#default-config)
30+
- [Commit Types](#commit-types)
31+
- [Available Rules](#available-rules)
32+
- [Available Formatters](#available-formatters)
33+
- [Extensibility](#extensibility)
34+
- [FAQ](#faq)
2435
- [License](#license)
2536

26-
### Installation
37+
## Installation
2738

28-
#### Releases
39+
### Releases
2940

3041
Download binary from [releases](https://github.com/conventionalcommit/commitlint/releases) and add it to your `PATH`
3142

32-
#### Using go
43+
### Using go
3344

3445
```bash
3546
go install github.com/conventionalcommit/commitlint@latest
3647
```
3748

38-
### Enable in Git Repo
39-
40-
- enable for a single repository, `cd` to repository directory
41-
42-
```bash
43-
commitlint init
44-
```
49+
## Setup
4550

46-
- enable globally for all repositories
47-
48-
```bash
49-
commitlint init --global
50-
```
51-
52-
### Quick Test
51+
- Enable for a single git repository, `cd` to repository directory
5352

5453
```bash
55-
# invalid commit message
56-
echo "fear: do not fear for commit message" | commitlint lint
57-
# ❌ type-enum: type 'fear' is not allowed, you can use one of [feat fix docs style refactor perf test build ci chore revert merge]
58-
59-
# valid commit message
60-
echo "feat: good commit message" | commitlint lint
61-
# ✔ commit message
54+
commitlint init
6255
```
6356

64-
### Benefits of using conventional commit
57+
- Enable globally for all git repositories
6558

66-
- Conventional Commit format. Read [Full Specification here](https://www.conventionalcommits.org/en/v1.0.0/#specification)
59+
```bash
60+
commitlint init --global
6761
```
68-
<type>[optional scope]: <description>
6962

70-
[optional body]
71-
72-
[optional footer(s)]
73-
```
63+
### Manual
7464

75-
- [Why Use Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#why-use-conventional-commits)
65+
- run `commitlint hook create` to create `.commitlint/hooks` containing git hooks
66+
- To enable in single repo
67+
- run `git config core.hooksPath /path/to/.commitlint/hooks`
68+
- To enable globally
69+
- run `git config --global core.hooksPath /path/to/.commitlint/hooks`
7670

77-
#### Commit Types
71+
## Quick Test
7872

79-
Commonly used commit types from [Conventional Commit Types](https://github.com/commitizen/conventional-commit-types)
73+
- Valid commit message
8074

81-
| Type | Description |
82-
|:---------|:---------------------------------------------------------------------------------|
83-
| feat | A new feature |
84-
| fix | A bug fix |
85-
| docs | Documentation only changes |
86-
| style | Changes that do not affect the meaning of the code (white-space, formatting etc) |
87-
| refactor | A code change that neither fixes a bug nor adds a feature |
88-
| perf | A code change that improves performance |
89-
| test | Adding missing tests or correcting existing tests |
90-
| build | Changes that affect the build system or external dependencies |
91-
| ci | Changes to our CI configuration files and scripts |
92-
| chore | Other changes that don't modify src or test files |
93-
| revert | Reverts a previous commit |
94-
| merge | Merges a branch |
75+
```bash
76+
echo "feat: good commit message" | commitlint lint
77+
# ✔ commit message
78+
```
9579

96-
### Commands
80+
- Invalid commit message
9781

98-
##### Custom config for each repo
82+
```bash
83+
echo "fear: do not fear for commit message" | commitlint lint
84+
# ❌ type-enum: type 'fear' is not allowed, you can use one of [build chore ci docs feat fix merge perf refactor revert style test]
85+
```
9986

100-
- run `commitlint create config` in repo root directory
87+
## Usage
10188

102-
this will create `commitlint.yaml` in that directory, you can customise the config to your need
89+
### Commands
10390

104-
##### Verify config file
91+
#### config
10592

106-
- run `commitlint verify` to verify if config is valid or not (according to config precedence)
93+
- To create config file, run `commitlint config create` this will create `commitlint.yaml`
10794

108-
- run `commitlint verify --config=/path/to/conf.yaml`to verify given config file
95+
- To validate config file, run `commitlint config check --config=/path/to/conf.yaml`
10996

110-
### Rules
97+
#### lint
11198

112-
The list of available lint rules
99+
To lint a message, you can use any one of the following
100+
- run `commitlint lint --message=file`
101+
- run `echo "message" | commitlint lint`
102+
- run `commitlint lint < file`
113103

114-
| name | argument | flags | description |
115-
| ---------------------- | -------- | ----------------- | -------------------------------------------- |
116-
| header-min-length | int | n/a | checks the min length of header (first line) |
117-
| header-max-length | int | n/a | checks the max length of header (first line) |
118-
| body-max-line-length | int | n/a | checks the max length of each line in body |
119-
| footer-max-line-length | int | n/a | checks the max length of each line in footer |
120-
| type-enum | []string | n/a | restrict type to given list of string |
121-
| scope-enum | []string | allow-empty: bool | restrict scope to given list of string |
122-
| type-min-length | int | n/a | checks the min length of type |
123-
| type-max-length | int | n/a | checks the max length of type |
124-
| scope-min-length | int | n/a | checks the min length of scope |
125-
| scope-max-length | int | n/a | checks the max length of scope |
126-
| description-min-length | int | n/a | checks the min length of description |
127-
| description-max-length | int | n/a | checks the max length of description |
128-
| body-min-length | int | n/a | checks the min length of body |
129-
| body-max-length | int | n/a | checks the max length of body |
130-
| footer-min-length | int | n/a | checks the min length of footer |
131-
| footer-max-length | int | n/a | checks the max length of footer |
132-
| type-charset | string | n/a | restricts type to given charset |
133-
| scope-charset | string | n/a | restricts scope to given charset |
104+
##### Precedence
134105

135-
### Library
106+
`commitlint lint` follows below order for `config` and `message`
136107

137-
#### Config Precedence
108+
###### Config
138109

139110
- `commitlint.yaml` config file in current directory
140-
- config file passed with `--config` command-line argument
111+
- config file passed to `--config` command-line argument
141112
- [default config](#default-config)
142113

143-
#### Commit Message Precedence
114+
###### Message
144115

145116
- `stdin` pipe stream
146-
- commit message file passed with `--message` command-line argument
117+
- commit message file passed to `--message` command-line argument
147118
- `.git/COMMIT_EDITMSG` in current directory
148119

149120
### Default Config
@@ -185,6 +156,83 @@ rules:
185156
- merge
186157
```
187158
188-
### License
159+
#### Commit Types
160+
161+
Commonly used commit types from [Conventional Commit Types](https://github.com/commitizen/conventional-commit-types)
162+
163+
| Type | Description |
164+
|:---------|:---------------------------------------------------------------------------------|
165+
| feat | A new feature |
166+
| fix | A bug fix |
167+
| docs | Documentation only changes |
168+
| style | Changes that do not affect the meaning of the code (white-space, formatting etc) |
169+
| refactor | A code change that neither fixes a bug nor adds a feature |
170+
| perf | A code change that improves performance |
171+
| test | Adding missing tests or correcting existing tests |
172+
| build | Changes that affect the build system or external dependencies |
173+
| ci | Changes to our CI configuration files and scripts |
174+
| chore | Other changes that don't modify src or test files |
175+
| revert | Reverts a previous commit |
176+
| merge | Merges a branch |
177+
178+
## Available Rules
179+
180+
The list of available lint rules
181+
182+
| name | argument | flags | description |
183+
| ---------------------- | -------- | ----------------- | -------------------------------------------- |
184+
| header-min-length | int | n/a | checks the min length of header (first line) |
185+
| header-max-length | int | n/a | checks the max length of header (first line) |
186+
| body-max-line-length | int | n/a | checks the max length of each line in body |
187+
| footer-max-line-length | int | n/a | checks the max length of each line in footer |
188+
| type-enum | []string | n/a | restrict type to given list of string |
189+
| scope-enum | []string | allow-empty: bool | restrict scope to given list of string |
190+
| type-min-length | int | n/a | checks the min length of type |
191+
| type-max-length | int | n/a | checks the max length of type |
192+
| scope-min-length | int | n/a | checks the min length of scope |
193+
| scope-max-length | int | n/a | checks the max length of scope |
194+
| description-min-length | int | n/a | checks the min length of description |
195+
| description-max-length | int | n/a | checks the max length of description |
196+
| body-min-length | int | n/a | checks the min length of body |
197+
| body-max-length | int | n/a | checks the max length of body |
198+
| footer-min-length | int | n/a | checks the min length of footer |
199+
| footer-max-length | int | n/a | checks the max length of footer |
200+
| type-charset | string | n/a | restricts type to given charset |
201+
| scope-charset | string | n/a | restricts scope to given charset |
202+
203+
204+
## Available Formatters
205+
206+
- default
207+
208+
```
209+
commitlint
210+
211+
→ input: "fear: do not fear for ..."
212+
213+
Errors:
214+
❌ type-enum: type 'fear' is not allowed, you can use one of [build chore ci docs feat fix merge perf refactor revert style test]
215+
216+
Total 1 errors, 0 warnings
217+
```
218+
219+
- JSON
220+
221+
```json
222+
{"errors":[{"message":"type 'fear' is not allowed, you can use one of [build chore ci docs feat fix merge perf refactor revert style test]","name":"type-enum"}],"input":"fear: do not fear for commit","status":false,"warnings":[]}
223+
```
224+
225+
## Extensibility
226+
227+
## FAQ
228+
229+
- How to have custom config for each repository?
230+
231+
Place `commitlint.yaml` file in repo root directory. linter follows [config precedence](#precedence).
232+
233+
To create a sample config, run `commitlint config create`
234+
235+
## License
189236

190237
All packages are licensed under [MIT License](https://github.com/conventionalcommit/commitlint/tree/master/LICENSE.md)
238+

0 commit comments

Comments
 (0)