How to run Git hook checks

Use the repository’s Lefthook configuration to validate commit messages, check staged source and Markdown files before committing, and validate documentation links before pushing.

Install the hooks

Enter the Nix development shell and install the workspace dependencies from the repository root:

nix develop
pnpm install

The Lefthook dependency installs the configured commit-msg, pre-commit, and pre-push hooks. Verify that the generated Git hooks are present and current:

pnpm exec lefthook check-install

The command exits successfully without output when the hooks are current.

Validate commit messages

Create or amend a commit normally to validate its message with Commitlint:

git commit
git commit --amend

EOS uses the unmodified @commitlint/config-conventional preset. Commit types must be one of build, chore, ci, docs, feat, fix, perf, refactor, revert, style, or test. Types must be lowercase. Subjects must not be empty, use sentence/start/Pascal/upper case, or end with a full stop. Headers and non-URL body or footer lines must not exceed 100 characters.

Validate a message from standard input without creating a commit:

printf '%s\n' 'docs: explain Git hook checks' | pnpm exec commitlint --verbose

Validate the latest commit directly:

pnpm exec commitlint --last --verbose

Local Git hooks can be bypassed with --no-verify. Pull-request title validation is the required merge check for the normal squash workflow. CI also reports invalid commits introduced directly on main, but cannot undo a push that has already landed.

Run the pre-commit checks

Create a commit normally to run the hook against staged files:

git commit

The hook checks formatting with Oxfmt, lints JavaScript and TypeScript with Oxlint, and lints Markdown with markdownlint. Independent checks run in parallel. Files that do not match a configured check are skipped.

Run the same checks without creating a commit when validating staged changes:

pnpm exec lefthook run pre-commit

Run the checks against every tracked matching file when validating the complete repository:

pnpm exec lefthook run pre-commit --all-files

Run the pre-push check

Push normally to validate repository documentation links when the pushed commits contain Markdown changes:

git push

Run the same repository-wide offline link check directly with the package script:

pnpm docs:links

Run all repository-wide Markdown formatting, linting, and link checks in parallel with:

pnpm docs:check

Correct a failed check

Read the named job and diagnostics in the hook output. For a Commitlint failure, edit the commit message to satisfy the reported rule and retry the commit. Apply source formatting with pnpm fmt, or apply Markdown formatting and supported lint fixes with pnpm docs:lint. Correct remaining lint or link failures manually.

Stage the corrected files and retry the Git operation:

git add <files>
git commit
git push

Repair the hook installation

Reinstall the generated Git hooks if check-install reports that they are missing or stale:

pnpm exec lefthook install
pnpm exec lefthook check-install