Guía completa de Git Hooks: Instalación, uso y consejos

Los hooks de Git te permiten automatizar tareas en tu flujo de trabajo ejecutando scripts antes o después de acciones de Git como commits o pushes. Ayudan a detectar problemas de forma temprana, a hacer cumplir las normas e incluso a solucionar problemas automáticamente.

Supongamos que has escrito un script para aplicar las normas de estilo del código. Puedes añadir ese script a un hook que se ejecute antes de un commit. Ahora, cada vez que alguien intenta realizar una confirmación, se ejecuta el hook. Si el código supera las comprobaciones del gancho, la confirmación se lleva a cabo. Si no es así, el commit se bloquea.

Y no se trata solo de señalar problemas. También puedes personalizar el script para solucionar esos problemas antes de que se realice la confirmación. En este artículo, voy a explicar todo lo que necesitas saber sobre los hooks de Git: qué son, cuáles son importantes y cómo implementarlos de forma eficaz.

¿Qué son los hooks de Git?

Los hooks de Git ejecutan automáticamente scripts personalizados cuando se producen ciertas acciones de Git, como antes o después de una confirmación, un envío o una fusión. Vienen integrados con Git, por lo que no es necesario instalar ninguna biblioteca externa.

Cuando inicializas un repositorio Git, Git crea los hooks de forma predeterminada. Los encontrarás en el directorio .git/hooks. Vienen con extensiones de .sample, que impiden que se ejecuten de forma predeterminada. Si deseas que se ejecuten de forma predeterminada, simplemente elimina la extensión .sample.

Puedes escribir los hooks en cualquier lenguaje de scripting ejecutable. Por ejemplo, dentro del archivo del gancho pre-commit, puedes añadir un script que compruebe si hay comentarios «To-do» en los archivos preparados y bloquee la confirmación si encuentra alguno. Esto significa que cada vez que intentas realizar una confirmación, Git busca comentarios que comiencen por «To-do» y falla si existen tareas pendientes. De esta forma, puedes crear ganchos personalizados para diferentes acciones de Git, como post-commit, pre-merge, pre-push y muchas más.

Tipos de ganchos Git

Antes de entrar en ejemplos prácticos, veamos los dos tipos de hooks de Git. 

Ganchos del lado del cliente: categorías y ejemplos comunes

Los hooks del lado del cliente se ejecutan en máquinas locales durante operaciones de Git, como commits, rebases y pushes. A continuación se muestran algunos ganchos de cliente populares y sus casos de uso específicos.

• pre-compromiso: Se ejecuta incluso antes de escribir el mensaje de confirmación. Puedes utilizarlo para aplicar estilos de código, ejecutar pruebas o comprobar si hay errores de sintaxis antes de realizar el commit. 
• prepare-commit-msg: Se ejecuta después de que Git cree el mensaje de confirmación predeterminado, pero antes de que aparezca el editor de mensajes de confirmación. Este gancho puede modificar o sustituir el mensaje predeterminado según la lógica del script personalizado. 
• mensaje de confirmación: Este hook se ejecuta justo después de guardar el mensaje de confirmación, pero antes de que Git complete la confirmación. Es tu último punto de control para aplicar las reglas de los mensajes de confirmación, como el formato, la estructura o el etiquetado.
• post-commit: Se ejecuta después de crear una confirmación. Se utiliza a menudo para notificaciones (como enviar un mensaje de Slack después de una confirmación) o para registrar (almacenar metadatos de confirmación).
• Después de la compra: Se ejecuta tras un comando « git checkout » correcto. Se inicia cuando cambias de rama o revisas una confirmación o ruta específica. Puedes utilizarlo para reconstruir las dependencias del proyecto, eliminar archivos temporales o notificar una nueva rama.
• Después de la fusión: Se ejecuta después de una operación de fusión correcta. Se utiliza habitualmente para actualizar dependencias, imprimir mensajes de fusión o borrar cachés.
• pre-rebase: Se ejecuta antes de una operación de rebase. Puedes utilizarlo para evitar el rebase de ramas protegidas, ejecutar pruebas antes de permitir el rebase o detener un rebase si hay cambios sin confirmar.
• pre-push: Se ejecuta antes de enviar los cambios. Ayuda a evitar envíos a ramas protegidas o a ejecutar pruebas previas al envío.
• Después de la reescritura: Se ejecuta después de que Git reescribe correctamente las confirmaciones. Se activa en operaciones como git commit --amend (que reescribe la última confirmación) o git rebase (que reescribe una serie de confirmaciones). Úsalo para actualizar referencias o activar pruebas y pasos de CI después de reescribir.
• pre-aplicar parche: Invocado por el comando ` git am `, este hook se ejecuta después de que se haya aplicado un parche al árbol de trabajo, pero antes de que se cree una nueva confirmación. Si las comprobaciones de este gancho fallan, puede salir con un estado distinto de cero e impedir que se aplique el parche.
• después de aplicar el parche: Git ejecuta esto después de aplicar el parche y crear la confirmación. No puede abortar la confirmación, pero funciona bien para registrar o enviar notificaciones.
• applypatch-msg: Git ejecuta esto antes de que git am aplique el parche. Úsalo para comprobar o editar el mensaje de confirmación propuesto para el parche.

