Commit messages matter.
Yet many of us still toss out a "fix stuff" or "wip" when we're moving fast. Maybe you let an AI agent vibe‑commit whatever it feels like.
That's totally fine in test branches, where you can clean them up later, but not in the main branch. The effort to write a good commit message is the same as writing a bad one. Although, the difference shows up six months later when you dig through the git logs and the messages don't give a clear picture of what happened.
I’ve written before about keeping a clean Git history and signing commits for security. Those posts were about how. But knowing and doing consistently are two different things. People (and perhaps even more so AI agents) forget.
Over the years I’ve tried several commit‑lint tools, but none have made me fully satisfied. Some were JS‑ or Python‑based, which means depending on a runtime ecosystem just to validate a commit message. Others looked very promising, like "conform", but are now almost abandoned with issue lists that does not get addressed.
I wanted a linter as a single binary, without runtime dependencies, that works out of the box and comes with sensible (in my view) defaults. The result was that I created Gommitlint. And I think it turned out pretty OK.
The goal was a tool that works just as well as a CLI tool as in a CI flow.
Gommitlint is thus a Git commit linter — a CLI tool written in Go for commit messages.
It validates commit messages against different configurable rules, for example Conventional Commits format, length and style of the subject line, sign‑off (DCO), cryptographic signatures (GPG or SSH), spelling, linear history, and limits for how far a branch may get ahead.
It can validate individual commits, commit ranges, entire branches against a base branch, or commit messages from stdin or files.
Since it’s a static binary it’s perfect for small container images and CI flows.
It runs in three modes: as a CLI for manual validation, as Git hooks (commit‑msg and pre‑push) to catch problems before they end up in history, and in CI/CD pipelines as a quality check.
Effort has gone into following good CLI UX practices, with the idea that it’s the small things that make a tool pleasant to use.
Tools that require initial configuration are demanding, so Gommitlint immediately enables several rules out of the box if no other configuration is provided: subject line max 100 characters and imperative mood, Conventional Commits format, sign‑off requirement, cryptographic signature verification, spell checking, linear history, and branch‑ahead limits.
You can disable or customize all of this as you like. The point is that it does something sensible right away without a config file.
The program supports installing git hooks, locally as well as globally.
For example: run gommitlint hook install --global and each commit will be validated before it’s created, for all projects.
gommitlint validate --base-branch=main --format=json
I learned a lot by building this project from scratch — everything from the Go ecosystem and hexagonal architecture in practice to good CLI design and more DevOps patterns. In side projects, the learning and insights are at least as valuable as the result.
The process was a mix of manual craft and AI prompting.
I wrote the base by hand, used AI to improve, analyze, and build out, went back to handwork and then AI again. And so on. There are a few parts I need to clean up more.
Gommitlint is open source (EUPL‑1.2) and available as binaries for Linux and BSD (and an untested and unsupported binary for macOS), system packages (.deb, .rpm, .apk) and container images.
Releases before the 1.0.0-series will have some embarrassing bugs or documentation misses, that is part of the deal. But, if you want to make it even better, issues, suggestions and contributions are welcome.
Happy Linting!
Links
Tool:
- Gommitlint on Codeberg
- Gommitlint-Action on Codeberg (Forgejo-Action)
- Gommitlint-Action on GitHub (GitHub-Action)
Related posts:
Top comments (0)