From 4a2f597695b2f6cdf95e0fda15b399fa8986a417 Mon Sep 17 00:00:00 2001 From: Xianpeng Shen Date: Sun, 12 Oct 2025 23:44:29 +0300 Subject: [PATCH 1/3] docs: add example.rst --- README.rst | 129 ++----------- commit_check/imperatives.py | 1 + docs/changelog.rst | 2 - docs/example.rst | 354 ++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 5 files changed, 375 insertions(+), 112 deletions(-) create mode 100644 docs/example.rst diff --git a/README.rst b/README.rst index a7f8a6a4..213dbff4 100644 --- a/README.rst +++ b/README.rst @@ -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 `_ page. -Configuration -------------- - -Use Default Configuration -~~~~~~~~~~~~~~~~~~~~~~~~~ - -- **Commit Check** uses a `default configuration `_ 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 `_ specification and branch names follow the `Conventional Branch `_ 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 `_ - -Usage ------ - -Running as GitHub Action -~~~~~~~~~~~~~~~~~~~~~~~~ - -Please see `commit-check/commit-check-action `_ - -Running as pre-commit hook -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Installation +------------ -.. tip:: - - Make sure ``pre-commit`` is `installed `_. - -.. 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 `_. -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 `_ 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 `_ specification and branch names follow the `Conventional Branch `_ 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 `_ + +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 `_. Examples -------- @@ -179,54 +135,7 @@ Check Branch Naming Failed The branch should follow Conventional Branch. See https://conventional-branch.github.io/ Suggest: Use / 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 `_ for all available checks. +More examples see `example documentation `_. Badging your repository ----------------------- diff --git a/commit_check/imperatives.py b/commit_check/imperatives.py index bab31cbd..1a1684f5 100644 --- a/commit_check/imperatives.py +++ b/commit_check/imperatives.py @@ -164,6 +164,7 @@ "raise", "read", "record", + "redesign", "refer", "refresh", "register", diff --git a/docs/changelog.rst b/docs/changelog.rst index db8da8b3..b6c5592f 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -1,5 +1,3 @@ -:status: new - Changelog ========= diff --git a/docs/example.rst b/docs/example.rst new file mode 100644 index 00000000..ad0854c2 --- /dev/null +++ b/docs/example.rst @@ -0,0 +1,354 @@ +Usage Examples +============== + +This guide demonstrates how to use commit-check to validate commit messages, branch names, and author information. + +There are several ways to use commit-check: as a pre-commit hook, via STDIN, or directly with files. + +Running as GitHub Action +------------------------ + +Please see `commit-check/commit-check-action `_ + +Running as pre-commit hook +--------------------------- + +1. **Install pre-commit:** + +.. tip:: + + Make sure ``pre-commit`` is `installed `_. + +.. code-block:: bash + + pip install pre-commit + +2. **Create .pre-commit-config.yaml:** + +.. 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 + +3. **Install the hooks:** + +.. code-block:: bash + + pre-commit install --hook-type pre-commit --hook-type commit-msg + +4. **Test the integration:** + +.. code-block:: bash + + # This will trigger validation automatically + git commit -m "feat: add new user authentication system" + + +Pre-commit Validation Examples +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**✅ Successful Validation:** + +.. code-block:: text + + $ git commit -m "feat: add user authentication system" + + check commit message.....................................................Passed + check committer name.....................................................Passed + check committer email....................................................Passed + [main abc1234] feat: add user authentication system + +**❌ Failed Validation:** + +.. code-block:: text + + $ git commit -m "bad commit message" + + check commit message.....................................................Failed + - hook id: check-message + - exit code: 1 + + 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 message check failed ==> bad commit message + It doesn't match regex: ^(feat|fix|docs|style|refactor|test|chore)(\(.+\))?: .+ + The commit message should follow Conventional Commits. See https://www.conventionalcommits.org + Suggest: Use (): with allowed types + + +Running as CLI +-------------- + +Commit-check provides several command-line options for different validation scenarios. via options or STDIN + +.. tip :: + Validate commit messages by piping them through STDIN. This is useful for testing or scripting. + +Available Commands see `commit-check --help `_ + +Message Validation Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + # Validate message from STDIN + echo "feat: new feature" | commit-check -m + + # Validate message from file + commit-check -m commit_message.txt + + # Validate current git commit message (from git log) + commit-check -m + + +**Reading from file:** + +.. code-block:: bash + + # Create a commit message file + cat > commit_message.txt << EOF + fix(auth): resolve login timeout issue + + Users were experiencing timeouts during login. + Increased session timeout and improved error handling. + + Fixes #123 + EOF + + # Validate from file + commit-check -m commit_message.txt + + # Or pipe file content + cat commit_message.txt | commit-check -m + + +Branch Validation Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + # Check current branch name + commit-check --branch + + # Example valid branch names: + # - feature/user-auth + # - fix/login-bug + # - hotfix/security-patch + # - release/v1.2.0 + +Author Validation Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + # Check author name + commit-check --author-name + + # Check author email + commit-check --author-email + + # Check both author name and email + commit-check --author-name --author-email + + +Configuration Examples +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + # Use custom configuration file + echo "feat: test" | commit-check --config my-config.toml -m + + # Use configuration from different directory + commit-check --config /path/to/config/cchk.toml -m + + +Valid Commit Message Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + # Basic feature + echo "feat: add user registration" | commit-check -m + + # Feature with scope + echo "feat(auth): implement OAuth2 login" | commit-check -m + + # Bug fix + echo "fix: resolve memory leak in parser" | commit-check -m + + # Documentation update + echo "docs: add installation guide" | commit-check -m + + # Breaking change + echo "feat!: redesign API endpoints" | commit-check -m + + # Merge commit (automatically allowed) + echo "Merge pull request #123 from feature/new-api" | commit-check -m + +Invalid Commit Message Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + # No type prefix + echo "added new feature" | commit-check -m + + # Capitalized (if configured to disallow) + echo "feat: Add new feature" | commit-check -m + + # Too short + echo "fix" | commit-check -m + + # Non-imperative mood + echo "feat: added login functionality" | commit-check -m + + # Unknown type + echo "unknown: some changes" | commit-check -m + +Error Output Examples +^^^^^^^^^^^^^^^^^^^^^ + +**Commit Message Validation Failure:** + +.. 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 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 (): with allowed types + +**Branch Name Validation Failure:** + +.. 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 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-branch.github.io/ + Suggest: Use / with allowed types or ignore_authors in config branch section to bypass + +**Commit Signature Validation Failure:** + +.. 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 + +**Imperative Mood Validation Failure:** + +.. 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 + + +Integration Tips +---------------- + +CI/CD Integration +~~~~~~~~~~~~~~~~ + +You can use commit-check in CI/CD pipelines: + +.. code-block:: bash + + # In your CI script + git log --format="%s" -n 1 | commit-check -m + + # or just + commit-check -m + +Scripting +~~~~~~~~~ + +Use commit-check in scripts to validate commit messages programmatically: + +.. code-block:: bash + + #!/bin/bash + # validate-commits.sh + + # Get all commit messages from last 10 commits + for i in {0..9}; do + msg=$(git log --format="%s" -n 1 --skip=$i) + if [ -n "$msg" ]; then + echo "Validating: $msg" + echo "$msg" | commit-check -m || exit 1 + fi + done + + echo "All commits are valid!" + +For more configuration options, see the `Configuration Documentation `_. diff --git a/docs/index.rst b/docs/index.rst index f500ea2d..a54420c5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,6 +6,7 @@ self what-is-new configuration + example migration troubleshoot changelog From ae162e30921427340668eb82288664644695eb73 Mon Sep 17 00:00:00 2001 From: Xianpeng Shen Date: Sun, 12 Oct 2025 23:49:50 +0300 Subject: [PATCH 2/3] docs: fix example.rst level inconsistent --- docs/example.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/example.rst b/docs/example.rst index ad0854c2..1653db46 100644 --- a/docs/example.rst +++ b/docs/example.rst @@ -103,7 +103,7 @@ Commit-check provides several command-line options for different validation scen Available Commands see `commit-check --help `_ Message Validation Examples -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash @@ -139,7 +139,7 @@ Message Validation Examples Branch Validation Examples -^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash @@ -153,7 +153,7 @@ Branch Validation Examples # - release/v1.2.0 Author Validation Examples -^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash @@ -168,7 +168,7 @@ Author Validation Examples Configuration Examples -^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash @@ -180,7 +180,7 @@ Configuration Examples Valid Commit Message Examples -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash @@ -203,7 +203,7 @@ Valid Commit Message Examples echo "Merge pull request #123 from feature/new-api" | commit-check -m Invalid Commit Message Examples -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash @@ -223,7 +223,7 @@ Invalid Commit Message Examples echo "unknown: some changes" | commit-check -m Error Output Examples -^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~ **Commit Message Validation Failure:** @@ -318,7 +318,7 @@ Integration Tips ---------------- CI/CD Integration -~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~ You can use commit-check in CI/CD pipelines: From 1cd8c3cc7ecbf27b07a99f36e069f20d4a3918cd Mon Sep 17 00:00:00 2001 From: Xianpeng Shen Date: Sun, 12 Oct 2025 23:57:25 +0300 Subject: [PATCH 3/3] docs: fix example.rst to link cli_args.html --- docs/example.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/example.rst b/docs/example.rst index 1653db46..e7301f13 100644 --- a/docs/example.rst +++ b/docs/example.rst @@ -100,7 +100,7 @@ Commit-check provides several command-line options for different validation scen .. tip :: Validate commit messages by piping them through STDIN. This is useful for testing or scripting. -Available Commands see `commit-check --help `_ +Available Commands see `commit-check --help `_ Message Validation Examples ~~~~~~~~~~~~~~~~~~~~~~~~~~~