Skip to content

docs: update README.rst for v2 #288

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
shenxianpeng merged 3 commits into from
Oct 3, 2025
Merged

docs: update README.rst for v2 #288

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7f80063
docs: update README.rst for v2
shenxianpeng Oct 3, 2025
a4e086d
chore: Update cchk.toml
shenxianpeng Oct 3, 2025
dcf8ffb
docs: update configuration.rst
shenxianpeng Oct 3, 2025
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
94 changes: 44 additions & 50 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,14 +42,14 @@ Configuration
Use Default Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~

- **Commit Check** uses a `default configuration <https://github.com/commit-check/commit-check/blob/main/commit_check/__init__.py>`_ if you do not provide a ``.commit-check.yml`` file.
- **Commit Check** uses a `default configuration <https://github.com/commit-check/commit-check/blob/main/docs/configuration.rst>`_ if you do not provide a ``cchk.toml`` or ``commit-check.toml`` file.

- The default configuration enforces commit message rules based on the `Conventional Commits <https://www.conventionalcommits.org/en/v1.0.0/#summary>`_ specification and branch naming rules based on the `Conventional Branch <https://conventional-branch.github.io/#summary>`_ convention.

Use Custom Configuration
~~~~~~~~~~~~~~~~~~~~~~~~

To customize the behavior, create a config file ``.commit-check.yml`` under your repository's root directory, e.g., `.commit-check.yml <https://github.com/commit-check/commit-check/blob/main/.commit-check.yml>`_
To customize the behavior, create a config file ``cchk.toml`` or ``commit-check.toml`` under your repository's root directory, e.g., `cchk.toml <https://github.com/commit-check/commit-check/blob/main/cchk.toml>`_

Usage
-----
Expand All @@ -75,9 +75,6 @@ Running as pre-commit hook
- id: check-branch
- id: check-author-name
- id: check-author-email
- id: check-commit-signoff
- id: check-merge-base # requires download all git history
- id: check-imperative

Running as CLI
~~~~~~~~~~~~~~
Expand Down Expand Up @@ -112,7 +109,7 @@ To configure the hook, create a script file in the ``.git/hooks/`` directory.
.. code-block:: bash

#!/bin/sh
commit-check --message --branch --author-name --author-email --commit-signoff --merge-base --imperative
commit-check --message --branch --author-name --author-email

Save the script file as ``pre-push`` and make it executable:

Expand All @@ -131,26 +128,21 @@ Check Commit Message Failed

Commit rejected by Commit-Check.

(c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c)
/ ._. \ / ._. \ / ._. \ / ._. \ / ._. \
__\( C )/__ __\( H )/__ __\( E )/__ __\( C )/__ __\( K )/__
(c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c)
/ ._. \ / ._. \ / ._. \ / ._. \ / ._. \
__\( C )/__ __\( H )/__ __\( E )/__ __\( C )/__ __\( K )/__
(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)
|| E || || R || || R || || O || || R ||
_.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._
|| E || || R || || R || || O || || R ||
_.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._
(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)
`-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´
`-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´

Type message check failed => my test commit message
It doesn't match regex: ^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test){1}(\([\w\-\.]+\))?(!)?: ([\w ])+([\s\S]*)

The commit message should be structured as follows:

<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Commit rejected.

More details please refer to https://www.conventionalcommits.org
Suggest: please check your commit message whether matches above regex
Type message check failed ==> test commit message check
It doesn't match regex: ^(chore|ci|docs|feat|fix|refactor|style|test){1}(\([\w\-\.]+\))?(!)?: ([\w ])+([\s\S]*)|(Merge).*|(fixup!.*)
The commit message should follow Conventional Commits. See https://www.conventionalcommits.org
Suggest: Use <type>(<scope>): <description> with allowed types


Check Branch Naming Failed
Expand All @@ -159,21 +151,21 @@ Check Branch Naming Failed

Commit rejected by Commit-Check.

