Skip to content

Commit linting ​

relizy commitlint checks commit messages with your Relizy config: the parser, the types and the packages of your releases. A commit that passes is the commit Relizy will bump, list and render in your changelogs.

Why not commitlint? ​

  • One source of truth: the types come from types, the scopes from your workspace packages and scopeMap. No second config to keep in sync.
  • The release parser: commitlint uses conventional-commits-parser, Relizy its own. A message accepted by commitlint can be ignored or classified differently by your release.
  • Bodies checked: Relizy copies commit bodies into your changelogs and release notes. Each body is rendered as in the changelog, and its code blocks are checked with your ESLint or a built-in parser.
  • No extra dependency: it ships with Relizy (pnpm add -D relizy), no @commitlint/* package needed.

What it checks ​

AreaChecks
Headertype(scope)!: subject format, known type, header length, subject period and meaning (and case, opt-in)
ScopesWorkspace packages, scopeMap keys and your list, required scope (opt-in), scope matching the changed files
BodyBlank line after the header, no markdown heading, valid markdown, changelog entry that keeps the changelog valid
Breaking changesOnly ! or a BREAKING CHANGE: footer can trigger a major bump
AI attributionNo AI co-author, session trailer or "Generated with" line

Every rule can be tuned or disabled, and you can write your own: see Rules and Custom Rules. No config is required to start; see Configuration to tune it.

Lint the commit being created ​

bash
npx relizy commitlint --install

It writes a commit-msg hook running relizy commitlint --edit "$1": in .husky/ when husky is set up, otherwise in the hooks directory of git (core.hooksPath or .git/hooks). An existing hook is kept (with a warning) unless you add --force. relizy init offers to install it too.

.git/hooks is not versioned: the hook only exists on the clone that wrote it, and the commits go through while relizy is not installed. To set it up on every clone, run the command at each install (relizy init adds it when it writes the hook there):

json
{
  "scripts": {
    "prepare": "relizy commitlint --install"
  }
}

Outside a git repository (a Docker build), it installs nothing and does not fail. With husky, the hook is in .husky/, versioned with the project, and the one relizy wrote in .git/hooks before husky is removed.

To write it by hand:

bash
# .husky/commit-msg
npx --no -- relizy commitlint --edit "$1"
json
{
  "simple-git-hooks": {
    "commit-msg": "npx --no -- relizy commitlint --edit \"$1\""
  }
}
yaml
# lefthook.yml
commit-msg:
  commands:
    relizy-commitlint:
      run: npx --no -- relizy commitlint --edit {1}

With simple-git-hooks, run npx simple-git-hooks to apply the config to git.

Lint the commits of a pull request ​

A commit can skip the hook (--no-verify, the web interface of GitHub or GitLab). Lint the commits in CI too: without --from, Relizy lints the commits of the pull or merge request (see default range) and fetches the missing history of a shallow clone.

yaml
# .github/workflows/commitlint.yml
name: Commit messages

on:
  pull_request:
    # `edited`: lint again when the title changes, with commitlint.title
    types: [opened, synchronize, reopened, edited]

jobs:
  commitlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 22
      - run: npm ci
      - run: npx relizy commitlint
yaml
# .gitlab-ci.yml
commitlint:
  image: node:22
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
  script:
    - npm ci
    - npx relizy commitlint

If your pull or merge requests are squash merged, their title becomes the commit Relizy reads for the bump and the changelog: lint it too with commitlint.title: true or --title. In GitHub Actions, each problem is also reported as an annotation on the pull request.

Read the output ​

A valid commit prints one line with its effect on the next release:

text
✔ feat(nuxt) → minor bump, 🚀 Enhancements

An invalid commit prints each problem with its rule and how to fix it, a suggested header when the mistakes can be fixed safely, the documentation of the failing rules and how to commit again. The hook stops the commit:

text
✖ fix(nuxtt): Typo.

  ✖ scope-enum          The scope "nuxtt" is not allowed
                        → did you mean "nuxt"? use a workspace package or one of: core,
                          @maz-ui/core, nuxt, @maz-ui/nuxt
  ✖ subject-full-stop   The subject ends with a period
                        → remove the final period
  ✖ subject-meaningful  The subject "Typo." does not describe the change
                        → describe what changed, in at least 2 words or 15 characters

  Suggested header: fix(nuxt): Typo
                    still to fix: subject-meaningful

────────────────────────────────────────────────────────────────────────
✖ The commit message is invalid: 3 errors, 0 warnings
  Rules: scope-enum          https://relizy.dev/commitlint/rules#scope-enum
         subject-full-stop   https://relizy.dev/commitlint/rules#subject-full-stop
         subject-meaningful  https://relizy.dev/commitlint/rules#subject-meaningful
  Fix:   edit the message and commit again, it is kept in .git/COMMIT_EDITMSG:
           $ git commit --edit --file .git/COMMIT_EDITMSG

Warnings are printed but never fail. --preview adds the changelog entry of each commit, --format json prints the report for programs: see CLI. AI agents can lint a message before committing with the lint_commit tool of the MCP server.

Next steps ​