Git worktrees + pre-commit: ramas paralelas y validación en CI
En cualquier equipo DevOps maduro aparece tarde o temprano el mismo cuello de botella: tienes que arreglar un hotfix en main, revisar una pull request de un compañero, seguir avanzando en tu feature y, además, ejecutar los tests antes de cada commit. Hacer git stash, cambiar de rama y volver a reconstruir el entorno una y otra vez es una pérdida de tiempo silenciosa pero constante. Aquí es donde entran en juego dos herramientas que, combinadas, cambian por completo la forma de trabajar: git worktree y pre-commit.
Qué es realmente un worktree
Un worktree es un directorio de trabajo adicional asociado al mismo repositorio. Cada worktree tiene su propio HEAD, su propio índice y su propio árbol de archivos, pero comparte el mismo .git subyacente. Esto significa que puedes tener main, release/2.4 y feature/pagos abiertas simultáneamente en tres carpetas distintas, sin copias completas del repositorio.
git worktree add ../hotfix-login -b hotfix/login-fix main
git worktree add ../review-pr-482 origin/feature/cache
git worktree list
La salida de git worktree list muestra algo como:
/srv/app abc1234 [main]
/srv/hotfix-login def5678 [hotfix/login-fix]
/srv/review-pr-482 9876abc [feature/cache]
Lo importante: no hay clones duplicados. El historial, las referencias y los objetos son compartidos. Solo se duplican los archivos de trabajo y el índice. Para proyectos grandes con dependencias pesadas (node_modules, virtualenvs, capas de Docker) esto sigue siendo relevante, pero el ahorro frente a git clone es notable, y sobre todo desaparece el riesgo de perder cambios por un stash olvidado.
Cuándo tiene sentido usar worktrees
- Hotfixes urgentes mientras tu feature a medio terminar sigue intacta.
- Revisiones de código donde necesitas ejecutar los tests de la rama del compañero sin ensuciar tu entorno.
- Comparaciones de rendimiento entre dos ramas ejecutándose en paralelo.
- Generación de builds para distintas versiones sin tocar el árbol principal.
El comando para limpiar un worktree cuando ya no lo necesitas es igual de simple:
git worktree remove ../hotfix-login
git worktree prune
Pre-commit: validación antes de que el commit exista
pre-commit es un framework en Python que gestiona hooks de Git declarados en un archivo .pre-commit-config.yaml. Ejecuta linters, formateadores, verificadores de secretos y tests rápidos antes de que el commit se cree. Si algo falla, el commit se aborta y tú decides qué hacer.
Un archivo mínimo pero realista podría verse así:
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.6.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-yaml
- id: detect-private-key
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.4.10
hooks:
- id: ruff
args: [--fix]
- id: ruff-format
- repo: https://github.com/gitleaks/gitleaks
rev: v8.18.4
hooks:
- id: gitleaks
La instalación es un único comando:
pip install pre-commit
pre-commit install
pre-commit run --all-files
El hook queda registrado en .git/hooks/pre-commit y se ejecuta en cada git commit. La primera vez descarga los entornos aislados en ~/.cache/pre-commit, así que no contamina tu entorno de proyecto.
El problema clásico: hooks que no se replican en CI
El error más común es tratar pre-commit como algo puramente local. Si los hooks viven solo en la máquina del desarrollador, cualquiera puede saltárselos con git commit --no-verify y el pipeline de CI acepta código que nunca pasó por el linter. La solución es invocar exactamente la misma configuración desde el pipeline.
En GitHub Actions sería algo así:
name: lint
on: [push, pull_request]
jobs:
pre-commit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- uses: pre-commit/action@v3.0.1
En GitLab CI:
pre-commit:
image: python:3.12-slim
before_script:
- pip install pre-commit
script:
- pre-commit run --all-files --show-diff-on-failure
Como la configuración vive en el repositorio, desarrollador y CI ejecutan los mismos hooks, con las mismas versiones. Eso elimina la clásica discusión de "en mi máquina funciona".
Cómo encajan worktrees y pre-commit
Aquí está el detalle que muchos pasan por alto: los hooks de Git instalados con pre-commit install se aplican al repositorio, no al worktree. Cuando creas un nuevo worktree, el directorio .git apunta al mismo repositorio compartido, por lo que los hooks ya están activos en el nuevo directorio. Esto es una ventaja enorme: puedes abrir un worktree para un hotfix y el mismo pre-commit validará tus cambios sin configuración adicional.
Sin embargo, hay dos matices prácticos:
- Caché de entornos:
pre-commitreutiliza~/.cache/pre-commitentre worktrees, así que no se reconstruyen los entornos cada vez. Es un gran ahorro de tiempo cuando tienes tres o cuatro worktrees activos. - Ejecución de tests: si tu hook incluye tests lentos, ejecutarlos en paralelo desde varios worktrees puede saturar la máquina. La recomendación es dejar en pre-commit solo validaciones rápidas (linters, formateadores, secretos) y delegar los tests completos al CI.
Un flujo de trabajo realista
Imagina que estás a mitad de un refactor grande y llega un bug crítico en producción. El flujo sería:
git worktree add ../fix-critico -b hotfix/pago-duplicado main
cd ../fix-critico
# editar, commitear: pre-commit se ejecuta automáticamente
git commit -am "fix: evita doble cargo en reintentos"
git push origin hotfix/pago-duplicado
Mientras tanto, tu worktree principal sigue con el refactor sin interrupciones. No hubo stash, no hubo cambio de rama, no hubo reconstrucción del entorno. Y el commit que subiste pasó exactamente las mismas validaciones que correrán en CI.
Buenas prácticas y trampas comunes
- No compartas el mismo worktree entre tareas: un worktree por rama, sin excepciones.
- Versiona el
.pre-commit-config.yamly fijareva un tag concreto, nunca amain. - Ejecuta
pre-commit autoupdateperiódicamente para no quedarte con versiones obsoletas de linters. - Evita hooks que muten archivos sin avisar: los formateadores con
--fixson útiles, pero el desarrollador debe saber que el commit fallará la primera vez. - Limpia worktrees huérfanos:
git worktree prunetras borrar carpetas manualmente. - En CI, usa
--all-filessolo en pipelines completos; en pre-push o pre-commit deja que pre-commit detecte los archivos modificados.
Conclusión
La combinación de git worktree y pre-commit ataca dos problemas distintos pero complementarios: la fricción de cambiar de contexto entre ramas y la inconsistencia entre lo que valida el desarrollador y lo que valida el pipeline. Con unos pocos comandos obtienes un entorno donde varias ramas conviven en paralelo, los hooks se ejecutan de forma idéntica en local y en CI, y el historial del repositorio refleja solo commits que ya pasaron las validaciones mín
comentarios(0)
$ dejar comentario