gommitlint

README

Gommitlint

Gommitlint validates Git commit messages against configurable rules.

---

Poor commit messages make debugging, code review, and changelog generation harder. Gommitlint catches issues before they enter your history.

• Sensible Defaults: Works out of the box with best practices enabled
• Conventional Commits: Supports the Conventional Commits standard
• CI/CD Ready: Multiple output formats for GitHub Actions, GitLab CI, and automation
• Git Hooks: Validate commits before they're created
• Single binary, zero dependencies: No Node.js, Python, or runtime required

Quick Start

What It Does

After installation, validate your commits:

gommitlint validate -v

Installation

Mise (requires mise 2026.1+):

mise use forgejo:itiquette/gommitlint@<version>

Linux packages:

Get your release and

# Debian/Ubuntu
sudo dpkg -i gommitlint_*_amd64.deb

# Red Hat/Fedora/SUSE
sudo rpm -i gommitlint-*-1.x86_64.rpm

# Alpine
sudo apk add --allow-untrusted gommitlint_*_x86_64.apk

Binary (Linux/BSD/macOS[^1]):

Get your Binary and

# Download and extract
tar -xzf gommitlint-<version>-<os>-<arch>.tar.gz

# Move to PATH
sudo mv gommitlint /usr/local/bin/

[^1]: macOS binaries are cross-compiled but untested and unsupported. Please don't report issues for unsupported platforms. But, If you'd like official macOS support with testing, send me an M5 for an unlimited loan :)

SHA-256 Git Repositories (Experimental):

For repositories using SHA-256 object format (git init --object-format=sha256), use the gommitlint-sha256 binaries available for Linux and macOS ARM64. Standard binaries use go-git which only supports SHA-1 repositories.[^2]

[^2]: See go-git#706 for SHA-256 support status.

Container:

podman pull codeberg.org/itiquette/gommitlint:<version>
podman run --rm -v $(pwd):/repo codeberg.org/itiquette/gommitlint:<version> validate

Download packages and binaries from the releases page. See verification for signature verification.

Basic Usage

# Validate last commit
gommitlint validate

# Validate all commits in feature branch against main
gommitlint validate --base-branch=main

# Validate specific commit range
gommitlint validate --range=main..feature-branch

# Create a basic template
gommitlint config init

Common Use Cases

Git Hook Integration

Validate commits locally with two hooks:

# Install hooks (commit-msg + pre-push)
gommitlint hook install

# Or install globally for all repositories
gommitlint hook install --global

• commit-msg: Validates message format before commit (blocks invalid commits)
• pre-push: Validates signatures before push (blocks unsigned commits)

CI/CD Pipeline

# Forgejo Actions (Codeberg)
- name: Validate commits
  run: |
    go install codeberg.org/itiquette/gommitlint@<version>
    gommitlint validate --base-branch=origin/${{ github.base_ref }} --format=forgejo

Validation Rules

Rule	Config	Description	Enabled
BranchAhead	branchahead	Max commits ahead of base branch (runs only with --base-branch, default limit: 5)	✓
CommitBody	commitbody	Commit body requirements (presence, length, line width)
ConventionalCommit	conventional	Conventional Commits format	✓
CryptoSignature	cryptosignature	GPG/SSH signature verification	✓
Identity	identity	Verifies committer identity
JiraReference	jirareference	Requires JIRA ticket references
LinearHistory	linearhistory	Requires linear history (no merge commits)
SignOff	signoff	Requires Signed-off-by trailer	✓
Spell	spell	Spell checking	✓
Subject	subject	Subject line length (default: max 100) and format	✓

Rules without ✓ require explicit enabling via rules.enabled.

BranchAhead runs only when --base-branch is provided. When active and repo.reference_branch is empty, it attempts to auto-detect a base branch (main, master, dev, develop, development).

Configuration

Gommitlint works out of the box with sensible defaults. Customize as needed - see Reference for the complete configuration schema.

Configuration Locations

Configuration files are searched in the following order:

1. Command-line flag: --gommitconfig=/path/to/config.yaml
2. Project directory: .gommitlint.yaml, .gommitlint.yml, or .gommitlint.toml
3. XDG config directory: $XDG_CONFIG_HOME/gommitlint/settings.yaml

Project-Specific Configuration

Create a .gommitlint.yaml in your project root:

gommitlint config init > .gommitlint.yaml

Example configuration:

gommitlint:
  message:
    subject:
      max_length: 80
  # Ignore specific commits by SHA hash (supports abbreviated SHAs)
  ignore_commits:
    - a1b2c3d4e5f6    # Legacy commit before gommitlint adoption
    - f6e5d4c3b2a1    # Emergency hotfix with non-standard format
  rules:
    enabled:
      - commitbody    # Require detailed commit messages
    disabled:
      - cryptosignature  # Don't require GPG/SSH signatures

Global Settings

Set default preferences that apply to all projects:

# Create XDG config directory
mkdir -p "${XDG_CONFIG_HOME}"/gommitlint

# Create user settings
gommitlint config init > "${XDG_CONFIG_HOME}"/gommitlint/settings.yaml

# Modify as needed

Output Formats

Progressive Verbosity

# Default
gommitlint validate

# Technical details
gommitlint validate -v

# Guidance
gommitlint validate -vv

Formats

# Human-readable (default, with colors when TTY detected)
gommitlint validate --format=text

# Plain text for scripting (prefix+CSV per line)
gommitlint validate --format=plain

# Machine-readable JSON
gommitlint validate --format=json

# Table format (structured output)
gommitlint validate --format=table

# CI/CD formats
gommitlint validate --format=forgejo   # Forgejo
gommitlint validate --format=github   # GitHub Actions 
gommitlint validate --format=gitlab   # GitLab CI

# Filter failed validations
gommitlint validate --format=plain | grep FAIL

Uninstallation

Important: Remove git hooks first (if installed):

gommitlint hook remove            # Remove local hooks
gommitlint hook remove --global   # Remove global hooks

Then uninstall based on installation method:

# Package manager installations
# Debian/Ubuntu
sudo dpkg -r gommitlint

# Red Hat/Fedora/SUSE
sudo rpm -e gommitlint

# Alpine
sudo apk del gommitlint

# Binary installation - remove the binary
rm /usr/local/bin/gommitlint  # or wherever you installed it

# Go installation - remove from GOPATH
rm $(go env GOPATH)/bin/gommitlint

Supported Platforms

Platform	amd64/x86_64	arm64/aarch64	riscv64	Packages
Linux	✓	✓	✓	.deb, .rpm, .apk, container
FreeBSD	✓	✓	✓	-
NetBSD	✓	✓	✓	-
OpenBSD	✓	✓	✓	-
macOS[^1]	-	✓	-	-

Note: Debian uses amd64/arm64, RPM/Alpine/archives use x86_64/aarch64.

CI/CD Actions

• gommitlint-action • Forgejo Action
• gommitlint-action • GitHub Action

Documentation

• Tutorial • Examples and troubleshooting
• Reference • Command syntax and technical specifications
• Architecture • Design principles and implementation
• Configuration Examples • Configuration examples
• Man Page • Linux/Unix manual page (man gommitlint)
• Artifact Verification • Verify release signatures
• Development • Development setup
• Issues • Report bugs or request features

See the Contributing guide for details on how to contribute to the project!

License

• Code: EUPL 1.2
• Documentation: CC0 1.0