(c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c)
/ ._. \ / ._. \ / ._. \ / ._. \ / ._. \
__\( C )/__ __\( H )/__ __\( E )/__ __\( C )/__ __\( K )/__
(c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c)
/ ._. \ / ._. \ / ._. \ / ._. \ / ._. \
__\( C )/__ __\( H )/__ __\( E )/__ __\( C )/__ __\( K )/__
(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)
|| E || || R || || R || || O || || R ||
_.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._
|| E || || R || || R || || O || || R ||
_.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._
(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)
`-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´
`-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´

Commit rejected.

Type branch check failed => patch-1
It doesn't match regex: ^(bugfix|feature|release|hotfix|task|chore)\/.+|(master)|(main)|(HEAD)|(PR-.+)
Branches must begin with these types: bugfix/ feature/ release/ hotfix/ task/ chore/
Suggest: run command `git checkout -b type/branch_name`
Type branch check failed ==> test-branch
It doesn't match regex: ^(feature|bugfix|hotfix|release|chore|feat|fix)\/.+|(master)|(main)|(HEAD)|(PR-.+)
The branch should follow Conventional Branch. See https://conventional-branches.github.io/
Suggest: git checkout -b <type>/<branch_name>


Check Commit Signature Failed
Expand All @@ -182,21 +174,21 @@ Check Commit Signature Failed

Commit rejected by Commit-Check.

(c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c)
/ ._. \ / ._. \ / ._. \ / ._. \ / ._. \
__\( C )/__ __\( H )/__ __\( E )/__ __\( C )/__ __\( K )/__
(c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c)
/ ._. \ / ._. \ / ._. \ / ._. \ / ._. \
__\( C )/__ __\( H )/__ __\( E )/__ __\( C )/__ __\( K )/__
(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)
|| E || || R || || R || || O || || R ||
_.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._
|| E || || R || || R || || O || || R ||
_.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._
(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)
`-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´
`-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´

Commit rejected.

Type signoff check failed => c92ce259ff041c91859c7fb61afdbb391e769d0f
Type require_signed_off_by check failed ==> fix: add missing file
It doesn't match regex: Signed-off-by:.*[A-Za-z0-9]\s+<.+@.+>
Signed-off-by not found in latest commit
Suggest: run command `git commit -m "conventional commit message" --signoff`
Suggest: git commit --amend --signoff or use --signoff on commit


Check Imperative Mood Failed
Expand All @@ -205,22 +197,24 @@ Check Imperative Mood Failed

Commit rejected by Commit-Check.

