Seamless integration of git hooks with Nix

Features

• Trivial integration for Nix projects (wires up a few things behind the scenes)

• Provide a low-overhead build of all the tooling available for the hooks to use (naive implementation of calling nix-shell does bring some latency when committing)

• Common hooks for languages like Python, Haskell, Elm, etc. See all hook options

• Run hooks as part of development and during CI

Getting started

devenv.sh

{ inputs, ... }:

{
  git-hooks.hooks = {
    # lint shell scripts
    shellcheck.enable = true;
    # execute example shell from Markdown files
    mdsh.enable = true;
    # format Python code
    black.enable = true;

    # override a package with a different version
    ormolu.enable = true;
    ormolu.package = pkgs.haskellPackages.ormolu;

    # some hooks have more than one package, like clippy:
    clippy.enable = true;
    clippy.packageOverrides.cargo = pkgs.cargo;
    clippy.packageOverrides.clippy = pkgs.clippy;
    # some hooks provide settings
    clippy.settings.allFeatures = true;
  };
}

See getting started.

Flakes support

Given the following flake.nix example:

{
  description = "An example project";

  inputs = {
    systems.url = "github:nix-systems/default";
    git-hooks.url = "github:cachix/git-hooks.nix";
  };

  outputs =
    {
      self,
      systems,
      nixpkgs,
      ...
    }@inputs:
    let
      forEachSystem = nixpkgs.lib.genAttrs (import systems);
    in
    {
      # Run the hooks with `nix fmt`.
      formatter = forEachSystem (
        system:
        let
          pkgs = nixpkgs.legacyPackages.${system};
          config = self.checks.${system}.pre-commit-check.config;
          inherit (config) package configFile;
          script = ''
            ${package}/bin/pre-commit run --all-files --config ${configFile}
          '';
        in
        pkgs.writeShellScriptBin "pre-commit-run" script
      );

      # Run the hooks in a sandbox with `nix flake check`.
      # Read-only filesystem and no internet access.
      checks = forEachSystem (system: {
        pre-commit-check = inputs.git-hooks.lib.${system}.run {
          src = ./.;
          hooks = {
            nixfmt-rfc-style.enable = true;
          };
        };
      });

      # Enter a development shell with `nix develop`.
      # The hooks will be installed automatically.
      # Or run pre-commit manually with `nix develop -c pre-commit run --all-files`
      devShells = forEachSystem (system: {
        default =
          let
            pkgs = nixpkgs.legacyPackages.${system};
            inherit (self.checks.${system}.pre-commit-check) shellHook enabledPackages;
          in
          pkgs.mkShell {
            inherit shellHook;
            buildInputs = enabledPackages;
          };
      });
    };
}

Add /.pre-commit-config.yaml to .gitignore. This file is auto-generated from the Nix configuration and doesn't need to be committed.

Enter a development shell with pre-commit hooks enabled:

nix develop

Run all hooks sandboxed:

nix flake check

Keep in mind that nix flake check runs in a sandbox. It doesn't have access to the internet and cannot modify files. This makes it a poor choice for formatting hooks that attempt to fix files automatically, or hooks that cannot easily be packaged to avoid impure access to the internet.

A better alternative in such cases is to run pre-commit through nix develop:

nix develop -c pre-commit run -a

Or configure a formatter like in the example above and use nix fmt:

nix fmt

flake-parts

If your flake uses flake-parts, we provide a flake-parts module as well. Checkout ./template/flake.nix for an example.

Nix

1. Optionally use binary caches to avoid compilation:

   nix-env -iA cachix -f https://cachix.org/api/v1/install
   cachix use pre-commit-hooks

2. Integrate hooks to be built as part of default.nix:

    let
      nix-pre-commit-hooks = import (builtins.fetchTarball "https://github.com/cachix/git-hooks.nix/tarball/master");
    in {
      # Configured with the module options defined in `modules/pre-commit.nix`:
      pre-commit-check = nix-pre-commit-hooks.run {
        src = ./.;
        # If your hooks are intrusive, avoid running on each commit with a default_states like this:
        # default_stages = ["manual" "pre-push"];
        hooks = {
          elm-format.enable = true;
   
          # override a package with a different version
          ormolu.enable = true;
          ormolu.package = pkgs.haskellPackages.ormolu;
          ormolu.settings.defaultExtensions = [ "lhs" "hs" ];
   
          # some hooks have more than one package, like clippy:
          clippy.enable = true;
          clippy.packageOverrides.cargo = pkgs.cargo;
          clippy.packageOverrides.clippy = tools.clippy;
          # some hooks provide settings
          clippy.settings.allFeatures = true;
        };
      };
    }

   Run $ nix-build -A pre-commit-check to perform the checks as a Nix derivation.

3. Integrate hooks to prepare environment as part of shell.nix:

    let
      pre-commit = import ./default.nix;
    in (import <nixpkgs> {}).mkShell {
      shellHook = ''
        ${pre-commit.pre-commit-check.shellHook}
      '';
      buildInputs = pre-commit.pre-commit-check.enabledPackages;
    }

   Add /.pre-commit-config.yaml to .gitignore.

   Run $ nix-shell to execute shellHook which will:

   • build the tools and .pre-commit-config.yaml config file symlink which references the binaries, for speed and safe garbage collection
   • provide the pre-commit executable that git commit will invoke

Optional

Direnv

.envrc:

use nix

Hooks

Ansible

• ansible-lint

C/C++/C#/ObjC

• clang-format.
  You may restrict which languages should be formatted by clang-format using clang-format.types_or. For example to check only C and C++ files:

  clang-format = {
    enable = true;
    types_or = lib.mkForce [ "c" "c++" ];
  };

  Otherwise, the default internal list is used which includes everything that clang-format supports.
