🪝 AudioLab Git Hooks¶

Automated code quality checks that run before commits.

📋 Available Hooks¶

1. pre-commit¶

Runs before each commit to ensure code quality.

Checks: - ✅ Code formatting (clang-format) - Validates C++ files are properly formatted - Fails if formatting violations detected - ✅ TODO/FIXME detection - Warns about new TODOs in staged code - Encourages documentation - 🔧 Quick compile check (optional, disabled by default)

Fix formatting issues:

# Auto-format all staged files
clang-format -i $(git diff --cached --name-only | grep -E '\.(cpp|hpp|h)$')

# Or use the GitHub Actions manual workflow
# Go to Actions → Manual Workflows → Select "format-fix"

2. commit-msg¶

Validates commit message format.

Format Required:

<type>(<scope>): <subject>

<body>

Valid Types: - feat - New feature - fix - Bug fix - docs - Documentation only - style - Code style/formatting - refactor - Code refactoring - test - Adding/updating tests - chore - Maintenance tasks - perf - Performance improvement - ci - CI/CD changes - build - Build system changes

Examples:

git commit -m "feat(core): add SIMD optimization for audio buffers"
git commit -m "fix(tests): resolve memory leak in test suite"
git commit -m "docs(readme): update installation guide"
git commit -m "refactor(dsp): simplify filter implementation"

🚀 Installation¶

Windows (PowerShell):¶

cd c:\AudioDev\audio-lab
.\.github\hooks\install-hooks.ps1

macOS/Linux (Bash):¶

cd /path/to/audio-lab
./.github/hooks/install-hooks.sh

Manual Installation:¶

# Copy hooks to .git/hooks/
cp .github/hooks/pre-commit .git/hooks/pre-commit
cp .github/hooks/commit-msg .git/hooks/commit-msg

# Make executable (Unix)
chmod +x .git/hooks/pre-commit .git/hooks/commit-msg

🔧 Configuration¶

Disable Specific Checks¶

Edit hooks in .git/hooks/ (they're local copies):

# Disable format check
# Comment out the formatting section in .git/hooks/pre-commit

# Disable TODO warnings
# Comment out the TODO detection section

Enable Compile Check¶

Uncomment in .git/hooks/pre-commit:

# Optional: Quick compile check
echo "🔨 Quick compile check..."
if [ -d "2 - FOUNDATION/build" ]; then
    cmake --build "2 - FOUNDATION/build" --target all -- -j4 || {
        echo "❌ Compile check failed"
        exit 1
    }
    echo "✅ Compile check OK"
fi

🚫 Bypassing Hooks¶

Not recommended, but sometimes necessary:

# Skip all hooks
git commit --no-verify

# Or use alias
git commit -n

When to bypass: - Emergency hotfixes - Work-in-progress commits (use wip: prefix) - Reverting bad commits

🐛 Troubleshooting¶

Hook not running¶

# Check if hooks are executable
ls -la .git/hooks/

# Reinstall hooks
.github/hooks/install-hooks.sh

clang-format not found¶

# Windows
choco install llvm

# macOS
brew install clang-format

# Linux
sudo apt-get install clang-format

Hook fails on Windows (line endings)¶

# Convert to Unix line endings
dos2unix .git/hooks/pre-commit
dos2unix .git/hooks/commit-msg

# Or use Git Bash instead of CMD

📊 Hook Workflow¶

┌─────────────────────┐
│   git commit        │
└──────────┬──────────┘
           │
           ▼
    ┌──────────────┐
    │ pre-commit   │  ← Format check, TODO scan
    └──────┬───────┘
           │ ✅ Pass
           ▼
    ┌──────────────┐
    │ commit-msg   │  ← Conventional commits check
    └──────┬───────┘
           │ ✅ Pass
           ▼
    ┌──────────────┐
    │ Commit OK!   │
    └──────────────┘

🔄 Integration with CI¶

Hooks provide local validation. CI provides remote validation.

Local (Hooks): - Fast feedback (seconds) - Catches obvious issues - Developer-friendly

Remote (CI): - Comprehensive checks - Multi-platform testing - Cannot be bypassed

Best Practice: - Use hooks for fast iteration - Let CI catch edge cases - Never rely on hooks alone

📚 Resources¶

Maintained by: AudioLab DevOps Team Last Updated: 2025-10-08