ln-742-precommit-setup

Does:

• Installs hook management tools (Husky or pre-commit)
• Configures staged file linting (lint-staged or pre-commit hooks)
• Sets up commit message validation (commitlint)
• Verifies hooks trigger correctly

Does NOT:

• Configure linters themselves (ln-741 does this)
• Set up test infrastructure (ln-743 does this)
• Modify source code

---

| Technology | Hook Manager | Staged Linting | Commit Validation |

|------------|--------------|----------------|-------------------|

| Node.js | Husky | lint-staged | commitlint |

| Python | pre-commit | pre-commit hooks | pre-commit hook |

| Mixed | Both (if needed) | Stack-specific | commitlint |

---

Before installing, check for existing hook configurations.

Files to Check:

| Tool | Indicators |

|------|------------|

| Husky | .husky/ directory, husky in package.json |

| pre-commit | .pre-commit-config.yaml |

| lint-staged | lint-staged in package.json or .lintstagedrc* |

| commitlint | commitlint.config., .commitlintrc |

Decision Logic:

1. If hooks exist and working: SKIP (inform user)
2. If partial setup: ASK user to complete or replace
3. If no hooks: CREATE from templates

---

Node.js Projects (Husky)

```bash

npm install -D husky

npx husky init

```

This creates:

• .husky/ directory
• .husky/pre-commit hook file
• Adds prepare script to package.json

Python Projects (pre-commit)

```bash

pip install pre-commit

# OR with uv:

uv add --dev pre-commit

pre-commit install

```

This creates:

• .git/hooks/pre-commit (managed by pre-commit)
• Requires .pre-commit-config.yaml for configuration

---

Node.js (lint-staged)

```bash

npm install -D lint-staged

```

Create configuration (.lintstagedrc.mjs or in package.json):

Key Rules:

• TypeScript files: ESLint + Prettier
• JSON/MD/CSS: Prettier only
• C# files: dotnet format (if mixed project)

> CRITICAL FIX: For .NET files, use correct syntax:

> "*.cs": "dotnet format --include" is WRONG

> Use: "*.cs": "dotnet format whitespace --include" or run dotnet format separately

Python (pre-commit hooks)

Configuration in .pre-commit-config.yaml:

```yaml

repos:

- repo: https://github.com/astral-sh/ruff-pre-commit

rev: v0.8.0

hooks:

- id: ruff

args: [--fix]

- id: ruff-format

```

---

Node.js (commitlint)

```bash

npm install -D @commitlint/cli @commitlint/config-conventional

```

Create commitlint.config.mjs with:

• Conventional Commits format
• Allowed types: feat, fix, docs, style, refactor, test, chore, ci
• Max header length: 100 characters

Update Husky hook

Add commit-msg hook:

```bash

echo 'npx --no -- commitlint --edit "$1"' > .husky/commit-msg

```

Python (pre-commit hook for commit message)

Add to .pre-commit-config.yaml:

```yaml

- repo: https://github.com/compilerla/conventional-pre-commit

rev: v3.4.0

hooks:

- id: conventional-pre-commit

stages: [commit-msg]

```

---

Verify hooks work correctly.

Test 1: Lint-staged triggers

```bash

# Create a file with lint issues

echo "const x=1" > test-file.ts

git add test-file.ts

git commit -m "test: verify hooks"

# Expected: lint-staged runs, either fixes or blocks

```

Test 2: Commit message validation

```bash

git commit --allow-empty -m "bad message"

# Expected: commitlint rejects

git commit --allow-empty -m "test: valid message format"

# Expected: commit succeeds

```

Cleanup:

```bash

rm test-file.ts

git reset HEAD~1 # If test commit was made

```

---

> RULE 1: Husky requires Git repository (git init first).

> RULE 2: lint-staged MUST have linters configured first (run ln-741 before ln-742).

> RULE 3: Document --no-verify escape hatch for emergency commits.

> RULE 4: pre-commit hooks should auto-fix when possible (--fix flag).

---

• [ ] Hook manager installed (Husky or pre-commit)
• [ ] Staged linting configured and working
• [ ] Commit message validation configured
• [ ] Test commit triggers hooks correctly
• [ ] User informed of:

- How hooks work

- How to skip hooks in emergency (git commit --no-verify)

- Commit message format required

---

| File | Purpose |

|------|---------|

| [husky_precommit_template.sh](references/husky_precommit_template.sh) | Husky pre-commit hook |

| [husky_commitmsg_template.sh](references/husky_commitmsg_template.sh) | Husky commit-msg hook |

| [lintstaged_template.mjs](references/lintstaged_template.mjs) | lint-staged configuration |

| [commitlint_template.mjs](references/commitlint_template.mjs) | commitlint configuration |

| [precommit_config_template.yaml](references/precommit_config_template.yaml) | Python pre-commit config |

| [hooks_guide.md](references/hooks_guide.md) | Detailed hooks guide |

---

| Error | Cause | Resolution |

|-------|-------|------------|

| Husky not running | Missing prepare script | Run npx husky init again |

| lint-staged fails | Missing linter | Run ln-741 first |

| pre-commit not found | Not in PATH | pip install pre-commit |

| Hooks not triggering | Git hooks disabled | Check .git/hooks/ permissions |

| Windows path issues | Shell script format | Use cross-platform syntax |

---

Document for users:

```bash

# Skip all hooks (use sparingly!)

git commit --no-verify -m "emergency: bypass hooks"

# Skip only pre-commit (keeps commit-msg)

HUSKY=0 git commit -m "fix: urgent hotfix"

```

---

Version: 2.0.0

Last Updated: 2026-01-10