Architecture Decision Record

Git Hook Automation with lefthook

Adopt lefthook to automatically run Biome formatting and linting at commit and push time.

2026-02-06 Accepted #tooling #quality #git-hook

Translations

German French Korean Portuguese Japanese

Git Hook Automation with lefthook

Decision

Adopt lefthook for Git Hook management.
Run biome format --write and then biome check --write on staged files in pre-commit.
Run biome format --write and then biome check --write on the files included in the push (committed changes) in pre-push as well.
Centralize hook definitions in lefthook.yml at the repository root.

Context

When formatting or linting is skipped locally, reviews include noisy non-essential diffs and comments. There was also inconsistency in per-developer hook setups, so we needed a version-controlled and reproducible approach.

Alternatives

Native Git hooks in .git/hooks configured manually: low reproducibility and hard to share.
Husky: proven option, but lefthook was preferred this time for lighter and simpler configuration.
CI-only validation: slower feedback and no early local detection.

Consequences

Quality checks are automated before commit and before push.
Formatting issues are detected early, reducing style inconsistency.
On failure, commit/push is blocked until fixes are applied and checks are rerun.