commit-check · shenxianpeng · Jun 21, 2026 · Jun 21, 2026 · Jun 21, 2026 · Jun 21, 2026
diff --git a/docs/blog/posts/ai-native-commit-check.md b/docs/blog/posts/ai-native-commit-check.md
@@ -0,0 +1,116 @@
+---
+date:
+  created: 2026-06-21
+readtime: 6
+categories:
+  - UPDATES
+tags:
+  - commit-check
+  - automation
+  - ai
+authors:
+  - shenxianpeng
+---
+
+# AI-native: JSON output and a Python API
+
+More and more commits are written — or at least drafted — by AI agents and
+automation. So Commit Check is also built for machines — not just humans reading
+terminal output. This post covers the two
+features that make that possible: machine-readable JSON output and an
+import-friendly Python API.
+
+<!-- more -->
+
+## Structured output with `--format json`
+
+Add `--format json` to any invocation and Commit Check returns structured data
+instead of decorated text. The exit code is unchanged (`0` = pass, `1` = fail),
+so existing CI scripts keep working:
+
+```bash
+echo "feat: add streaming support" | commit-check -m --format json
+```
+
+```json
+{
+  "status": "pass",
+  "checks": [
+    { "check": "message",           "status": "pass", "value": "", "error": "", "suggest": "" },
+    { "check": "subject_imperative", "status": "pass", "value": "", "error": "", "suggest": "" }
+  ]
+}
+```
+
+When a check fails, each result carries the full `error`
+and `suggest` fields an agent needs to **self-correct** — no scraping required:
+
+```bash
+echo "wip bad commit" | commit-check -m --format json
+```
+
+```json
+{
+  "status": "fail",
+  "checks": [
+    {
+      "check":   "message",
+      "status":  "fail",
+      "value":   "wip bad commit",
+      "error":   "The commit message should follow Conventional Commits. See https://www.conventionalcommits.org",
+      "suggest": "Use <type>(<scope>): <description>, where <type> is one of: feat, fix, docs, ..."
+    }
+  ]
+}
+```
+
+Pass the `suggest` string back to an LLM, and it has what it needs to
+rewrite the message and retry.
+
+## Quieter text, for humans
+
+If you live in a terminal but find the ASCII banner noisy, two modes dial it
+down:
+
+- `--no-banner` keeps the failure details and suggestions but drops the
+  ASCII-art banner.
+- `--compact` prints a single `[FAIL]` line per failing check (and implies
+  `--no-banner`).
+
+```bash
+echo "wip bad commit" | commit-check -m --compact
+```
+
+```text
+[FAIL] message: wip bad commit
+```
+
+## The Python API — no subprocess needed
+
+For tools and agents running in Python, spawning a subprocess to validate
+a string adds unnecessary overhead. The `commit_check.api` module exposes
+functions that return plain dicts — easy to serialize, forward to an LLM,
+or chain into a larger workflow:
+
+```python
+from commit_check.api import validate_message, validate_branch, validate_all
+
+result = validate_message("feat: add streaming support")
+if result["status"] != "pass":
+    # hand result straight back to your agent loop
+    ...
+```
+
+Because the functions return the same structured shape as the JSON output,
+you can move between CLI and in-process validation without changing how you
+handle results.
+
+## Why this matters
+
+The same policy that protects a human's `git commit` now protects an agent's
+automated one — and gives that agent the precise feedback it needs to fix its
+own mistakes. One `cchk.toml`, enforced identically whether the author is a
+person, a CI job, or a model.
+
+Read more in the
+[README](https://github.com/commit-check/commit-check#ai-native-usage).
diff --git a/docs/blog/posts/configuring-commit-check.md b/docs/blog/posts/configuring-commit-check.md
@@ -0,0 +1,135 @@
+---
+date:
+  created: 2026-06-21
+readtime: 7
+categories:
+  - UPDATES
+tags:
+  - commit-check
+  - configuration
+authors:
+  - shenxianpeng
+---
+
+# From zero-config to org-wide policy
+
+Commit Check works the moment you install it, but its real strength shows up
+when you start shaping the policy to fit your team. This post covers everything from the default behavior to organization-wide
+shared configuration.
+
+<!-- more -->
+
+## Three places to configure
+
+Commit Check resolves configuration in order of priority:
+
+1. **Command-line arguments** — override settings for a single run
+2. **Environment variables** — `CCHK_*` variables, ideal for CI
+3. **Configuration files** — `cchk.toml` or `commit-check.toml`
+
+If none of these exist, the lenient defaults apply: Conventional Commits for
+messages, Conventional Branch for branch names.
+
+## A real `cchk.toml`
+
+Drop a `cchk.toml` (or `.github/cchk.toml`) in your repository root to take
+control:
+
+```toml
+[commit]
+# https://www.conventionalcommits.org
+conventional_commits = true
+subject_imperative = true
+subject_max_length = 80
+subject_min_length = 5
+allow_commit_types = ["feat", "fix", "docs", "style", "refactor", "test", "chore", "ci"]
+allow_merge_commits = true
+allow_wip_commits = false
+require_signed_off_by = false
+# Bypass checks for bot/automation authors and co-authors:
+ignore_authors = ["dependabot[bot]", "renovate[bot]", "copilot[bot]"]
+
+[branch]
+# https://conventional-branch.github.io/
+conventional_branch = true
+allow_branch_types = ["feature", "bugfix", "hotfix", "release", "chore", "feat", "fix"]
+```
+
+Every field maps to a rule that runs at commit, push, or CI time. Because the
+file lives in your repo, the policy is reviewed and versioned like code.
+
+!!! tip "IDE autocompletion comes for free"
+    Commit Check's TOML schema is published on
+    [SchemaStore](https://www.schemastore.org/), so editors like VS Code (via
+    *Even Better TOML*), PyCharm, and IntelliJ give you autocompletion,
+    validation, and inline docs for `cchk.toml` — no manual schema path needed.
+
+## CLI and environment overrides
+
+For one-off checks or pipeline tweaks, skip the file entirely:
+
+```bash
+# Override per run
+commit-check --message --subject-imperative=true --subject-max-length=72
+
+# Or via environment variables
+export CCHK_SUBJECT_IMPERATIVE=true
+export CCHK_SUBJECT_MAX_LENGTH=72
+commit-check --message
+```
+
+The same overrides work inside pre-commit hook `args`, so a single repo can
+loosen a shared rule without forking the whole policy.
+
+## Share one policy across many repos
+
+`inherit_from` is the feature that makes Commit Check work across an
+organization. Point each repository at a base config and override only what
+differs:
+
+```toml
+# .github/cchk.toml — inherit the org base, then adjust locally
+inherit_from = "github:my-org/.github:cchk.toml"
+
+[commit]
+subject_max_length = 72  # local override wins
+```
+
+`inherit_from` accepts several sources:
+
+- **GitHub shorthand:** `github:owner/repo:path/to/cchk.toml`
+- **Pinned to a ref:** `github:owner/repo@main:path/to/cchk.toml`
+- **Local path:** `../shared/cchk.toml`
+- **HTTPS URL:** `https://example.com/cchk.toml`
+
+The `github:` shorthand fetches from `raw.githubusercontent.com`, and plain
+HTTP URLs are rejected for security. Local settings always override the
+inherited base — so the org sets the floor, and each repo customizes from
+there.
+
+## Don't forget push safety
+
+Policy isn't only about message wording. Use `--no-force-push` in a `pre-push`
+hook to catch history-rewriting pushes:
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/commit-check/commit-check
+    rev: v2.6.0
+    hooks:
+      - id: check-no-force-push
+        stages: [pre-push]
+```
+
+A note: piping `git push` into `commit-check` is **not** a prevention
+mechanism — by then the push has already started. Use the `pre-push` hook
+instead.
+
+## Summary
+
+Start with zero config, add a `cchk.toml` when you want stricter rules, and
+reach for `inherit_from` when you want one standard across every repository.
+Same engine, same file format, scaling with your team.
+
+Full reference: <https://commit-check.github.io/commit-check/configuration.html>
diff --git a/docs/blog/posts/introducing-commit-check.md b/docs/blog/posts/introducing-commit-check.md
@@ -0,0 +1,88 @@
+---
+date:
+  created: 2026-06-21
+readtime: 6
+categories:
+  - ANNOUNCEMENTS
+tags:
+  - commit-check
+authors:
+  - shenxianpeng
+---
+
+# One policy file for your Git history
+
+Most teams have a wiki page titled something like "How we write commit
+messages." It covers commit conventions, branch naming, sign-offs, and
+author email consistency — and then nobody reads it.
+
+**Commit Check** exists to turn that wiki page into something Git actually
+enforces.
+
+<!-- more -->
+
+## A policy engine, not a linter
+
+Commit Check is a lightweight policy engine for Git *metadata* — the parts of a
+commit that live around your code rather than inside it:
+
+- **Commit messages** — Conventional Commits, subject length, imperative mood
+- **Branch names** — Conventional Branch types like `feature/`, `bugfix/`, `release/`
+- **Author identity** — name and email consistency
+- **Sign-off trailers** — `Signed-off-by` for DCO workflows
+- **Push safety** — catch accidental force-pushes before they rewrite history
+
+That word — *policy* — matters. Instead of scattering rules across a CI
+script, a pre-commit hook, and a stale convention doc, you write them
+**once** in a versioned `cchk.toml`.
+
+## Write it once, enforce it everywhere
+
+That single policy file is read by every enforcement point:
+
+```bash
+pip install commit-check
+commit-check --message --branch
+```
+
+The same `cchk.toml` then drives:
+
+- the **CLI** for local one-off checks,
+- **pre-commit** hooks so problems are caught before a commit lands,
+- **CI / GitHub Actions** so pull requests are validated for the whole team.
+
+Because the policy is committed alongside your code, it is reviewed, diffed, and
+versioned like everything else. When the rules change, the change shows up in a
+pull request.
+
+## Zero configuration to start
+
+You do not need a config file to begin. With no `cchk.toml`, Commit Check
+applies lenient, sensible defaults: commit messages should follow
+[Conventional Commits](https://www.conventionalcommits.org/) and branch names
+should follow the [Conventional Branch](https://conventional-branch.github.io/)
+convention. That is enough to get value on day one.
+
+```bash
+echo "feat: add streaming support" | commit-check -m
+```
+
+When you need stricter rules — a maximum subject length, required sign-off,
+or an allow-list of commit types — add a `cchk.toml`. The next post walks
+through the details.
+
+## Add the badge
+
+Once Commit Check is guarding your repository, let people know:
+
+```text
+[![commit-check](https://img.shields.io/badge/commit--check-enabled-brightgreen?logo=Git&logoColor=white&color=%232c9ccd)](https://github.com/commit-check/commit-check)
+```
+
+## Where to go next
+
+- **Getting Started:** <https://commit-check.github.io/commit-check/>
+- **GitHub Action:** <https://github.com/commit-check/commit-check-action>
+- **Source & issues:** <https://github.com/commit-check/commit-check>
+
+Clean commits. Clear standards. One policy file.
diff --git a/docs/blog/posts/myfirst.md b/docs/blog/posts/myfirst.md
diff --git a/docs/blog/posts/mysecond.md b/docs/blog/posts/mysecond.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -8,10 +8,10 @@ copyright: "© Copyright 2022 - 2026, shenxianpeng."
 nav:
   - Home: index.md
   - Getting Started: getting-started.md
-  # - Blog:
-  #     - blog/index.md
-exclude_docs: |
-  blog/**
+  - Blog:
+      - blog/index.md
+# exclude_docs: |
+#   blog/**
 
 theme:
   name: material