Skip to content

Commit 39e60ab

Browse files
authored
docs: bring the site in step with v2.19.1 (#56)
1 parent a7b345f commit 39e60ab

7 files changed

Lines changed: 143 additions & 24 deletions

File tree

‎docs/changelog.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ below and to the page that documents the feature properly.
1111

1212
| Version | What changed | Documented in |
1313
|---|---|---|
14+
| [2.19.1](#v2191) | `develop` accepted by default; stricter merge-subject, fixup, WIP and sign-off checks | [CC201](rules.md#cc201) · [CC001](rules.md#cc001) · [CC009](rules.md#cc009) |
1415
| [2.19.0](#v2190) | Branch descriptions held to the Conventional Branch grammar; Amp, OpenHands, Factory Droid and Jules recognised | [CC201](rules.md#cc201) · [CC013](rules.md#cc013) |
1516
| [2.18.3](#v2183) | `--fix` corrects a message in place; `--branch` reads GitLab, Bitbucket, Azure and Jenkins variables | [Fixing a message in place](example.md#fixing-a-message-in-place) · [Other CI](guides/other-ci.md) |
1617
| [2.18.0](#v2180) | AI disclosure policy: three rules, and the correction written for you | [Policy guides](guides/policies.md#asking-for-disclosure-instead) · [CC014](rules.md#cc014) |
@@ -31,6 +32,79 @@ below and to the page that documents the feature properly.
3132
| [2.5.0](#v250) | Organization-wide config with `inherit_from` | [Across an organization](guides/organization.md) |
3233
| [2.0.0](#v200) | Configuration moved from YAML to TOML — breaking | [Migrating from v1](migration.md) |
3334

35+
## v2.19.1 (2026-10-16) { #v2191 }
36+
37+
### Changed
38+
39+
* **`develop` is accepted by default** — the Conventional Branch
40+
specification counts `develop` as a trunk branch beside `main` and
41+
`master`, but [CC201](rules.md#cc201) failed it unless
42+
`allow_branch_names` listed it. It now passes like `main` and `master`, and
43+
the spec-strict config needs only the types and the description grammar.
44+
This only widens what passes.
45+
See PR [#612](https://github.com/commit-check/commit-check/pull/612).
46+
47+
* **Only merge subjects a tool wrote are exempt** — any subject starting with
48+
`Merge ` skipped [CC001](rules.md#cc001) and the subject rules. Now only
49+
the forms git, GitHub, GitLab and Bitbucket write are exempt, such as
50+
`Merge branch 'x' into 'y'` and `Merge pull request #12 from …`. A typed
51+
subject such as `Merge the parser rewrite` is judged like any other, so it
52+
now fails CC001.
53+
See PR [#619](https://github.com/commit-check/commit-check/pull/619).
54+
55+
* **A commit message file is checked as git will store it** — the
56+
`commit-msg` hook runs before git strips comments, so git's comment block,
57+
and with `git commit -v` the whole diff, were read as part of the message.
58+
Comment lines and everything from the scissors line on are now dropped
59+
first. A subject-only commit written in the editor now fails
60+
[CC011](rules.md#cc011) when `require_body` is on, and a `Signed-off-by:`
61+
line in the diff no longer counts. `--fix` keeps the comment and diff
62+
blocks in the file.
63+
See PR [#618](https://github.com/commit-check/commit-check/pull/618).
64+
65+
### Fixed
66+
67+
* **[CC009](rules.md#cc009) rejects `squash!` and `amend!` too** — with
68+
`allow_fixup_commits = false` only `fixup!` commits failed.
69+
See PR [#613](https://github.com/commit-check/commit-check/pull/613).
70+
71+
* **[CC010](rules.md#cc010) catches every WIP marker** — `WIP` followed by a
72+
newline, a tab or a dash passed. Any subject that begins with the word `WIP`
73+
or `[WIP]`, in any case, now fails; `wipe the cache` still passes.
74+
See PR [#616](https://github.com/commit-check/commit-check/pull/616).
75+
76+
* **[CC012](rules.md#cc012) reads only a real trailer** — `Signed-off-by:`
77+
text anywhere in the message passed, including the subject and a line with
78+
no name. The check now needs a trailer line with a name and an address, and
79+
it runs in linear time on any input.
80+
See PR [#621](https://github.com/commit-check/commit-check/pull/621).
81+
82+
* **[CC002](rules.md#cc002) and [CC003](rules.md#cc003) skip only a real type
83+
prefix** — any leading `word:` was skipped, even with
84+
`conventional_commits = false`, so `Added: support for X` passed the
85+
imperative check. The prefix is now skipped only when Conventional Commits
86+
is on and the type is allowed.
87+
See PR [#622](https://github.com/commit-check/commit-check/pull/622).
88+
89+
* **[CC013](rules.md#cc013) sees two more AI co-author forms** — a trailer
90+
with a blank before the colon, `Co-authored-by : Claude <…>`, which git
91+
still reads as a trailer, and the line Cursor's agent writes,
92+
`Co-authored-by: Cursor Agent <cursoragent@cursor.com>`.
93+
See PR [#623](https://github.com/commit-check/commit-check/pull/623).
94+
95+
* **The config is found from a subdirectory** — run below the top of a
96+
repository, commit-check found no config and used the built-in defaults
97+
without saying so. It now falls back to the top of the work tree, and a
98+
relative `inherit_from` is read next to the config that names it.
99+
See PR [#625](https://github.com/commit-check/commit-check/pull/625) and
100+
[Where the config file lives](configuration.md#where-the-config-file-lives).
101+
102+
* **A parent config is read up to 1 MiB** — `inherit_from` now refuses a
103+
larger parent, or a local path that is not a regular file, and continues
104+
with the local config as it does when a parent is unreachable.
105+
See PR [#614](https://github.com/commit-check/commit-check/pull/614) and
106+
[Across an organization](guides/organization.md).
107+
34108
## v2.19.0 (2026-10-14) { #v2190 }
35109

36110
### Added

‎docs/configuration.md‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,11 @@ Check searches four locations and uses the first that exists:
4545
3. `.github/cchk.toml`
4646
4. `.github/commit-check.toml`
4747

48+
Run from a subdirectory of a repository, where none of the four is in the
49+
current directory, it looks in the same four places at the top of the
50+
repository's work tree. The current directory still comes first, so a package
51+
in a monorepo can keep a config of its own.
52+
4853
Pass `--config` to point at one directly and skip the search:
4954

5055
```console
@@ -229,7 +234,7 @@ conventional_branch = true
229234
allow_branch_types = ["feature", "bugfix", "hotfix", "release", "chore"]
230235
# true also holds the part after "/" to the spec's grammar
231236
require_description_grammar = false
232-
# allow_branch_names = [] # optional: extra standalone names, e.g. ["develop"]
237+
# allow_branch_names = [] # optional: extra standalone names, e.g. ["staging"]
233238
# require_rebase_target = "main" # optional: no rebase requirement by default
234239
# ignore_authors = [] # optional: as above, for branch checks
235240
```
@@ -264,7 +269,7 @@ Used from a hook definition, with no config file anywhere in the repository:
264269
```yaml title=".pre-commit-config.yaml"
265270
repos:
266271
- repo: https://github.com/commit-check/commit-check
267-
rev: v2.19.0
272+
rev: v2.19.1
268273
hooks:
269274
- id: check-message
270275
args:
@@ -308,7 +313,7 @@ The full mapping between the three forms:
308313
| `author_name_pattern=^.+ .+$` | `CCHK_AUTHOR_NAME_PATTERN=^.+ .+$` | `--author-name-pattern=^.+ .+$` |
309314
| `conventional_branch = true` | `CCHK_CONVENTIONAL_BRANCH=true` | `--conventional-branch=true` |
310315
| `allow_branch_types = ["feature"]` | `CCHK_ALLOW_BRANCH_TYPES=feature,bugfix` | `--allow-branch-types=feature,bugfix` |
311-
| `allow_branch_names = ["develop"]` | `CCHK_ALLOW_BRANCH_NAMES=develop,staging` | `--allow-branch-names=develop,staging` |
316+
| `allow_branch_names = ["staging", "production"]` | `CCHK_ALLOW_BRANCH_NAMES=staging,production` | `--allow-branch-names=staging,production` |
312317
| `require_description_grammar = true` | `CCHK_REQUIRE_DESCRIPTION_GRAMMAR=true` | `--require-description-grammar=true` |
313318
| `require_rebase_target = "main"` | `CCHK_REQUIRE_REBASE_TARGET=main` | `--require-rebase-target=main` |
314319
| `allow_force_push = true` | `CCHK_ALLOW_FORCE_PUSH=true` | `--no-force-push` (sets `allow_force_push` to `false`) |
@@ -364,7 +369,7 @@ the same thing twice, so read the description rather than the cell:
364369
| commit | allow_merge_commits | bool | true | Allow merge commits. |
365370
| commit | allow_revert_commits | bool | true | Allow revert commits. |
366371
| commit | allow_empty_commits | bool | true | Allow empty commits. |
367-
| commit | allow_fixup_commits | bool | true | Allow fixup commits (e.g., "fixup! <commit message>"). |
372+
| commit | allow_fixup_commits | bool | true | Allow fixup commits: `fixup!`, `squash!` and `amend!` subjects. |
368373
| commit | allow_wip_commits | bool | true | Allow work-in-progress commits (e.g., "WIP: <commit message>"). |
369374
| commit | require_body | bool | false | Require a body in the commit message. |
370375
| commit | ignore_authors | list[str] | [] (none ignored) | List of commit authors **or co-authors** (`Co-authored-by:` lines) to bypass all commit checks. Useful for bots (e.g., `"dependabot[bot]"`, `"coderabbitai[bot]"`). |
@@ -377,7 +382,7 @@ the same thing twice, so read the description rather than the cell:
377382
| branch | conventional_branch | bool | true | Enforce Conventional Branch specification. |
378383
| branch | allow_branch_types | list[str] | ["feature", "bugfix", "hotfix", "release", "chore", "feat", "fix", "build", "ci", "docs", "perf", "refactor", "style", "test", "ai", "claude", "codex", "copilot", "cursor", "dependabot", "renovate"] | Allowed branch types when `conventional_branch` is true. The default is a superset of the [Conventional Branch spec](https://conventionalbranch.org/): the spec's types (`feature`, `bugfix`, `hotfix`, `release`, `chore`, their aliases `feat` and `fix`, and the AI agent prefixes `ai`, `claude`, `codex`, `copilot`, `cursor`) plus the other Conventional Commit types (`build`, `ci`, `docs`, `perf`, `refactor`, `style`, `test`) and bot prefixes (`dependabot`, `renovate`). For strict spec-only validation, set this option explicitly to the spec's types; [CC201](rules.md#cc201) has the full config. |
379384
| branch | require_description_grammar | bool | false | Also hold the description after `<type>/` to the Conventional Branch grammar: lowercase letters and digits, words joined by single hyphens, dots only inside a word. Off by default, because bot branches such as `dependabot/npm_and_yarn/lodash-4.17.21` do not follow it. See [CC201](rules.md#cc201). |
380-
| branch | allow_branch_names | list[str] | [] (empty list) | Additional standalone branch names allowed when conventional_branch is true (e.g., ["develop", "staging"]). By default, master, main, HEAD, and PR-* are always allowed. |
385+
| branch | allow_branch_names | list[str] | [] (empty list) | Additional standalone branch names allowed when conventional_branch is true (e.g., ["staging", "production"]). By default, main, master, develop, HEAD, and PR-* are always allowed. |
381386
| branch | require_rebase_target | str | "" (no requirement) | Target branch for rebase requirement. If not set, no rebase validation is performed. |
382387
| push | allow_force_push | bool | true | Allow force pushes. Set to `false` to block force pushes when used as a pre-push hook or with `--no-force-push`. |
383388
| branch | ignore_authors | list[str] | [] (none ignored) | List of authors to ignore (i.e., always allow). |

‎docs/example.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -159,7 +159,7 @@ pushed:
159159
```yaml title=".pre-commit-config.yaml"
160160
repos:
161161
- repo: https://github.com/commit-check/commit-check
162-
rev: v2.19.0
162+
rev: v2.19.1
163163
hooks:
164164
- id: check-no-force-push
165165
stages: [pre-push]
@@ -273,9 +273,11 @@ A check that had nothing to judge reports a **skip**, not a pass. The common
273273
case is a merge subject: `Merge branch 'x'` is git's writing, so
274274
[CC002](rules.md#cc002), [CC003](rules.md#cc003), [CC004](rules.md#cc004) and
275275
[CC005](rules.md#cc005) decline it rather than grade prose the author never
276-
wrote. Only git's literal `Merge ` prefix qualifies (plus `fixup! ` for
277-
CC003); a subject that merely starts with the lowercase word is judged like
278-
any other.
276+
wrote. Only subjects that merge tools write qualify: git's `Merge branch
277+
'…'`, `Merge tag '…'` and their relatives, GitLab's `Merge branch 'x' into
278+
'y'`, and GitHub's and Bitbucket's `Merge pull request #…` (plus `fixup! ` for
279+
CC003). A subject someone typed that starts with `Merge ` is judged like any
280+
other.
279281

280282
Text mode names every skipped check in one line on stderr, leaving stdout and
281283
the exit code untouched — a skip is still not a failure:

‎docs/guides/organization.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,10 @@ inherit_from = "github:my-org/.github@v1:cchk.toml"
8181
```
8282

8383
Useful in a monorepo, where the shared config is already checked out.
84+
A relative path is looked up next to the config file that names it first,
85+
so a path written relative to that file works from any directory. Only
86+
when nothing is there is it tried from the current directory, then from
87+
the top of the repository.
8488

8589
=== "HTTPS URL"
8690

@@ -90,6 +94,11 @@ inherit_from = "github:my-org/.github@v1:cchk.toml"
9094

9195
Plain HTTP is rejected.
9296

97+
Whatever the source, a parent config is read up to 1 MiB. A larger one, or a
98+
local path that is not a regular file, is treated as unreachable. Only one
99+
level is followed: an `inherit_from` inside the parent config is reported on
100+
stderr and ignored.
101+
93102
!!! warning "Inheritance fails open"
94103

95104
If the parent config is unreachable — a network blip, a renamed file, a

‎docs/guides/policies.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,7 @@ instead.
142142

143143
These rules read only the message. Jules and OpenHands can commit under their
144144
own bot identity instead of adding a co-author line, and such a commit passes
145-
when its message carries no trailer.
145+
when its message contains no recognized AI signature.
146146

147147
!!! warning "This checks disclosure, not authorship"
148148

‎docs/guides/pre-commit.md‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Add Commit Check to `.pre-commit-config.yaml`:
88
```yaml title=".pre-commit-config.yaml"
99
repos:
1010
- repo: https://github.com/commit-check/commit-check
11-
rev: v2.19.0
11+
rev: v2.19.1
1212
hooks:
1313
- id: check-message
1414
- id: check-branch
@@ -54,9 +54,12 @@ $ pre-commit install --hook-type pre-push
5454
a branch push, such as `git push --follow-tags`, the tags on every commit the
5555
push carries.
5656

57-
pre-commit runs no hook for a push that creates a ref without carrying new
58-
commits. So a new tag pushed on its own, when the commit it points at is
59-
already on the remote, is never seen by `check-tag`.
57+
pre-commit works out which commits a push carries from your remote-tracking
58+
refs, such as `origin/main`, and runs no hook for a push that creates a ref
59+
without carrying new commits by that measure. So a new tag pushed on its own,
60+
when the commit it points at is already in a remote-tracking ref, is never seen
61+
by `check-tag`. The same holds for a tag that `git push --follow-tags` sends
62+
along with a branch push in that case.
6063

6164
## Configuring without a TOML file
6265

@@ -65,7 +68,7 @@ Options can be passed as hook arguments, which keeps everything in one file:
6568
```yaml title=".pre-commit-config.yaml"
6669
repos:
6770
- repo: https://github.com/commit-check/commit-check
68-
rev: v2.19.0
71+
rev: v2.19.1
6972
hooks:
7073
- id: check-message
7174
args:
@@ -87,7 +90,7 @@ colon, and lets the commit through:
8790
```yaml title=".pre-commit-config.yaml"
8891
repos:
8992
- repo: https://github.com/commit-check/commit-check
90-
rev: v2.19.0
93+
rev: v2.19.1
9194
hooks:
9295
- id: check-message
9396
args: [--fix]

‎docs/rules.md‎

Lines changed: 34 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,12 @@ Checks that the commit message subject follows the
160160
[Conventional Commits](https://www.conventionalcommits.org) specification:
161161
`<type>(<scope>)!: <description>`.
162162

163+
A subject that a merge tool writes, such as git's `Merge branch 'main' into
164+
topic` or GitHub's `Merge pull request #12 from …`, is accepted as it is;
165+
whether merge commits are allowed at all is [CC006](#cc006)'s call. A subject
166+
someone typed that merely starts with `Merge `, such as `Merge the parser
167+
rewrite`, is judged like any other.
168+
163169
**Why is this bad?**
164170

165171
A free-form subject can only be read by a human. A structured one can be read by
@@ -194,6 +200,11 @@ fix(parser): handle empty input
194200

195201
Checks that the description in the subject line starts with a capital letter.
196202

203+
The description is what follows a `<type>(<scope>)!:` prefix, and the prefix
204+
is skipped only when Conventional Commits is on and the type is one of
205+
`allow_commit_types`. Otherwise the subject is read from its first word, so
206+
`Added: support for X` is judged on `Added`.
207+
197208
**Why is this bad?**
198209

199210
Nothing is inherently wrong with either casing — but mixing them is. A history
@@ -228,6 +239,11 @@ fix: Handle empty input
228239
Checks that the first word of the description is in the imperative mood —
229240
`fix`, not `fixed`, `fixes`, or `fixing`.
230241

242+
The description is what follows a `<type>(<scope>)!:` prefix, and the prefix
243+
is skipped only when Conventional Commits is on and the type is one of
244+
`allow_commit_types`. Otherwise the subject is read from its first word, so
245+
`Added: support for X` is judged on `Added`.
246+
231247
**Why is this bad?**
232248

233249
This is Git's own convention: a subject should complete the sentence *"If
@@ -411,7 +427,8 @@ once it is pushed, adding a message means rewriting history.
411427

412428
**What it does**
413429

414-
Rejects `fixup!` and `squash!` commits.
430+
Rejects `fixup!`, `squash!` and `amend!` commits, the ones `git commit
431+
--fixup`, `--squash` and `--fixup=amend:` write.
415432

416433
**Why is this bad?**
417434

@@ -440,7 +457,9 @@ git rebase -i --autosquash main
440457

441458
**What it does**
442459

443-
Rejects work-in-progress commits — subjects beginning with `WIP`.
460+
Rejects work-in-progress commits — subjects beginning with the word `WIP` or
461+
with `[WIP]`, in any case and whatever follows. Words that merely start with
462+
the letters, such as `wipe`, pass, and so does a body that mentions WIP.
444463

445464
**Why is this bad?**
446465

@@ -471,6 +490,11 @@ git commit --amend -m "feat: add a caching layer for role lookups"
471490

472491
Requires a non-empty body after the subject line.
473492

493+
A message file is judged as the message git will store: comment lines, and
494+
everything from the `git commit -v` scissors line on, do not count. So a
495+
subject-only commit written in the editor fails, although git's comment block
496+
follows the subject when the hook runs.
497+
474498
**Why is this bad?**
475499

476500
The subject says *what* changed; the diff already says that too. The body says
@@ -501,7 +525,9 @@ incident on 2026-05-11, long after the upstream had recovered.
501525

502526
**What it does**
503527

504-
Requires a `Signed-off-by:` trailer in the commit message.
528+
Requires a `Signed-off-by:` trailer in the commit message: a line of its own
529+
that names a person and an `<address>`, as `git commit --signoff` writes it.
530+
The same text inside the subject or a sentence of the body does not count.
505531

506532
**Why is this bad?**
507533

@@ -761,7 +787,7 @@ Checks that the current branch name follows the
761787
[Conventional Branch](https://conventionalbranch.org/) specification:
762788
`<type>/<description>`.
763789

764-
`master`, `main`, `HEAD`, and `PR-*` are always accepted.
790+
`main`, `master`, `develop`, `HEAD`, and `PR-*` are always accepted.
765791

766792
By default only the type is checked, and any description after the `/` is
767793
accepted. With `require_description_grammar` the description has to follow
@@ -804,18 +830,18 @@ feature/role-caching
804830
because bot branches such as `dependabot/npm_and_yarn/lodash-4.17.21` do
805831
not follow it.
806832
* `branch.allow_branch_names` — additional standalone names to accept, such as
807-
`["develop", "staging"]`.
833+
`["staging", "production"]`.
808834
* `branch.ignore_authors` — bypass the check for specific authors.
809835

810-
To check branches exactly as the specification does, set the spec's types,
811-
the description grammar, and its third trunk branch, `develop`:
836+
To check branches exactly as the specification does, set the spec's types and
837+
the description grammar. Its trunk branches, `main`, `master` and `develop`,
838+
are accepted already:
812839

813840
```toml title="cchk.toml"
814841
[branch]
815842
conventional_branch = true
816843
allow_branch_types = ["feature", "feat", "bugfix", "fix", "hotfix", "release", "chore", "ai", "claude", "codex", "copilot", "cursor"]
817844
require_description_grammar = true
818-
allow_branch_names = ["develop"]
819845
```
820846

821847
With that, `commit-check --branch` agrees with every case of the

0 commit comments

Comments
 (0)