commitlint-scope

Git commit conventional scope linter.

Table of contents

• commitlint-scope
  • Table of contents
  • Purpose
  • Quick start
    • Install
      • Docker Hub
      • Binaries
    • Run
      • Binary
      • Docker
  • Configuration file
    • Init
    • Overview
  • Zero Configuration
  • CI
    • GitHub Actions
    • GitLab CI
    • Bitbucket Pipelines
    • Important Notes for All CI Systems
  • JSON schema
  • License

Purpose

Lint changed files against configured scope. Similar to CODEOWNERS. Useful if your dev-flow requires strict scoped file changes control over CI process.

Quick start

Install

Docker Hub

docker pull thumbrise/commitlint-scope:latest-alpine

Binaries

https://github.com/thumbrise/commitlint-scope/releases

No CGO

Binaries are statically compiled (CGO_ENABLED=0) and work without external dependencies on Linux, macOS, and Windows.

Run

Go to your repository root.

cd /path/to/your/repo/

Binary

commitlint-scope run --from main --to feature

Docker

docker run --rm -v "$(pwd):/repo" -w /repo thumbrise/commitlint-scope:latest-alpine run --from main --to feature --verbose

Configuration file

Init

Generate .commitlint-scope.yaml file.

commitlint-scope init

Overview

#$schema: https://github.com/thumbrise/commitlint-scope/blob/main/docs/schema/config.v3.json

# Scope parsing customization. Not required, if you follow common conventional header. In example: 'type!(scope): subject'
#scopeRegex: ^[a-z]+(?:\((?P<scope>[^)]+)\))?!?:\s

# If your commit messages use a non-comma separator between scopes (e.g. 'feat(api | db): msg'), set it here.
#scopeSeparator: ","

# Patterns list: each item specifies a list of scopes and the corresponding file glob patterns.
patterns:
  - scopes: ["auth"]
    files: ["services/auth/**"]

  - scopes: ["migrations", "sql"]
    files: ["database/migrations/*.sql"]

  - scopes: ["frontend", "assets"]
    files: ["**/assets/**", "**/frontend/**"]

  - scopes: ["docs", "md"]
    files: ["**/*.md"]

  - scopes: ["some.dot.scope", "any-anotherscope"]
    files: ["**/rail.v1.json"]

Without a configuration file, each scope is used as a glob pattern by appending /**. Multiple scopes in a single commit use intersection semantics — a file is flagged as an outsider only if it fails to match all declared scopes' patterns. For example, feat(api, db): ... checks files against both api and db patterns; a file matching at least one scope's patterns passes. If a scope separator other than comma is used, set scopeSeparator in the config.

For example:

feat(auth, docs): Some subject

Linter will check changed files against glob patterns auth/** and docs/**. A file that matches at least one scope's patterns passes; only files failing both scopes are flagged as outsiders.

CI

GitHub Actions

name: Lint Commit Scopes
on:
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository (full history)
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Lint commit scopes
        run: |
          docker run --rm \
            -v "${{ github.workspace }}:/repo" \
            -w /repo \
            thumbrise/commitlint-scope:latest-alpine \
            run \
            --from ${{ github.event.pull_request.base.sha }} \
            --to ${{ github.event.pull_request.head.sha }} \
            --verbose

GitLab CI

commitlint:
  image: thumbrise/commitlint-scope:latest-alpine
  stage: test
  variables:
    GIT_DEPTH: 0
  script:
    - commitlint-scope run --from $CI_MERGE_REQUEST_DIFF_BASE_SHA --to $CI_COMMIT_SHA
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Bitbucket Pipelines

pipelines:
  pull-requests:
    '**':
      - step:
          name: Lint commit scopes
          image: thumbrise/commitlint-scope:latest-alpine # For production - use specific version
          script:
            - git fetch --unshallow || true
            - commitlint-scope run --from $BITBUCKET_PR_DESTINATION_BRANCH --to $BITBUCKET_COMMIT

Important Notes for All CI Systems

• Always do a full clone (fetch-depth: 0 or equivalent) so git rev-list can find all commits.
• For shallow clones, use git fetch --unshallow or ensure the required commit range is available, otherwise git rev-list will fail.
• If your CI doesn't provide base/target commit variables, specify the SHAs manually.
• The image already includes safe directory configuration (safe.directory '*') for smooth operation.

---

JSON schema

https://github.com/thumbrise/commitlint-scope/blob/main/docs/schema/config.v3.json

License

Apache 2.0