🪝 GIT HOOKS - AUDIOLAB¶

Git hooks personalizados para prevenir errores comunes y enforcing standards.

📋 HOOKS DISPONIBLES¶

✅ `pre-commit`¶

Ejecuta antes de cada commit

Validaciones: - ❌ Previene commits directos a main/master - 🔐 Detecta secretos (API keys, passwords, tokens) - 📦 Previene archivos grandes (>5MB) - sugiere Git LFS - 🗑️ Detecta archivos temporales (.swp, .o, .exe, etc.) - 🔧 (Opcional) Ejecuta linters (clang-format, flake8, ESLint)

✅ `pre-push`¶

Ejecuta antes de cada push

Validaciones: - 🛡️ Bloquea force push a branches protegidos - ⚠️ Advierte al pushear a main/master directamente - 🔄 Verifica que branch esté actualizado con remote - 📝 Valida naming convention de branches - 🧪 (Opcional) Ejecuta tests antes de push

✅ `commit-msg`¶

Valida formato de mensajes de commit

Validaciones: - 📋 Enforza formato AudioLab: type(scope): description - 📏 Verifica longitud (<72 chars recomendado) - 🔤 Valida lowercase después del tipo - 🚫 Previene mensajes vagos ("fix", "update", etc.) - 📝 Valida formato del body (blank line después del subject)

🚀 INSTALACIÓN¶

Método 1: Manual (Para un solo repositorio)¶

# Navegar al repositorio
cd /path/to/audio-lab

# Copiar hooks a .git/hooks/
cp "2 - FOUNDATION/03_INFRA/03_01_version_control/examples/hooks/"* .git/hooks/

# Hacer ejecutables (Linux/Mac)
chmod +x .git/hooks/pre-commit
chmod +x .git/hooks/pre-push
chmod +x .git/hooks/commit-msg

# Windows (Git Bash)
# Los permisos de ejecución deberían estar OK por default

Método 2: Script Automatizado¶

# Crear script de instalación
cat > install-hooks.sh << 'EOF'
#!/bin/bash
HOOKS_DIR="2 - FOUNDATION/03_INFRA/03_01_version_control/examples/hooks"
GIT_HOOKS_DIR=".git/hooks"

echo "Installing AudioLab Git hooks..."

for hook in pre-commit pre-push commit-msg; do
    if [ -f "$HOOKS_DIR/$hook" ]; then
        cp "$HOOKS_DIR/$hook" "$GIT_HOOKS_DIR/$hook"
        chmod +x "$GIT_HOOKS_DIR/$hook"
        echo "✅ Installed $hook"
    fi
done

echo "✨ Hooks installed successfully!"
EOF

chmod +x install-hooks.sh
./install-hooks.sh

Método 3: Template Global (Para todos los repos futuros)¶

# Configurar directorio de templates
git config --global init.templateDir ~/.git-templates

# Crear estructura
mkdir -p ~/.git-templates/hooks