Ganchos del lado del servidor: categorías y casos de uso

Los hooks del lado del servidor se ejecutan en servidores Git remotos y se activan cuando se producen eventos remotos, como antes o después de enviar a un repositorio.

• pre-recibir: El control remoto ejecuta esto antes de aceptar un envío. Puedes utilizarlo para imponer un estilo de código coherente entre los usuarios o realizar comprobaciones de seguridad antes de aceptar los cambios de un cliente.
• Actualización: Mientras que pre-receive se ejecuta una vez por cada push, el hook de actualización se ejecuta por cada referencia (rama o etiqueta) que se modifica en un solo push.
• después de recibir: Se ejecuta una vez completada la operación git push. A menudo se utiliza para enviar notificaciones, realizar registros exhaustivos o activar canalizaciones de CI/CD.
• Después de la actualización: Se ejecuta después de que Git actualice todas las referencias en un push. Puedes utilizarlo para notificaciones sencillas porque, a diferencia de post-receive, no puede acceder a los registros antiguos y nuevos de cada actualización de referencia.
• transacción de referencia: Se activa cuando se prepara, confirma o cancela una transacción de referencia, por lo que puede ejecutarse varias veces. Úsalo para validar o rechazar actualizaciones en múltiples referencias en una sola transacción, o para registrar y auditar cambios de referencia.
• Ir a la caja: Se activa cuando realizas un git push a una rama que actualmente está seleccionada en el control remoto. Con este gancho, puedes actualizar archivos en el servidor después de un envío, registrar los cambios o bloquear envíos no seguros directamente al directorio de trabajo.
• pre-auto-gc: Se ejecuta justo antes de que Git active la recolección automática de basura. Puedes utilizarlo para registrar el inicio de la recolección de basura, bloquearla durante operaciones que consumen muchos recursos o gestionar cualquier tarea necesaria previa a la recolección de basura.
• proc-receive: Se ejecuta cuando el comando git-receive-pack procesa un envío entrante. Actualiza las referencias (ramas y etiquetas) en el repositorio remoto y comunica los resultados al cliente.

Configuración de los hooks de Git

En esta sección, encontrarás los pasos para instalar y configurar los ganchos git. También verás cómo crear ganchos personalizados desde cero. 

Mecánica de instalación y configuración

Cuando inicializas un repositorio Git, Git crea automáticamente un conjunto de hooks dentro de la carpeta .git/hooks. Para verlos, abre tu terminal y ve a la raíz del repositorio donde ejecutaste git init. Desde ahí, abre el directorio oculto .git y, a continuación, el subdirectorio hooks. Un simple comando « cd » hace todo esto por ti y te proporciona acceso al subdirectorio hooks.

cd .git/hooks

Una vez dentro, verás los ganchos predeterminados con la extensión .sample. Para habilitar un gancho predeterminado, elimina la extensión .sample para ese gancho y hazlo ejecutable.

Por ejemplo, utiliza el siguiente comando para eliminar la extensión .sample del gancho pre-commit.

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

A continuación, hazlo ejecutable utilizando el siguiente comando:

chmod +x .git/hooks/pre-commit

Esto cubre la edición y la habilitación de los ganchos predeterminados. Para crear ganchos personalizados desde cero, sigue estos pasos.

