Skip to content

Setup Pre-Commit Hooks

Overview

Pre-commit hooks automatically validate your code and documentation before each commit, catching issues early. This project uses Husky for git hooks with integrated validation scripts.

What Gets Validated

The husky pre-commit hook validates two categories:

1. Generated Files (when source files are staged)

When files matching the generated pattern are staged, the hook runs pnpm run validate:generated:

  • env-mapping.yaml, dependency-map.yaml - Configuration sources
  • *.generated.ts, *.generated.json - Generated TypeScript/JSON
  • Dockerfile, _env-blocks.tpl - Generated container/Helm files
  • feature-flags.*.ts - Generated feature flag files
  • .generated-checksums.json - Checksums manifest

2. Documentation (when docs/*.md files are staged)

When documentation files are staged, the hook:

  1. Generates indexes - Updates docs/*/index.md files and auto-stages changes
  2. Generates MkDocs nav - Updates mkdocs.yml navigation and auto-stages changes
  3. Validates frontmatter - Checks YAML frontmatter in all docs files

Prerequisites

  • Node.js 18+ (for pnpm and husky)
  • Python 3.7+ (for docs scripts)

Installation

Automatic (After Clone)

Husky is already configured. After cloning and running pnpm install:

pnpm install

This automatically sets up git hooks via husky's prepare script.

Verify Installation

Check that hooks are active:

# Should show .husky/_
git config core.hooksPath

# Test the hooks manually
./.husky/pre-commit

Manual Testing

Run validation scripts directly:

# Test generated files validation
pnpm run validate:generated

# Test docs validation
./docs/scripts/generate-indexes.sh
python3 ./docs/scripts/generate-mkdocs-nav.py
./docs/scripts/validate-docs.sh

Using Pre-commit Framework (Optional)

For additional linting beyond what husky provides, you can also use the pre-commit framework:

pip install pre-commit
pre-commit run --all-files

Note: Do NOT run pre-commit install as it conflicts with husky's core.hooksPath setting. Use pre-commit for manual linting only.

Usage

Automatic (Default Behavior)

Once installed, hooks run automatically on commit:

git add docs/new-feature.md
git commit -m "docs: add new feature documentation"
# Husky pre-commit hook runs automatically

If validation fails:

  • Commit is blocked
  • Errors are displayed
  • Fix issues and try again

Auto-Staging of Generated Files

The docs validation hooks automatically stage files they modify:

git add docs/how-to/my-new-doc.md
git commit -m "docs: add new how-to guide"
# Hook detects docs changed
# → Generates/updates docs/how-to/index.md (auto-staged if changed)
# → Generates/updates mkdocs.yml navigation (auto-staged if changed)
# → Validates frontmatter
# Commit succeeds with all generated files included

Skip Hooks (Use Sparingly)

To bypass hooks in exceptional cases:

git commit --no-verify -m "docs: emergency fix"

Warning: Only use --no-verify when absolutely necessary. The CI/CD pipeline will still validate, so issues will be caught there.

Troubleshooting

Hooks Not Running

Problem: Commit succeeds without running hooks

Solution:

# Verify husky is configured
git config core.hooksPath
# Should output: .husky/_

# If not set, run pnpm install to trigger husky prepare
pnpm install

# Test hook manually
./.husky/pre-commit

Validation Script Fails

Problem: Scripts not found or not executable

Solution:

chmod +x docs/scripts/validate-docs.sh
chmod +x docs/scripts/generate-indexes.sh
chmod +x .husky/pre-commit

Generated Files Out of Sync

Problem: pnpm run validate:generated fails

Solution:

# Regenerate all files
cd src/charts/syrf-common && pnpm run generate:env-blocks
cd src/services/web && pnpm run generate:flags
python scripts/generate-dockerfiles.py

# Update checksums
pnpm run update-checksums

See Working with Generated Files for detailed guidance.

Documentation Index Out of Date

Problem: Index files or mkdocs.yml are stale

Solution:

./docs/scripts/generate-indexes.sh
python3 ./docs/scripts/generate-mkdocs-nav.py

Configuration Files

File Purpose
.husky/pre-commit Main pre-commit hook script
.pre-commit-config.yaml Pre-commit framework config (optional linting)
.markdownlint.json Markdown linting rules
.yamllint.yml YAML linting rules
docs/scripts/validate-docs.sh Documentation validation script
docs/scripts/generate-indexes.sh Index generation script
docs/scripts/generate-mkdocs-nav.py MkDocs nav generation script

CI/CD Integration

Pre-commit hooks are complementary to CI/CD validation:

Validation Point Scope Action on Failure
Husky Pre-commit Local, per commit Block commit
CI/CD Pull requests, pushes Block merge

Both run the same validation scripts, ensuring consistent quality checks locally and in CI/CD.

Best Practices

  1. Run pnpm install after cloning to set up husky hooks
  2. Test validation manually before large commits
  3. Don't skip validation without good reason
  4. Fix issues before committing rather than using --no-verify
  5. Keep generated files in sync by running generators when source files change

Disabling Husky Hooks

To temporarily disable husky hooks:

# Set environment variable
HUSKY=0 git commit -m "message"

To permanently remove husky:

pnpm remove husky
git config --unset core.hooksPath