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

Use an active mise shell for the commands in this guide.

Install the repository tools and workspace dependencies from the repository root:

mise install
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

Lefthook passes staged source filenames to ultracite fix. Ultracite formats these files and applies safe lint fixes. Lefthook adds the fixed files to the Git index. It then passes all staged filenames to nx affected --stdin. Nx selects affected projects and runs their lint, format, and Markdown checks. Nx owns parallel execution and the task cache.

Lefthook preserves unstaged hunks before the jobs start. It restores these hunks after it adds the fixed staged version to the index. The hook test verifies this behavior for a file that has separate staged and unstaged hunks.

Filenames with spaces and commas remain separate. Lefthook quotes each filename for Ultracite. The fix helper prefixes a filename that can look like a command option. The Nx helper uses one filename per line. Both helpers reject filenames with line breaks. Rename these files and stage them again. The selected targets inspect their full project inputs, including unstaged files. They do not validate an isolated snapshot of the Git index.

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:

nx run eos-documentation:docs:links

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

nx run eos-documentation: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. Ultracite fixes supported staged source files before the checks run. Apply the same fix to the repository with nx run eos:fmt. Apply Markdown 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