Para abrir un nuevo archivo en .git/hooks/, ejecuta:

nano .git/hooks/commit-msg

Crea el script en este archivo. Ejemplo:

 #!/bin/sh
echo "✅ Commit message hook triggered"

Guarda y sal, luego hazlo ejecutable:

chmod +x .git/hooks/commit-msg 

En el ejemplo anterior, cada vez que se realiza la confirmación, los ganchos imprimen un mensaje. " Commit message hook triggered"

Hay otra forma de configurar ganchos personalizados. Cuando inicializas un repositorio, Git incluye ganchos predeterminados. Puedes editar estos valores predeterminados utilizando directorios de plantillas. 

Así es como funciona: Cuando ejecutas git init, Git copia el contenido del directorio de plantillas global al directorio .git/ del nuevo repositorio, incluidos los hooks. Si añades scripts de ganchos personalizados al directorio de plantillas global, cada nuevo repositorio que crees heredará esos ganchos personalizados automáticamente.

Creación y personalización de scripts de gancho

En primer lugar, debes determinar qué es lo que deseas lograr. ¿Se trata de detectar mensajes de confirmación vagos, evitar envíos accidentales o borrar cachés? Es importante definir el objetivo desde el principio, ya que los diferentes hooks de Git tienen diferentes propósitos y debes saber cuál utilizar. 

Por ejemplo, si deseas comprobar el estilo del mensaje de confirmación, utilizarás el gancho commit-msg. Si deseas evitar ciertos envíos a la rama principal, debes hacerlo con un gancho pre-push. 

Una vez que hayas elegido el gancho, la siguiente decisión es el idioma. En macOS y Linux, suele bastar con un pequeño script Bash (o simplemente sh). En Windows, algunos equipos se apoyan en PowerShell. 