• clang-tidy
• cmake-format

Clojure

• cljfmt
• zprint

Crystal

• crystal

Dart

• dart analyze
• dart format

Dhall

• dhall format

Dockerfile

• hadolint

Editorconfig

• eclint
• editorconfig-checker

Elm

• elm-format
• elm-review
• elm-test

Elixir

• credo
• dialyzer
• mix-format
• mix-test

Fortran

• fprettify

Git

• annex
• check-merge-conflicts
• commitizen
• convco
• forbid-new-submodules
• gitlint
• gptcommit
• no-commit-to-branch

Golang

• gofmt: Runs go fmt
• golangci-lint
• golines
• gotest: Runs go test
• govet
• revive
• staticcheck

Haskell

• cabal-fmt
• cabal-gild
• cabal2nix
• fourmolu
• hindent
• hlint
• hpack
• ormolu
• stylish-haskell

HTML

• html-tidy

JavaScript/TypeScript

• biome
• denofmt
• denolint
• eslint
• rome: (alias to the biome hook)

JSON

• check-json
• pretty-format-json

Julia

• JuiaFormatter.jl

LaTeX

• chktex
• lacheck
• latexindent

Link checker

• lychee
• mkdocs-linkcheck

Lua

• luacheck
• lua-ls
• selene
• stylua

Markdown

• markdownlint
• mdformat
• mdl
• mdsh

Nix

• alejandra
• deadnix
• flake-checker
• nil
• nixfmt-classic
• nixfmt-rfc-style
• nixpkgs-fmt
• statix

OCaml

• dune-fmt
• dune-opam-sync
• ocp-indent
• opam-lint

PHP

• phpcbf
• php-cs-fixer
• phpcs
• phpstan
• psalm

Purescript

• purs-tidy
• purty

Python

• autoflake
• black
• check-builtin-literals
• check-docstring-first
• check-python
• fix-encoding-pragma
• flake8
• flynt
• isort
• mypy
• name-tests-test
• poetry-check: Run poetry check.
• poetry-lock: Run poetry lock.
• pylint
• pyright
• python-debug-statements
• pyupgrade
• ruff
• ruff-format
• single-quoted-strings
• sort-requirements-txt
• uv

Rust

• cargo-check
• clippy
• rustfmt

Secret detection

• pre-commit-ensure-sops
• ripsecrets
• trufflehog: Secret scanner

Shell

• bats
• beautysh
• shellcheck
• shfmt

Spell checker

• cspell
• hunspell
• proselint
• typos
• vale

Terraform

• terraform-format: built-in formatter (using OpenTofu's fmt)
• terraform-validate: built-in validator (using OpenTofu's validate)
• tflint

TOML

• check-toml
• taplo fmt

Typst

• typstfmt
• typstyle

YAML

• check-yaml
• sort-simple-yaml
• yamlfmt
• yamllint

Various other hooks

• actionlint
• check-added-large-files
• check-case-conflicts
• check-executables-have-shebangs
• checkmake
• check-shebang-scripts-are-executable
• check-symlinks
• check-vcs-permalinks
• check-xml
• circleci
• conform
• detect-aws-credentials
• detect-private-keys
• end-of-file-fixer
• fix-byte-order-marker
• headache
• mixed-line-endings
• mkdocs-linkcheck
• openapi-spec-validator
• prettier
• reuse
• sort-file-contents
• tagref
• topiary
• treefmt
• trim-trailing-whitespace
• zizmor

Custom hooks

Sometimes it is useful to add a project specific command as an extra check that is not part of the pre-defined set of hooks provided by this project.

Example configuration:

 let
   nix-pre-commit-hooks = import (builtins.fetchTarball "https://github.com/cachix/git-hooks.nix/tarball/master");
 in {
   pre-commit-check = nix-pre-commit-hooks.run {
     hooks = {
       # ...

       # Example custom hook for a C project using Make:
       unit-tests = {
         enable = true;

         # The name of the hook (appears on the report table):
         name = "Unit tests";

         # The command to execute (mandatory):
         entry = "make check";

         # The pattern of files to run on (default: "" (all))
         # see also https://pre-commit.com/#hooks-files
         files = "\\.(c|h)$";

         # List of file types to run on (default: [ "file" ] (all files))
         # see also https://pre-commit.com/#filtering-files-with-types
         # You probably only need to specify one of `files` or `types`:
         types = [ "text" "c" ];

         # Exclude files that were matched by these patterns (default: [ ] (none)):
         excludes = [ "irrelevant\\.c" ];

         # The language of the hook - tells pre-commit
         # how to install the hook (default: "system")
         # see also https://pre-commit.com/#supported-languages
         language = "system";

         # Set this to false to not pass the changed files
         # to the command (default: true):
         pass_filenames = false;

         # Which git hooks the command should run for (default: [ "pre-commit" ]):
         stages = ["pre-push"];
       };
     };
   };
 }

Custom hooks are defined with the same schema as pre-defined hooks.

Contributing hooks

Everyone is encouraged to add new hooks.

Have a look at the existing hooks and the options.

There's no guarantee the hook will be accepted, but the general guidelines are:

• Nix closure of the tool should be small e.g. < 50MB. A problematic example:

  $ du -sh $(nix-build -A go)
  463M  /nix/store/v4ys4lrjngf62lvvrdbs7r9kbxh9nqaa-go-1.18.6

• The tool must not be very specific (e.g. language tooling is OK, but project specific tooling is not)
• The tool needs to live in a separate repository (even if a simple bash script, unless it's a oneliner)