Skip to content

docs: update README.md with additional docs #70

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 15, 2025
Merged

docs: update README.md with additional docs #70

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -161,3 +161,4 @@ cython_debug/

.vscode
.DS_Store
.ruff_cache
189 changes: 40 additions & 149 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,84 +1,34 @@
# commitlint
# Conventional Commitlint

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

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.
`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.

## Conventional Commits
## Usage

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.
This structure improves readability, facilitates automated changelog generation, and ensures a consistent commit history.
### GitHub Actions

The commit message should follow this structure:

```
<type>(<optional scope>): <description>

[Optional body]
```

**Type:** Indicates the type of change, such as build, ci, docs, feat, fix, perf, refactor, style, test, chore, revert, or bump.
E.g., `feat: add JSON parser`.

**Scope:** Additional contextual information.
E.g., `feat(parser): add JSON parser`.

**Description:** Brief description of the commit.

**Body:** A detailed description of the commit.

For more details, please refer to the Conventional Commits specification at https://www.conventionalcommits.org/en/v1.0.0/

> 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).

## How to use

### For pre-commit

1. Add the following configuration on `.pre-commit-config.yaml`.

```yaml
repos:
...
- repo: https://github.com/opensource-nepal/commitlint
rev: v1.2.0
hooks:
- id: commitlint
...
```

2. Install the `commit-msg` hook in your project repo:

```bash
pre-commit install --hook-type commit-msg
```

Installing using only `pre-commit install` will not work.

> **_NOTE:_** Avoid using commit messages that start with '#'.
> This might result in unexpected behavior with commitlint.

### For GitHub Actions

If you have any existing workflows, add the following steps:
If you have an existing workflow, add the following steps:

```yaml
...
steps:
...
- name: Run commitlint

- name: Conventional Commitlint
uses: opensource-nepal/commitlint@v1

...
```

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

```yaml
name: Commitlint
name: Conventional Commitlint

on:
push:
Expand All @@ -88,116 +38,57 @@ on:
jobs:
commitlint:
runs-on: ubuntu-latest
name: Commitlint
name: Conventional Commitlint
steps:
- name: Run commitlint
- name: Conventional Commitlint
uses: opensource-nepal/commitlint@v1
```

> **_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.
> **_Note:_** The `commitlint` GitHub Action is triggered only by `push`, `pull_request`, or `pull_request_target` events.

#### GitHub Action Inputs

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

#### GitHub Action Outputs

| # | Name | Type | Description |
| --- | ------------- | ------- | ---------------------------------------------------------------------------- |
| 1 | **exit_code** | Integer | The exit code of the commitlint step. |
| 2 | **status** | String | The outcome of the commitlint step. Possible values: 'success' or 'failure'. |

## CLI (Command Line Interface)
| # | Name | Type | Description |
| --- | ------------- | ------- | ------------------------------------------------------------ |
| 1 | **exit_code** | Integer | The exit code of the commitlint step. |
| 2 | **status** | String | The outcome of the commitlint step (`success` or `failure`). |

### Installation
### Pre-commit

```shell
pip install commitlint
```
1. Add the following configuration to `.pre-commit-config.yaml`:

### Usage

```
commitlint [-h] [-V] [--file FILE] [--hash HASH] [--from-hash FROM_HASH] [--to-hash TO_HASH] [--skip-detail] [-q | -v]
[commit_message]

positional arguments:
commit_message The commit message to be checked

