Skip to content

Coco Lint

Jump to bottom
Griffen Fargo edited this page Aug 2, 2026 · 1 revision

Coco Lint

coco lint scans a range of commits and validates each message against the project's commitlint rules (or built-in Conventional Commits rules when commitlint is not installed). It reports violations with per-commit detail and exits non-zero when any commit fails, making it suitable as a CI gate or pre-merge check.

Basic Usage

# Lint commits on the current branch vs. main
coco lint

# Lint commits since a specific ref
coco lint --since feature-branch-base

# Lint an explicit range
coco lint --range abc123..def456

# Fail on warnings too (default: only errors fail)
coco lint --severity warning

# Auto-fix non-conforming subjects via AI reword + rebase
coco lint --fix

Options

Flag Default Description
--since <ref> — Lint commits in <ref>..HEAD instead of comparing against the default branch
--range <range> — Lint an explicit commit range (e.g. "abc123..def456")
--fix false Reword non-conforming commit subjects via LLM + interactive rebase. Mutates history.
--force false With --fix: proceed despite merges in range, already-pushed commits, or a dirty worktree
--severity <level> error Exit non-zero when a commit has a violation at or above this level (error or warning)
--language <lang> config value Write reworded subjects in this language (with --fix)
--json false Emit machine-readable JSON output

--since and --range are mutually exclusive. When neither is given, the default range is <defaultBranch>..HEAD (uses your configured defaultBranch or falls back to main).

Output

$ coco lint

Linting 5 commit(s) in main..HEAD

✓ abc1234 feat(watch): add continuous daemon
✓ def5678 fix(config): sanitize argv before merging
✗ bad9012 added some stuff
    subject must not be sentence-case
    type is required (e.g. feat:, fix:, chore:)
✓ ghi3456 chore(deps): bump react

4 passing, 1 failing, 0 warning, 0 skipped

Merge commits are marked skipped (their subject is auto-generated by git and outside the author's control).

Auto-Fix (--fix)

When --fix is passed, coco:

  1. Identifies commits with commitlint errors.
  2. Sends each failing subject (plus the body and the violation messages) to the configured LLM, asking it to produce a conforming rewrite.
  3. Validates the rewritten subject against commitlint. If it still fails, retries once with the new errors as feedback.
  4. Proposes an interactive rebase plan showing the rewrites.
  5. Executes the rebase (reword only, no squash/drop/edit).

Safety Guards

--fix refuses to run when:

  • A rebase/merge/cherry-pick is already in progress
  • The worktree has uncommitted changes
  • The range contains merge commits
  • The range has already been pushed to its upstream

Pass --force to override these (you understand the risk of rewriting published history).

The root commit is never rewordable (no --root rebase support).

CI Usage

# GitHub Actions example
- name: Lint commit messages
  run: coco lint --severity warning

Exit code 1 means at least one commit violates at the configured severity. Exit code 0 means all commits conform.

See Also

Clone this wiki locally