From 0e70be9c3d2c4cf37734c5eceb06bb08c66024b9 Mon Sep 17 00:00:00 2001
From: Niklas Voss <niklas.voss@gmail.com>
Date: Tue, 28 Apr 2026 13:31:15 +0200
Subject: [PATCH] feat: add commitlint hook (disabled by default)

---
 README.md | 33 +++++++++++++++++++++++++++++++++
 flake.nix |  6 ++++++
 2 files changed, 39 insertions(+)

diff --git a/README.md b/README.md
index 7e92188..101692a 100644
--- a/README.md
+++ b/README.md
@@ -87,6 +87,39 @@ cobra: $(COBRA)
 	$(COBRA) help
 ```
 
+### Default git hooks
+
+The dev shell installs the following git hooks automatically:
+
+| Hook         | Stage        | Description                                     |
+| ---          | ---          | ---                                             |
+| `fmt`        | `pre-commit` | Runs `make fmt`                                 |
+| `lint`       | `pre-commit` | Runs `make lint`                                |
+| `osv-scanner`| `pre-commit` | Runs `make scan` on dependency file changes     |
+| `commitlint` | `commit-msg` | Validates commit messages against [Conventional Commits](https://www.conventionalcommits.org/) (disabled by default) |
+
+To enable the `commitlint` hook, set `commitlint.enable = true` in `preCommitHooks` and add a `.commitlintrc.yml` to the project root:
+
+```yaml
+extends:
+  - "@commitlint/config-conventional"
+rules:
+  type-enum:
+    - 2
+    - always
+    - - feat
+      - fix
+      - docs
+      - chore
+      - refactor
+      - test
+      - ci
+      - perf
+      - revert
+```
+
+All default hooks can be disabled per-project via `preCommitHooks` (see below).
+
 ### Customizing the dev shell
 
 Modify `flake.nix` to adjust Go version, packages, and pre-commit hooks:
diff --git a/flake.nix b/flake.nix
index 216eb74..0a84095 100644
--- a/flake.nix
+++ b/flake.nix
@@ -69,6 +69,12 @@
           files = "\\.(mod|sum)$|requirements\\.txt$";
           pass_filenames = false;
         };
+        commitlint = mkDefaultAttrs {
+          enable = false;
+          entry = "${pkgs.commitlint}/bin/commitlint --edit";
+          stages = ["commit-msg"];
+          pass_filenames = false;
+        };
       };
       gitHooks = git-hooks.lib.${system}.run {
         src = nixpkgs.path;