optional arguments:
-h, --help show this help message and exit
-V, --version show program's version number and exit
--file FILE Path to a file containing the commit message
--hash HASH Commit hash
--from-hash FROM_HASH
From commit hash
--to-hash TO_HASH To commit hash
--skip-detail Skip the detailed error message check
-q, --quiet Ignore stdout and stderr
-v, --verbose Verbose output
```

### Examples

Check commit message directly:

```shell
$ commitlint "chore: my commit message"
```

Check commit message from file:

```shell
$ commitlint --file /foo/bar/commit-message.txt
```

> **_NOTE:_** For `--file` option, avoid using commit messages that start with '#'.
> This might result in unexpected behavior with commitlint.

Check commit message of a hash:

```shell
$ commitlint --hash 9a8c08173
```

Check commit message of a hash range:

```shell
$ commitlint --from-hash 00bf73fef7 --to-hash d6301f1eb0
```

Check commit message skipping the detail check:

```shell
$ commitlint --skip-detail "chore: my commit message"
# or
$ commitlint --skip-detail --hash 9a8c08173
```
```yaml
repos:
...
- repo: https://github.com/opensource-nepal/commitlint
rev: v1.3.0
hooks:
- id: commitlint
...
```

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

```shell
$ commitlint --quiet "chore: my commit message"
```
```bash
pre-commit install --hook-type commit-msg
```

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

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

Version check:
## CLI (Command Line Interface)

```shell
$ commitlint --version
# or
$ commitlint -V
```
For CLI usage, please refer to [cli.md](./docs/cli.md).

## Contribution

We appreciate feedback and contribution to this package. To get started please see our [contribution guide](./CONTRIBUTING.md).
We appreciate feedback and contributions to this package. To get started, please see our [contribution guide](./CONTRIBUTING.md).
88 changes: 88 additions & 0 deletions docs/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
# Commitlint CLI

## Installation

```shell
pip install commitlint
```

## Usage

```
commitlint [-h] [-V] [--file FILE] [--hash HASH] [--from-hash FROM_HASH] [--to-hash TO_HASH] [--skip-detail] [--hide-input]
[-q | -v]
[commit_message]

Check if a commit message follows the Conventional Commits format.

Positional arguments:
commit_message The commit message to be checked.

Options:
-h, --help Show this help message and exit.
-V, --version Show the program's version number and exit.
--file FILE Path to a file containing the commit message.
--hash HASH Commit hash.
--from-hash FROM_HASH Commit hash to start checking from.
--to-hash TO_HASH Commit hash to check up to.
--skip-detail Skip detailed error messages.
--hide-input Hide input from stdout.
-q, --quiet Suppress stdout and stderr.
-v, --verbose Enable verbose output.
```

## Examples

Check a commit message directly:

```shell
$ commitlint "chore: my commit message"
```

Check a commit message from a file:

```shell
$ commitlint --file /foo/bar/commit-message.txt
```

> **_Note:_** When using the `--file` option, avoid commit messages that start with `#`, as this may cause unexpected behavior with `commitlint`.

Check the commit message of a specific hash:

```shell
$ commitlint --hash 9a8c08173
```

Check commit messages within a hash range:

```shell
$ commitlint --from-hash 00bf73fef7 --to-hash d6301f1eb0
```

Check a commit message while skipping detailed error messages:

```shell
$ commitlint --skip-detail "chore: my commit message"
# or
$ commitlint --skip-detail --hash 9a8c08173
```

Run `commitlint` in quiet mode:

```shell
$ commitlint --quiet "chore: my commit message"
```

Run `commitlint` in verbose mode:

```shell
$ commitlint --verbose "chore: my commit message"
```

Check the version:

```shell
$ commitlint --version
# or
$ commitlint -V
```
26 changes: 26 additions & 0 deletions docs/conventional-commits.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Conventional Commits

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.
This structure improves readability, facilitates automated changelog generation, and ensures a consistent commit history.

The commit message should follow this structure:

```
<type>(<optional scope>): <description>

[Optional body]
```

**Type:** Indicates the type of change, such as build, ci, docs, feat, fix, perf, refactor, style, test, chore, revert, or bump.
E.g., `feat: add JSON parser`.

**Scope:** Additional contextual information.
E.g., `feat(parser): add JSON parser`.

**Description:** Brief description of the commit.

**Body:** A detailed description of the commit.

For more details, please refer to the Conventional Commits specification at https://www.conventionalcommits.org/en/v1.0.0/

> 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).
Loading