orni_attack/tools/hooks/README.md

Git Hooks - Orni Attack

Este directorio contiene los git hooks versionados para el proyecto Orni Attack.

Los hooks permiten ejecutar automáticamente verificaciones de calidad de código antes de hacer commits.

---

📦 Instalación

Instalación automática (recomendada)

Ejecuta el script de instalación desde la raíz del proyecto:

./tools/hooks/install.sh

Instalación manual

cp tools/hooks/pre-commit .git/hooks/
chmod +x .git/hooks/pre-commit

---

🔍 Hooks disponibles

pre-commit

Se ejecuta automáticamente antes de cada commit.

Realiza dos verificaciones en los archivos .cpp y .hpp modificados:

1. 🎨 clang-format (formato de código)

• Acción: Formatea automáticamente el código según .clang-format
• Comportamiento: Si encuentra problemas de formato, los arregla automáticamente y añade los cambios al commit
• Resultado: Código siempre bien formateado sin esfuerzo manual

2. 🔍 clang-tidy (análisis estático)

• Acción: Verifica el código según las reglas de .clang-tidy
• Comportamiento:
  • ✅ Si no hay errores → commit permitido
  • ❌ Si hay errores → commit bloqueado y muestra los errores
• Resultado: Previene commits con problemas de calidad

---

📋 Ejemplo de uso

# 1. Modificas código
vim source/game/entities/nau.cpp

# 2. Añades al staging
git add source/game/entities/nau.cpp

# 3. Intentas commit
git commit -m "feat: añadir nueva funcionalidad"

# → El hook se ejecuta automáticamente:
🔍 Pre-commit hook: verificando código...
📝 Archivos a revisar: source/game/entities/nau.cpp

🎨 Ejecutando clang-format...
  ✏️  Formateado: source/game/entities/nau.cpp
✅ Archivos formateados automáticamente y añadidos al commit

🔍 Ejecutando clang-tidy...
  ✅ source/game/entities/nau.cpp

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Pre-commit hook: TODO OK
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  🎨 clang-format: OK (archivos formateados)
  🔍 clang-tidy: OK (sin errores)

[main abc1234] feat: añadir nueva funcionalidad
 1 file changed, 10 insertions(+)

---

❌ ¿Qué pasa si hay errores?

Si clang-tidy encuentra errores, el hook bloquea el commit y te muestra:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ COMMIT BLOQUEADO: clang-tidy encontró errores
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

❌ Errores en source/game/entities/nau.cpp:
source/game/entities/nau.cpp:42:10: error: method 'getPosition' can be made const
      ^
                                                                      const

💡 Soluciones:
  1. Corrige los errores manualmente
  2. O ejecuta: make tidy (aplica fixes automáticos)
  3. Luego: git add <archivos> && git commit

⚠️  Si necesitas saltarte el hook (NO RECOMENDADO):
  git commit --no-verify

Soluciones

Opción 1: Arreglar manualmente

Edita el archivo y corrige los errores que muestra clang-tidy.

Opción 2: Auto-fix con make tidy

make tidy              # Aplica fixes automáticos
git add .              # Añade los cambios
git commit -m "..."    # Intenta commit de nuevo

Opción 3: Saltar el hook (NO RECOMENDADO)

git commit --no-verify -m "mensaje"

⚠️ Solo usa --no-verify en casos excepcionales, ya que permite commits con código de baja calidad.

---

🚀 Ventajas

✅ Solo código nuevo: Revisa únicamente archivos modificados (rápido) ✅ Automático: No tienes que acordarte de ejecutar clang-tidy ✅ Formato automático: clang-format arregla el código por ti ✅ Bloquea errores: Previene commits con problemas de calidad ✅ No ralentiza compilación: Solo se ejecuta en commits, no en make ✅ Excluye código externo: Ignora automáticamente audio/ y legacy/

---

🔧 Configuración

Los hooks usan las configuraciones del proyecto:

• .clang-format: Reglas de formato de código
• .clang-tidy: Reglas de análisis estático
• CMakeLists.txt: Exclusiones de directorios (audio/, legacy/)

Si modificas estas configuraciones, los hooks aplicarán automáticamente las nuevas reglas.

---

🗑️ Desinstalación

Para desinstalar el hook:

rm .git/hooks/pre-commit

O para deshabilitarlo temporalmente:

mv .git/hooks/pre-commit .git/hooks/pre-commit.disabled

Para volver a habilitarlo:

mv .git/hooks/pre-commit.disabled .git/hooks/pre-commit

---

📚 Más información

• clang-format: https://clang.llvm.org/docs/ClangFormat.html
• clang-tidy: https://clang.llvm.org/extra/clang-tidy/
• Git hooks: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks

---

⚠️ Nota para desarrolladores

Los hooks de git están en .git/hooks/ y no se versionan automáticamente. Por eso este directorio tools/hooks/ contiene copias versionadas que se pueden instalar fácilmente.

Cada nuevo desarrollador debe ejecutar el instalador al clonar el repositorio:

git clone <repo-url>
cd orni
./tools/hooks/install.sh

---

🐛 Troubleshooting

"clang-format: command not found"

Instala clang-format:

# macOS
brew install clang-format

# Ubuntu/Debian
sudo apt install clang-format

# Arch Linux
sudo pacman -S clang

"clang-tidy: command not found"

Instala clang-tidy:

# macOS
brew install llvm
export PATH="/opt/homebrew/opt/llvm/bin:$PATH"

# Ubuntu/Debian
sudo apt install clang-tidy

# Arch Linux
sudo pacman -S clang

Hook no se ejecuta

Verifica que el hook tiene permisos de ejecución:

ls -la .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Errores en macOS sobre SDK

El hook detecta automáticamente el SDK de macOS usando xcrun --show-sdk-path. Si falla, asegúrate de tener Command Line Tools instaladas:

xcode-select --install