# Copiar hooks
cp examples/hooks/* ~/.git-templates/hooks/
chmod +x ~/.git-templates/hooks/*

# Ahora todo nuevo repo tendrá los hooks automáticamente
git init nuevo-proyecto  # Hooks incluidos!

🔧 CONFIGURACIÓN¶

Personalizar Hooks¶

Edita los hooks en .git/hooks/ para ajustar:

`pre-commit`:¶

# Cambiar tamaño máximo de archivo
MAX_FILE_SIZE=10485760  # 10MB

# Habilitar/deshabilitar checks específicos
# Comentar secciones que no necesites

`pre-push`:¶

# Modificar branches protegidos
PROTECTED_BRANCHES="main master develop staging production release"

# Habilitar tests automáticos
# Descomentar sección de tests

`commit-msg`:¶

# Ajustar longitud máxima
if [ $SUBJECT_LENGTH -gt 80 ]; then  # Cambiar de 72 a 80

# Agregar tipos personalizados
PATTERN="^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|wip)(\([a-z0-9-]+\))?: .+"

🎯 USO¶

Workflow Normal¶

Los hooks se ejecutan automáticamente:

# Commit (trigger: pre-commit, commit-msg)
git commit -m "feat(dsp): add reverb algorithm"

# Si falla algún check:
# ❌ ERROR: [descripción del problema]
# [sugerencias de cómo arreglar]

# Push (trigger: pre-push)
git push origin feature/my-feature

Bypass Hooks (Usar con PRECAUCIÓN)¶

# Saltear todos los hooks
git commit --no-verify -m "emergency fix"
git push --no-verify

# O solo pre-commit
git commit --no-verify
# (pero commit-msg igual valida)

⚠️ ADVERTENCIA: Solo usa --no-verify en emergencias reales.

📊 EJEMPLOS DE VALIDACIONES¶

✅ CASOS QUE PASAN¶

# Commits válidos
git commit -m "feat(dsp): implement Schroeder reverb"
git commit -m "fix(audio): resolve buffer underrun on startup"
git commit -m "docs: update API documentation for effects"
git commit -m "refactor(core): optimize memory allocation"
git commit -m "perf(dsp): vectorize convolution loop"

# Branch names válidos
feature/dsp/reverb-algorithm
fix/audio/buffer-underrun
experiment/ml/source-separation
hotfix/plugin/vst3-crash

❌ CASOS QUE FALLAN¶

# Commit messages inválidos
git commit -m "fixed bug"
# ❌ No sigue formato type(scope): description

git commit -m "feat: add stuff"
# ❌ Muy vago, no explica QUÉ se agregó

git commit -m "FEAT(dsp): Add reverb"
# ❌ Tipo en mayúsculas (debe ser lowercase)

git commit -m "feat(dsp): Add reverb algorithm."
# ❌ Termina con punto

# Intentos de commit directo a main
git checkout main
git commit -m "feat: quick fix"
# ❌ Direct commits to main are not allowed!

# Archivos con secretos
echo "api_key = 'sk-1234567890abcdef'" > config.py
git add config.py
git commit -m "feat: add config"
# ❌ Potential secrets detected!

# Archivos grandes
dd if=/dev/zero of=large.bin bs=1M count=10
git add large.bin
git commit -m "feat: add binary"
# ❌ Large files detected (>5MB)

# Force push a protected branch
git push --force origin main
# ❌ Force push to protected branch 'main' is not allowed!

🛠️ TROUBLESHOOTING¶

Problema: "Permission denied" al ejecutar hook¶

Solución:

chmod +x .git/hooks/pre-commit
chmod +x .git/hooks/pre-push
chmod +x .git/hooks/commit-msg

Problema: Hook no se ejecuta¶

Verificar:

# 1. Hook existe?
ls -la .git/hooks/

# 2. Es ejecutable?
ls -l .git/hooks/pre-commit

# 3. Tiene shebang correcto?
head -1 .git/hooks/pre-commit
# Debe ser: #!/bin/bash

Problema: False positives en detección de secretos¶

Opciones:

Temporal: Bypass con --no-verify
Permanente: Editar pre-commit, ajustar SECRET_PATTERNS
Mejor: Renombrar variable para no match pattern

# En vez de:
API_KEY = "..."

# Usar:
EXTERNAL_SERVICE_KEY = "..."  # Menos probable de triggerear

Problema: Tests toman mucho tiempo en pre-push¶

Solución:

# Opción 1: Deshabilitar tests locales, confiar en CI
# (comentar sección de tests en pre-push)

# Opción 2: Solo tests rápidos localmente
# Modificar pre-push para correr solo unit tests, no integration

# Opción 3: Bypass ocasionalmente
git push --no-verify  # Solo para pushes a feature branches

📚 RECURSOS ADICIONALES¶

Documentación Relacionada¶

COMMIT_MESSAGE_ART.md - Guía de mensajes de commit
BRANCHING_PHILOSOPHY.md - Naming conventions
DISASTER_RECOVERY_PHILOSOPHY.md - Qué hacer si hooks bloquean algo importante

Git Hooks Documentation¶

🤝 CONTRIBUTING¶

Mejorar Hooks¶

Si encuentras un check útil que falta:

Edita hook en examples/hooks/
Testea en tu repo local
Crea PR con mejora
Documenta en este README

Reportar Issues¶

Hook tiene bug? → Crea issue
Check es muy estricto? → Sugiere ajuste
False positive? → Reporta patrón

📝 CHANGELOG¶

v1.0.0 (2025-10-09)¶

✨ Initial release
✅ pre-commit: secrets, large files, temp files, direct main commits
✅ pre-push: force push protection, branch naming, sync check
✅ commit-msg: AudioLab format validation

Última actualización: 2025-10-09 Maintainer: AudioLab Foundation