diff --git a/.gitignore b/.gitignore index ec82a33..d0f8a0f 100644 --- a/.gitignore +++ b/.gitignore @@ -161,3 +161,4 @@ cython_debug/ .vscode .DS_Store +.ruff_cache diff --git a/README.md b/README.md index 9e24bd4..341a46e 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# 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) @@ -6,79 +6,29 @@ [![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: - -``` -(): - -[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: @@ -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). diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000..d9b8f32 --- /dev/null +++ b/docs/cli.md @@ -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 +``` diff --git a/docs/conventional-commits.md b/docs/conventional-commits.md new file mode 100644 index 0000000..8f5b8bd --- /dev/null +++ b/docs/conventional-commits.md @@ -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: + +``` +(): + +[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).