gitfluff

Commit message linter with presets, custom formats, and cleanup automation. Fully compliant with Conventional Commits 1.0.0.

This npm package distributes prebuilt gitfluff binaries for Node.js environments. The correct release artifact is automatically downloaded during installation.

Quick Start

Install globally:

npm install -g gitfluff

Run without installation:

npx [email protected] --version

Lint a commit message:

gitfluff lint .git/COMMIT_EDITMSG

Auto-clean and rewrite:

gitfluff lint .git/COMMIT_EDITMSG --write

Hook Integrations

Native Git Hook

Install commit-msg hook:

gitfluff hook install commit-msg

With auto-cleanup:

gitfluff hook install commit-msg --write

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.4.0
    hooks:
      - id: gitfluff-lint
        stages: [commit-msg]
        # args: ["--msg-pattern", "^JIRA-[0-9]+: .+"]  # optional regex override

Install the hooks:

pre-commit install

Husky

Initialize Husky:

npx husky init

Create commit-msg hook:

echo 'npx gitfluff lint "$1"' > .husky/commit-msg

Make it executable:

chmod +x .husky/commit-msg

Lefthook

Add to lefthook.yml:

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

Install hooks:

npx lefthook install

Optional configuration

gitfluff works without any configuration. When you do want custom rules, add a .gitfluff.toml file in your repository:

preset = "conventional-body"

[rules]
write = true

[[rules.cleanup]]
find = "(?i)wip"
replace = "WIP"

All keys are optional—omit the file to stick with the default Conventional Commits preset.

Advanced usage

• Override rules inline with CLI flags: --preset, --msg-pattern, --exclude, --cleanup, --cleanup-pattern, --single-line, --require-body.
• Combine with --write to apply cleanups when running inside hooks or automation.
• Set GITFLUFF_BINARY to point at a custom build if you need to test unpublished binaries.

License

MIT © Na'aman Hirschfeld and contributors