Troubleshooting¶
A check fails and you need the commit through anyway¶
Every check can be bypassed. Doing so is sometimes the right call — you are mid-rebase, or the rule is wrong and fixing it properly can wait — but the bypass is the second thing to reach for. The first is reading what failed: every diagnostic names the rule, quotes the value that failed it, and links to the page explaining it.
Take an author name check that rejects a one-character name:
check committer name.....................................................Failed
- hook id: check-author-name
- exit code: 1
Commit rejected by Commit-Check.
CC101 author-name check failed ==> 12
The committer name seems invalid
Suggest: git config user.name 'Your Name'
Docs: https://commit-check.com/rules/#cc101
12 is the value Git actually recorded as the author — usually a sign that
user.name was never set on this machine, or was set by a script. The fix is
the one the Suggest: line gives:
Skipping one hook¶
When the check is genuinely wrong for a single commit, skip that hook by ID and
leave the rest running. SKIP is a
pre-commit feature, so it
takes the hook's id, not the rule ID:
The IDs are check-message, check-branch, check-author-name,
check-author-email and check-no-force-push.
Skipping every hook¶
--no-verify bypasses the whole pre-commit run — Commit Check and everything
else you have configured:
A local bypass is not a CI bypass
SKIP and --no-verify only affect the hooks on your machine. If the same
policy runs in CI — through the
GitHub Action, say — it will
check the commit again when you push, and reject it there. To exempt a
commit everywhere, change the policy rather than the invocation: turn the
rule off in cchk.toml, or add the author to
ignore_authors if the exemption is
permanent.
A rule fires that you never turned on¶
Commit Check is not silent by default. Whichever checks you asked for run with
their defaults already applied, even with no config file present: --message
enforces Conventional Commits, the 5–80 character subject limits and an
allow-list of ten commit types; --branch enforces Conventional Branch and an
allow-list of twenty-one branch types; --author-name and --author-email
apply the built-in patterns. The Default column in the
rules reference shows every rule's starting state, and
the configuration page spells the split out.
To see what a given repository is actually enforcing, check which config file
it picked up — the search order is in
where the config file lives, and
--config overrides it:
Nothing is checked at all¶
A check only runs when its own flag is passed. commit-check --message never
evaluates branch rules, and commit-check --branch never reads the commit
message — so a hook wired up with the wrong flag passes silently, forever.
Each rule in the rules reference lists the flag that activates it.
Something else¶
If the failure does not match anything above, the JSON output shows exactly what was evaluated and why, which is usually enough to see where the config disagrees with the expectation:
Failing that, open an issue with that output attached.