Automatización de Verificaciones de Código con Git Pre-Commit Hooks

Todo desarrollador conoce la frustración de hacer push de código solo para que los pipelines de CI/CD fallen debido a problemas de formato o errores de linting. ¿Qué tal si pudieras detectar estos problemas antes de que lleguen siquiera a tu repositorio? Los git pre-commit hooks ofrecen una solución poderosa que ejecuta verificaciones automatizadas localmente, ahorrando tiempo y manteniendo una calidad de código consistente en todo tu equipo.

Este artículo te guía a través de la configuración de git pre-commit hooks usando el framework pre-commit, configurando herramientas esenciales como ESLint, Prettier y Black, e implementando mejores prácticas que mantienen tu flujo de trabajo de desarrollo fluido y eficiente.

¿Qué Son los Git Pre-Commit Hooks?

Los Git hooks son scripts que Git ejecuta antes o después de eventos como commit, push y receive. Un git pre-commit hook específicamente se ejecuta después de que preparas los cambios pero antes de que Git cree el commit. Si el hook termina con un estado distinto de cero, Git cancela el commit, dándote la oportunidad de corregir los problemas primero.

Aunque puedes escribir hooks como scripts de shell simples en .git/hooks/, gestionarlos se vuelve complejo a medida que tu proyecto crece. Ahí es donde el framework pre-commit brilla—proporciona una manera estandarizada de gestionar y compartir hooks en tu equipo.

¿Por Qué Usar el Framework Pre-Commit?

El framework pre-commit resuelve varios puntos problemáticos con los Git hooks nativos:

• Instalación y actualizaciones fáciles: Los hooks tienen versiones y se instalan mediante una configuración YAML simple
• Agnóstico al lenguaje: Ejecuta linters de Python, formateadores de JavaScript y scripts de shell desde una sola configuración
• Ejecución selectiva: Los hooks se ejecutan solo en archivos modificados, manteniendo los commits rápidos
• Consistencia del equipo: Comparte el mismo archivo .pre-commit-config.yaml en todo tu equipo

Configurando Pre-Commit en Tu Proyecto

Primero, instala el paquete pre-commit:

pip install pre-commit

Crea un archivo .pre-commit-config.yaml en la raíz de tu proyecto. Aquí tienes una configuración práctica que cubre necesidades comunes:

repos:
  # Correcciones básicas de archivos
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files

  # Formateo de Python con Black
  - repo: https://github.com/psf/black
    rev: 24.2.0
    hooks:
      - id: black
        files: \.py$

  # Verificación de tipos de Python con Mypy
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.8.0
    hooks:
      - id: mypy
        additional_dependencies: [types-all]
        files: \.py$

  # JavaScript/TypeScript con Prettier
  - repo: https://github.com/pre-commit/mirrors-prettier
    rev: v3.1.0
    hooks:
      - id: prettier
        files: \.(js|jsx|ts|tsx|json|css|md)$

  # Linting de JavaScript/TypeScript con ESLint
  - repo: https://github.com/pre-commit/mirrors-eslint
    rev: v8.56.0
    hooks:
      - id: eslint
        files: \.(js|jsx|ts|tsx)$
        additional_dependencies:
          - eslint-config-standard
          - eslint-plugin-react

  # Ejecutar pruebas del proyecto
  - repo: local
    hooks:
      - id: pytest
        name: pytest
        entry: pytest
        language: system
        pass_filenames: false
        always_run: true

Instala los git hooks:

pre-commit install

Ahora tus hooks se ejecutarán automáticamente en cada commit. Para ejecutarlos manualmente en todos los archivos:

pre-commit run --all-files

Optimizando el Rendimiento de los Hooks

La velocidad importa—los hooks lentos desaniman a los desarrolladores de hacer commits frecuentemente. Sigue estas prácticas:

Ejecuta hooks solo en archivos preparados: El framework pre-commit hace esto por defecto, pero asegúrate de que tus hooks personalizados respeten este patrón.

Usa herramientas rápidas: Elige Ruff sobre Flake8 para Python, o Biome sobre ESLint para JavaScript cuando la velocidad sea crítica.

Omite verificaciones costosas localmente: Reserva las suites de pruebas completas para CI/CD. Los hooks locales deben enfocarse en victorias rápidas como formateo y linting básico.

Paraleliza cuando sea posible: Algunas herramientas soportan ejecución paralela. Por ejemplo, pytest puede ejecutar pruebas en paralelo con pytest-xdist.

Mejores Prácticas para la Adopción del Equipo

Lograr que tu equipo adopte pre-commit hooks requiere una implementación reflexiva:

Empieza pequeño: Comienza con hooks no intrusivos como la eliminación de espacios en blanco al final. Agrega verificaciones más estrictas gradualmente.

Documenta la configuración: Incluye instrucciones de instalación en tu README. Hazlo parte de tu proceso de incorporación.

Maneja diferencias de entorno: Usa hooks agnósticos al lenguaje cuando sea posible. Para herramientas específicas del lenguaje, asegúrate de que tu .pre-commit-config.yaml especifique versiones compatibles.

Proporciona vías de escape: A veces los desarrolladores necesitan omitir hooks. La bandera --no-verify omite todos los hooks:

git commit --no-verify -m "Corrección de emergencia"

Úsala con moderación y documenta cuándo es apropiado.

Enfoques Alternativos

Aunque pre-commit es el framework más popular, existen alternativas:

Husky: Popular en proyectos de JavaScript, se integra bien con scripts de npm.

Git hooks nativos: Scripts de shell directos en .git/hooks/ ofrecen máximo control pero carecen de portabilidad.

Lefthook: Alternativa rápida y multiplataforma con soporte de ejecución paralela.

Para la mayoría de equipos, pre-commit ofrece el mejor equilibrio de características, rendimiento y soporte del ecosistema.

Errores Comunes y Soluciones

Fallos de hooks en CI: Asegúrate de que los entornos de CI tengan todas las dependencias necesarias instaladas. Considera ejecutar pre-commit run --all-files como un paso de CI.

Problemas específicos de plataforma: Prueba los hooks en todas las plataformas que usa tu equipo. Usa Docker para entornos consistentes si es necesario.

Conflictos de merge en archivos de configuración: Mantén los cambios de .pre-commit-config.yaml mínimos y atómicos. Actualiza las versiones de hooks en commits separados.

Conclusión

Los git pre-commit hooks transforman la calidad del código de un proceso reactivo a uno proactivo. Al detectar problemas antes de que entren a tu repositorio, ahorras tiempo, reduces el cambio de contexto y mantienes estándares más altos en toda tu base de código. Comienza con hooks básicos de formateo, agrega gradualmente linters y verificadores de tipos, y siempre prioriza la velocidad para mantener fluido el flujo de trabajo de tu equipo.

La clave para una adopción exitosa radica en equilibrar la minuciosidad con la experiencia del desarrollador. Los hooks rápidos y enfocados que proporcionan valor inmediato se convertirán en una parte indispensable del flujo de trabajo de tu equipo.

Preguntas Frecuentes

Gain control over your UX

See how users are using your site as if you were sitting next to them, learn and iterate faster with OpenReplay. — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.