Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit bbfa423

Browse files
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

Lines changed: 1 addition & 0 deletions
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

Lines changed: 40 additions & 149 deletions
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

Lines changed: 88 additions & 0 deletions
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

Lines changed: 26 additions & 0 deletions
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)

AltStyle によって変換されたページ (->オリジナル) /