Gommitlint

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

COMMIT [abc1234] feat: add user authentication
 ✓ BranchAhead
 ✓ ConventionalCommit
 ✓ CryptoSignature
 ✓ LinearHistory
 ✓ SignOff
 ✓ Spell
 ✓ Subject
✓ All checks passed

When a commit fails validation:

COMMIT [def5678] add user feature
 ✓ BranchAhead
 ✗ ConventionalCommit - Must follow format: type(scope): description
 ✓ CryptoSignature
 ✓ LinearHistory
 ✓ SignOff
 ✓ Spell
 ✓ Subject
✗ 1 issue(s) found

Installation

Linux packages:

# 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¹ ):

# Download and extract
tar -xzf gommitlint-<version>-<os>-<arch>.tar.gz
# Move to PATH
sudo mv gommitlint /usr/local/bin/

Mise (requires mise 2026.1+):

mise use -g gommitlint@latest

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 commitsrun:| go install codeberg.org/itiquette/gommitlint@<version>
 gommitlint validate --base-branch=origin/${{ github.base_ref }} --format=forgejo

Validation Rules

Rules without ✓ require explicit enabling via rules.enabled.

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 formatrules:enabled:- commitbody # Require detailed commit messagesdisabled:- 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 (no colors, one result 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

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

CI/CD Actions

• gommitlint-action • Forgejo Action
• gommitlint-action • GitHub Action (coming soon)

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