From 14e52e75bd15e4bf37844b4ce3ca2c72ce27be36 Mon Sep 17 00:00:00 2001 From: shenxianpeng Date: Fri, 29 May 2026 08:44:47 +0300 Subject: [PATCH 1/3] docs: add commit-check vs commitlint vs GitHub Rulesets comparison page - Feature-by-feature comparison tables for both commitlint and GitHub Rulesets - Honest positioning: commitlint is the standard, commit-check is broader - GitHub Rulesets are complementary, not competitive (platform vs portable) - 'Use commitlint if / Use commit-check if' decision guide - ASCII workflow diagram showing how all three fit together --- docs/compare.rst | 207 +++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 208 insertions(+) create mode 100644 docs/compare.rst diff --git a/docs/compare.rst b/docs/compare.rst new file mode 100644 index 00000000..ae70b9b3 --- /dev/null +++ b/docs/compare.rst @@ -0,0 +1,207 @@ +commit-check vs commitlint vs GitHub Rulesets +================================================ + +Choosing the right tool depends on what you need to enforce, where you need to +enforce it, and your team's existing stack. This page compares **commit-check** +with the two most common alternatives people ask about: `commitlint`_ and +`GitHub Rulesets`_. + +.. _commitlint: https://commitlint.js.org/ +.. _GitHub Rulesets: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets + + +TL;DR +----- + +- **commitlint** is the standard choice for commit message linting. + 18.6k stars, 3k+ dependents on npm — it is the incumbent and does its one + job well. + +- **commit-check** is for teams that want a broader Git metadata policy layer: + messages, branch names, author identity, sign-off trailers, force-push + safety — in one versioned TOML file that works locally, in CI, and with + AI toolchains. + +- **GitHub Rulesets** are platform-native enforcement built into GitHub. + commit-check complements them with portable, config-as-code, local-first + validation that works **before** code reaches GitHub — in your editor, in + pre-commit hooks, and in CI pipelines on any platform. + + +commit-check vs commitlint +-------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 30 35 35 + + * - Feature + - Commit Check + - commitlint + * - Conventional Commits enforcement + - ✅ semantic-aware + - ✅ semantic-aware + * - Branch naming validation + - ✅ Conventional Branch + - ❌ + * - Force push blocking + - ✅ pre-push hook + - ❌ + * - Author name / email validation + - ✅ + - ❌ + * - Signed-off-by trailer enforcement + - ✅ built-in + - Partial (community plugin) + * - Bot / automation author bypass + - ✅ + - ❌ + * - Zero-config defaults + - ✅ works out of the box + - ❌ requires config file + * - Configuration format + - TOML + - JS / JSON / YAML / TS + * - Organization-level shared config + - ✅ ``inherit_from`` (github: or URL) + - ✅ shareable npm config packages + * - Runtime + - **Python** (3.9+) + - **Node.js** (≥22.12) + * - Pre-commit / Git hook integration + - ✅ first-class + - ✅ via husky + * - CI/CD integration + - ✅ env vars + CLI args + - ✅ + * - GitHub Actions + - ✅ dedicated action + - ✅ community actions + * - Machine-readable JSON output + - ✅ ``--format json``, Python API + - ❌ (text formatters only) + * - Python API (no subprocess) + - ✅ ``commit_check.api`` + - ❌ (JavaScript API only) + * - Open source + - ✅ MIT + - ✅ MIT + + +Which one should you use? +~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Use commitlint if:** + +- You **only** need commit message linting +- Your project already uses Node.js and npm +- You want the established ecosystem with thousands of existing integrations + +**Use commit-check if:** + +- You want to validate **branch names** too (Conventional Branch) +- You want **author / email / signoff** checks in the same tool +- You want **TOML** policy files that are easy to read and diff +- You want **Python-native** tooling (no Node.js dependency) +- You want **JSON output** for automation scripts or AI agents +- You want **zero-config defaults** — run ``commit-check --message`` and get sensible checks immediately +- You want **one shared policy** across many repositories via ``inherit_from`` + + +commit-check vs GitHub Rulesets +-------------------------------- + +GitHub Rulesets are the native policy layer on GitHub.com. They can: + +- Require pull requests, status checks, and CODEOWNERS reviews +- Require signed commits +- Block force pushes +- Restrict commit metadata (author email patterns, commit message regex, **branch/tag name regex**) +- Apply at the **organization** or **enterprise** level +- Protect branches and tags with ``fnmatch`` patterns + +These are powerful and complementary capabilities. commit-check does **not** +compete with them — it operates at a different layer. + +.. list-table:: + :header-rows: 1 + :widths: 30 35 35 + + * - Feature + - Commit Check + - GitHub Rulesets + * - Conventional Commits enforcement + - ✅ semantic-aware + - Partial (regex only, no type/scope awareness) + * - Branch naming convention validation + - ✅ Conventional Branch (semantic) + - ✅ regex patterns + * - Author name / email validation + - ✅ + - ✅ (email regex in push rulesets) + * - Signed-off-by enforcement + - ✅ + - ❌ + * - Force push blocking + - ✅ local pre-push + - ✅ server-side + * - Require pull requests + - ❌ (not its scope) + - ✅ + * - Require status checks / CODEOWNERS + - ❌ (not its scope) + - ✅ + * - Require signed commits + - ❌ (not its scope) + - ✅ + * - Configuration format + - **TOML** (versionable, diffable) + - GitHub UI or REST API + * - Works offline / locally + - ✅ + - ❌ + * - Works in pre-commit hooks + - ✅ + - ❌ + * - Works on any Git platform + - ✅ + - ❌ (GitHub only) + * - Instant feedback (before push) + - ✅ + - ❌ (only on push) + * - Free for all teams + - ✅ MIT + - Requires GitHub plan (Free/Team/Enterprise) + + +How they fit together +~~~~~~~~~~~~~~~~~~~~~ + +GitHub Rulesets are **platform-native enforcement**. commit-check is +**portable, config-as-code, local-first**, and usable before code reaches +GitHub. + +.. code-block:: text + + ┌─────────────────────────────────────────────┐ + │ Your Workflow │ + │ │ + │ [Editor] ──► [pre-commit] ──► [git push] ──► [GitHub] │ + │ │ │ │ + │ commit-check GitHub Rulesets │ + │ (local feedback) (server gating) │ + └─────────────────────────────────────────────┘ + +A recommended setup: + +#. **commit-check** in pre-commit hooks gives developers instant feedback before + they commit or push — catching malformed messages, non-standard branch names, + and missing sign-offs at the desk. +#. **GitHub Rulesets** enforce platform-level requirements that only GitHub can + provide — signed commits, required reviews, status checks. +#. Both can share the same policy intent: your ``cchk.toml`` defines what a + valid commit looks like; Rulesets add a second layer of defense on the + server. + +This is not an either/or choice. Many teams will use **both** — commit-check +for local and CI validation, GitHub Rulesets for repository-level gating. diff --git a/docs/index.rst b/docs/index.rst index a54420c5..777a6b80 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,6 +6,7 @@ self what-is-new configuration + compare example migration troubleshoot From 9eb86b5986203f93e363a499e1b9cd9ff7820e02 Mon Sep 17 00:00:00 2001 From: shenxianpeng Date: Fri, 29 May 2026 08:50:17 +0300 Subject: [PATCH 2/3] docs: add GitHub Rulesets to README comparison; deduplicate docs/compare.rst - Add GitHub Rulesets column to the existing Why Commit Check? feature matrix in README - Add footnotes explaining GitHub Rulesets regex-based enforcement and plan requirements - Trim docs/compare.rst: remove overlapping commitlint table, keep decision guide + workflow - docs/compare.rst now links to README matrix as the canonical feature comparison --- README.rst | 45 +++++++++++++++++++++++++++-- docs/compare.rst | 74 ++++++------------------------------------------ 2 files changed, 51 insertions(+), 68 deletions(-) diff --git a/README.rst b/README.rst index 18d91d64..a54f2147 100644 --- a/README.rst +++ b/README.rst @@ -440,94 +440,113 @@ Why Commit Check? ----------------- The table below compares common approaches to commit policy enforcement. -``commitlint`` is a specialized commit-message linter. Custom Git hooks and -the ``pre-commit`` framework are integration mechanisms, so the last column +``commitlint`` is a specialized commit-message linter. `GitHub Rulesets`_ +are platform-native server-side enforcement. Custom Git hooks and the +``pre-commit`` framework are integration mechanisms, so the last column reflects a DIY approach rather than built-in product features. +.. _GitHub Rulesets: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets + .. list-table:: :header-rows: 1 - :widths: 26 16 16 16 26 + :widths: 20 14 14 14 14 24 * - Feature - Commit Check - commitlint - YACC [#f2]_ + - GitHub Rulesets [#f4]_ - Custom hooks * - Conventional Commits enforcement - ✅ - ✅ - Partial + - Partial [#f5]_ - DIY * - Branch naming validation - ✅ - ❌ - ✅ + - ✅ [#f5]_ - DIY * - Force push blocking - ✅ - ❌ - ❌ + - ✅ - DIY * - Author name / email validation - ✅ - ❌ - ✅ + - ✅ [#f5]_ - DIY * - Signed-off-by trailer enforcement - ✅ - Partial [#f1]_ - ❌ + - ❌ - DIY * - Co-author ignore list - ✅ - ❌ - Partial [#f3]_ + - ❌ - DIY * - Organization-level shared config - ✅ - ✅ - ✅ + - ✅ - DIY * - Zero-config defaults - ✅ - ❌ - ❌ + - ✅ - ❌ * - Works without Node.js - ✅ - ❌ - ✅ + - ✅ - Depends * - Native TOML configuration - ✅ - ❌ - ❌ + - ❌ - Depends * - Git hook / pre-commit integration - ✅ - Partial - ❌ + - ❌ - ✅ * - CI/CD-friendly configuration - ✅ - Partial - ❌ + - ❌ - DIY * - Open source & free - ✅ - ✅ - ❌ + - ❌ [#f6]_ - ✅ * - Client-side (pre-commit) enforcement - ✅ - ✅ - ❌ + - ❌ - ✅ * - AI-native (JSON API + Python SDK) - ✅ - ❌ - ❌ - ❌ + - ❌ *For* ``commitlint``, organization-level shared config is typically delivered via shareable config packages or local files. @@ -539,6 +558,14 @@ the plugin supports global → project → repository config inheritance; it is a server-side pre-receive hook and merge check (no client-side pre-commit), is paid (per-user licensing), and runs on Java (no Node.js needed). +*For* `GitHub Rulesets`_, push rulesets enforce metadata via regex patterns — +they can match branch/tag names, commit messages, and author email, but have +no awareness of Conventional Commits semantics (types, scopes, breaking-change +markers). They apply server-side and require a GitHub plan (Free for public +repos, Team/Enterprise for private/internal repos with push rulesets). They +are not portable to other Git platforms and do not provide local pre-commit +feedback. + ``DIY`` means you can implement a capability with custom Git hooks or ``pre-commit`` scripts, but it is not provided as a turnkey policy layer. @@ -557,6 +584,18 @@ provided as a turnkey policy layer. or service users (bots), but does not parse ``Co-authored-by:`` trailers in commit messages. +.. [#f4] See `commit-check vs GitHub Rulesets + `_ + for a detailed comparison and how they fit together. + +.. [#f5] GitHub Rulesets enforce these via regex patterns in push rulesets + (metadata restrictions). They are regex-based and do not understand + Conventional Commits or Conventional Branch semantics. + +.. [#f6] GitHub Rulesets require a GitHub plan. Push rulesets (metadata + restrictions) require Team or Enterprise plans for private/internal repos; + branch/tag rulesets are available on Free plans for public repos. + Versioning ---------- diff --git a/docs/compare.rst b/docs/compare.rst index ae70b9b3..ca8c87b4 100644 --- a/docs/compare.rst +++ b/docs/compare.rst @@ -2,12 +2,11 @@ commit-check vs commitlint vs GitHub Rulesets ================================================ Choosing the right tool depends on what you need to enforce, where you need to -enforce it, and your team's existing stack. This page compares **commit-check** -with the two most common alternatives people ask about: `commitlint`_ and -`GitHub Rulesets`_. +enforce it, and your team's existing stack. This page is the long-form +companion to the `feature matrix in the README`_ — it explains the tradeoffs +and how the tools fit together. -.. _commitlint: https://commitlint.js.org/ -.. _GitHub Rulesets: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets +.. _feature matrix in the README: https://github.com/commit-check/commit-check#why-commit-check TL;DR @@ -28,68 +27,13 @@ TL;DR pre-commit hooks, and in CI pipelines on any platform. -commit-check vs commitlint --------------------------- - -.. list-table:: - :header-rows: 1 - :widths: 30 35 35 - - * - Feature - - Commit Check - - commitlint - * - Conventional Commits enforcement - - ✅ semantic-aware - - ✅ semantic-aware - * - Branch naming validation - - ✅ Conventional Branch - - ❌ - * - Force push blocking - - ✅ pre-push hook - - ❌ - * - Author name / email validation - - ✅ - - ❌ - * - Signed-off-by trailer enforcement - - ✅ built-in - - Partial (community plugin) - * - Bot / automation author bypass - - ✅ - - ❌ - * - Zero-config defaults - - ✅ works out of the box - - ❌ requires config file - * - Configuration format - - TOML - - JS / JSON / YAML / TS - * - Organization-level shared config - - ✅ ``inherit_from`` (github: or URL) - - ✅ shareable npm config packages - * - Runtime - - **Python** (3.9+) - - **Node.js** (≥22.12) - * - Pre-commit / Git hook integration - - ✅ first-class - - ✅ via husky - * - CI/CD integration - - ✅ env vars + CLI args - - ✅ - * - GitHub Actions - - ✅ dedicated action - - ✅ community actions - * - Machine-readable JSON output - - ✅ ``--format json``, Python API - - ❌ (text formatters only) - * - Python API (no subprocess) - - ✅ ``commit_check.api`` - - ❌ (JavaScript API only) - * - Open source - - ✅ MIT - - ✅ MIT +commitlint or commit-check? +--------------------------- +See the `feature matrix in the README`_ for a side-by-side comparison of +commitlint, commit-check, YACC, GitHub Rulesets, and custom hooks. -Which one should you use? -~~~~~~~~~~~~~~~~~~~~~~~~~ +Here is the decision guide: **Use commitlint if:** From eb36191c86f0a2b80b444abb9e84ed217615f246 Mon Sep 17 00:00:00 2001 From: shenxianpeng Date: Fri, 29 May 2026 08:57:12 +0300 Subject: [PATCH 3/3] docs: remove compare page; consolidate into README table MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Delete docs/compare.rst (redundant with README 'Why Commit Check?' table) - Remove compare from docs/index.rst toctree - README table: fix GitHub Rulesets 'Zero-config defaults' ❌ (not ✅) - Renumber footnotes after removing compare page link - All GitHub Rulesets info now lives in the single README feature matrix --- README.rst | 20 +++---- docs/compare.rst | 151 ----------------------------------------------- docs/index.rst | 1 - 3 files changed, 8 insertions(+), 164 deletions(-) delete mode 100644 docs/compare.rst diff --git a/README.rst b/README.rst index a54f2147..767295f9 100644 --- a/README.rst +++ b/README.rst @@ -455,19 +455,19 @@ reflects a DIY approach rather than built-in product features. - Commit Check - commitlint - YACC [#f2]_ - - GitHub Rulesets [#f4]_ + - GitHub Rulesets - Custom hooks * - Conventional Commits enforcement - ✅ - ✅ - Partial - - Partial [#f5]_ + - Partial [#f4]_ - DIY * - Branch naming validation - ✅ - ❌ - ✅ - - ✅ [#f5]_ + - ✅ [#f4]_ - DIY * - Force push blocking - ✅ @@ -479,7 +479,7 @@ reflects a DIY approach rather than built-in product features. - ✅ - ❌ - ✅ - - ✅ [#f5]_ + - ✅ [#f4]_ - DIY * - Signed-off-by trailer enforcement - ✅ @@ -503,7 +503,7 @@ reflects a DIY approach rather than built-in product features. - ✅ - ❌ - ❌ - - ✅ + - ❌ - ❌ * - Works without Node.js - ✅ @@ -533,7 +533,7 @@ reflects a DIY approach rather than built-in product features. - ✅ - ✅ - ❌ - - ❌ [#f6]_ + - ❌ [#f5]_ - ✅ * - Client-side (pre-commit) enforcement - ✅ @@ -584,15 +584,11 @@ provided as a turnkey policy layer. or service users (bots), but does not parse ``Co-authored-by:`` trailers in commit messages. -.. [#f4] See `commit-check vs GitHub Rulesets - `_ - for a detailed comparison and how they fit together. - -.. [#f5] GitHub Rulesets enforce these via regex patterns in push rulesets +.. [#f4] GitHub Rulesets enforce these via regex patterns in push rulesets (metadata restrictions). They are regex-based and do not understand Conventional Commits or Conventional Branch semantics. -.. [#f6] GitHub Rulesets require a GitHub plan. Push rulesets (metadata +.. [#f5] GitHub Rulesets require a GitHub plan. Push rulesets (metadata restrictions) require Team or Enterprise plans for private/internal repos; branch/tag rulesets are available on Free plans for public repos. diff --git a/docs/compare.rst b/docs/compare.rst deleted file mode 100644 index ca8c87b4..00000000 --- a/docs/compare.rst +++ /dev/null @@ -1,151 +0,0 @@ -commit-check vs commitlint vs GitHub Rulesets -================================================ - -Choosing the right tool depends on what you need to enforce, where you need to -enforce it, and your team's existing stack. This page is the long-form -companion to the `feature matrix in the README`_ — it explains the tradeoffs -and how the tools fit together. - -.. _feature matrix in the README: https://github.com/commit-check/commit-check#why-commit-check - - -TL;DR ------ - -- **commitlint** is the standard choice for commit message linting. - 18.6k stars, 3k+ dependents on npm — it is the incumbent and does its one - job well. - -- **commit-check** is for teams that want a broader Git metadata policy layer: - messages, branch names, author identity, sign-off trailers, force-push - safety — in one versioned TOML file that works locally, in CI, and with - AI toolchains. - -- **GitHub Rulesets** are platform-native enforcement built into GitHub. - commit-check complements them with portable, config-as-code, local-first - validation that works **before** code reaches GitHub — in your editor, in - pre-commit hooks, and in CI pipelines on any platform. - - -commitlint or commit-check? ---------------------------- - -See the `feature matrix in the README`_ for a side-by-side comparison of -commitlint, commit-check, YACC, GitHub Rulesets, and custom hooks. - -Here is the decision guide: - -**Use commitlint if:** - -- You **only** need commit message linting -- Your project already uses Node.js and npm -- You want the established ecosystem with thousands of existing integrations - -**Use commit-check if:** - -- You want to validate **branch names** too (Conventional Branch) -- You want **author / email / signoff** checks in the same tool -- You want **TOML** policy files that are easy to read and diff -- You want **Python-native** tooling (no Node.js dependency) -- You want **JSON output** for automation scripts or AI agents -- You want **zero-config defaults** — run ``commit-check --message`` and get sensible checks immediately -- You want **one shared policy** across many repositories via ``inherit_from`` - - -commit-check vs GitHub Rulesets --------------------------------- - -GitHub Rulesets are the native policy layer on GitHub.com. They can: - -- Require pull requests, status checks, and CODEOWNERS reviews -- Require signed commits -- Block force pushes -- Restrict commit metadata (author email patterns, commit message regex, **branch/tag name regex**) -- Apply at the **organization** or **enterprise** level -- Protect branches and tags with ``fnmatch`` patterns - -These are powerful and complementary capabilities. commit-check does **not** -compete with them — it operates at a different layer. - -.. list-table:: - :header-rows: 1 - :widths: 30 35 35 - - * - Feature - - Commit Check - - GitHub Rulesets - * - Conventional Commits enforcement - - ✅ semantic-aware - - Partial (regex only, no type/scope awareness) - * - Branch naming convention validation - - ✅ Conventional Branch (semantic) - - ✅ regex patterns - * - Author name / email validation - - ✅ - - ✅ (email regex in push rulesets) - * - Signed-off-by enforcement - - ✅ - - ❌ - * - Force push blocking - - ✅ local pre-push - - ✅ server-side - * - Require pull requests - - ❌ (not its scope) - - ✅ - * - Require status checks / CODEOWNERS - - ❌ (not its scope) - - ✅ - * - Require signed commits - - ❌ (not its scope) - - ✅ - * - Configuration format - - **TOML** (versionable, diffable) - - GitHub UI or REST API - * - Works offline / locally - - ✅ - - ❌ - * - Works in pre-commit hooks - - ✅ - - ❌ - * - Works on any Git platform - - ✅ - - ❌ (GitHub only) - * - Instant feedback (before push) - - ✅ - - ❌ (only on push) - * - Free for all teams - - ✅ MIT - - Requires GitHub plan (Free/Team/Enterprise) - - -How they fit together -~~~~~~~~~~~~~~~~~~~~~ - -GitHub Rulesets are **platform-native enforcement**. commit-check is -**portable, config-as-code, local-first**, and usable before code reaches -GitHub. - -.. code-block:: text - - ┌─────────────────────────────────────────────┐ - │ Your Workflow │ - │ │ - │ [Editor] ──► [pre-commit] ──► [git push] ──► [GitHub] │ - │ │ │ │ - │ commit-check GitHub Rulesets │ - │ (local feedback) (server gating) │ - └─────────────────────────────────────────────┘ - -A recommended setup: - -#. **commit-check** in pre-commit hooks gives developers instant feedback before - they commit or push — catching malformed messages, non-standard branch names, - and missing sign-offs at the desk. -#. **GitHub Rulesets** enforce platform-level requirements that only GitHub can - provide — signed commits, required reviews, status checks. -#. Both can share the same policy intent: your ``cchk.toml`` defines what a - valid commit looks like; Rulesets add a second layer of defense on the - server. - -This is not an either/or choice. Many teams will use **both** — commit-check -for local and CI validation, GitHub Rulesets for repository-level gating. diff --git a/docs/index.rst b/docs/index.rst index 777a6b80..a54420c5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,7 +6,6 @@ self what-is-new configuration - compare example migration troubleshoot