git-hooks

Git Hooks

Overview

This skill provides comprehensive guidance on modern git hook implementations across multiple ecosystems, with primary focus on .NET/C# and strong support for JavaScript/TypeScript and Python. It covers framework selection, setup workflows, performance optimization, security integration, testing strategies, and team collaboration patterns.

Key capabilities:

1. Adaptive framework recommendations based on ecosystem, scale, and requirements
2. Complete lifecycle support from tool selection → setup → configuration → testing → maintenance
3. Performance-first approach with parallel execution and incremental processing patterns
4. Security by default with mandatory secret scanning integration
5. CI/CD integration for defense-in-depth validation (local + remote)
6. Real-world examples with copy-paste ready configurations

When to Use This Skill

Use this skill when you need to:

• Set up git hooks for a new or existing project
• Choose a git hook framework (Husky.Net vs lefthook vs Husky vs pre-commit)
• Configure pre-commit hooks for code formatting, linting, security scanning
• Configure commit-msg hooks for Conventional Commits validation
• Configure pre-push hooks for running tests or build validation
• Integrate ecosystem tools (dotnet format, ESLint/Prettier, Black/Ruff/mypy)
• Enforce Conventional Commits with commitlint
• Scan for secrets before commits (gitleaks, TruffleHog)
• Optimize hook performance (slow hooks blocking developers)
• Test git hooks (unit testing, integration testing)
• Deploy hooks to a team (automatic installation, CI/CD enforcement)
• Troubleshoot hook issues (activation problems, performance issues)
• Handle monorepo hook patterns

Trigger scenarios:

• "Set up git hooks for my .NET project"
• "How do I enforce code formatting before commits?"
• "Configure Conventional Commits validation"
• "My pre-commit hook is too slow"
• "Should I use Husky.Net or lefthook for C#?"
• "Integrate secret scanning with git hooks"

Quick Start Decision Tree

Which framework should I use?

Answer these questions:

1. What's your primary ecosystem?

   • .NET/C# only → Consider Husky.Net (native integration) or lefthook (performance)
   • JavaScript/TypeScript only → Use Husky + lint-staged + commitlint
   • Python only → Use pre-commit framework
   • Multiple languages (polyglot) → Use lefthook or pre-commit

2. What's your team size/scale?

   • Solo developer or small team → Any framework works; choose based on ecosystem
   • Medium team (5-20) → Prioritize ease of installation and CI/CD integration
   • Large team/enterprise (20+) → Prioritize performance (lefthook), standardization

3. What's your performance requirement?

   • Speed is critical → Use lefthook (parallel execution, Go-based)
   • Speed is moderate concern → Any framework with incremental processing
   • Speed is not a concern → Choose based on ecosystem familiarity

Quick recommendations

Ecosystem	Solo/Small Team	Medium Team	Large Team/Enterprise
.NET/C#	Husky.Net	Husky.Net or lefthook	lefthook
JavaScript/TypeScript	Husky + lint-staged	Husky + lint-staged	Husky + lint-staged or lefthook
Python	pre-commit	pre-commit	pre-commit or lefthook
Polyglot	lefthook or pre-commit	lefthook	lefthook

Framework Comparison at a Glance

Feature	Husky.Net	lefthook	Husky (JS)	pre-commit
Performance	Moderate	Excellent (parallel)	Good (with lint-staged)	Good
Ecosystem	.NET/C#	Any	JavaScript/TS	Any (Python primary)
Config Format	JSON (task-runner.json)	YAML	Shell scripts + package.json	YAML
Parallel Execution	❌ No	✅ Yes	❌ No	Partial
Learning Curve	Low (.NET devs)	Moderate	Low (JS devs)	Low (Python devs)
Monorepo Support	Moderate	Excellent	Excellent	Good

📖 For detailed comparison: See references/framework-comparison.md for comprehensive feature analysis, pros/cons, and selection criteria.

Core Capabilities

1. .NET/C# Workflows

Quick Start: Install Husky.Net (dotnet tool install Husky) or lefthook (scoop install lefthook), configure task-runner.json or lefthook.yml, and verify.

Key patterns:

• Use ${staged} or {staged_files} for incremental processing
• Integrate dotnet format (pre-commit) and dotnet test (pre-push)
• Attach Husky.Net to .csproj for automatic team installation

📖 For complete setup: See references/setup-workflows.md

Examples:

• examples/husky-net-dotnet-format.json
• examples/lefthook-dotnet.yml

---

2. JavaScript/TypeScript Workflows

Quick Start: Install dependencies (npm install --save-dev husky lint-staged @commitlint/cli), initialize Husky (npx husky init), configure lint-staged in package.json, and add hooks.

Key patterns:

• Use lint-staged for incremental processing (15x speedup)
• Integrate ESLint, Prettier, and commitlint
• Automatic installation via prepare script

📖 For complete setup: See references/setup-workflows.md

Examples:

• examples/husky-javascript-package.json

---

3. Python Workflows

Quick Start: Install pre-commit (pip install pre-commit), create .pre-commit-config.yaml with Black/Ruff/mypy hooks, and run pre-commit install.

Key patterns:

• Use Ruff for 10-100x faster linting than Flake8/pylint
• Extensive plugin ecosystem (hundreds of pre-built hooks)
• Automatic environment management

📖 For complete setup: See references/setup-workflows.md

Examples:

• examples/pre-commit-python.yaml

---

4. Polyglot Workflows

For repositories with multiple languages, use lefthook (recommended for performance) or pre-commit.

📖 For complete setup: See references/setup-workflows.md

Examples:

• examples/lefthook-polyglot.yml

---

5. Conventional Commits & Semantic Versioning

