Skip to content

Commit ea86934

Browse files
shenxianpengclaude
shenxianpeng
and
claude
authored
docs(blog): add three articles introducing commit-check (#6)
Adds three blog posts to `docs/blog/posts/` for the commit-check site. ## Articles 1. **One policy file for your Git history** (`introducing-commit-check.md`) — overview of commit-check as a lightweight policy engine for Git metadata; one `cchk.toml`, enforced across CLI / pre-commit / CI; zero-config defaults and the enabled badge. 2. **From zero-config to org-wide policy** (`configuring-commit-check.md`) — configuration priority (CLI args → `CCHK_*` env → config file), a real `cchk.toml`, SchemaStore IDE autocompletion, CLI/env overrides, `inherit_from` for org-wide config, and `pre-push` force-push safety. 3. **AI-native: JSON output and a Python API** (`ai-native-commit-check.md`) — `--format json` structured output with `error`/`suggest` for agent self-correction, `--no-banner` / `--compact` quieter modes, and the `commit_check.api` Python interface. All content is drawn from the current project README and `cchk.toml`. Each post uses the existing blog frontmatter format (date, categories, tags, author `shenxianpeng`). 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- _Generated by [Claude Code](https://claude.ai/code/session_01GDSwJ4o6by3HrzUSzhFLJG)_ <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added blog post introducing Commit Check and its policy-driven workflow. * Added configuration guide for setting up rules across CLI, environment variables, and `cchk.toml` with sharing via inheritance. * Added AI-native Commit Check post, including `--format json` structured output and an in-process Python API. * Updated site navigation to enable the Blog section and included blog pages in the build. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent ee6c650 commit ea86934

6 files changed

Lines changed: 343 additions & 42 deletions

File tree

‎docs/blog/posts/ai-native-commit-check.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
---
2+
date:
3+
created: 2026-06-21
4+
readtime: 6
5+
categories:
6+
- UPDATES
7+
tags:
8+
- commit-check
9+
- automation
10+
- ai
11+
authors:
12+
- shenxianpeng
13+
---
14+
15+
# AI-native: JSON output and a Python API
16+
17+
More and more commits are written — or at least drafted — by AI agents and
18+
automation. So Commit Check is also built for machines — not just humans reading
19+
terminal output. This post covers the two
20+
features that make that possible: machine-readable JSON output and an
21+
import-friendly Python API.
22+
23+
<!-- more -->
24+
25+
## Structured output with `--format json`
26+
27+
Add `--format json` to any invocation and Commit Check returns structured data
28+
instead of decorated text. The exit code is unchanged (`0` = pass, `1` = fail),
29+
so existing CI scripts keep working:
30+
31+
```bash
32+
echo "feat: add streaming support" | commit-check -m --format json
33+
```
34+
35+
```json
36+
{
37+
"status": "pass",
38+
"checks": [
39+
{ "check": "message", "status": "pass", "value": "", "error": "", "suggest": "" },
40+
{ "check": "subject_imperative", "status": "pass", "value": "", "error": "", "suggest": "" }
41+
]
42+
}
43+
```
44+
45+
When a check fails, each result carries the full `error`
46+
and `suggest` fields an agent needs to **self-correct** — no scraping required:
47+
48+
```bash
49+
echo "wip bad commit" | commit-check -m --format json
50+
```
51+
52+
```json
53+
{
54+
"status": "fail",
55+
"checks": [
56+
{
57+
"check": "message",
58+
"status": "fail",
59+
"value": "wip bad commit",
60+
"error": "The commit message should follow Conventional Commits. See https://www.conventionalcommits.org",
61+
"suggest": "Use <type>(<scope>): <description>, where <type> is one of: feat, fix, docs, ..."
62+
}
63+
]
64+
}
65+
```
66+
67+
Pass the `suggest` string back to an LLM, and it has what it needs to
68+
rewrite the message and retry.
69+
70+
## Quieter text, for humans
71+
72+
If you live in a terminal but find the ASCII banner noisy, two modes dial it
73+
down:
74+
75+
- `--no-banner` keeps the failure details and suggestions but drops the
76+
ASCII-art banner.
77+
- `--compact` prints a single `[FAIL]` line per failing check (and implies
78+
`--no-banner`).
79+
80+
```bash
81+
echo "wip bad commit" | commit-check -m --compact
82+
```
83+
84+
```text
85+
[FAIL] message: wip bad commit
86+
```
87+
88+
## The Python API — no subprocess needed
89+
90+
For tools and agents running in Python, spawning a subprocess to validate
91+
a string adds unnecessary overhead. The `commit_check.api` module exposes
92+
functions that return plain dicts — easy to serialize, forward to an LLM,
93+
or chain into a larger workflow:
94+
95+
```python
96+
from commit_check.api import validate_message, validate_branch, validate_all
97+
98+
result = validate_message("feat: add streaming support")
99+
if result["status"] != "pass":
100+
# hand result straight back to your agent loop
101+
...
102+
```
103+
104+
Because the functions return the same structured shape as the JSON output,
105+
you can move between CLI and in-process validation without changing how you
106+
handle results.
107+
108+
## Why this matters
109+
110+
The same policy that protects a human's `git commit` now protects an agent's
111+
automated one — and gives that agent the precise feedback it needs to fix its
112+
own mistakes. One `cchk.toml`, enforced identically whether the author is a
113+
person, a CI job, or a model.
114+
115+
Read more in the
116+
[README](https://github.com/commit-check/commit-check#ai-native-usage).

‎docs/blog/posts/configuring-commit-check.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
date:
3+
created: 2026-06-21
4+
readtime: 7
5+
categories:
6+
- UPDATES
7+
tags:
8+
- commit-check
9+
- configuration
10+
authors:
11+
- shenxianpeng
12+
---
13+
14+
# From zero-config to org-wide policy
15+
16+
Commit Check works the moment you install it, but its real strength shows up
17+
when you start shaping the policy to fit your team. This post covers everything from the default behavior to organization-wide
18+
shared configuration.
19+
20+
<!-- more -->
21+
22+
## Three places to configure
23+
24+
Commit Check resolves configuration in order of priority:
25+
26+
1. **Command-line arguments** — override settings for a single run
27+
2. **Environment variables** — `CCHK_*` variables, ideal for CI
28+
3. **Configuration files** — `cchk.toml` or `commit-check.toml`
29+
30+
If none of these exist, the lenient defaults apply: Conventional Commits for
31+
messages, Conventional Branch for branch names.
32+
33+
## A real `cchk.toml`
34+
35+
Drop a `cchk.toml` (or `.github/cchk.toml`) in your repository root to take
36+
control:
37+
38+
```toml
39+
[commit]
40+
# https://www.conventionalcommits.org
41+
conventional_commits = true
42+
subject_imperative = true
43+
subject_max_length = 80
44+
subject_min_length = 5
45+
allow_commit_types = ["feat", "fix", "docs", "style", "refactor", "test", "chore", "ci"]
46+
allow_merge_commits = true
47+
allow_wip_commits = false
48+
require_signed_off_by = false
49+
# Bypass checks for bot/automation authors and co-authors:
50+
ignore_authors = ["dependabot[bot]", "renovate[bot]", "copilot[bot]"]
51+
52+
[branch]
53+
# https://conventional-branch.github.io/
54+
conventional_branch = true
55+
allow_branch_types = ["feature", "bugfix", "hotfix", "release", "chore", "feat", "fix"]
56+
```
57+
58+
Every field maps to a rule that runs at commit, push, or CI time. Because the
59+
file lives in your repo, the policy is reviewed and versioned like code.
60+
61+
!!! tip "IDE autocompletion comes for free"
62+
Commit Check's TOML schema is published on
63+
[SchemaStore](https://www.schemastore.org/), so editors like VS Code (via
64+
*Even Better TOML*), PyCharm, and IntelliJ give you autocompletion,
65+
validation, and inline docs for `cchk.toml` — no manual schema path needed.
66+
67+
## CLI and environment overrides
68+
69+
For one-off checks or pipeline tweaks, skip the file entirely:
70+
71+
```bash
72+
# Override per run
73+
commit-check --message --subject-imperative=true --subject-max-length=72
74+
75+
# Or via environment variables
76+
export CCHK_SUBJECT_IMPERATIVE=true
77+
export CCHK_SUBJECT_MAX_LENGTH=72
78+
commit-check --message
79+
```
80+
81+
The same overrides work inside pre-commit hook `args`, so a single repo can
82+
loosen a shared rule without forking the whole policy.
83+
84+
## Share one policy across many repos
85+
86+
`inherit_from` is the feature that makes Commit Check work across an
87+
organization. Point each repository at a base config and override only what
88+
differs:
89+
90+
```toml
91+
# .github/cchk.toml — inherit the org base, then adjust locally
92+
inherit_from = "github:my-org/.github:cchk.toml"
93+
94+
[commit]
95+
subject_max_length = 72 # local override wins
96+
```
97+
98+
`inherit_from` accepts several sources:
99+
100+
- **GitHub shorthand:** `github:owner/repo:path/to/cchk.toml`
101+
- **Pinned to a ref:** `github:owner/repo@main:path/to/cchk.toml`
102+
- **Local path:** `../shared/cchk.toml`
103+
- **HTTPS URL:** `https://example.com/cchk.toml`
104+
105+
The `github:` shorthand fetches from `raw.githubusercontent.com`, and plain
106+
HTTP URLs are rejected for security. Local settings always override the
107+
inherited base — so the org sets the floor, and each repo customizes from
108+
there.
109+
110+
## Don't forget push safety
111+
112+
Policy isn't only about message wording. Use `--no-force-push` in a `pre-push`
113+
hook to catch history-rewriting pushes:
114+
115+
```yaml
116+
# .pre-commit-config.yaml
117+
repos:
118+
- repo: https://github.com/commit-check/commit-check
119+
rev: v2.6.0
120+
hooks:
121+
- id: check-no-force-push
122+
stages: [pre-push]
123+
```
124+
125+
A note: piping `git push` into `commit-check` is **not** a prevention
126+
mechanism — by then the push has already started. Use the `pre-push` hook
127+
instead.
128+
129+
## Summary
130+
131+
Start with zero config, add a `cchk.toml` when you want stricter rules, and
132+
reach for `inherit_from` when you want one standard across every repository.
133+
Same engine, same file format, scaling with your team.
134+
135+
Full reference: <https://commit-check.github.io/commit-check/configuration.html>

‎docs/blog/posts/introducing-commit-check.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
date:
3+
created: 2026-06-21
4+
readtime: 6
5+
categories:
6+
- ANNOUNCEMENTS
7+
tags:
8+
- commit-check
9+
authors:
10+
- shenxianpeng
11+
---
12+
13+
# One policy file for your Git history
14+
15+
Most teams have a wiki page titled something like "How we write commit
16+
messages." It covers commit conventions, branch naming, sign-offs, and
17+
author email consistency — and then nobody reads it.
18+
19+
**Commit Check** exists to turn that wiki page into something Git actually
20+
enforces.
21+
22+
<!-- more -->
23+
24+
## A policy engine, not a linter
25+
26+
Commit Check is a lightweight policy engine for Git *metadata* — the parts of a
27+
commit that live around your code rather than inside it:
28+
29+
- **Commit messages** — Conventional Commits, subject length, imperative mood
30+
- **Branch names** — Conventional Branch types like `feature/`, `bugfix/`, `release/`
31+
- **Author identity** — name and email consistency
32+
- **Sign-off trailers** — `Signed-off-by` for DCO workflows
33+
- **Push safety** — catch accidental force-pushes before they rewrite history
34+
35+
That word — *policy* — matters. Instead of scattering rules across a CI
36+
script, a pre-commit hook, and a stale convention doc, you write them
37+
**once** in a versioned `cchk.toml`.
38+
39+
## Write it once, enforce it everywhere
40+
41+
That single policy file is read by every enforcement point:
42+
43+
```bash
44+
pip install commit-check
45+
commit-check --message --branch
46+
```
47+
48+
The same `cchk.toml` then drives:
49+
50+
- the **CLI** for local one-off checks,
51+
- **pre-commit** hooks so problems are caught before a commit lands,
52+
- **CI / GitHub Actions** so pull requests are validated for the whole team.
53+
54+
Because the policy is committed alongside your code, it is reviewed, diffed, and
55+
versioned like everything else. When the rules change, the change shows up in a
56+
pull request.
57+
58+
## Zero configuration to start
59+
60+
You do not need a config file to begin. With no `cchk.toml`, Commit Check
61+
applies lenient, sensible defaults: commit messages should follow
62+
[Conventional Commits](https://www.conventionalcommits.org/) and branch names
63+
should follow the [Conventional Branch](https://conventional-branch.github.io/)
64+
convention. That is enough to get value on day one.
65+
66+
```bash
67+
echo "feat: add streaming support" | commit-check -m
68+
```
69+
70+
When you need stricter rules — a maximum subject length, required sign-off,
71+
or an allow-list of commit types — add a `cchk.toml`. The next post walks
72+
through the details.
73+
74+
## Add the badge
75+
76+
Once Commit Check is guarding your repository, let people know:
77+
78+
```text
79+
[![commit-check](https://img.shields.io/badge/commit--check-enabled-brightgreen?logo=Git&logoColor=white&color=%232c9ccd)](https://github.com/commit-check/commit-check)
80+
```
81+
82+
## Where to go next
83+
84+
- **Getting Started:** <https://commit-check.github.io/commit-check/>
85+
- **GitHub Action:** <https://github.com/commit-check/commit-check-action>
86+
- **Source & issues:** <https://github.com/commit-check/commit-check>
87+
88+
Clean commits. Clear standards. One policy file.

‎docs/blog/posts/myfirst.md‎

Lines changed: 0 additions & 18 deletions
This file was deleted.

‎docs/blog/posts/mysecond.md‎

Lines changed: 0 additions & 20 deletions
This file was deleted.

‎mkdocs.yml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,10 @@ copyright: "© Copyright 2022 - 2026, shenxianpeng."
88
nav:
99
- Home: index.md
1010
- Getting Started: getting-started.md
11-
# - Blog:
12-
# - blog/index.md
13-
exclude_docs: |
14-
blog/**
11+
- Blog:
12+
- blog/index.md
13+
# exclude_docs: |
14+
# blog/**
1515

1616
theme:
1717
name: material

0 commit comments

Comments
 (0)