Skip to content

Commit bbfa423

Browse files
aj3shaj3sh
authored
docs: update README.md with additional docs (#70)
1 parent 94575ce commit bbfa423

File tree

4 files changed

+155
-149
lines changed

4 files changed

+155
-149
lines changed

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -161,3 +161,4 @@ cython_debug/
161161

162162
.vscode
163163
.DS_Store
164+
.ruff_cache

‎README.md

+40-149
Original file line numberDiff line numberDiff line change
@@ -1,84 +1,34 @@
1-
# commitlint
1+
# Conventional Commitlint
22

33
[![PyPI version](https://badge.fury.io/py/commitlint.svg)](https://badge.fury.io/py/commitlint)
44
[![CI status](https://github.com/opensource-nepal/commitlint/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/opensource-nepal/commitlint/actions)
55
[![Downloads](https://img.shields.io/pypi/dm/commitlint.svg?maxAge=180)](https://pypi.org/project/commitlint/)
66
[![codecov](https://codecov.io/github/opensource-nepal/commitlint/graph/badge.svg?token=lRmPZsIHb6)](https://codecov.io/github/opensource-nepal/commitlint)
77
[![License](https://img.shields.io/pypi/l/commitlint?label=License)](https://github.com/opensource-nepal/commitlint/blob/main/LICENSE)
88

9-
commitlint is a tool designed to lint your commit messages according to the [Conventional Commits](https://www.conventionalcommits.org/) standard for your pre-commit hook and GitHub Actions.
9+
`commitlint` is a tool that lints commit messages according to the [Conventional Commits](./docs/conventional-commits.md) standard. It can be used in GitHub Actions and as a pre-commit hook.
1010

11-
## Conventional Commits
11+
## Usage
1212

13-
A conventional commit message follows a specific format that includes a prefix indicating the type of change, an optional scope for context, and a concise description of the modification.
14-
This structure improves readability, facilitates automated changelog generation, and ensures a consistent commit history.
13+
### GitHub Actions
1514

16-
The commit message should follow this structure:
17-
18-
```
19-
<type>(<optional scope>): <description>
20-
21-
[Optional body]
22-
```
23-
24-
**Type:** Indicates the type of change, such as build, ci, docs, feat, fix, perf, refactor, style, test, chore, revert, or bump.
25-
E.g., `feat: add JSON parser`.
26-
27-
**Scope:** Additional contextual information.
28-
E.g., `feat(parser): add JSON parser`.
29-
30-
**Description:** Brief description of the commit.
31-
32-
**Body:** A detailed description of the commit.
33-
34-
For more details, please refer to the Conventional Commits specification at https://www.conventionalcommits.org/en/v1.0.0/
35-
36-
> NOTE: commitlint also checks the length of the commit header (**max 72 characters**). The commit header refers to the first line of the commit message (excluding the body).
37-
38-
## How to use
39-
40-
### For pre-commit
41-
42-
1. Add the following configuration on `.pre-commit-config.yaml`.
43-
44-
```yaml
45-
repos:
46-
...
47-
- repo: https://github.com/opensource-nepal/commitlint
48-
rev: v1.2.0
49-
hooks:
50-
- id: commitlint
51-
...
52-
```
53-
54-
2. Install the `commit-msg` hook in your project repo:
55-
56-
```bash
57-
pre-commit install --hook-type commit-msg
58-
```
59-
60-
Installing using only `pre-commit install` will not work.
61-
62-
> **_NOTE:_** Avoid using commit messages that start with '#'.
63-
> This might result in unexpected behavior with commitlint.
64-
65-
### For GitHub Actions
66-
67-
If you have any existing workflows, add the following steps:
15+
If you have an existing workflow, add the following steps:
6816

6917
```yaml
7018
...
7119
steps:
7220
...
73-
- name: Run commitlint
21+
22+
- name: Conventional Commitlint
7423
uses: opensource-nepal/commitlint@v1
24+
7525
...
7626
```
7727

78-
If you don't have any workflows, create a new GitHub workflow, e.g. `.github/workflows/commitlint.yaml`.
28+
If you don't have any workflows, create a new GitHub workflow file, e.g., `.github/workflows/commitlint.yaml`:
7929

8030
```yaml
81-
name: Commitlint
31+
name: Conventional Commitlint
8232

8333
on:
8434
push:
@@ -88,116 +38,57 @@ on:
8838
jobs:
8939
commitlint:
9040
runs-on: ubuntu-latest
91-
name: Commitlint
41+
name: Conventional Commitlint
9242
steps:
93-
- name: Run commitlint
43+
- name: Conventional Commitlint
9444
uses: opensource-nepal/commitlint@v1
9545
```
9646
97-
> **_NOTE:_** commitlint GitHub Actions will only be triggered by "push", "pull_request", or "pull_request_target" events. The difference between "pull_request" and "pull_request_target" is that "pull_request" is more secure for public repos while "pull_request_target" is necessary for private repos.
47+
> **_Note:_** The `commitlint` GitHub Action is triggered only by `push`, `pull_request`, or `pull_request_target` events.
9848

9949
#### GitHub Action Inputs
10050

10151
| # | Name | Type | Default | Description |
10252
| --- | ----------------- | ------- | ---------------------- | --------------------------------------------------------------------- |
103-
| 1 | **fail_on_error** | Boolean | `true` | Determines whether the GitHub Action should fail if commitlint fails. |
104-
| 2 | **verbose** | Boolean | `false` | Verbose output. |
105-
| 3 | **token** | String | `secrets.GITHUB_TOKEN` | Github Token for fetching commits using Github API. |
53+
| 1 | **fail_on_error** | Boolean | `true` | Whether the GitHub Action should fail if commitlint detects an issue. |
54+
| 2 | **verbose** | Boolean | `false` | Enables verbose output. |
55+
| 3 | **token** | String | `secrets.GITHUB_TOKEN` | GitHub Token for fetching commits using the GitHub API. |
10656

10757
#### GitHub Action Outputs
10858

109-
| # | Name | Type | Description |
110-
| --- | ------------- | ------- | ---------------------------------------------------------------------------- |
111-
| 1 | **exit_code** | Integer | The exit code of the commitlint step. |
112-
| 2 | **status** | String | The outcome of the commitlint step. Possible values: 'success' or 'failure'. |
113-
114-
## CLI (Command Line Interface)
59+
| # | Name | Type | Description |
60+
| --- | ------------- | ------- | ------------------------------------------------------------ |
61+
| 1 | **exit_code** | Integer | The exit code of the commitlint step. |
62+
| 2 | **status** | String | The outcome of the commitlint step (`success` or `failure`). |
11563

116-
### Installation
64+
### Pre-commit
11765

118-
```shell
119-
pip install commitlint
120-
```
66+
1. Add the following configuration to `.pre-commit-config.yaml`:
12167

122-
### Usage
123-
124-
```
125-
commitlint [-h] [-V] [--file FILE] [--hash HASH] [--from-hash FROM_HASH] [--to-hash TO_HASH] [--skip-detail] [-q | -v]
126-
[commit_message]
127-
128-
positional arguments:
129-
commit_message The commit message to be checked
130-
131-
optional arguments:
132-
-h, --help show this help message and exit
133-
-V, --version show program's version number and exit
134-
--file FILE Path to a file containing the commit message
135-
--hash HASH Commit hash
136-
--from-hash FROM_HASH
137-
From commit hash
138-
--to-hash TO_HASH To commit hash
139-
--skip-detail Skip the detailed error message check
140-
-q, --quiet Ignore stdout and stderr
141-
-v, --verbose Verbose output
142-
```
143-
144-
### Examples
145-
146-
Check commit message directly:
147-
148-
```shell
149-
$ commitlint "chore: my commit message"
150-
```
151-
152-
Check commit message from file:
153-
154-
```shell
155-
$ commitlint --file /foo/bar/commit-message.txt
156-
```
157-
158-
> **_NOTE:_** For `--file` option, avoid using commit messages that start with '#'.
159-
> This might result in unexpected behavior with commitlint.
160-
161-
Check commit message of a hash:
162-
163-
```shell
164-
$ commitlint --hash 9a8c08173
165-
```
166-
167-
Check commit message of a hash range:
168-
169-
```shell
170-
$ commitlint --from-hash 00bf73fef7 --to-hash d6301f1eb0
171-
```
172-
173-
Check commit message skipping the detail check:
174-
175-
```shell
176-
$ commitlint --skip-detail "chore: my commit message"
177-
# or
178-
$ commitlint --skip-detail --hash 9a8c08173
179-
```
68+
```yaml
69+
repos:
70+
...
71+
- repo: https://github.com/opensource-nepal/commitlint
72+
rev: v1.3.0
73+
hooks:
74+
- id: commitlint
75+
...
76+
```
18077

181-
Run commitlint in quiet mode:
78+
2. Install the `commit-msg` hook in your project repository:
18279

183-
```shell
184-
$ commitlint --quiet "chore: my commit message"
185-
```
80+
```bash
81+
pre-commit install --hook-type commit-msg
82+
```
18683

187-
Run commitlint in verbose mode:
84+
Running only `pre-commit install` will not work.
18885

189-
```shell
190-
$ commitlint --verbose "chore: my commit message"
191-
```
86+
> **_Note:_** Avoid using commit messages that start with `#`, as this may cause unexpected behavior with `commitlint`.
19287

193-
Version check:
88+
## CLI (Command Line Interface)
19489

195-
```shell
196-
$ commitlint --version
197-
# or
198-
$ commitlint -V
199-
```
90+
For CLI usage, please refer to [cli.md](./docs/cli.md).
20091

20192
## Contribution
20293

203-
We appreciate feedback and contribution to this package. To get started please see our [contribution guide](./CONTRIBUTING.md).
94+
We appreciate feedback and contributions to this package. To get started, please see our [contribution guide](./CONTRIBUTING.md).

‎docs/cli.md

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Commitlint CLI
2+
3+
## Installation
4+
5+
```shell
6+
pip install commitlint
7+
```
8+
9+
## Usage
10+
11+
```
12+
commitlint [-h] [-V] [--file FILE] [--hash HASH] [--from-hash FROM_HASH] [--to-hash TO_HASH] [--skip-detail] [--hide-input]
13+
[-q | -v]
14+
[commit_message]
15+
16+
Check if a commit message follows the Conventional Commits format.
17+
18+
Positional arguments:
19+
commit_message The commit message to be checked.
20+
21+
Options:
22+
-h, --help Show this help message and exit.
23+
-V, --version Show the program's version number and exit.
24+
--file FILE Path to a file containing the commit message.
25+
--hash HASH Commit hash.
26+
--from-hash FROM_HASH Commit hash to start checking from.
27+
--to-hash TO_HASH Commit hash to check up to.
28+
--skip-detail Skip detailed error messages.
29+
--hide-input Hide input from stdout.
30+
-q, --quiet Suppress stdout and stderr.
31+
-v, --verbose Enable verbose output.
32+
```
33+
34+
## Examples
35+
36+
Check a commit message directly:
37+
38+
```shell
39+
$ commitlint "chore: my commit message"
40+
```
41+
42+
Check a commit message from a file:
43+
44+
```shell
45+
$ commitlint --file /foo/bar/commit-message.txt
46+
```
47+
48+
> **_Note:_** When using the `--file` option, avoid commit messages that start with `#`, as this may cause unexpected behavior with `commitlint`.
49+
50+
Check the commit message of a specific hash:
51+
52+
```shell
53+
$ commitlint --hash 9a8c08173
54+
```
55+
56+
Check commit messages within a hash range:
57+
58+
```shell
59+
$ commitlint --from-hash 00bf73fef7 --to-hash d6301f1eb0
60+
```
61+
62+
Check a commit message while skipping detailed error messages:
63+
64+
```shell
65+
$ commitlint --skip-detail "chore: my commit message"
66+
# or
67+
$ commitlint --skip-detail --hash 9a8c08173
68+
```
69+
70+
Run `commitlint` in quiet mode:
71+
72+
```shell
73+
$ commitlint --quiet "chore: my commit message"
74+
```
75+
76+
Run `commitlint` in verbose mode:
77+
78+
```shell
79+
$ commitlint --verbose "chore: my commit message"
80+
```
81+
82+
Check the version:
83+
84+
```shell
85+
$ commitlint --version
86+
# or
87+
$ commitlint -V
88+
```

‎docs/conventional-commits.md

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Conventional Commits
2+
3+
A conventional commit message follows a specific format that includes a prefix indicating the type of change, an optional scope for context, and a concise description of the modification.
4+
This structure improves readability, facilitates automated changelog generation, and ensures a consistent commit history.
5+
6+
The commit message should follow this structure:
7+
8+
```
9+
<type>(<optional scope>): <description>
10+
11+
[Optional body]
12+
```
13+
14+
**Type:** Indicates the type of change, such as build, ci, docs, feat, fix, perf, refactor, style, test, chore, revert, or bump.
15+
E.g., `feat: add JSON parser`.
16+
17+
**Scope:** Additional contextual information.
18+
E.g., `feat(parser): add JSON parser`.
19+
20+
**Description:** Brief description of the commit.
21+
22+
**Body:** A detailed description of the commit.
23+
24+
For more details, please refer to the Conventional Commits specification at https://www.conventionalcommits.org/en/v1.0.0/
25+
26+
> NOTE: commitlint also checks the length of the commit header (**max 72 characters**). The commit header refers to the first line of the commit message (excluding the body).

0 commit comments

Comments
 (0)