gitfluff

Commit message linter with presets, custom formats, and cleanup automation. Fully compliant with Conventional Commits 1.0.0. Skips linting while Git is creating a merge commit.

This Python package distributes prebuilt gitfluff binaries. On first use, the correct release binary for your platform is downloaded and cached under ~/.cache/gitfluff. The binary's SHA-256 checksum is verified against the release's published checksums manifest before extraction.

Quick Start

Install with uv:

uv tool install gitfluff

Run without installation (uvx):

uvx gitfluff --version

Lint a commit message:

gitfluff lint .git/COMMIT_EDITMSG

Auto-clean and rewrite:

gitfluff lint .git/COMMIT_EDITMSG --write

Optional: fail after rewrite (recommended for hooks)

Add a .gitfluff.toml to enable automatic cleanup and stop the commit if a rewrite happened:

preset = "conventional"
write = true

[rules]
exit_nonzero_on_rewrite = true

Hook Integrations

Native Git Hook

Install commit-msg hook:

gitfluff hook install commit-msg

With auto-cleanup:

gitfluff hook install commit-msg --write

Hook installation respects core.hooksPath (including relative paths) and works correctly in linked git worktrees.

pre-commit Framework

Add to .pre-commit-config.yaml:

default_install_hook_types:
  - pre-commit
  - commit-msg

repos:
  - repo: https://github.com/Goldziher/gitfluff
    rev: v0.9.0
    hooks:
      - id: gitfluff-lint
        stages: [commit-msg]
        # args: ["--write"]  # optional, or set `write = true` in .gitfluff.toml
        # args: ["--msg-pattern", "^JIRA-[0-9]+: .+"]  # optional regex override

Install the hooks:

pre-commit install

Lefthook (uvx)

Add to lefthook.yml:

commit-msg:
  commands:
    gitfluff:
      run: uvx gitfluff lint {1}

Install hooks:

npx lefthook install

Optional configuration

No configuration is required—the default Conventional Commits rules apply immediately. If you want project overrides, create .gitfluff.toml:

preset = "conventional-body"  # optional preset override
write = true

[rules]
no_emojis = true
ai_cleanup = true  # set to false to disable AI attribution cleanup
title_suffix = "\\(JIRA-[0-9]+\\)"
exit_nonzero_on_rewrite = true

Any setting can be left out; omit the file entirely to keep defaults. Unknown config keys now trigger an error rather than being silently ignored.

Advanced usage

• Override rules per-invocation using CLI flags (e.g. --preset, --msg-pattern, --cleanup-pattern, --exclude, --cleanup, --single-line, --no-emojis, --ascii-only, --title-prefix, --title-suffix, --no-ai-cleanup).
• Set GITFLUFF_BINARY to point at a custom build when testing unpublished versions.
• Clear the cache (rm ~/.cache/gitfluff/gitfluff*) to force a fresh download.

License

MIT © Na'aman Hirschfeld and contributors