Migrating from v1¶

Version 2.0 replaced the YAML configuration with TOML. The change is mechanical — nothing about what Commit Check validates went away — but the two formats express policy very differently, and there is no automatic conversion.

In v1 a config file was a list of checks, each carrying its own regex, error message and suggestion. You wrote the pattern; Commit Check ran it. In v2 the patterns are built in and the file selects and tunes them by name. A v1 file was mostly regex; a v2 file is mostly booleans.

The practical consequence: you do not translate a v1 file line by line. You decide which rules you want and write those down, which is usually far shorter.

Converting the file¶

Take a representative v1 config:

.commit-check.yml (v1)

checks:
- check: message
    regex: '^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test){1}(\([\w\-\.]+\))?(!)?: ([\w ])+([\s\S]*)|(Merge).*|(fixup!.*)'
    error: "The commit message should be structured as follows:\n\n
    <type>[optional scope]: <description>\n
    [optional body]\n
    [optional footer(s)]\n\n
    More details please refer to https://www.conventionalcommits.org"
    suggest: please check your commit message whether matches above regex

- check: branch
    regex: ^(bugfix|feature|release|hotfix|task|chore)\/.+|(master)|(main)|(HEAD)|(PR-.+)
    error: "Branches must begin with these types: bugfix/ feature/ release/ hotfix/ task/ chore/"
    suggest: run command `git checkout -b type/branch_name`

- check: author_name
    regex: ^[A-Za-zÀ-ÖØ-öø-ÿĀ-ſƀ-ɏ ,.\'-]+$|.*(\[bot])
    error: The committer name seems invalid
    suggest: run command `git config user.name "Your Name"`

- check: author_email
    regex: ^.+@.+$
    error: The committer email seems invalid
    suggest: run command `git config user.email yourname@example.com`

- check: commit_signoff
    regex: Signed-off-by:.*[A-Za-z0-9]\s+<.+@.+>
    error: Signed-off-by not found in latest commit
    suggest: run command `git commit -m "conventional commit message" --signoff`

- check: merge_base
    regex: main # it can be master, develop, devel etc based on your project.
    error: Current branch is not rebased onto target branch
    suggest: Please ensure your branch is rebased with the target branch

Every one of those checks still exists. Named rather than spelled out, the whole file becomes:

cchk.toml (v2)

[commit]
conventional_commits = true
require_signed_off_by = true

[branch]
conventional_branch = true
require_rebase_target = "main"

The regexes are gone because they were restating the built-in behaviour. So are error and suggest: Commit Check now supplies both, along with a stable rule ID and a link to the rule's documentation.

Check your type lists before deleting the old file

"Restating the built-in behaviour" is nearly true, not exactly true, and the gap is silent — the shorter file above accepts slightly less than the v1 one it replaces. Two types in that v1 example are missing from the v2 defaults:

revert as a commit type. revert: drop the cache passed under v1 and is rejected by the default allow_commit_types. (Unrelated to allow_revert_commits, which governs Git's own Revert "..." commits and is on by default.)
task as a branch type. task/CC-42 passed under v1 and is rejected by the default allow_branch_types.

Keep them by naming the list you want, remembering that setting either option replaces the default rather than adding to it:

[commit]
allow_commit_types = ["build", "chore", "ci", "docs", "feat", "fix",
                      "perf", "refactor", "revert", "style", "test"]

[branch]
allow_branch_types = ["bugfix", "chore", "feature", "hotfix", "release", "task"]

Compare your own v1 regex against every option before deleting it — this is the one part of the migration that fails quietly, months later, on a commit that used to be fine.

What each v1 check became¶

v1 `check:`	v2 option	Rule
`message`	`[commit] conventional_commits`	CC001
`branch`	`[branch] conventional_branch`	CC201
`author_name`	`[commit] author_name_pattern`	CC101
`author_email`	`[commit] author_email_pattern`	CC102
`commit_signoff`	`[commit] require_signed_off_by`	CC012
`merge_base`	`[branch] require_rebase_target`	CC202
`imperative`	`[commit] subject_imperative`	CC003

The two *_pattern options are the exception to "no more regexes": they exist so an author policy stricter than the default stays expressible.

Keeping a custom message format¶

If the v1 regex enforced something that is not Conventional Commits — JIRA smart commits, say — that is what message_pattern is for. Set it and it replaces the generated Conventional Commits pattern entirely:

cchk.toml

[commit]
message_pattern = "^PROJ-\\d+: .+"

Converting the command line¶

Only the config flag changed, and only because the file did:

$ commit-check --config .commit-check.yml    # v1
$ commit-check --config cchk.toml            # v2

A config file is now optional. With none, the defaults apply immediately:

$ commit-check --message --branch

Doing the migration¶

Keep the old file until you are done:

$ cp .commit-check.yml .commit-check.yml.backup

Write cchk.toml — in the repository root or in .github/. Use the table above rather than translating regexes.
Check it against real commits without failing anything, which is what --dry-run is for:
```
$ commit-check --message --branch --author-name --author-email --dry-run
```
Try a message that should fail, so you know the policy is doing something:
```
$ echo "nonsense" | commit-check --message
```
A passing run on a message that ought to fail usually means the config file was not found — see where the config file lives.
Delete .commit-check.yml and the backup.

If something does not work¶

The config file is not found. It has to be named cchk.toml or commit-check.toml, in the repository root or .github/. Any other name needs --config.

TOML fails to parse. Usually unquoted strings, True instead of true, or a trailing comma in an array. Editors validate the file against the published schema — see where the config file lives.

A rule does not behave as expected. Check the option name and its default in every option; the allow_* options in particular describe what is permitted, so false is the strict setting.

Something else. Open an issue — include the output of commit-check --message --format json.