git-hooks

What this skill does

# 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](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](references/setup-workflows.md#netc-workflows)

**Examples:**

- [examples/husky-net-dotnet-format.json](examples/husky-net-dotnet-format.json)
- [examples/lefthook-dotnet.yml](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](references/setup-workflows.md#javascripttypescript-workflows)

**Examples:**

- [examples/husky-javascript-package.json](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](references/setup-workflows.md#python-workflows)

**Examples:**

- [examples/pre-commit-python.yaml](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](references/setup-workflows.md#polyglot-workflows)

**Examples:**

- [examples/lefthook-polyglot.yml](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](references/conventional-commits.md)

**Examples:**

- [examples/commitlint.config.js](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](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](references/performance-optimization.md)

---

### 8. Testing & Validation

**Levels:**

- **Unit testing** - Test individual hook scripts
- **Integration testing** - Test complete workflow
- **CI/CD validation** - Run same