A dead-simple tool to manage pre-commit hooks for Git.

iprecommit runs shell commands and fails the hook if they fail. You can filter commands on glob patterns (e.g., *.py for Python-only checks) and define fix commands (e.g., for auto-formatters).

[[pre_commit]]
name = "PythonFormat"
cmd = ["black", "--check"]
filters = ["*.py"]
fix_cmd = ["black"]

[[pre_commit]]
name = "UnitTests"
cmd = ["./run_tests"]
pass_files = false

That's it.

Getting started

Install it with pip or pipx:

pip install iprecommit

Then, initialize a pre-commit check in your git repository:

cd path/to/some/git/repo
iprecommit install

iprecommit install will create a file called precommit.toml to configure your pre-commit checks.

Now, whenever you run git commit, the checks in precommit.toml will be run automatically. You can also run the pre-commit checks manually:

iprecommit run

Some pre-commit issues can be fixed automatically:

iprecommit fix

By default, iprecommit run and iprecommit fix operate only on staged changes. To only consider unstaged changes as well, pass the --unstaged flag. To run on every file in the repository (committed, unstaged, and staged), pass the --all flag.

FAQs

Why not pre-commit?

pre-commit is (as far as I can tell) the most widely-used library for pre-commit hook management.

I used pre-commit for a while. Here's why I created iprecommit:

• I hated configuring my pre-commit checks in YAML.
• The colored output is hard to read with a dark theme, and this won't be fixed.
• I just wanted an intelligent way to run shell commands before git commit, not a "multi-language package manager".
• With a custom template at IPRECOMMIT_TOML_TEMPLATE, and autofix and fail_fast set to true, iprecommit does what I want and I rarely have to think about it.

Reasons you might prefer pre-commit:

• You like pre-commit's more extensive configuration options.
• You need one of the Git hooks that pre-commit supports and iprecommit doesn't.

Why not Husky?

Husky is a pre-commit tool that is popular in the JavaScript ecosystem.

iprecommit has a few features that Husky doesn't:

• iprecommit can pass only changed files to your checks.
• iprecommit checks can auto-fix problems (for instance, reformatting code).
• Husky will stop at the first failing check, while iprecommit will run all checks (unless fail_fast is set).

How do I disable a failing check?

Set IPRECOMMIT_SKIP to a comma-separated list of checks to skip, e.g.:

$ IPRECOMMIT_SKIP="Check1,Check2" git commit -m '...'

To persistently skip a check, set skip = true in the precommit.toml file.

User guide

Pre-commit checks

[[pre_commit]]
name = "PythonFormat"
cmd = ["black", "--check"]
filters = ["*.py"]
fix_cmd = ["black"]

• name is optional.
• Changed files are passed to the command unless pass_files = false.
• filters is applied to the set of staged files. If the result is empty, the check is not run. Filters may be literal paths (example.py), glob patterns (*.py), or exclude patterns (!example.py, !*.py).
• If fix_cmd is present, then iprecommit fix will unconditionally run the command. filters still applies as usual.
• Commands run in the root of the Git repository by default. If you need the command to run elsewhere, set working_dir.

Commit message checks

# commit-msg checks
[[commit_msg]]
name = "CommitMessageFormat"
cmd = ["iprecommit-commit-msg-format", "--max-line-length", "72"]

• name and cmd are the only supported keys for commit_msg checks.
• cmd is passed the name of a single file which holds the message's contents.

Pre-push checks

# pre-push checks (run on commit messages)
[[pre_push]]
name = "NoForbiddenStrings"
cmd = ["iprecommit-no-forbidden-strings", "--commits"]

• name and cmd are the only supported keys for pre_push checks.
• cmd is passed a list of Git revisions to be pushed to the remote repository.

Autofix

If the top-level autofix option is set to true in the TOML file, then when a fixable check fails, iprecommit run will automatically invoke iprecommit fix, and then re-run iprecommit run after. This is useful if you have, e.g., auto-formatting checks that can fix themselves without human intervention.

Custom commands

These commands are designed to be used with iprecommit, but they can also be used independently.

• iprecommit-commit-msg-format checks the format of the commit message.
• iprecommit-newline-at-eof checks that each file ends with a newline.
• iprecommit-no-forbidden-strings checks for forbidden strings.
• iprecommit-typos checks for common typos.

Customization

• If you want to create your own template for precommit.toml to be used by iprecommit install, then set the environment variable IPRECOMMIT_TOML_TEMPLATE to the path to the file.