(c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c)
/ ._. \ / ._. \ / ._. \ / ._. \ / ._. \
__\( C )/__ __\( H )/__ __\( E )/__ __\( C )/__ __\( K )/__
(c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c)
/ ._. \ / ._. \ / ._. \ / ._. \ / ._. \
__\( C )/__ __\( H )/__ __\( E )/__ __\( C )/__ __\( K )/__
(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)
|| E || || R || || R || || O || || R ||
_.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._
|| E || || R || || R || || O || || R ||
_.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._ _.' '-' '._
(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)
`-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´
`-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´ `-´

Commit rejected.

Type imperative check failed => Added file
It doesn't match regex: imperative mood pattern
Commit message should use imperative mood (e.g., "Add feature" not "Added feature")
Suggest: Use imperative mood in commit message like "Add", "Fix", "Update", "Remove"
Type imperative check failed ==> fix: added missing file
It doesn't match regex:
Commit message should use imperative mood (e.g., 'Add feature' not 'Added feature')
Suggest: Use imperative mood in the subject line


And many more... see `commit-check.toml <cchk.toml>`_ for all available checks.

Badging your repository
-----------------------
Expand Down
2 changes: 1 addition & 1 deletion cchk.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
conventional_commits = true
subject_capitalized = false
subject_imperative = true
subject_max_length = 50
subject_max_length = 80
subject_min_length = 5
allow_commit_types = ["feat", "fix", "docs", "style", "refactor", "test", "chore", "ci"]
allow_merge_commits = true
Expand Down
62 changes: 36 additions & 26 deletions docs/configuration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,13 @@ Configuration

``commit-check`` configuration file support TOML format.

See ``cchk.toml`` for the default configuration values.
See ``cchk.toml`` for an example configuration.

**Default Behavior**: When no configuration file exists, commit-check uses sensible defaults with minimal restrictions.

Only conventional commits format, subject capitalization, and imperative mood are enforced by default.

No length limits, author restrictions, or rebase requirements are applied.

commit-check can be configured via a ``cchk.toml`` or ``commit-check.toml`` file.

Expand All @@ -17,26 +22,26 @@ The file should be placed in the root of your repository.
conventional_commits = true
subject_capitalized = true
subject_imperative = true
subject_max_length = 50
subject_min_length = 5
# subject_max_length = 50 # Optional - no limit by default
# subject_min_length = 5 # Optional - no limit by default
allow_commit_types = ["feat", "fix", "docs", "style", "refactor", "test", "chore"]
allow_merge_commits = true
allow_revert_commits = true
allow_empty_commits = false
allow_fixup_commits = true
allow_wip_commits = false
require_body = false
allow_authors = []
ignore_authors = ["dependabot[bot]", "dependabot-preview[bot]"]
require_signed_off_by = true
required_signoff_name = "Your Name"
required_signoff_email = "your.email@example.com"
# allow_authors = [] # Optional - all authors allowed by default
# ignore_authors = [] # Optional - no authors ignored by default
require_signed_off_by = false
# required_signoff_name = "Your Name" # Optional
# required_signoff_email = "your.email@example.com" # Optional

[branch]
# https://conventional-branch.github.io/
conventional_branch = true
allow_branch_types = ["feature", "bugfix", "hotfix", "release", "chore", "feat", "fix"]
require_rebase_target = "main"
# require_rebase_target = "main" # Optional - no rebase requirement by default



Expand Down Expand Up @@ -69,12 +74,12 @@ options table description
* - commit
- subject_max_length
- int
- 50
- None (no limit)
- Maximum length of the subject line.
* - commit
- subject_min_length
- int
- 5
- None (no limit)
- Minimum length of the subject line.
* - commit
- allow_commit_types
Expand Down Expand Up @@ -111,6 +116,21 @@ options table description
- bool
- false
- Require a body in the commit message.
* - commit
- allow_authors
- list[str]
- [] (all allowed)
- List of allowed authors. If empty, all authors are allowed except those in ignore_authors.
* - commit
- ignore_authors
- list[str]
- [] (none ignored)
- List of authors to ignore (i.e., always allow).
Comment on lines +120 to +128
Copy link
Contributor

@coderabbitai coderabbitai bot Oct 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Clarify the allow_authors / ignore_authors defaults

The new description is self‑contradictory: it says that an empty allow_authors means “all authors are allowed except those in ignore_authors,” while the very next row explains that ignore_authors members are “always allow[ed].” Please reconcile these statements so readers know whether authors listed in ignore_authors are permitted or blocked when allow_authors is empty. A consistent explanation (and matching example comment above) is needed to avoid misconfiguration.

🤖 Prompt for AI Agents 
In docs/configuration.rst around lines 120 to 128, the two rows for
allow_authors and ignore_authors are self-contradictory; decide and document a
single consistent behavior and update both rows and the example
accordingly—specifically, make ignore_authors explicitly "List of authors to
always allow (exempt from allow_authors restrictions)" and change the
allow_authors row to "[] (all allowed) — If empty, all authors are allowed;
authors listed in ignore_authors are still permitted." Ensure the example
comment above matches this wording.

* - commit
- require_signed_off_by
- bool
- false
- Require "Signed-off-by" line in the commit message footer.
* - branch
- conventional_branch
- bool
Expand All @@ -121,18 +141,8 @@ options table description
- list[str]
- ["feature", "bugfix", "hotfix", "release", "chore", "feat", "fix"]
- Allowed branch types when conventional_branch is true.
* - author
- allow_authors
- list[str]
- []
- List of allowed authors. If empty, all authors are allowed except those in ignore_authors.
* - author
- ignore_authors
- list[str]
- ["dependabot[bot]", "dependabot-preview[bot]"]
- List of authors to ignore (i.e., always allow).
* - author
- require_signed_off_by
- bool
- true
- Require "Signed-off-by" line in the commit message footer.
* - branch
- require_rebase_target
- str
- None (no requirement)
- Target branch for rebase requirement. If not set, no rebase validation is performed.
Loading