gitfluff

Commit messages should be clear, consistent, and human-friendly. gitfluff is a commit linter for the AI agent era: it keeps your history tidy, removes noisy AI signatures, and enforces lightweight standards without getting in your way.

Why gitfluff

• Clean history by default with Conventional Commits.
• Automatically strips common AI attribution banners and trailers.
• Optional policies for ticket prefixes/suffixes and character hygiene.
• Works locally, in hooks, and in CI with the same rules.
• Zero-config to start, fully configurable when you need it.

Quick start

Lint the message Git is editing:

gitfluff lint .git/COMMIT_EDITMSG

Auto-clean the message in place:

gitfluff lint .git/COMMIT_EDITMSG --write

Install the commit-msg hook:

gitfluff hook install commit-msg

Install

Homebrew:

brew tap goldziher/tap
brew install gitfluff

npm (checksums verified before extraction):

pnpm add -g gitfluff

Cargo:

cargo install gitfluff

One-off runs:

pnpm dlx gitfluff@0.9.1 --version
uvx gitfluff --version

Optional configuration

No config is required. If you want project-wide rules, add .gitfluff.toml:

preset = "conventional"
write = true

[rules]
no_emojis = true
ascii_only = false
exit_nonzero_on_rewrite = true
ai_cleanup = true  # set to false to disable AI attribution cleanup

title_prefix = "ABC-123"
title_prefix_separator = " * "

Notes:

• title_prefix and title_suffix can be simple literals or a pattern like ABC-[0-9]+.
• write = true applies safe cleanups and preserves your intent.
• ai_cleanup = false disables the built-in removal of AI attribution trailers and banners.
• Under [rules.message], enforce_length = true and enforce_case = true keep the Conventional Commits length and subject-case checks even though a custom pattern replaces the spec check.
• The hook honors your config automatically.
• Unknown config keys now trigger an error rather than being silently ignored.
• --exclude and --cleanup both split on the first ->, so --exclude 'REGEX->MESSAGE' sets a custom error message and an argument without -> is treated as the whole regex. Colons in constructs like (?:...) are therefore safe, but a regex cannot itself contain ->.

Common use cases

• Keep human-readable commits even when AI tools help draft them.
• Enforce ticket references without teaching everyone a new workflow.
• Stop emoji and non-ASCII characters when your tooling requires it.

Hooks and tooling

gitfluff works with pre-commit, Husky, Lefthook, and raw Git hooks. If you already use a hook manager, just call gitfluff lint from your commit-msg hook. It accepts the commit message path as the first argument.

Hook installation respects core.hooksPath (including relative paths resolved against the working-tree top level) and works correctly in linked git worktrees. To replace an existing hook, use --force; the original is backed up as commit-msg.bak, or commit-msg.bak.1, commit-msg.bak.2, and so on if a backup already exists.

Conventional Commits compliance

By default, gitfluff enforces the Conventional Commits 1.0.0 format, including title line structure, optional body and footer rules, and BREAKING CHANGE support.

---

If you want a stricter or custom format, you can override the title check with a custom pattern in CI or config. Run gitfluff lint --help for the full command reference.