Pre-commit hooks

Cómo funciona

Git ejecuta el hook pre-commit antes de crear el commit. Si termina con un código distinto de cero, detiene la operación. Un gestor de hooks puede distribuir su configuración y facilitar la instalación en cada equipo.

Ejemplo: seleccionar controles útiles

Ejecuta análisis de secretos y comprobaciones rápidas sobre los archivos preparados. Si encuentra un token, el mensaje debe señalar el archivo y permitir corregirlo antes de volver a intentar el commit.

Reserva pruebas de integración, análisis largos y construcciones completas para CI o una ejecución explícita. El objetivo es una respuesta breve y accionable en el momento de guardar el cambio.

Configuración con el framework pre-commit

# .pre-commit-config.yaml (actualiza las versiones con `pre-commit autoupdate`)
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-merge-conflict
      - id: check-added-large-files
        args: ['--maxkb=500']
      - id: detect-private-key
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.24.0
    hooks:
      - id: gitleaks
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.12.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format
  - repo: local
    hooks:
      - id: conventional-commit
        name: Mensaje con Conventional Commits
        entry: ./scripts/validar-mensaje.sh
        language: script
        stages: [commit-msg]

pre-commit install --hook-type pre-commit --hook-type commit-msg
pre-commit run --all-files      # en CI o tras añadir un hook nuevo

Cada hook se instala en un entorno aislado con la versión fijada, por lo que todas las personas ejecutan exactamente lo mismo.

Herramientas según el ecosistema

Herramienta	Encaja en
pre-commit	Proyectos políglotas, hooks de la comunidad
Husky + lint-staged	Proyectos JavaScript/TypeScript
Lefthook	Cualquier lenguaje, binario único y ejecución en paralelo
prek	Reimplementación rápida compatible con la configuración de pre-commit

Qué poner y qué no

Sí (segundos)	No (mejor en CI)
Formateo de los archivos modificados	Suite completa de pruebas
Detección de secretos	Builds completos y análisis largos
Linters rápidos sobre archivos en el stage	Escaneo de todas las dependencias
Validación de YAML, JSON y conflictos sin resolver	Pruebas de integración
Formato del mensaje de commit	Despliegues

Si un hook tarda más de unos pocos segundos, la gente usará --no-verify y el control desaparecerá en la práctica.

Secretos: la razón principal

Un secreto que llega a un commit queda en el historial aunque se borre después, y si se hace push, debe considerarse comprometido y rotarse. El hook local evita la mayoría de los casos; el escaneo en el servidor (push protection de GitHub o GitLab, o Gitleaks en CI) cubre a quien no tenga los hooks instalados. Los agentes de código también hacen commits: los mismos hooks los protegen (feedback sensors).

Criterios de implementación

Versiona la configuración y documenta cómo instalarla. Comprueba los archivos del índice de Git, no solo el directorio de trabajo. Repite en CI los controles obligatorios, ya que los hooks locales pueden omitirse.