Tools: commitlint (validation), commitizen (interactive prompts), semantic-release (automated versioning)

Quick Start: Install commitlint, configure rules, add commit-msg hook

📖 For complete setup: See references/conventional-commits.md

Examples:

• examples/commitlint.config.js

---

6. Security & Secret Scanning

Tools: gitleaks (secret detection), TruffleHog (800+ secret types with API validation)

Quick Start: Install gitleaks/TruffleHog, add to pre-commit hooks, configure allowlist for false positives

Best Practice: Scan locally (pre-commit) AND in CI/CD (pull requests)

📖 For complete setup: See references/secret-scanning.md

---

7. Performance Optimization

Key strategies:

1. Incremental processing - Only process staged files (15x speedup)
2. Parallel execution - Run hooks in parallel with lefthook (90% speedup)
3. Fast tools - Use Ruff (10-100x faster than Flake8/pylint)
4. Caching - ESLint --cache, dotnet --no-build

📖 For detailed strategies: See references/performance-optimization.md

---

8. Testing & Validation

Levels:

• Unit testing - Test individual hook scripts
• Integration testing - Test complete workflow
• CI/CD validation - Run same checks locally and remotely (defense in depth)

📖 For examples and patterns: See references/testing-strategies.md

---

9. Troubleshooting

Common issues:

• Hooks not running - Run framework install command, check core.hooksPath
• Hooks too slow - Use incremental processing, parallel execution, faster tools
• Windows path issues - Use quotes and forward slashes

Migration strategies: Gradual rollout (formatting → linting → commit validation → testing/security)

📖 For complete troubleshooting: See references/troubleshooting.md

---

Configuration Examples

Complete examples are available in the examples/ directory:

• examples/husky-net-dotnet-format.json - Husky.Net with dotnet format
• examples/lefthook-dotnet.yml - lefthook for .NET/C#
• examples/husky-javascript-package.json - Husky + lint-staged for JS/TS
• examples/pre-commit-python.yaml - pre-commit for Python
• examples/lefthook-polyglot.yml - lefthook for polyglot repositories
• examples/commitlint.config.js - Conventional Commits configuration

---

Migration & Adoption

Gradual Rollout Strategy

Phase 1: Start with formatting (low risk)

• Add dotnet format / Prettier / Black
• Warning mode (don't block commits)
• Team feedback and adjustment

Phase 2: Add linting

• Add ESLint / Ruff / StyleCop
• Error mode (block commits)
• Fix existing violations

Phase 3: Add commit message validation

• Add commitlint
• Educate team on Conventional Commits
• Provide commitizen for assistance

Phase 4: Add testing and security

• Add dotnet test in pre-push
• Add gitleaks in pre-commit
• CI/CD enforcement

---

Test Scenarios

Scenario 1: Framework Selection for .NET Project

User Query: "I need to set up git hooks for my C# project with 15 developers"

Expected Behavior:

• Skill activates on keywords: "git hooks", "C#", ".NET"
• Provides Quick Start Decision Tree guiding to framework selection
• Considers team size (medium team)
• Recommends Husky.Net (native integration) or lefthook (performance)
• Links to framework comparison and setup workflows

---

Scenario 2: Performance Optimization Request

User Query: "My pre-commit hook is taking 35 seconds and blocking developers from committing"

Expected Behavior:

• Skill activates on keywords: "pre-commit hook", "slow", "performance"
• Recognizes performance problem
• Provides immediate optimization strategies
• Links to performance-optimization.md for deep-dive

---

Scenario 3: Framework Comparison Request

User Query: "Should I use Husky.Net or lefthook for our .NET team?"

Expected Behavior:

• Skill activates on framework names: "Husky.Net", "lefthook"
• Provides framework comparison matrix
• Asks relevant follow-up questions (team size, performance requirements)
• Guides decision based on context

---

Scenario 4: Conventional Commits Implementation

User Query: "How do I enforce Conventional Commits in my JavaScript project?"

Expected Behavior:

• Skill activates on keywords: "Conventional Commits", "JavaScript", "enforce"
• Recognizes commit validation need
• Provides setup steps for commitlint
• Links to conventional-commits.md for complete guide

---

Scenario 5: Secret Scanning Integration

User Query: "I want to prevent developers from accidentally committing secrets to our repository"

Expected Behavior:

• Skill activates on keywords: "secrets", "prevent", "commit"
• Recognizes security requirement
• Recommends gitleaks or TruffleHog
• Links to secret-scanning.md
• Mentions both local (pre-commit) and CI/CD enforcement

---

References

Official Documentation (access via MCP servers):

• Husky.Net: https://alirezanet.github.io/Husky.Net/
• lefthook: https://github.com/evilmartians/lefthook
• Husky (JS): https://typicode.github.io/husky/
• pre-commit: https://pre-commit.com/
• commitlint: https://commitlint.js.org/

Detailed references:

• references/framework-comparison.md - Framework comparison and selection criteria
• references/setup-workflows.md - Setup workflows for all ecosystems
• references/conventional-commits.md - Conventional Commits setup
• references/secret-scanning.md - Secret scanning integration
• references/performance-optimization.md - Performance strategies
• references/testing-strategies.md - Testing and validation patterns
• references/troubleshooting.md - Troubleshooting guide

Version History

• v1.0.0 (2025-12-26): Initial release

---

Last Updated

Date: 2025-11-28 Model: claude-opus-4-5-20251101

Research Sources: Microsoft Learn MCP, Context7 MCP (Husky.Net, lefthook, Husky, pre-commit repositories), Perplexity MCP (2024-2025 best practices), Firecrawl MCP (official documentation sites), Ref MCP (commitlint, semantic-release).