Skip to content

Commit a488ff5

Browse files
claudeclaude
committed
docs(blog): add three articles introducing commit-check
Add three blog posts for the commit-check site: - One policy file for your Git history (overview / why commit-check) - From zero-config to org-wide policy (configuration & inherit_from) - AI-native: JSON output and a Python API (machine-readable usage) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GDSwJ4o6by3HrzUSzhFLJG
1 parent af282e0 commit a488ff5

3 files changed

Lines changed: 342 additions & 0 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 built to be *consumed* by machines, not only
19+
read by humans squinting at ASCII art in a terminal. 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+
The interesting case is failure. Each failing check 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+
Feed that `suggest` string straight back to an LLM and it has everything it
68+
needs to rewrite the message and try again.
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 already running in Python, spawning a subprocess just to
91+
validate a string is wasteful. The `commit_check.api` module exposes a
92+
lightweight interface that returns plain dicts — easy to serialize, forward to
93+
an LLM, 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 the full AI-native guide in the
116+
[README](https://github.com/commit-check/commit-check#ai-native-usage).

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

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

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

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

0 commit comments

Comments
 (0)