gommitlint

Gommitlint

---

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

• Sensible Defaults: Works out of the box with best opinionated 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 other runtimes required. Go-binary executable power!

Quick Start

Example - validate your latest commit

After installation, validate your commits:

gommitlint validate -v

Installation

Mise (requires mise 2026.1+, with forgejo support):

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, and I'll get to it :)

SHA-256 Git Repositories:

For repositories using SHA-256 object format (git init --object-format=sha256), use the gommitlint-sha256 binaries available for Linux and macOS ARM64. The SHA-256 variant uses Git CLI-backed repository operations for validation, while the standard binary continues to use go-git for 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

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

Exit code is 0 when all commits pass and 1 on validation failures. Environmental problems use BSD sysexits.h codes: 65 malformed input, 66 missing input (bad ref, missing config file), 69 git unavailable, 70 internal software error, 77 key/trust failure, 78 bad config. 2 covers command misuse and cancellation without a signal; 130/131/143 come from SIGINT/SIGQUIT/SIGTERM. Most CI pipelines only need exit != 0 or exit == 1; see man gommitlint for the full table. Validation results go to stdout; logs and diagnostics go to stderr, so gommitlint validate --format=json 2>/dev/null | jq . yields clean JSON regardless of log level.

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. Rules with thate are enabled per default can be disabled via rules.disabled.

NOTE: BranchAhead runs ONLY when --base-branch is provided, as it needs a branch for comparison.

Configuration

Gommitlint works out of the box with a set of rules enabled by default. 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

Creating project-Specific Configuration

The easy way is to generate 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

Shared Team Configuration

Use local extends when you want one repo config to build on another local file:

gommitlint:
  extends:
    - .gommitlint.team.yaml
  message:
    subject:
      max_length: 80

For teams that want to share policy from a central repository, use managed_sources and vendor the remote file explicitly with gommitlint config sync:

gommitlint:
  extends:
    - .gommitlint.team.yaml
  managed_sources:
    - id: team-policy
      source: https://codeberg.org/example/policies/raw/tag/v1.2.3/gommitlint.yaml
      strategy: vendor
      destination: .gommitlint.team.yaml
      integrity:
        sha256: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

The source field can also come from an environment variable during config sync:

gommitlint:
  managed_sources:
    - id: team-policy
      source: ${GOMMITLINT_POLICY_URL}
      strategy: vendor
      destination: .gommitlint.team.yaml
      integrity:
        sha256: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

gommitlint config sync
gommitlint validate

gommitlint config check
gommitlint config check --format=json

validate stays local-only; it never fetches the network. config sync is the explicit step that downloads, verifies, and vendors the managed file. Environment-variable sources are resolved only during config sync; normal validation still uses the vendored local file.

Built-in Presets

Built-in presets can be composed through extends:

gommitlint:
  extends:
    - preset:conventional
    - preset:secure

Available presets:

Preset	Purpose
preset:minimal	low-friction onboarding
preset:conventional	recommended default conventional setup
preset:ambitious	stronger commit quality and structure
preset:secure	stronger authorship and integrity checks

Common shared-config workflow:

gommitlint config show --format=json
gommitlint config check
gommitlint config sync --check
gommitlint config sync --source team-policy

Use --view=compact for a short text summary, or --view=verbose for full source graph, provenance, and managed-source details.

For a step-by-step debugging workflow, see docs/config-troubleshooting.md.

config show now includes a source graph and selected value provenance so you can see both the inheritance chain and where key effective settings came from, including explicit rule enable/disable overrides. When a value overrides an earlier one, the previous source and value are shown too, and provenance explains why key values and rule states are active.

For environment-based managed sources, config show also reports whether the source is direct or environment-driven and shows the referenced environment variable name.

config check groups managed-source issues with explicit codes and next-step hints so multi-source troubleshooting is easier in both local shells and CI logs. It also includes a managed-source summary block so larger policy setups are easier to scan.

For environment-based managed sources, config show and config check now expose the configured source string, referenced environment variable, whether the last sync resolved it from env, and the recommended next command when troubleshooting fails.

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

Themes

# Select a color theme (default keeps existing colors)
gommitlint validate --theme=dracula

# Light themes

gommitlint validate --theme=gruvbox-light

Available themes: default, dracula, gruvbox-dark, gruvbox-light, tokyonight, tokyonight-day, everforest-dark, everforest-light, nord, catppuccin-mocha, catppuccin-latte, onedark, solarized-dark, solarized-light.

Shell Completion

# Bash
gommitlint completion bash

# Zsh
gommitlint completion zsh

# Fish
gommitlint completion fish

# Install all supported shells
gommitlint completion --all

Installs completions to user-level locations (respecting XDG_DATA_HOME/XDG_CONFIG_HOME), for example:

• bash: ~/.local/share/bash-completion/completions/gommitlint
• zsh: ~/.local/share/zsh/completions/_gommitlint
• fish: ~/.config/fish/completions/gommitlint.fish

Bash requires bash-completion to be enabled and Zsh needs the completion directory in your fpath (the installer points to the correct path). Fish uses the command name for completions; ensure the binary name you run is on your PATH.

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