# commitlint
[](https://badge.fury.io/py/commitlint)
[](https://github.com/opensource-nepal/commitlint/actions)
[](https://pypi.org/project/commitlint/)
[](https://codecov.io/github/opensource-nepal/commitlint)
[](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.
## 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).
## 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:
```yaml
...
steps:
...
- name: Run commitlint
uses: opensource-nepal/commitlint@v1
...
```
If you don't have any workflows, create a new GitHub workflow, e.g. `.github/workflows/commitlint.yaml`.
```yaml
name: Commitlint
on:
push:
branches: ['main']
pull_request:
jobs:
commitlint:
runs-on: ubuntu-latest
name: Commitlint
steps:
- name: Run 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.
#### 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. |
#### 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)
### Installation
```shell
pip install commitlint
```
### 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
```
Run commitlint in quiet mode:
```shell
$ commitlint --quiet "chore: my commit message"
```
Run commitlint in verbose mode:
```shell
$ commitlint --verbose "chore: my commit message"
```
Version check:
```shell
$ commitlint --version
# or
$ commitlint -V
```
## Contribution
We appreciate feedback and contribution to this package. To get started please see our [contribution guide](./CONTRIBUTING.md).
Raw data
{
"_id": null,
"home_page": "https://github.com/opensource-nepal/commitlint",
"name": "commitlint",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "commitlint, commit lint, python commitlint, conventional commit, conventional commit message, python commit, github actions, pre-commit",
"author": "opensource-nepal",
"author_email": "aj3sshh@gmail.com, sugatbajracharya49@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/bb/12/61ea68efec07118b2e5a9c0be5a8cb94a77d62dc90609d66eb9d0feebd69/commitlint-1.3.0.tar.gz",
"platform": null,
"description": "# commitlint\n\n[](https://badge.fury.io/py/commitlint)\n[](https://github.com/opensource-nepal/commitlint/actions)\n[](https://pypi.org/project/commitlint/)\n[](https://codecov.io/github/opensource-nepal/commitlint)\n[](https://github.com/opensource-nepal/commitlint/blob/main/LICENSE)\n\ncommitlint 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.\n\n## Conventional Commits\n\nA 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.\nThis structure improves readability, facilitates automated changelog generation, and ensures a consistent commit history.\n\nThe commit message should follow this structure:\n\n```\n<type>(<optional scope>): <description>\n\n[Optional body]\n```\n\n**Type:** Indicates the type of change, such as build, ci, docs, feat, fix, perf, refactor, style, test, chore, revert, or bump.\nE.g., `feat: add JSON parser`.\n\n**Scope:** Additional contextual information.\nE.g., `feat(parser): add JSON parser`.\n\n**Description:** Brief description of the commit.\n\n**Body:** A detailed description of the commit.\n\nFor more details, please refer to the Conventional Commits specification at https://www.conventionalcommits.org/en/v1.0.0/\n\n> 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).\n\n## How to use\n\n### For pre-commit\n\n1. Add the following configuration on `.pre-commit-config.yaml`.\n\n ```yaml\n repos:\n ...\n - repo: https://github.com/opensource-nepal/commitlint\n rev: v1.2.0\n hooks:\n - id: commitlint\n ...\n ```\n\n2. Install the `commit-msg` hook in your project repo:\n\n ```bash\n pre-commit install --hook-type commit-msg\n ```\n\n Installing using only `pre-commit install` will not work.\n\n> **_NOTE:_** Avoid using commit messages that start with '#'.\n> This might result in unexpected behavior with commitlint.\n\n### For GitHub Actions\n\nIf you have any existing workflows, add the following steps:\n\n```yaml\n...\nsteps:\n ...\n - name: Run commitlint\n uses: opensource-nepal/commitlint@v1\n ...\n```\n\nIf you don't have any workflows, create a new GitHub workflow, e.g. `.github/workflows/commitlint.yaml`.\n\n```yaml\nname: Commitlint\n\non:\n push:\n branches: ['main']\n pull_request:\n\njobs:\n commitlint:\n runs-on: ubuntu-latest\n name: Commitlint\n steps:\n - name: Run commitlint\n uses: opensource-nepal/commitlint@v1\n```\n\n> **_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.\n\n#### GitHub Action Inputs\n\n| # | Name | Type | Default | Description |\n| --- | ----------------- | ------- | ---------------------- | --------------------------------------------------------------------- |\n| 1 | **fail_on_error** | Boolean | `true` | Determines whether the GitHub Action should fail if commitlint fails. |\n| 2 | **verbose** | Boolean | `false` | Verbose output. |\n| 3 | **token** | String | `secrets.GITHUB_TOKEN` | Github Token for fetching commits using Github API. |\n\n#### GitHub Action Outputs\n\n| # | Name | Type | Description |\n| --- | ------------- | ------- | ---------------------------------------------------------------------------- |\n| 1 | **exit_code** | Integer | The exit code of the commitlint step. |\n| 2 | **status** | String | The outcome of the commitlint step. Possible values: 'success' or 'failure'. |\n\n## CLI (Command Line Interface)\n\n### Installation\n\n```shell\npip install commitlint\n```\n\n### Usage\n\n```\ncommitlint [-h] [-V] [--file FILE] [--hash HASH] [--from-hash FROM_HASH] [--to-hash TO_HASH] [--skip-detail] [-q | -v]\n [commit_message]\n\npositional arguments:\n commit_message The commit message to be checked\n\noptional arguments:\n -h, --help show this help message and exit\n -V, --version show program's version number and exit\n --file FILE Path to a file containing the commit message\n --hash HASH Commit hash\n --from-hash FROM_HASH\n From commit hash\n --to-hash TO_HASH To commit hash\n --skip-detail Skip the detailed error message check\n -q, --quiet Ignore stdout and stderr\n -v, --verbose Verbose output\n```\n\n### Examples\n\nCheck commit message directly:\n\n```shell\n$ commitlint \"chore: my commit message\"\n```\n\nCheck commit message from file:\n\n```shell\n$ commitlint --file /foo/bar/commit-message.txt\n```\n\n> **_NOTE:_** For `--file` option, avoid using commit messages that start with '#'.\n> This might result in unexpected behavior with commitlint.\n\nCheck commit message of a hash:\n\n```shell\n$ commitlint --hash 9a8c08173\n```\n\nCheck commit message of a hash range:\n\n```shell\n$ commitlint --from-hash 00bf73fef7 --to-hash d6301f1eb0\n```\n\nCheck commit message skipping the detail check:\n\n```shell\n$ commitlint --skip-detail \"chore: my commit message\"\n# or\n$ commitlint --skip-detail --hash 9a8c08173\n```\n\nRun commitlint in quiet mode:\n\n```shell\n$ commitlint --quiet \"chore: my commit message\"\n```\n\nRun commitlint in verbose mode:\n\n```shell\n$ commitlint --verbose \"chore: my commit message\"\n```\n\nVersion check:\n\n```shell\n$ commitlint --version\n# or\n$ commitlint -V\n```\n\n## Contribution\n\nWe appreciate feedback and contribution to this package. To get started please see our [contribution guide](./CONTRIBUTING.md).\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "commitlint is is a pre-commit hook designed to lint your commit messages according to the Conventional Commits standard.",
"version": "1.3.0",
"project_urls": {
"Changelog": "https://github.com/opensource-nepal/commitlint/blob/main/CHANGELOG.md",
"Homepage": "https://github.com/opensource-nepal/commitlint",
"Source": "https://github.com/opensource-nepal/commitlint"
},
"split_keywords": [
"commitlint",
" commit lint",
" python commitlint",
" conventional commit",
" conventional commit message",
" python commit",
" github actions",
" pre-commit"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5870d48b07b8b56c5864a716902dd5bcc439f68ca72dc22784824dcb9448507d",
"md5": "ac0656cba8c0c2dd39564642e3a1b5b9",
"sha256": "64691dace7caa58ab9bdf904fca27d899935025b445a1c216c911d8fba0b22e4"
},
"downloads": -1,
"filename": "commitlint-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ac0656cba8c0c2dd39564642e3a1b5b9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 27314,
"upload_time": "2024-08-30T04:25:50",
"upload_time_iso_8601": "2024-08-30T04:25:50.638059Z",
"url": "https://files.pythonhosted.org/packages/58/70/d48b07b8b56c5864a716902dd5bcc439f68ca72dc22784824dcb9448507d/commitlint-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bb1261ea68efec07118b2e5a9c0be5a8cb94a77d62dc90609d66eb9d0feebd69",
"md5": "dd60fc95bd69116510ec022f18f9186b",
"sha256": "a8d7f2de60ed0d29d63c1ff2bd71c31acd9425b5e2c2685d90c09abfbb2e3c7f"
},
"downloads": -1,
"filename": "commitlint-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "dd60fc95bd69116510ec022f18f9186b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 28914,
"upload_time": "2024-08-30T04:25:52",
"upload_time_iso_8601": "2024-08-30T04:25:52.034810Z",
"url": "https://files.pythonhosted.org/packages/bb/12/61ea68efec07118b2e5a9c0be5a8cb94a77d62dc90609d66eb9d0feebd69/commitlint-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-30 04:25:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "opensource-nepal",
"github_project": "commitlint",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "commitlint"
}
JSON
