Skip to content

docs: add comprehensive examples page #303

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 12, 2025
Merged

docs: add comprehensive examples page #303

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
4a2f597
docs: add example.rst
shenxianpeng Oct 12, 2025
ae162e3
docs: fix example.rst level inconsistent
shenxianpeng Oct 12, 2025
1cd8c3c
docs: fix example.rst to link cli_args.html
shenxianpeng Oct 12, 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
129 changes: 19 additions & 110 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,88 +48,44 @@ Version 2.0.0 is a major release featuring a new configuration format, a moderni

For the full list of updates and improvements, visit the `What's New <https://commit-check.github.io/commit-check/what-is-new.html>`_ page.

Configuration
-------------

Use Default Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~

- **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 is lenient — it only checks whether commit messages follow the `Conventional Commits <https://www.conventionalcommits.org/en/v1.0.0/#summary>`_ specification and branch names follow the `Conventional Branch <https://conventional-branch.github.io/#summary>`_ convention.

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

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

Usage
-----

Running as GitHub Action
~~~~~~~~~~~~~~~~~~~~~~~~

Please see `commit-check/commit-check-action <https://github.com/commit-check/commit-check-action>`_

Running as pre-commit hook
~~~~~~~~~~~~~~~~~~~~~~~~~~
Installation
------------

.. tip::

Make sure ``pre-commit`` is `installed <https://pre-commit.com/#install>`_.

.. code-block:: yaml

- repo: https://github.com/commit-check/commit-check
rev: the tag or revision
hooks:
- id: check-message
- id: check-branch
- id: check-author-name
- id: check-author-email

Running as CLI
~~~~~~~~~~~~~~

Install globally
To install Commit Check, you can use pip:

.. code-block:: bash

sudo pip3 install -U commit-check
pip install commit-check

Install locally

.. code-block:: bash

pip install -U commit-check

Install from source code
Or install directly from the GitHub repository:

.. code-block:: bash

pip install git+https://github.com/commit-check/commit-check.git@main

Then, run ``commit-check --help`` or ``cchk --help`` (alias for ``commit-check``) from the command line.

For more information, see the `docs <https://commit-check.github.io/commit-check/cli_args.html>`_.

Running as Git Hooks
~~~~~~~~~~~~~~~~~~~~

To configure the hook, create a script file in the ``.git/hooks/`` directory.
Configuration
-------------

.. code-block:: bash
Use Default Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~

#!/bin/sh
commit-check --message --branch --author-name --author-email
- **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.

Save the script file as ``pre-push`` and make it executable:
- The default configuration is lenient — it only checks whether commit messages follow the `Conventional Commits <https://www.conventionalcommits.org/en/v1.0.0/#summary>`_ specification and branch names follow the `Conventional Branch <https://conventional-branch.github.io/#summary>`_ convention.

.. code-block:: bash
Use Custom Configuration
~~~~~~~~~~~~~~~~~~~~~~~~

chmod +x .git/hooks/pre-push
To customize the behavior, create a configuration file named ``cchk.toml`` or ``commit-check.toml`` in your repository's root directory, e.g., `cchk.toml <https://github.com/commit-check/commit-check/blob/main/cchk.toml>`_

Usage
-----

Now, ``git push`` will trigger this hook automatically.
For detailed usage instructions including pre-commit hooks, CLI commands, and STDIN examples, see the `Usage Examples documentation <https://commit-check.github.io/commit-check/example.html>`_.

Examples
--------
Expand Down Expand Up @@ -179,54 +135,7 @@ Check Branch Naming Failed
The branch should follow Conventional Branch. See https://conventional-branch.github.io/
Suggest: Use <type>/<description> with allowed types or ignore_authors in config branch section to bypass


Check Commit Signature Failed

.. code-block:: text

Commit rejected by Commit-Check.

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

Commit rejected.

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: git commit --amend --signoff or use --signoff on commit


Check Imperative Mood Failed

.. code-block:: text

Commit rejected by Commit-Check.

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

Commit rejected.

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 `configuration <https://commit-check.github.io/commit-check/configuration.html>`_ for all available checks.
More examples see `example documentation <https://commit-check.github.io/commit-check/example.html>`_.

Badging your repository
-----------------------
Expand Down
1 change: 1 addition & 0 deletions commit_check/imperatives.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -164,6 +164,7 @@
"raise",
"read",
"record",
"redesign",
"refer",
"refresh",
"register",
Expand Down
2 changes: 0 additions & 2 deletions docs/changelog.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
:status: new

Changelog
=========

Expand Down
Loading
Loading