Si tu repositorio es políglota, es posible que prefieras un intérprete universal como Python o Node.js para que todos puedan ejecutar la misma lógica. Por lo tanto, la clave es incluir un shebang (#!/bin/sh, #!/usr/bin/env python3, etc.) en la parte superior para que Git sepa cómo ejecutarlo.

Un ejemplo sencillo de gancho pre-commit que impide el commit de archivos de .env. Esto evita enviar accidentalmente claves API confidenciales.

#!/bin/sh

# Block committing secrets
if git diff --cached --name-only | grep -q ".env"; then
  echo "❌ .env file detected in commit! Remove it before committing."
  exit 1
fi

exit 0

Cuando quieras desactivar los hooks, la forma más sencilla es cambiarles temporalmente el nombre (cambia pre-commit por pre-commit.off) o eliminar su permiso de ejecución. 

Sin embargo, si solo necesitas omitirlo una vez, utiliza git commit --no-verify para omitir los ganchos de confirmación y git push --no-verify para omitir los ganchos de envío. Incluso puedes desactivar los hooks de forma global indicando a Git que apunte a una carpeta vacía con git config core.hooksPath /dev/null.

Casos de uso comunes y ejemplos de hooks de Git

Los hooks de Git son especialmente útiles para automatizar pruebas, comprobaciones de seguridad y aplicar estándares de calidad en tu flujo de trabajo. 

Escenarios prácticos de automatización

Aplicar el estilo del código o linting: El gancho pre-commit se utiliza a menudo para automatizar el formateo del código y detectar posibles errores antes de que se realice la confirmación.

Por ejemplo, en el siguiente gancho pre-commit, prettier se encarga automáticamente del formato y prepara los cambios antes de confirmarlos. A continuación, se puede ejecutar un linter, y la confirmación solo se realizará correctamente si el linting se supera. Si falla, se detiene la confirmación.

#!/bin/sh

# Collect staged JS/TS files
FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(js|ts|tsx)$')
[ -z "$FILES" ] && exit 0

echo "Formatting with Prettier..."
npx --yes prettier --write $FILES

# Re-stage files that Prettier changed
echo "$FILES" | xargs git add

echo "Linting with ESLint..."
npx --yes eslint $FILES
STATUS=$?

if [ $STATUS -ne 0 ]; then
  echo "ESLint found issues. Fix them or commit with --no-verify if needed."
  exit $STATUS
fi

echo "Pre-commit checks passed."
exit 0

Ejecutar pruebas automatizadas: Puedes configurar los ganchos para que ejecuten pruebas automatizadas antes de enviar cualquier cambio. Por ejemplo, el siguiente gancho pre-push detecta y ejecuta automáticamente las pruebas pytest disponibles en tu repositorio antes de enviar los cambios.

#!/bin/sh
echo "Running tests before push..."
pytest -q
STATUS=$?
[ $STATUS -eq 0 ] || { echo "Tests failed. Push aborted."; exit $STATUS;

Bloquea automáticamente el envío de datos confidenciales: Los archivos confidenciales como .env, .pem o .key suelen contener información secreta. El siguiente ejemplo de gancho pre-commit comprueba si existen dichos patrones y bloquea la confirmación si los contiene.

#!/bin/sh
set -e

STAGED=$(git diff --cached --name-only --diff-filter=ACM)

# Block dotenv and private keys
echo "$STAGED" | grep -E '\.env(\.|$)|(^|/)\.env$|\.pem$|\.key$|id_rsa$' >/dev/null 2>&1 && {
  echo "Sensitive file detected in staged changes. Remove it from the commit."
  exit 1
}

Consejos para escribir hooks de Git eficaces

Aquí he incluido algunos consejos que me han resultado útiles a la hora de escribir hooks de Git. 

Mantén los ganchos bien sujetos.

Los hooks se ejecutan cada vez que activas determinadas acciones de Git, así que procura que sean ligeros. Si tienes conjuntos de pruebas grandes, ejecútalos en CI en lugar de en ganchos locales para obtener un mejor rendimiento. Ejecutar linters, formateadores o comprobaciones en todo el repositorio en cada confirmación ralentizará tu trabajo, así que limita las comprobaciones a los archivos que realmente hayan cambiado.

Mantener la compatibilidad entre plataformas 

Asegúrate de que tus ganchos funcionen correctamente en diferentes sistemas operativos. Utiliza shebangs portátiles, gestiona los finales de línea de forma coherente (utiliza LF en lugar de CRLF) y no codifiques rutas absolutas. 

En su lugar, utiliza PATH y scripts de proyecto locales como npm run lint o python -m para que se ejecute en múltiples entornos.

Estrategias de depuración

Añade un registro detallado o un indicador de depuración (por ejemplo, HOOK_DEBUG=1) para rastrear cómo se ejecuta el script. Imprime detalles como el directorio actual, la rama o los archivos que se están preparando. Esto facilita seguir el flujo de ejecución y detectar dónde se producen los errores.

Prueba los ganchos con diferentes entradas y simula escenarios de fallo localmente antes de aplicar los cambios. Si un hook bloquea el progreso de forma inesperada, puedes omitirlo temporalmente con el indicador ` --no-verify ` de Git o utilizando variables de entorno diseñadas para omitir hooks.

Para mantener un comportamiento coherente en todos los sistemas operativos, evita los comandos específicos del sistema operativo y da preferencia a los lenguajes de scripting portátiles.

Documenta claramente los ganchos.

Una buena documentación mejora la comprensión del equipo y facilita la incorporación de nuevos miembros. Mantén un archivo README central en el que se detalle el propósito, el comportamiento y el uso de cada gancho. Incluye cómo ejecutar, requisitos previos, resolución de problemas y consejos para evitarlos. Además, proporciona instrucciones de instalación/configuración. 

Técnicas avanzadas de implementación y mejores prácticas para los hooks de Git

Si eres un usuario más avanzado, estos consejos pueden resultarte útiles:

Optimización del rendimiento

Para optimizar el rendimiento en flujos de trabajo complejos, reduce las dependencias externas evitando bibliotecas pesadas. Esto reduce el tiempo de arranque y disminuye los puntos de fallo. 

Almacena en caché los resultados de procesos costosos, como el linting, para que puedas reutilizarlos cuando los archivos no hayan cambiado. 

Si los ganchos contienen varias comprobaciones, paralízalos para que se ejecuten simultáneamente. Además, modulariza los scripts de gancho. Esto significa que los ganchos de estructura son componentes pequeños y reutilizables que solo ejecutan las partes relevantes en función del contexto.

Encadenamiento de ganchos y orquestación

Utiliza el encadenamiento de ganchos para ejecutar varios ganchos en un solo evento git. Por ejemplo, en un gancho pre-commit, es posible que quieras ejecutar linting, luego ejecutar pruebas y luego formatear el código, todo encadenado. Cada comando se ejecuta uno tras otro, y si alguno falla (sale con un estado distinto de cero), los comandos posteriores se pueden omitir para evitar una confirmación incorrecta. 

Cuando las acciones del gancho son independientes, también puedes ejecutarlas en paralelo para ahorrar tiempo. Ahí es donde se utiliza la orquestación para gestionar la ejecución de las tareas en el orden correcto.

Gestión de la configuración 

Cada repositorio tiene su propio directorio .git/hooks. Esto significa que si deseas realizar las mismas comprobaciones (por ejemplo, linting) en varios proyectos, tendrás que copiarlas y pegarlas en todos ellos. Una mejor manera es gestionar los hooks de forma centralizada para que todos los repositorios puedan acceder a ellos y ejecutarlos.

Puedes hacerlo con un solo comando: git config --global core.hooksPath ~/.githooks . Esto le indica a Git que busque ganchos en la carpeta ~/.githooks. Cualquier hook que crees allí se compartirá automáticamente en todos tus repositorios.

También puedes hacer que la lógica de los ganchos sea más dinámica con archivos de configuración (JSON o YAML). En lugar de codificar de forma rígida una lógica diferente para cada repositorio, tu script de hook puede leer el archivo de configuración de ese repositorio y aplicar las reglas correctas automáticamente.

Ejecución condicional

Dentro de los scripts de gancho, puedes añadir condiciones sencillas para que solo se ejecuten cuando sea relevante. Eso podría significar comprobar el nombre de la rama actual, ver qué archivos han cambiado realmente o leer una variable de entorno que les indique que deben omitirlos.

Si deseas tener más control, utiliza un marco como pre-commit, en el que se declara en un archivo de configuración qué ganchos se ejecutan en cada etapa. También puedes añadir lógica condicional, como ejecutar hooks solo en determinadas ramas, omitir hooks con variables o incluso añadir condiciones basadas en el tiempo. Esto hace que tus scripts de gancho sean dinámicos y se adapten a los flujos de trabajo reales.

Estrategias de colaboración y puesta en común 

Hay dos formas de centralizar los hooks de Git y compartirlos entre repositorios y equipos:

Plantillas Git

Cuando inicializas un repositorio, Git añade algunos ganchos predeterminados en el directorio git/hooks. Estos provienen de la plantilla predeterminada de Git.

Para crear hooks personalizados de forma centralizada, puedes crear un directorio de plantillas Git, escribir tus hooks allí y configurar Git globalmente para que utilice este nuevo directorio como plantilla predeterminada. 

git config --global init.templateDir /path/to/hooks-template

Pero este método carece de control de versiones para los ganchos. Esto resulta especialmente útil si tus ganchos cambian con poca frecuencia. Si actualizas los hooks con frecuencia y necesitas control de versiones, te recomendamos utilizar el siguiente método.

Repositorio central de git

Crea un repositorio central dedicado y controlado por versiones, y almacena todos tus scripts de gancho personalizados en ese repositorio, separado de los repositorios del proyecto. Así podrás realizar actualizaciones en los hooks independientemente del código base del proyecto. 

Estos ganchos deben estar estandarizados, lo que significa que hay que evitar codificar rutas o valores vinculados a un único repositorio.

Esta configuración es especialmente útil para los equipos, ya que todos pueden obtener actualizaciones periódicamente y sincronizarlas con sus proyectos. 

Un enfoque más eficiente es utilizar un script de configuración que clone el repositorio central de hooks y copie los scripts de hooks en el directorio .git/hooks de cada proyecto. Ejemplo de script de configuración: 

#!/usr/bin/env bash
set -euo pipefail

# Location of the shared hooks template repo
HOOKS_TEMPLATE_REPO="git@github.com:your-org/git-hooks-template.git"
HOOKS_TEMPLATE_DIR="$HOME/.git-hooks-template"

# Clone or update the template repo
 echo "Cloning hooks template repo..."
 git clone "$HOOKS_TEMPLATE_REPO" "$HOOKS_TEMPLATE_DIR"

# The repo where you want hooks installed
TARGET_REPO="${1:-$(pwd)}"
TARGET_HOOKS_DIR="$TARGET_REPO/.git/hooks"

# --- Copy strategy ---
echo "Copying hooks into $TARGET_HOOKS_DIR..."
cp -r "$HOOKS_TEMPLATE_DIR/"* "$TARGET_HOOKS_DIR/"

# 4. Make sure hooks are executable
chmod +x "$TARGET_HOOKS_DIR"/* || true

echo "✅ Hooks installed successfully into $TARGET_REPO"

Otra opción es utilizar enlaces simbólicos. Puedes vincular el directorio .git/hooks de cada proyecto a los scripts de tu repositorio de hooks controlado por versiones. Así que cada vez que actualices el repositorio central, los hooks se actualizarán automáticamente porque el enlace simbólico apunta a él.

Para mantener la fiabilidad de este sistema, establece un proceso claro para el mantenimiento de los ganchos. Los miembros del equipo deben proponer cambios en los hooks con solicitudes de extracción, fusionarlos solo después de revisarlos y mantener la documentación actualizada a medida que los hooks evolucionan. 

Integración de Git Hooks con los flujos de trabajo de desarrollo

Los hooks de Git desempeñan un papel importante en la integración continua (CI). Para contextualizar, CI significa fusionar cambios con frecuencia y, a continuación, ejecutar compilaciones y pruebas para detectar problemas de forma temprana. Al conectar hooks con herramientas de CI/CD como Jenkins, GitHub Actions o GitLab CI, puedes activar compilaciones, ejecutar pruebas e incluso implementar aplicaciones automáticamente en función de los eventos de Git.

Por ejemplo, un gancho pre-receive del lado del servidor ejecuta un script personalizado en el servidor Git antes de aceptar un push. Si el script falla, el servidor rechaza el envío. Puedes utilizar esto para comprobar si la última compilación de CI en esa rama se ha superado antes de permitir el envío. Esa ejecución de CI puede incluir comprobaciones de cobertura de código, pruebas unitarias o de integración, o incluso análisis de seguridad.

Los hooks también pueden automatizar tareas de implementación. Un gancho posterior a la recepción puede activar un webhook que inicia un canal de CI/CD. Cuando el código se fusiona con el principal, automáticamente se inicia el ciclo de compilación → implementación → lanzamiento.

Consideraciones de seguridad y mejores prácticas 

Si mantienes ganchos centrales para facilitar la colaboración y compartir información veraz, asegúrate de que el directorio de ganchos tenga permisos de archivo seguros para evitar el acceso no autorizado. Solo los usuarios de confianza deben tener acceso de escritura. 

Siempre debes validar las entradas o los parámetros que reciben tus scripts de gancho para evitar ataques de inyección de código. Por ejemplo, valida las entradas según patrones estrictos, como permitir solo nombres de ramas con caracteres alfanuméricos y guiones, o etiquetas que coincidan con vMAJOR.MINOR.PATCH. 

Nunca codifiques datos confidenciales en scripts de gancho. En su lugar, utiliza variables de entorno o herramientas específicas de gestión de secretos para proporcionar credenciales de forma segura en tiempo de ejecución. Puedes integrar herramientas como Gitleaks con ganchos pre-commit para ejecutar análisis de seguridad en busca de información confidencial en los cambios que estás a punto de confirmar.

Alguien puede redirigir tu hook para enviar el código o la información a un servidor diferente. Por lo tanto, limita los dominios a los que pueden acceder tus hooks. Utiliza un proxy o un cortafuegos para bloquear los servidores de destino desconocidos. Además, asegúrate de que tus registros no muestren información confidencial en los mensajes que se muestran. 

Conclusión

Los hooks de Git son una forma eficaz de automatizar tareas y aplicar estándares directamente en tu flujo de trabajo de desarrollo. Ayudan con todo, desde el estilo del código y las pruebas hasta la implementación y las comprobaciones de seguridad.

Al utilizarlos correctamente, reduces los errores, ahorras tiempo y facilitas la colaboración entre equipos.

Comienza con comprobaciones sencillas previas al compromiso y, a continuación, prueba configuraciones más avanzadas, como la orquestación, la gestión centralizada o las integraciones de CI/CD. Si eres usuario de Git y quieres mejorar tus habilidades, echa un vistazo a este curso avanzado de Git.